Conecte los seguimientos de GenAI del OpenTelemetry a los eventos de resultados

Los rastreos OpenTelemetry y los eventos estructurados Telemetry resuelven diferentes partes de una investigación de un agente de IA. Mantenga modelos, agentes y herramientas detallados en un backend de observabilidad compatible con OTLP. Envíe un evento de resultado de terminal más pequeño a Telemetry cuando desee inspeccionar SQL sobre el éxito, el costo, la latencia, la versión, la cuenta, la transferencia o el valor del producto revisado.

Telemetry no expone un punto final OTLP y no es un backend de seguimiento OpenTelemetry. La conexión es un identificador de correlación propiedad de la aplicación, no una segunda exportación de cada tramo.

Utilice cada sistema para el trabajo previsto

Una traza OpenTelemetry es muy adecuada para responder:

• qué tramo o herramienta dominó una ejecución lenta;
• cómo se movía el control entre las operaciones de agente, modelo, recuperación y herramienta;
• qué excepción o dependencia explica una falla individual;
• qué atributos detallados estaban presentes dentro de un límite de retención de rastros aprobado.

Un evento de resultados compacto es muy adecuado para responder:

• qué versión tiene la mayor tasa de éxito de tareas terminales;
• qué flujo de trabajo cuesta más por resultado aceptado;
• si los reintentos de herramientas o las transferencias humanas aumentaron esta semana;
• qué nivel de cliente se vio afectado por una categoría de error acotada;
• si una puntuación de evaluación cambió después de una versión modelo o de sugerencia.

No copie todos los atributos de intervalo en el evento. Decida qué preguntas agregadas necesitan una columna duradera y incluya esos campos en la lista de permitidos.

Mapear la semántica deliberadamente

El Convenciones semánticas de IA generativa OpenTelemetry define atributos en evolución y abarca convenciones para operaciones de modelos, agentes y herramientas. Fije las versiones de convención semántica y biblioteca de instrumentación utilizadas por su servicio y luego revise la asignación durante las actualizaciones.

Las convenciones semánticas pueden cambiar a medida que maduran. No asuma que un atributo observado en un SDK o marco tiene la misma estabilidad o disponibilidad en todas partes. Trate la asignación exacta como código de aplicación versionado.

Emitir un resultado terminal al lado del rastro

Este contenedor JavaScript lee el ID de seguimiento actual y registra el resultado de la aplicación después de la ejecución del agente. La traza continúa siendo exportada por el OpenTelemetry SDK configurado; sólo los campos seleccionados van a Telemetry.

import { trace } from "@opentelemetry/api";
import telemetry from "telemetry-sh";

telemetry.init(process.env.TELEMETRY_API_KEY);

export async function runSupportAgent({
  agent,
  input,
  operationId,
  accountId,
  release,
}) {
  const startedAt = Date.now();
  let status = "success";
  let errorType;
  let result;

  try {
    result = await agent.run(input);
    return result;
  } catch (error) {
    status = "failed";
    errorType = classifyAgentError(error);
    throw error;
  } finally {
    const activeSpan = trace.getActiveSpan();
    const traceId = activeSpan?.spanContext().traceId;

    await telemetry.log("agent_run_completed", {
      operation_id: operationId,
      trace_id: traceId,
      workflow: "support_resolution",
      account_id: accountId,
      status,
      error_type: errorType,
      duration_ms: Date.now() - startedAt,
      human_handoff: result?.handoffRequired ?? false,
      tool_call_count: result?.toolCallCount ?? 0,
      release,
    });
  }
}

Haga que el error en la entrega de eventos no sea fatal, a menos que el flujo de trabajo empresarial requiera explícitamente lo contrario. Utilice un tiempo de espera breve, reintentos limitados, cierre ordenado y la guía de entrega en procesamiento por lotes, contrapresión y apagado.

Agregar el uso del modelo solo una vez

Si la instrumentación OpenTelemetry ya observa las solicitudes del proveedor, eso no coloca automáticamente el uso de la solicitud en Telemetry. Decida si una pregunta SQL agregada requiere un evento llm_request_completed separado.

Cuando lo haga, emita un evento por solicitud facturable con:

• operation_id, run_id y un trace_id aprobado opcional;
• provider, requested_model, response_model y service_tier;
• entrada, entrada en caché, salida y otras categorías de tokens definidas por separado;
• estimated_cost_usd y una fuente de precios versionada;
• latency_ms, status, attempt, feature y release.

No derive el costo de la duración del tramo. Utilice el uso informado por el proveedor y una tabla de tarifas revisada, luego concilie las estimaciones con la factura del proveedor. El Guía de costos de solicitud OpenAI muestra ese patrón.

Proteger el límite de los datos

La telemetría de IA generativa puede contener datos inusualmente sensibles. No envíe estos campos a Telemetry de forma predeterminada:

• contenido de aviso o finalización;
• instrucciones del sistema o contenido de cadena de pensamiento;
• texto del documento recuperado o incrustaciones;
• argumentos de herramienta, respuestas de herramienta, salida de shell o contenido de archivo;
• encabezados de autorización, cookies, claves API, credenciales de bases de datos o cadenas de conexión;
• mensajes de excepción sin restricciones o equipaje OpenTelemetry;
• datos personales que no han pasado la revisión de recopilación y retención del producto.

Prefiera categorías como input_category, output_category, tool_name, error_type, policy_result y review_outcome. Aplicar la lista de permitidos antes de llamar a cualquiera de los exportadores; eliminar un campo de un panel no lo elimina de los datos almacenados.

Consultar resultados y conservar el enlace de seguimiento

Utilice SQL para realizar comparaciones agregadas y al mismo tiempo conservar el puntero de correlación que necesitan los respondedores:

SELECT
  release,
  workflow,
  COUNT(*) AS completed_runs,
  SUM(CASE WHEN status = 'success' THEN 1 ELSE 0 END) AS successful_runs,
  SUM(CASE WHEN human_handoff THEN 1 ELSE 0 END) AS handoffs,
  ROUND(AVG(duration_ms), 0) AS average_duration_ms,
  MAX(trace_id) AS example_trace_id
FROM agent_run_completed
WHERE timestamp_utc >= now() - INTERVAL '7 days'
GROUP BY release, workflow
ORDER BY completed_runs DESC;

MAX(trace_id) es sólo un puntero de ejemplo del grupo, no un seguimiento representativo. Para una investigación, abra las filas subyacentes, seleccione la ejecución relevante y pegue su trace_id en el backend de seguimiento. Si ese backend admite una plantilla de URL estable, cree el enlace en una herramienta interna de acceso controlado en lugar de enviar credenciales de proveedor o nombres de host privados como campos de evento.

Validar la conexión

Antes del lanzamiento de producción:

1. Genere una ejecución exitosa, un error de herramienta, un reintento recuperado y un error de terminal.
2. Confirme que el backend de seguimiento contiene el árbol de extensión esperado.
3. Confirme que Telemetry contiene un evento de terminal por ejecución y los eventos de solicitud o herramienta previstos.
4. Compare los identificadores de correlación de eventos y seguimiento.
5. Verifique que no haya indicaciones, completaciones, argumentos, credenciales ni contenido privado.
6. Comportamiento de prueba cuando cualquiera de los exportadores es lento o no está disponible.
7. Propietarios de documentos, retención, versión de convenciones semánticas, muestreo y transferencia de la investigación.

Para arquitectura general y ejemplos de SDK, lea Telemetry con OpenTelemetry. Para el diseño de resultados específicos del agente, continúe con evaluar agentes de IA con SQL y Agente de IA que monitorea los límites del producto.