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

Use Microsoft Foundry Toolkit para Visual Studio Code para recopilar 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:

Approach Úselo para Datos y responsabilidades
Inspector del agente Envíe una solicitud local, inspeccione los eventos de respuesta en directo y de herramientas, o pause el código en un punto de interrupción. El servidor proporciona eventos de protocolo y diagnósticos de desarrollo. Este enfoque no requiere el recopilador de OTLP ni crea el historial de trazas en la nube.
Seguimiento local Compara los tramos de modelos, herramientas y agentes registrados durante el desarrollo. La aplicación exporta la telemetría al recopilador local de Toolkit. Usted configura la instrumentación y administra los datos locales almacenados.
Seguimiento de agentes alojados Investigue las solicitudes gestionadas por un agente implementado en Foundry. Los seguimientos residen en el recurso de Application Insights conectado del proyecto. El acceso, la retención y los cargos siguen la configuración de recursos de Azure.

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

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. El marco o una biblioteca de instrumentación deben crear spans y exportarlos al collector.

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.

SDK o framework Python JavaScript y TypeScript (Node.js)
Framework del Agente de Microsoft Instrumentación de OpenTelemetry integrada. No hay una guía específica para la configuración de Toolkit.
SDK de inferencia de ia de Azure (versión preliminar) Instrumentador de SDK de Azure. instrumentación del SDK de Azure.
SDK de proyectos de Foundry Instrumentador del cliente (versión preliminar). Instrumente el cliente openAI o SDK de Azure subyacente.
SDK de agentes clásicos de Foundry Instrumentador del SDK de Azure. No hay ninguna guía específica de configuración de Toolkit.
Anthropic instrumentador de OpenLLMetry. Instrumentación de Traceloop.
Google GenAI (Gemini) Instrumentador de OpenTelemetry de Google GenAI. No hay una guía específica para configurar Toolkit.
LangChain Instrumentador de OpenLLMetry. Instrumentación de Traceloop.
SDK de OpenAI, incluidos los clientes de OpenAI de Azure instrumentador de OpenLLMetry. Instrumentación de Traceloop.
SDK de agentes de OpenAI OpenLLMetry trace processor. No hay una guía específica para la configuración de Toolkit.

"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 colector acepta datos de 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. La instrumentación OpenLLMetry y Traceloop no es una biblioteca de 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 para desarrolladores>Monitor>Seguimiento.

  2. Seleccione Iniciar el 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 la aplicación o la biblioteca de alojamiento ya configuran proveedores de OpenTelemetry, configure sus exportadores existentes en lugar de agregar otra configuración de proveedor. Las variables específicas OTEL_EXPORTER_OTLP_*_ENDPOINT de 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 Rastreo, seleccione Actualizar y, a continuación, seleccione el nuevo rastreo para inspeccionar sus tramos.

Agent Framework proporciona instrumentación para clientes de modelos, agentes y operaciones de 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 primero el recopilador, configure la instrumentación antes de crear clientes y, a continuación, ejecute la aplicación y actualice la lista de trazas.

Captura de pantalla del recopilador de OTLP local en ejecución con puntos de conexión gRPC y HTTP y una lista de seguimiento rellenada.

Endpoints del colector

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:

Exportador Punto final
OTLP gRPC http://localhost:4317
Exportador de seguimiento HTTP de OTLP http://localhost:4318/v1/traces
Exportador de registros HTTP de OTLP http://localhost:4318/v1/logs

Algunos exportadores HTTP aceptan http://localhost:4318 y anexan la ruta de acceso de señal. Siga la configuración del exportador en lugar de anexar la ruta de acceso dos veces. Algunas bibliotecas de instrumentación envían contenido de mensajes como registros de registro, por lo que exportar tramos por sí solos podría no proporcionar 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 colector en lugar de asumir que hace referencia al 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 tomada de una fila de la 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 línea elegida 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.

SDK Paquete adicional Instrumentación después de la configuración compartida
OpenAI, incluidos los clientes de OpenAI de Azure opentelemetry-instrumentation-openai from opentelemetry.instrumentation.openai import OpenAIInstrumentor
OpenAIInstrumentor().instrument()
Anthropic opentelemetry-instrumentation-anthropic from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor
AnthropicInstrumentor().instrument()
LangChain opentelemetry-instrumentation-langchain from opentelemetry.instrumentation.langchain import LangchainInstrumentor
LangchainInstrumentor().instrument()
Google GenAI opentelemetry-instrumentation-google-genai os.environ["OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"] = "NO_CONTENT"
from opentelemetry.instrumentation.google_genai import GoogleGenAiSdkInstrumentor
GoogleGenAiSdkInstrumentor().instrument()
Seguimiento del cliente de Projects Foundry (versión preliminar) azure-core-tracing-opentelemetry, junto con azure-ai-projects os.environ["AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING"] = "true"
from azure.ai.projects.telemetry import AIProjectInstrumentor
AIProjectInstrumentor().instrument(enable_content_recording=False)
SDK de agentes clásicos de Foundry azure-core-tracing-opentelemetry, junto con azure-ai-agents os.environ["AZURE_SDK_TRACING_IMPLEMENTATION"] = "opentelemetry"
from azure.ai.agents.telemetry import AIAgentsInstrumentor
AIAgentsInstrumentor().instrument()
SDK de inferencia de ia de Azure (versión preliminar) azure-core-tracing-opentelemetry, junto con azure-ai-inference os.environ["AZURE_SDK_TRACING_IMPLEMENTATION"] = "opentelemetry"
from azure.ai.inference.tracing import AIInferenceInstrumentor
AIInferenceInstrumentor().instrument()

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 agentes de OpenAI, trazado de agentes de OpenAI.

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 logging 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 del instrumentor y las directrices sobre el manejo 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:

SDK Paquete de instrumentación Importación y entrada de inscripción
OpenAI, incluidos los clientes de OpenAI de Azure @traceloop/instrumentation-openai const { OpenAIInstrumentation } = require('@traceloop/instrumentation-openai');
new OpenAIInstrumentation({ traceContent: false })
Anthropic @traceloop/instrumentation-anthropic const { AnthropicInstrumentation } = require('@traceloop/instrumentation-anthropic');
new AnthropicInstrumentation({ traceContent: false })
LangChain @traceloop/instrumentation-langchain const { LangChainInstrumentation } = require('@traceloop/instrumentation-langchain');
new LangChainInstrumentation({ traceContent: false })
Operaciones de SDK de Azure, incluida Azure AI Inference @azure/opentelemetry-instrumentation-azure-sdk const { createAzureSdkInstrumentation } = require('@azure/opentelemetry-instrumentation-azure-sdk');
createAzureSdkInstrumentation()

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

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

Importante

Estos ejemplos desactivan la captura de contenido de mensajes para los instrumentors genAI enumerados. Esta no es una garantía general de supresión. Revise otros exportadores, el registro del SDK, los atributos de span y la instrumentación personalizada antes de compartir datos. Consulte la documentación del instrumentor vinculado para ver los paquetes y las API compatibles.

Inspeccionar y administrar 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 de desarrollo controlada de Agent Framework, establezca enable_sensitive_data=True en su configuración existente para registrar contenido de prompt, respuesta y herramienta admitido. Restáuralo a False cuando se complete la prueba. Otros instrumentadores tienen su propia configuración de contenido.

Caution

La grabación de contenido puede capturar datos personales, secretos, argumentos de herramienta y resultados. Utilice datos de prueba no confidenciales y minimice o redacte el contenido antes de que entre en la telemetría. No active la grabación de contenido de producción únicamente para rellenar una vista de entrada y salida vacía.

Captura de pantalla de un árbol de spans de flujo de trabajo local y la pestaña Metadatos del span seleccionado, con identificadores de solicitud, trace y conversación censurados.

Los seguimientos recopilados se almacenan en una base de datos SQLite local denominada traces.db, en el subdirectorio .aitk dentro de tu carpeta personal tracing. 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 las trazas 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 sube la 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

Use la pestaña Traces del agente para conectar Application Insights y buscar una solicitud del 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 compartida de Application Insights del proyecto, no una preferencia de espacio de trabajo local. La creación de recursos y la recopilación de telemetría pueden incurrir en cargos Azure. Confirme el proyecto y el recurso seleccionados antes de enviarlos.

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

  5. Espere un momento para la ingesta y, a continuación, vuelva a abrir Trazas. Utilice el intervalo de tiempo, Buscar por identificador de conversación, Estado o los filtros Duración para buscar la solicitud.

    Captura de pantalla de los filtros de seguimiento del agente hospedado y las solicitudes completadas, con identificadores de recursos y solicitudes censurados.

  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.

Captura de pantalla de una conversación de agente hospedado con operaciones y metadatos de agente, modelo y herramientas, con identificadores de recurso y conversación censurados.

Conectar Application Insights habilita el seguimiento 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 de cliente adicional.

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.

Origen de datos Responsibilities
Trazas locales Proteja el acceso a la base de datos local y a los datos copiados. Detener el recopilador no detiene otros exportadores configurados en la aplicación.
Trazas en la nube Application Insights y Log Analytics controlan los cargos de acceso, retención y telemetría. Los filtros de Toolkit no cambian esas políticas.
Llamadas a modelos y herramientas La colección local no impide que las solicitudes salgan del equipo. Revise el tratamiento de datos de todos los servicios conectados, incluidas las herramientas que no son de Microsoft.

Use la guía de seguimiento de Foundry para la seguridad y privacidad y la retención de datos y el costo. Para la identidad de producción, el aislamiento de red y el acceso a sistemas posteriores, siga la seguridad y el control de datos del agente alojado. No trate las credenciales locales como permisos del agente implementado.

Troubleshooting

Problema Elementos que se deben comprobar
El seguimiento no está disponible en la barra lateral. Confirme que la extensión actual está instalada y habilitada en el entorno donde se ejecuta. El seguimiento local requiere que se cargue su componente nativo de SQLite.
El colector no se inicia. Compruebe si hay otro proceso que esté usando el puerto 4317 o 4318 y revise la salida del kit de herramientas. Evite los colectores competidores en los mismos puertos.
Una solicitud local se realiza correctamente, pero no aparece ninguna traza. Confirme que la instrumentación se ejecuta antes de la solicitud, el recopilador se está ejecutando y el exportador usa el protocolo y el punto de conexión correctos. Compruebe las invalidaciones de punto de conexión, los errores del exportador y la telemetría almacenada en búfer y, a continuación, seleccione Actualizar.
Los spans aparecen sin mensajes. Compruebe la configuración de grabación de contenido y los atributos admitidos. Algunas bibliotecas también requieren un exportador de registros. Que falte contenido no significa necesariamente que la recopilación haya fallado.
Las trazas en la nube están vacías. Confirme la conexión del proyecto y Application Insights, genere tráfico nuevo, expanda el intervalo de tiempo y permita el retraso de ingesta.
Las consultas en la nube producen un error de autorización. Compruebe el acceso de lectura a Application Insights y Log Analytics, incluidas las tablas protegidas, mediante los requisitos previos del servicio.
Un seguimiento anterior no tiene detalles en el kit de herramientas. La consulta de detalles abarca siete días. Consulte los registros retenidos más antiguos en Foundry o Azure Monitor.

Contenido relacionado

  • Se actualizó por última vez el