Exportación de trazas de gateway LLM a Traceloop con OpenTelemetry

TrueFoundry AI Gateway exporta trazas de OpenTelemetry a Traceloop a través de OTLP/HTTP utilizando el https://api.traceloop.com/v1/traces punto final y un token Bearer en el encabezado Authorization . Cada solicitud LLM que pasa por la pasarela produce un árbol de spans que llega al panel de control de Traceloop sin necesidad de cambios en el código de la aplicación o en la topología de despliegue.

Esta publicación cubre la ruta de generación de trazas dentro de la TrueFoundry AI Gateway y cómo Traceloop ingiere y presenta esos datos. También describe la superficie de configuración y los controles de privacidad de datos disponibles a nivel de pasarela.

Cómo la pasarela genera trazas

La TrueFoundry AI Gateway está construida sobre el framework Hono y se ejecuta como un pod sin estado que maneja más de 250 solicitudes por segundo en una única vCPU con aproximadamente 3 ms de latencia añadida por solicitud. La pasarela opera en una arquitectura dividida donde un plano de control gestiona la configuración y uno o más pods de pasarela procesan el tráfico de inferencia.

Cuando llega una solicitud, la pasarela ejecuta la siguiente secuencia en la ruta crítica:

1. Token JWT validado contra claves públicas almacenadas en caché en memoria (descargadas una vez del IdP y actualizadas a través de NATS)
2. Autorización verificada contra un mapa de usuario a modelo en memoria, mantenido actualizado por NATS pub/sub
3. El identificador del modelo se resuelve a un punto final de proveedor físico mediante la lógica de enrutamiento del Modelo Virtual que se ejecuta en memoria.
4. La solicitud se traduce del formato compatible con OpenAI al formato del proveedor de destino a través de una capa adaptadora.
5. La solicitud se reenvía al proveedor y la respuesta se transmite de vuelta al cliente.

Ninguno de estos pasos realiza llamadas externas, excepto la propia llamada al proveedor. La limitación de velocidad ejecuta el algoritmo de cubo de tokens de ventana deslizante contra el estado en memoria. La evaluación de las barreras de seguridad (cuando está configurada) se ejecuta concurrentemente con la llamada al modelo para las comprobaciones de entrada y secuencialmente para las comprobaciones de salida.

Una vez completada la solicitud, el gateway publica el árbol de spans de forma asíncrona en NATS. El exportador de OTEL lee de esta ruta asíncrona y reenvía los spans al punto final externo configurado. Debido a que la ruta de exportación está completamente desacoplada de la ruta de solicitud, un backend de OTEL lento o inalcanzable nunca añade latencia al cliente y nunca provoca que una solicitud falle. Si Traceloop no es accesible, los spans se descartan en el exportador y se registran internamente. El propio almacenamiento interno de trazas de TrueFoundry no se ve afectado porque la exportación es aditiva.

El gateway genera spans en cinco etapas: el manejador HTTP de entrada, la autenticación, la resolución del modelo, la llamada al proveedor de salida y el ensamblaje de la respuesta en streaming. Cada span lleva un conjunto consistente de atributos.

El gen_ai.los atributos siguen las Convenciones Semánticas de OpenTelemetry para Sistemas de IA Generativa. Esto significa que los datos de traza que llegan a Traceloop son estructuralmente idénticos a los que produciría cualquier aplicación instrumentada con OpenLLMetry.

‍

Lo que Traceloop hace con los datos

Traceloop es una plataforma de observabilidad de LLM construida sobre OpenLLMetry, que es su capa de instrumentación OpenTelemetry de código abierto. El backend de Traceloop acepta datos de traza OTLP/HTTP y los indexa para el panel de control de Traceloop. La plataforma es nativa de trazas. Las métricas como el uso de tokens, la latencia y el costo se calculan a partir de los atributos de los spans, en lugar de una transmisión de métricas OTLP separada. Por eso, configurar solo el exportador de trazas en TrueFoundry es suficiente, ya que no hay /v1/metrics punto final en la superficie de ingesta de Traceloop.

Traceloop organiza los datos en torno a tres abstracciones principales. Las trazas son la unidad de nivel superior y corresponden directamente a una solicitud de LLM o a un flujo de trabajo de agente. Los spans dentro de una traza representan operaciones individuales (una llamada a LLM, una invocación de herramienta y un paso de recuperación). Los entornos se asignan a las etapas de despliegue y cada entorno tiene su propia clave API, lo que permite que las trazas de Desarrollo, Staging y Producción permanezcan aisladas en el panel de control.

El Traceloop panel de control muestra el uso de tokens a lo largo del tiempo, las distribuciones de latencia, las tasas de error y los desgloses del modelo directamente desde IA generativa.* atributos de span. Dado que TrueFoundry rellena estos atributos en cada span, el panel de control de Traceloop se completa automáticamente sin necesidad de instrumentación SDK en la capa de aplicación.

‍
‍

Traceloop también es compatible con el versionado de prompts y los pipelines de pruebas de regresión, pero esas características operan a nivel del SDK de la aplicación y están fuera del alcance de esta integración. La integración a nivel de pasarela cubre la superficie completa de observabilidad: cada solicitud que pasa por TrueFoundry produce un rastro en Traceloop, independientemente del proveedor o modelo de LLM que se invoque.

La superficie de integración

La conexión entre TrueFoundry y Traceloop es una única solicitud POST OTLP/HTTP a https://api.traceloop.com/v1/traces que transporta lotes de spans codificados en Proto. La autenticación se realiza mediante un token Bearer en el Authorization encabezado. El token es una clave API de Traceloop con ámbito para un entorno específico.

TrueFoundry expone esta configuración en AI Gateway → Controls → Settings → OTEL Config. La sección del exportador de trazas Otel acepta los siguientes campos.

El punto final debe incluir la ruta completa /v1/traces . El exportador de TrueFoundry no añade automáticamente las rutas de señal. Esto difiere del OTel Collector otlphttp exportador, que añade la ruta automáticamente desde la URL base. Ambos resuelven al mismo destino.

Las claves API de Traceloop se generan por entorno desde la página de Entornos en el panel de control de Traceloop. Una clave se muestra solo una vez en el momento de su creación. El valor de la clave se pasa en el encabezado como Bearer <key> incluyendo el Bearer prefijo como una cadena literal.

Controles de privacidad de datos

La pasarela proporciona un Excluir datos de solicitud conmutador en la sección de Configuración de OTEL. Cuando está habilitado, el exportador elimina tfy.input y tfy.output y tfy.input_short_hand de cada span antes de reenviarlo a Traceloop. Los atributos de span restantes (recuentos de tokens, nombres de modelos, latencia y metadatos de enrutamiento) no se ven afectados. Este conmutador es apropiado cuando las indicaciones o las finalizaciones contienen información de identificación personal (PII) del usuario o contenido propietario que no debe salir del límite del clúster.

El Atributos de recursos adicionales campo permite añadir pares clave-valor personalizados a cada span exportado. Esto es útil para el etiquetado de entornos, la atribución de centros de coste y el filtrado multi-inquilino dentro de un único entorno de Traceloop.

‍

Resumen de la arquitectura

Cada solicitud de LLM a través de TrueFoundry AI Gateway genera un árbol de spans que cubre la autenticación y el enrutamiento, la llamada al proveedor y la respuesta. Una vez completada la solicitud, el gateway publica este árbol de spans en NATS de forma asíncrona. El exportador de OTEL lee de NATS y envía lotes codificados en Proto a https://api.traceloop.com/v1/traces con un token Bearer. Traceloop indexa los spans y muestra el uso de tokens, la latencia y los desgloses del modelo en su panel de control a partir de los gen_ai.atributos en cada span.

No se requieren sidecars. No se requieren cambios en el código de la aplicación. No es necesario añadir ningún SDK de OpenLLMetry a los servicios que llaman al gateway. La integración opera completamente en la capa del gateway y cubre el 100% del tráfico que pasa a través de él, independientemente del estado de instrumentación de la aplicación que realiza la llamada.

La propiedad arquitectónica que lo hace tan limpio es la publicación asíncrona en NATS. Dado que la exportación de spans está desacoplada de la ruta de solicitud, la integración añade cero latencia a las llamadas de inferencia y no introduce ninguna dependencia de disponibilidad de Traceloop. El gateway procesa las solicitudes a pleno rendimiento, sea o no accesible Traceloop.

‍