Mide el salto sobre el que vas a discutir

El mejor registro de esta base de código existe para zanjar una discusión concreta antes de que se convirtiera en una reescritura.

Nuestro chat llega a sus herramientas pidiéndole al proveedor que las llame. Así que una sola invocación cruza internet dos veces más de lo necesario: navegador → proveedor → nosotros → proveedor → navegador. Hay un arreglo arquitectónico evidente, y es una semana de trabajo.

Nadie había medido el salto.

/**
 * Record how long this service takes to answer an MCP call.
 *
 * The number this exists to produce is not our own speed — it is the cost of
 * the hop. merchants can time the whole round-trip but cannot see how much of
 * it was us, so the two numbers only mean something together.
 *
 * suggest-options-tool and suggest-palettes-tool are the useful probes. They
 * perform no I/O at all — they validate their input and hand back a reshaped
 * copy — so whatever merchants observes for one of those iterations, minus
 * what we report here, is inference plus transport and nothing else.
 */

Tres cosas hacen de esto un instrumento y no un número.

Nombra una sonda. No «mide las herramientas»: mide estas dos, que no hacen entrada/salida alguna, de modo que la resta aísla el transporte. Diseñar la medición es casi todo el trabajo.

Registra dos relojes, y explica cuál usar:

// Time inside the handler. Small for every tool that does no I/O,
// which is exactly why it is not the number to subtract.
'duration_ms' => (int) round((hrtime(true) - $started) / 1_000_000),

// Time since the request entered PHP. This is the one to subtract from what
// merchants observed: middleware timing starts after the framework has
// booted, and locally that gap was 80ms against 2ms of actual work — so
// `duration_ms` alone would flatter us badly and make the hop look far more
// expensive than it is.
'request_ms' => defined('LARAVEL_START')
    ? (int) round((microtime(true) - LARAVEL_START) * 1000)
    : null,

Ochenta milisegundos de arranque del framework frente a dos de trabajo real. Registra sólo el tiempo del manejador y concluirías que el salto cuesta ochenta milisegundos más de lo que cuesta —y luego dedicarías una semana a eliminarlo apoyándote en tu propio error de medición.

Separa tu tráfico del de los demás:

// Distinguishes our own widget's traffic (which arrives via the provider's
// connector on a valid token) from third-party agents, whose latency profile
// is somebody else's network.
'via_token' => $request->bearerToken() !== null,

Un endpoint de herramientas público lo llama gente que no conoces, por redes que no ves. Mezclar su latencia con tus percentiles produce un número que no describe a nadie.

El principio: mide antes de reconstruir. Adivinar ese salto habría sido una mala razón para rehacer el bucle de agente, y una razón igual de mala para no hacerlo.

Registra la pregunta que te van a hacer

Cada campo de este capítulo existe porque alguien preguntó algo concreto.

¿Por qué va lento? → duration_ms, request_ms, iterations. ¿Por qué es caro? → los recuentos de tokens, tool_count. ¿Por qué paró ahí? → stop_reason, y el tope reportado. ¿Funciona el cacheo del prompt? → cache_read_input_tokens. ¿Es tráfico nuestro? → via_token. ¿Merece la pena rehacer el bucle? → la sonda.

Registrarlo todo no es observabilidad; es una factura y un pajar. Escribe las preguntas que esperas que te hagan sobre una función que no puedes reproducir, registra exactamente los campos que las responden, y borra los campos que nadie ha consultado nunca.

Lo que sostiene este capítulo

• Reproducir no está disponible. Lo que registraste en su momento es todo lo que tendrás.
• Nombres y tamaños, nunca entradas ni resultados. Los argumentos de las herramientas son las palabras del propio usuario.
• Registra recuentos de caracteres en vez de texto para separar una respuesta larga de una lenta sin almacenarla.
• Una línea estructurada por ida y vuelta, con el número de iteración, para poder reconstruir un turno.
• Diseña la sonda, no pongas sólo un cronómetro. Elige las operaciones que no hacen entrada/salida para que una resta signifique algo.
• Registra dos relojes y di cuál restar. El arranque del framework eclipsaba el trabajo real y habría falseado el resultado.
• Separa tu propio tráfico del de terceros antes de citar un percentil.
• Mide antes de reconstruir. Una suposición es mala razón para una semana de trabajo, e igual de mala para no hacerla.