Cómo crear observabilidad de LLM neutral para el proveedor con OpenTelemetry

La observabilidad de LLM se ve afectada cuando cada equipo de aplicaciones registra las respuestas de los proveedores en su propio formato. Durante un incidente, los equipos de la plataforma deben responder preguntas concretas: qué equipo realizó la solicitud, qué alcance de clave API se utilizó, qué modelo se solicitó, qué proveedor realmente lo atendió, si se produjo un reintento o una alternativa, cuántos tokens se consumieron, qué depósito de latencia cambió y qué clase de error causó la falla. También necesitan esas respuestas sin copiar indicaciones sin procesar, completaciones, claves de proveedores o identificadores de clientes en almacenes de registros genéricos.

La respuesta práctica es instrumentar la puerta de enlace multimodelo API como punto de control de observabilidad. El seguimiento a nivel de aplicación sigue siendo importante, pero la puerta de enlace es donde se pueden normalizar la selección de proveedores, los reintentos, las alternativas, la contabilidad de uso, la propiedad de las solicitudes y la aplicación de la privacidad antes de que la telemetría llegue a las herramientas posteriores. Para los equipos que operan un LLM empresarial API, esto se convierte en la diferencia entre datos de depuración dispersos y un modelo operativo neutral para el proveedor.

Defina primero el contrato de observabilidad

Comience con un contrato de atributos escrito, no con capturas de pantalla del panel. El contrato debe definir los metadatos mínimos que debe emitir cada solicitud de LLM, qué campos pueden salir de la puerta de enlace, qué campos están restringidos y qué campos nunca se exportan.

Un contrato básico útil incluye metadatos de propiedad, enrutamiento, modelo, uso, latencia y resultados. Los atributos de propiedad identifican la organización, el equipo, el entorno, la carga de trabajo, la aplicación y el alcance clave API. Los atributos de enrutamiento identifican la ruta de la puerta de enlace, la versión de la política, el proveedor solicitado, el modelo solicitado, el proveedor seleccionado, el modelo seleccionado, el recuento de reintentos, el recuento de respaldo y si se utilizó streaming. Los atributos de uso capturan tokens de entrada, tokens de salida, tokens de entrada almacenados en caché, tokens de razonamiento cuando estén disponibles, recuento de solicitudes y clase de costo estimada. Los atributos de resultado capturan el estado, el código de error del proveedor cuando es seguro, la clase de error normalizado, el resultado de la validación, el estado de tiempo de espera y el modelo de respuesta final.

Mantenga el contrato neutral respecto al proveedor. Un error específico del proveedor, como una respuesta de límite de velocidad, una respuesta de modelo sobrecargada, una falla de validación de esquema, un rechazo de seguridad, un tiempo de espera o un error de ventana de contexto, debe asignarse a una clase de error normalizada que los paneles puedan agrupar entre proveedores. El código de error del proveedor original puede ser útil, pero debe tratarse como datos de diagnóstico restringidos, no como una dimensión principal del panel.

Utilice un modelo de tramo centrado en puerta de enlace

Una estructura de seguimiento clara evita que la telemetría LLM se convierta en una pila plana de tramos. Utilice un intervalo de solicitudes de aplicación entrante, un intervalo de operaciones LLM lógica y intervalos secundarios para el trabajo que realiza la puerta de enlace.

Una jerarquía típica se ve así:

inbound.http_request
  llm.operation
    llm.provider_attempt
    llm.provider_attempt.retry
    llm.provider_attempt.fallback
    retrieval.query
    tool.call
    output.validation

El intervalo de solicitudes entrantes representa la solicitud de la persona que llama a la puerta de enlace. El intervalo de operación lógica de LLM representa la tarea de LLM visible para el usuario, incluso si la puerta de enlace realiza varios intentos de proveedor. Los intervalos de intentos del proveedor capturan cada llamada real a un modelo ascendente API. Los intervalos de recuperación, herramientas y validación deben ser elementos secundarios de la operación lógica cuando forman parte de la producción de la respuesta final.

Esta separación es importante durante los incidentes. Si una solicitud retrocede de un modelo a otro, la operación lógica puede tener éxito mientras que el primer intento del proveedor falla. Si el resultado final no supera la validación del esquema, el intento del proveedor puede tener éxito técnico mientras que la operación lógica falla. Sin intervalos separados, los paneles ocultan las fallas del proveedor detrás de respuestas exitosas del usuario final o exageran las fallas que se recuperaron exitosamente.

Asignar atributos de OpenTelemetry GenAI detrás de un asignador interno

Existen convenciones semánticas de OpenTelemetry para que los productores de telemetría utilicen nombres y atributos comunes en bases de código, bibliotecas y plataformas.El proyecto OpenTelemetry ahora apunta las convenciones de IA generativa a un repositorio GenAI separado, y esas convenciones definen los atributos de solicitud y respuesta del modelo, como el nombre del proveedor, el modelo solicitado, el modelo de respuesta, los tokens de entrada, los tokens de salida, los tokens de razonamiento y los tokens de entrada almacenados en caché.

Utilice esos atributos GenAI donde encajen, pero no distribuya los nombres de los atributos sin procesar por todo el código de la puerta de enlace. Envuélvalos detrás de un pequeño mapeador de telemetría. Ese asignador debe aceptar un registro de solicitud interno y producir atributos de intervalo estandarizados.

record LlmTelemetryContext {
  organization_id
  team_id
  environment
  api_key_scope
  route_name
  route_policy_version
  workload_class
  provider_requested
  model_requested
  provider_selected
  model_response
  input_tokens
  output_tokens
  cached_input_tokens
  reasoning_tokens
  retry_count
  fallback_count
  normalized_error_class
}

El asignador puede emitir atributos OpenTelemetry GenAI para los campos estándar y atributos de puerta de enlace privada para el contexto empresarial. Mantenga los atributos privados en un espacio de nombres controlado, por ejemplo llm_gateway.organization_id, llm_gateway.team_id, llm_gateway.key_scope, llm_gateway.route_policy y llm_gateway.workload_class.

Este diseño le brinda telemetría neutral para el proveedor y al mismo tiempo protege el código base contra la rotación. Las convenciones de GenAI aún están evolucionando, por lo que el asignador es donde los nombres pueden cambiar sin editar cada controlador, módulo de reintento, adaptador de transmisión y componente de validación.

Separar metadatos del contenido confidencial

Los seguimientos de LLM son inusualmente confidenciales porque los datos de depuración más útiles pueden ser los mismos datos que no deben conservarse ampliamente: solicitudes, documentos recuperados, parámetros de herramientas, finalizaciones, identificadores de usuario, cliente identificadores y credenciales de proveedor sin procesar. La postura predeterminada debe ser la observabilidad de los metadatos primero.

Los campos predeterminados recomendados incluyen hash de solicitud, ID de plantilla de solicitud, versión de solicitud, ID de esquema, nombre de herramienta, colección de recuperación, nombre de ruta, recuento de tokens, latencia, clase de error normalizado y estado de validación. Estos campos responden a muchas preguntas operativas sin exportar contenido sin procesar.

La captura de mensajes sin procesar y de finalización debe ser voluntaria, tener un tiempo limitado, tener acceso controlado y redactarse antes de la exportación. No lo habilites globalmente como una característica de conveniencia. Cuando sea necesaria la captura de contenido para un incidente de producción, adjunte una marca de depuración a un conjunto reducido de solicitudes, dirija esos seguimientos a un backend restringido y establezca una ventana de retención breve.

Los identificadores hash no constituyen una anonimización automática. Si el espacio de entrada es pequeño o predecible, los valores hash se pueden revertir adivinando. Para identificadores de clientes o usuarios confidenciales, considere la posibilidad de eliminarlos, identificarlos sustitutos, agruparlos, truncarlos o utilizar hash con claves con controles de claves estrictos. Utilice hashes principalmente para una correlación estable cuando se comprenda el riesgo, no como una respuesta general de privacidad.

Haga cumplir la privacidad en el recopilador

La guía de OpenTelemetry dice que los datos confidenciales deben manejarse antes de exportarlos. El recopilador puede eliminar, aplicar hash, filtrar, redactar o transformar atributos de telemetría utilizando procesadores como atributos, filtro, redacción y transformación. Eso convierte al Collector en una segunda línea de defensa después de la instrumentación de la puerta de enlace en sí.

Un canal de Collector práctico debe usar una lista de permitidos para atributos de bajo riesgo, eliminar campos de solicitud y respuesta sin procesar de forma predeterminada, enmascarar valores que coincidan con patrones bloqueados y enrutar rastros de mayor sensibilidad por separado cuando la captura de contenido está habilitada explícitamente. El procesador de atributos de OpenTelemetry Collector admite acciones como eliminar y hash. El procesador de redacción está diseñado para eliminar atributos que no están en una lista de permitidos y enmascarar valores que coincidan con patrones bloqueados.

Por ejemplo, la puerta de enlace puede evitar la emisión de contenido sin procesar de forma predeterminada, mientras que el recopilador aún elimina atributos como llm.prompt.raw, llm.completion.raw, provider.api_key, authorization y cookie si aparecen debido a un error o integración de biblioteca. Trate esto como un control de defensa en profundidad, no como una razón para emitir datos inseguros casualmente.

Reintentos, alternativas y validación de instrumentos por separado

Los reintentos y las alternativas a menudo son invisibles en API métricas agregadas. Esa invisibilidad provoca dos problemas operativos. En primer lugar, la latencia puede degradarse porque una respuesta exitosa puede ocultar múltiples intentos fallidos.En segundo lugar, el costo puede aumentar porque una sola solicitud de usuario puede crear varias llamadas de modelo ascendentes.

Cada intervalo de intentos de proveedor debe incluir el número de intentos, el motivo del reintento, el proveedor seleccionado, el modelo seleccionado, el tiempo de espera previsto, la latencia, el uso del token cuando esté disponible y el resultado. Si se produce un retroceso, el intervalo de retroceso debe identificar la política de ruta original, el motivo del retroceso y el modelo realmente utilizado para la respuesta final.

La validación de salida estructurada debe ser su propio intervalo o evento. Capture el ID del esquema, la versión del esquema, el resultado de la validación, el recuento de intentos de reparación y el estado final. No almacene la salida completa no válida de forma predeterminada. Una falla de validación es operativamente diferente de un error de transporte del proveedor, y los paneles no deben confundirlos.

Cree paneles en torno a preguntas, no a proveedores

La observabilidad neutral del proveedor debe responder preguntas operativas directamente. Los paneles útiles incluyen latencia p95 y p99 por modelo, proveedor, equipo, entorno y clase de carga de trabajo; uso de tokens por equipo y ruta; tasa de falla por clase de error normalizado; reintentar la amplificación por política de ruta; frecuencia de respaldo por modelo solicitado; errores de ventana contextual por plantilla de aviso; fallas de validación de salida estructurada por esquema; y ejemplos de seguimiento de muestra para solicitudes fallidas, costosas o lentas.

Mantenga los informes de facturación y uso total fuera de los seguimientos de muestra. El muestreo de cola es útil para la depuración, pero puede distorsionar los totales. Los totales de tokens, los recuentos de solicitudes y los libros de costos deben provenir de contadores, libros de solicitudes o sistemas de conciliación de facturación no muestreados. Los seguimientos deben explicar por qué se produjo una solicitud costosa o lenta; no deberían ser la única fuente de verdad financiera.

Utilice el muestreo de cola para seguimientos de alto valor

El procesador de muestreo de cola de OpenTelemetry Collector puede tomar decisiones de muestreo una vez completados los intervalos, incluidas políticas basadas en atributos y valores numéricos. Esto es útil para el tráfico LLM porque a menudo se sabe si un seguimiento es valioso solo después de que finaliza la respuesta.

Conserve los seguimientos para errores del proveedor, fallas de validación, latencia muy alta, uso de token inusualmente costoso, fallas de la ventana de contexto, intentos de respaldo y solicitudes etiquetadas de depuración manualmente. Pruebe el tráfico exitoso de rutina a un ritmo más bajo. Esto mantiene los rastros que tienen más probabilidades de explicar los incidentes mientras se controla el volumen de almacenamiento.

Un modelo de política razonable es simple: mantener siempre los errores, mantener siempre las solicitudes por encima de un umbral de latencia o token, mantener siempre los seguimientos etiquetados con depuración y muestrear probabilísticamente las solicitudes ordinarias exitosas. Revise los umbrales a medida que cambie el tráfico. Un umbral que resulta útil durante la adopción temprana puede ser demasiado bajo una vez que aumenta el tráfico de producción.

Agregar pruebas de contrato para telemetría

La telemetría debe probarse como un contrato API porque de ello dependen los paneles de control posteriores, las alertas, los controles de costos y los flujos de trabajo de incidentes. Agregue pruebas que ejecuten solicitudes de puerta de enlace representativas y afirmen que se emiten los intervalos y atributos requeridos.

Las pruebas deben verificar que una solicitud exitosa emita el intervalo de operación LLM lógica, un intervalo de intentos del proveedor, el modelo solicitado, el modelo de respuesta, el nombre del proveedor, los recuentos de tokens cuando estén disponibles, los metadatos del alcance clave o del equipo, la versión de la política de ruta y el estado final. Las pruebas de reintento deben afirmar el número de intentos y los motivos de los reintentos. Las pruebas de respaldo deben validar tanto el intento fallido como el intento final exitoso del proveedor. Las pruebas de validación deben afirmar el ID del esquema, el estado de validación y el recuento de intentos de reparación.

Las pruebas de seguridad son igualmente importantes. Afirme que las claves de proveedor sin procesar, los encabezados de autorización, las cookies, las solicitudes sin procesar, las completaciones sin procesar y los identificadores de clientes no aprobados no están presentes en la telemetría exportada.Estas pruebas no deberían cerrarse cuando un desarrollador agrega un nuevo atributo de intervalo sin clasificarlo.

Lista de verificación de implementación

• Contrato de atributos: Definir atributos obligatorios, opcionales, restringidos y prohibidos.
• Jerarquía de intervalos: Solicitudes entrantes separadas, operaciones lógicas de LLM, intentos de proveedor, reintentos, respaldos, llamadas de recuperación, llamadas a herramientas y validación.
• Mapeo semántico: Utilice atributos OpenTelemetry GenAI donde encajen y atributos de puerta de enlace privada para el contexto de propiedad y enrutamiento.
• Política de privacidad: De forma predeterminada, use hashes, ID de plantilla, ID de esquema, nombres de herramientas, recuentos de tokens, latencia y clases de error en lugar de sin formato. content.
• Procesadores recopiladores: Eliminar campos prohibidos, redactar patrones bloqueados, incluir en listas permitidas atributos de bajo riesgo y enrutar seguimientos sensibles por separado.
• Política de muestreo: Realizar muestreos finales de seguimientos de alto valor y mantener métricas agregadas sin muestrear.
• Paneles de control: Cree vistas sobre latencia, uso, fallas, reintentos, respaldos, validación y factores de costos.
• Alertas: Alerta sobre clases de error normalizadas, cambios de latencia p99, amplificación de reintentos, picos de respaldo, fallas de validación y token anomalías.
• Pruebas de contrato: Afirme que la telemetría requerida está presente y que la telemetría confidencial está ausente.

Compensaciones para decidir explícitamente

La instrumentación a nivel de puerta de enlace proporciona metadatos consistentes rápidamente, pero puede pasar por alto el contexto específico de la aplicación a menos que los equipos pasen metadatos de solicitud estructurados, como inquilino, flujo de trabajo, plantilla de solicitud y nombre de la característica. Haga que esos metadatos formen parte del contrato de solicitud de puerta de enlace en lugar de depender de registros de formato libre.

La captura de contenido completo mejora la depuración y la evaluación, pero aumenta la privacidad, la seguridad, la retención y la carga de control de acceso. Muchos equipos deberían comenzar solo con hash, ID de plantilla, ID de esquema y extractos redactados.

Las clases de error neutrales para el proveedor hacen que los paneles se puedan utilizar en múltiples API de modelo, pero comprimen los detalles específicos del proveedor. Mantenga los códigos de error del proveedor sin procesar solo cuando sea seguro y restrinja el acceso a ellos.

Las convenciones de OpenTelemetry GenAI reducen el bloqueo, pero las convenciones seguirán evolucionando. Un asignador interno le brinda los beneficios de la estandarización sin permitir que los nombres de atributos inestables se filtren a través del código base.

Conclusión

La observabilidad LLM neutral del proveedor no es solo el seguimiento agregado a las llamadas de modelo. Es un contrato operativo en la capa de puerta de enlace: intervalos consistentes, modelo normalizado y metadatos de proveedores, contexto de propiedad, uso de tokens, reintento y visibilidad de respaldo, controles de privacidad, reglas de muestreo y pruebas que evitan que se filtren datos confidenciales.

Comience con la puerta de enlace porque ya ve las decisiones más importantes: quién realizó la solicitud, qué política la enruta, qué proveedor la atendió, cuánto costó en tokens, cuánto tiempo tomó, si se ejecutó la lógica de recuperación y qué falló. Una vez que esa base sea estable, los equipos de aplicaciones pueden agregar un contexto de flujo de trabajo más rico sin que cada equipo invente su propio sistema de observabilidad LLM.

Lecturas relacionadas

• telemetría de enrutamiento alternativo