Recopilación e inspección de seguimientos en Microsoft Foundry Toolkit

Utilice Microsoft Foundry Toolkit for Visual Studio Code para recopilar los seguimientos locales o ver la telemetría de los agentes implementados en Microsoft Foundry. Una traza agrupa las operaciones grabadas para una solicitud. Cada operación es un span con tiempo, estado y cualquier atributo o evento proporcionado por la instrumentación.

En este artículo se trata primero la recopilación local y, después, el seguimiento en la nube para los agentes implementados. Elija el origen de datos que coincida con su investigación:

Un agente hospedado ejecuta el código personalizado en Foundry Agent Service. Foundry administra el hospedaje, pero usted sigue siendo responsable del código y las dependencias. El seguimiento no reemplaza la creación y la implementación del agente.

Prerequisites

• Visual Studio Code con la extensión actual de Foundry Toolkit pública. Consulte Instalar Foundry Toolkit.
• Una aplicación que puede ejecutarse localmente, con sus conexiones de modelo y herramientas configuradas.
• En el primer ejemplo, una aplicación Python Microsoft Agent Framework y su entorno de Python seleccionado. Para otros SDK, use la configuración de Python o configuración de JavaScript y TypeScript.
• Para el seguimiento en la nube, un agente implementado y un recurso Application Insights conectado a su proyecto de Foundry, o permiso para conectar o crear uno.
• Para las consultas en la nube, se requiere el rol Lector de Log Analytics en el recurso de Application Insights conectado. Para las tablas protegidas, asigne también el rol Lector de datos de supervisión con privilegios. Consulte los requisitos previos del trazado de Foundry.

La recopilación local no requiere permisos de Application Insights ni de telemetría en la nube. Las llamadas de modelo y la ejecución de herramientas pueden seguir usando servicios remotos y incurrir en cargos.

Recopilar trazas locales

El recopilador local recibe telemetría mediante el protocolo OpenTelemetry (OTLP). No instrumenta una aplicación automáticamente. Su marco o una biblioteca de instrumentación debe crear spans y exportarlos al recopilador.

Configuración del SDK y del lenguaje

Los SDK con instrumentación integrada siguen necesitando un exportador. Otros SDK usan un paquete de instrumentación independiente.

"Ninguna guía de configuración del kit de herramientas dedicado" significa que no hay ninguna ruta de instalación específica del SDK aquí para ese idioma, no que el recopilador rechace su telemetría. El recopilador acepta datos OTLP. El instrumentador determina qué operaciones y detalles del mensaje se capturan.

En estos ejemplos se usan opciones de instrumentación seleccionadas, no una lista exhaustiva de bibliotecas compatibles. OpenLLMetry y la instrumentación de Traceloop son bibliotecas ajenas a Microsoft.

Configurar la instrumentación

Use este procedimiento con una aplicación existente de Python Agent Framework. Mantenga el agente y el recopilador en el mismo entorno local para este tutorial.

1. Seleccione Foundry Toolkit en la barra de actividades y, a continuación, Herramientas de desarrollador>>Monitor>>Seguimiento.

2. Seleccione Iniciar recopilador antes de ejecutar la aplicación.

3. En el entorno de Python de la aplicación, instale el exportador de gRPC si aún no está declarado en las dependencias:

   python -m pip install opentelemetry-exporter-otlp-proto-grpc
   

   Referencia: OpenTelemetry Python exportadores de OTLP.

4. Configure OpenTelemetry una vez al inicio de la aplicación, antes de construir o ejecutar el agente:

   import os
   
   os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "http://localhost:4317"
   os.environ["OTEL_EXPORTER_OTLP_PROTOCOL"] = "grpc"
   
   from agent_framework.observability import configure_otel_providers
   
   configure_otel_providers(enable_sensitive_data=False)
   

   Referencia: observabilidad de Agent Framework.

   Si su aplicación o biblioteca de hospedaje ya configura los proveedores de OpenTelemetry, configure sus exportadores existentes en lugar de agregar otra configuración de proveedor. Las variables OTEL_EXPORTER_OTLP_*_ENDPOINT específicas de la señal pueden anular el punto de conexión base. Compruebe si hay una configuración de seguimiento, registro o métrica existente que apunte a otro lugar.

5. Ejecute la aplicación con su punto de entrada normal y envíe una solicitud que active el agente. Deje que la solicitud finalice y dé tiempo al exportador para enviar telemetría antes de detener el proceso.

6. En Seguimiento, seleccione Actualizar y, a continuación, seleccione el nuevo seguimiento para inspeccionar sus spans.

Agent Framework instrumenta los clientes de modelo admitidos, los agentes y las operaciones del flujo de trabajo. Otros marcos pueden requerir una biblioteca de instrumentación. La compatibilidad de OTLP permite al recopilador recibir datos, mientras que los atributos emitidos y las convenciones semánticas de IA generativas determinan lo que muestra el visor.

Para otro SDK o lenguaje, use la configuración siguiente en lugar de la configuración de Agent Framework. Inicie el recopilador primero, configure la instrumentación antes de crear los clientes y, a continuación, ejecute la aplicación y actualice la lista de seguimientos.

Puntos de conexión del recopilador

Haga coincidir el protocolo del exportador con el punto de conexión del recopilador. El kit de herramientas escucha en localhost con estos valores predeterminados:

Algunos exportadores HTTP aceptan http://localhost:4318 y agregan la ruta de la señal por sí mismos. Siga la configuración del exportador en lugar de anexar la ruta de acceso dos veces. Algunas bibliotecas de instrumentación envían el contenido del mensaje como registros, por lo que exportar los spans por sí solos puede no proporcionar los detalles de entrada y salida.

Estos puertos no están relacionados con el servidor HTTP del agente y los puertos del depurador. En un entorno de desarrollo remoto o contenedor, localhost hace referencia a ese entorno. Establezca la conexión adecuada al recopilador en lugar de asumir que se refiere a su escritorio.

configuración del SDK de Python

En los ejemplos siguientes se supone que la aplicación ya tiene su SDK de modelo, credenciales y configuración del modelo. Instale las dependencias compartidas y el paquete adicional para el SDK desde la tabla siguiente:

python -m pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

Referencia: Sdk de OpenTelemetry Python, exportadores de OTLP.

Agregue esta configuración compartida una vez al inicio de la aplicación, seguida de la instrumentación de una fila de tabla. No lo combine con la configuración del proveedor de otra biblioteca.

import os

os.environ["TRACELOOP_TRACE_CONTENT"] = "false"
os.environ["OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"] = "false"
os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "false"

from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
    OTLPSpanExporter,
)

provider = TracerProvider(
    resource=Resource.create({"service.name": "my-agent"})
)
provider.add_span_processor(BatchSpanProcessor(
    OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")
))
trace.set_tracer_provider(provider)

Referencia: Procesadores TracerProvider y span, OTLPSpanExporter.

Instale el paquete en la fila que elija con python -m pip install <package>. Los ejemplos openAI, Anthropic, LangChain y agentes de OpenAI independientes usan instrumentación de OpenLLMetry que no es de Microsoft. Las versiones del SDK y las API de modelo pueden generar detalles diferentes.

Para Foundry Projects, siga las instrucciones de seguimiento del lado cliente y cree su cliente openAI después de la instrumentación. Esta guía difiere del SDK de agentes clásicos. No instrumente las mismas llamadas openAI con AIProjectInstrumentor y un instrumentor openAI independiente.

Para el SDK de OpenAI Agents, instale opentelemetry-instrumentation-openai-agents y agregue este código después de la configuración compartida:

from agents import set_trace_processors
from opentelemetry.instrumentation.openai_agents import OpenAIAgentsInstrumentor

set_trace_processors([])
OpenAIAgentsInstrumentor().instrument()

Referencia: Instrumentación de OpenAI Agents, Seguimiento de OpenAI Agents.

En este ejemplo se reemplazan los procesadores de seguimiento existentes antes de agregar el procesador OpenTelemetry. Sin ese reemplazo, el SDK también puede exportar seguimientos a su back-end predeterminado. Si necesita usar procesadores existentes, revise los destinos de seguimiento antes de cambiarlos. Mantenga habilitado el seguimiento del SDK para que el procesador OpenTelemetry reciba eventos.

Después de que una aplicación de corta duración finalice sus solicitudes, llame a provider.force_flush() antes de salir para enviar trazas almacenadas en búfer. Para obtener ayuda para adaptar estos fragmentos de código, use la herramienta Tracing Code Gen del kit de herramientas.

Exportar registros del registro de mensajes

Algunos instrumentadores emiten contenido de mensajes como registros de OpenTelemetry en lugar de atributos de span. Si decide registrar ese contenido en una prueba de desarrollo controlada, agregue esta configuración una vez junto con el proveedor de seguimiento de Python anterior:

from opentelemetry import _logs
from opentelemetry.sdk._logs import LoggerProvider
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter

logger_provider = LoggerProvider(resource=provider.resource)
logger_provider.add_log_record_processor(BatchLogRecordProcessor(
    OTLPLogExporter(endpoint="http://localhost:4318/v1/logs")
))
_logs.set_logger_provider(logger_provider)

Referencia: SDK de registro de OpenTelemetry Python, OTLPLogExporter.

Llame a logger_provider.force_flush() antes de salir de una aplicación de corta duración. Un exportador de registros no activa la captura de contenido por sí misma. Siga la configuración de contenido de su instrumentador y la guía de gestión de datos.

Configuración del SDK de JavaScript y TypeScript

Para aplicaciones Node.js, comparta un proveedor de trazas y registre la instrumentación de su SDK. En este ejemplo se usa CommonJS y la configuración del proveedor de JavaScript 2.x de OpenTelemetry. Las aplicaciones typeScript compiladas en CommonJS pueden usar el mismo orden de inicialización.

La aplicación ya debe tener su SDK de modelo, las credenciales y la configuración del modelo. Instale las dependencias compartidas y el instrumentor de OpenAI:

npm install @opentelemetry/api @opentelemetry/sdk-trace-node \
  @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-proto \
  @opentelemetry/instrumentation @traceloop/instrumentation-openai

Referencia: exportadores de JavaScript de OpenTelemetry, instrumentación de OpenAI.

Creación de tracing.cjs:

const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { BatchSpanProcessor } = require('@opentelemetry/sdk-trace-base');
const {
  OTLPTraceExporter
} = require('@opentelemetry/exporter-trace-otlp-proto');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { OpenAIInstrumentation } = require('@traceloop/instrumentation-openai');

const provider = new NodeTracerProvider({
  spanProcessors: [
    new BatchSpanProcessor(new OTLPTraceExporter({
      url: 'http://localhost:4318/v1/traces'
    }))
  ]
});
provider.register();

registerInstrumentations({
  instrumentations: [new OpenAIInstrumentation({ traceContent: false })]
});

module.exports = provider;

Referencia: NodeTracerProvider, instrumentación de OpenAI.

Cargue este archivo antes de importar o requerir el SDK del modelo. Por ejemplo, ejecute node --require ./tracing.cjs app.cjs para una aplicación CommonJS. Para otro SDK, reemplace el paquete de OpenAI, la importación y la entrada de configuración por la fila coincidente:

Los paquetes de Traceloop son instrumentación ajena a Microsoft. Para una aplicación de Foundry Projects, instrumente el cliente que realiza la solicitud del modelo. La instrumentación del SDK de Azure no reemplaza a la instrumentación de OpenAI para las llamadas realizadas a través de un cliente OpenAI.

Para los módulos ECMAScript nativos, siga la configuración de ESM de OpenTelemetry. La carga de la instrumentación después del SDK de destino puede dejar las llamadas sin instrumentar. Al cerrar, espere provider.shutdown() después de que las solicitudes se completen para exportar los spans en búfer.

Inspeccionar y administrar los seguimientos locales

Utiliza el árbol de spans para seguir la solicitud desde la orquestación de agentes hasta las operaciones del modelo y de las herramientas.

1. Seleccione un span lento o fallido.
2. Inspeccione su duración y estado.
3. Abra Input + Output para los mensajes registrados, cuando lo proporcione la instrumentación, o Metadatos para los atributos de span.

Los ejemplos mantienen desactivada la captura de contenido confidencial. Los datos de tiempo sin mensajes pueden ser el resultado esperado.

Para una prueba controlada de desarrollo con Agent Framework, establezca enable_sensitive_data=True en su configuración existente para registrar el contenido admitido de peticiones, respuestas y herramientas. Restáurelo a False cuando la prueba finalice. Otros instrumentadores tienen su propia configuración de contenido.

Los seguimientos recopilados persisten en una base de datos SQLite local llamada traces.db, en el subdirectorio tracing de .aitk dentro de su carpeta de inicio de usuario. Cerrar el visor no los elimina.

Seleccione Detener recopilador para detener la recopilación local. El agente y las llamadas a su modelo continúan ejecutándose. Para quitar registros locales, seleccione las trazas de la lista y seleccione Eliminar.

El almacenamiento local es independiente de Application Insights. La eliminación de seguimientos locales no quita la telemetría en la nube y borrar una conversación en Inspector no elimina ninguno de los dos almacenes.

Ver los seguimientos del agente hospedado

Después de la implementación, use seguimientos en la nube para investigar el agente que se ejecuta en Foundry en lugar del proceso local. El kit de herramientas consulta el recurso de Application Insights conectado del proyecto. No carga su base de datos de seguimiento local.

Confirme los requisitos previos de la nube antes de empezar. El acceso solo al agente no concede permiso para consultar la telemetría.

Conexión de Application Insights e inspección de una solicitud

Utilice la pestaña Seguimientos del agente para conectar Application Insights y encontrar una solicitud de agente implementado.

1. En la barra lateral Foundry Toolkit, abra Mis recursos>Agentes. Seleccione la pestaña Agente hospedado y, a continuación, seleccione el nombre del agente.

2. Seleccione Trazas. Si el proyecto no tiene ningún recurso conectado, seleccione Habilitar App Insights.

3. En Configuración de App Insights, seleccione un nombre de recurso de Application Insights existente. Como alternativa, elija crear un recurso y completar los campos de recurso y área de trabajo necesarios. Seleccione Enviar y espere la confirmación.

   Esto cambia la conexión de Application Insights compartida del proyecto, no una preferencia local del área de trabajo. La creación de recursos y la recopilación de telemetría pueden incurrir en cargos Azure. Confirme el proyecto y el recurso previstos antes de enviar.

4. Vuelva a Playground y envíe una solicitud de prueba al agente implementado.

5. Deje tiempo para la ingesta y, a continuación, vuelva a abrir Seguimientos. Utilice el intervalo de tiempo, Buscar por identificador de conversación, Estado o los filtros Duración para localizar la solicitud.

   

6. Seleccione una traza y, a continuación, un span, para revisar Metadatos y entrada y salida, cuando el contenido esté disponible.

Para inspeccionar las operaciones asociadas a una conversación, seleccione su identificador de conversación en la lista de seguimiento. La vista de conversación muestra un árbol de operaciones y metadatos.

La conexión de Application Insights habilita el seguimiento del lado del servidor de Foundry. La visibilidad de las llamadas de modelo, las llamadas a herramientas y el código personalizado también depende de la biblioteca de hospedaje y la instrumentación del marco. Consulte Configurar el seguimiento en Foundry para la recopilación del lado del servicio y la instrumentación adicional del cliente.

La consulta trace-detail de Toolkit cubre actualmente los últimos siete días. Se trata de una ventana de consulta, no una configuración de retención. Para los datos más antiguos, use el portal de Foundry o Azure Monitor, sujeto a la configuración de retención del área de trabajo conectada.

Datos, acceso, retención y costo

Decida dónde debe ir la telemetría antes de habilitar la captura de contenido o conectar un recurso en la nube. La misma solicitud puede generar spans locales, telemetría en la nube y datos enviados a proveedores de modelos o herramientas.

Utilice la orientación de seguimiento de Foundry para la seguridad y privacidad y la retención de datos y coste. Para la identidad de producción, el aislamiento de red y el acceso descendente, siga la seguridad del agente hospedado y la gestión de datos. No trate las credenciales locales como permisos del agente implementado.

Troubleshooting

Contenido relacionado

• Depurar agentes con Agent Inspector.
• Conceptos del seguimiento de agente.
• Configurar el seguimiento del lado del cliente.