Observability

Habilitar observabilidad (C#)

Para habilitar la observabilidad para el cliente de chat, debe compilar el cliente de chat de la siguiente manera:

// Using the Azure OpenAI client as an example
var instrumentedChatClient = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
    .GetChatClient(deploymentName)
    .AsIChatClient() // Converts a native OpenAI SDK ChatClient into a Microsoft.Extensions.AI.IChatClient
    .AsBuilder()
    .UseOpenTelemetry(sourceName: "MyApplication", configure: (cfg) => cfg.EnableSensitiveData = true)    // Enable OpenTelemetry instrumentation with sensitive data
    .Build();

Para habilitar la observabilidad para el agente, debe compilar el agente de la siguiente manera:

var agent = new ChatClientAgent(
    instrumentedChatClient,
    name: "OpenTelemetryDemoAgent",
    instructions: "You are a helpful assistant that provides concise and informative responses.",
    tools: [AIFunctionFactory.Create(GetWeatherAsync)]
).WithOpenTelemetry(sourceName: "MyApplication", enableSensitiveData: true);    // Enable OpenTelemetry instrumentation with sensitive data

Configuración

Ahora que el cliente de chat y el agente están instrumentados, puede configurar los exportadores de OpenTelemetry para enviar los datos de telemetría al back-end deseado.

Huellas

Para exportar seguimientos al back-end deseado, puede configurar el SDK de OpenTelemetry en el código de inicio de la aplicación. Por ejemplo, para exportar seguimientos a un recurso de Azure Monitor:

using Azure.Monitor.OpenTelemetry.Exporter;
using OpenTelemetry;
using OpenTelemetry.Trace;
using OpenTelemetry.Resources;
using System;

var SourceName = "MyApplication";

var applicationInsightsConnectionString = Environment.GetEnvironmentVariable("APPLICATION_INSIGHTS_CONNECTION_STRING")
    ?? throw new InvalidOperationException("APPLICATION_INSIGHTS_CONNECTION_STRING is not set.");

var resourceBuilder = ResourceBuilder
    .CreateDefault()
    .AddService(ServiceName);

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource(SourceName)
    .AddSource("*Microsoft.Extensions.AI") // Listen to the Experimental.Microsoft.Extensions.AI source for chat client telemetry
    .AddSource("*Microsoft.Extensions.Agents*") // Listen to the Experimental.Microsoft.Extensions.Agents source for agent telemetry
    .AddAzureMonitorTraceExporter(options => options.ConnectionString = applicationInsightsConnectionString)
    .Build();

Metrics

Del mismo modo, para exportar métricas al back-end deseado, puede configurar el SDK de OpenTelemetry en el código de inicio de la aplicación. Por ejemplo, para exportar métricas a un recurso de Azure Monitor:

using Azure.Monitor.OpenTelemetry.Exporter;
using OpenTelemetry;
using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using System;

var applicationInsightsConnectionString = Environment.GetEnvironmentVariable("APPLICATION_INSIGHTS_CONNECTION_STRING")
    ?? throw new InvalidOperationException("APPLICATION_INSIGHTS_CONNECTION_STRING is not set.");

var resourceBuilder = ResourceBuilder
    .CreateDefault()
    .AddService(ServiceName);

using var meterProvider = Sdk.CreateMeterProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource(SourceName)
    .AddMeter("*Microsoft.Agents.AI") // Agent Framework metrics
    .AddAzureMonitorMetricExporter(options => options.ConnectionString = applicationInsightsConnectionString)
    .Build();

Registros

Los registros se capturan a través del marco de registro que está usando, por ejemplo Microsoft.Extensions.Logging, . Para exportar registros a un recurso de Azure Monitor, puede configurar el proveedor de registro en el código de inicio de la aplicación:

using Azure.Monitor.OpenTelemetry.Exporter;
using Microsoft.Extensions.Logging;

var applicationInsightsConnectionString = Environment.GetEnvironmentVariable("APPLICATION_INSIGHTS_CONNECTION_STRING")
    ?? throw new InvalidOperationException("APPLICATION_INSIGHTS_CONNECTION_STRING is not set.");

using var loggerFactory = LoggerFactory.Create(builder =>
{
    // Add OpenTelemetry as a logging provider
    builder.AddOpenTelemetry(options =>
    {
        options.SetResourceBuilder(resourceBuilder);
        options.AddAzureMonitorLogExporter(options => options.ConnectionString = applicationInsightsConnectionString);
        // Format log messages. This is default to false.
        options.IncludeFormattedMessage = true;
        options.IncludeScopes = true;
    })
    .SetMinimumLevel(LogLevel.Debug);
});

// Create a logger instance for your application
var logger = loggerFactory.CreateLogger<Program>();

Panel de Aspire

Considere la posibilidad de usar el panel de Aspire como una manera rápida de visualizar los seguimientos y las métricas durante el desarrollo. Para más información, consulte la documentación de Aspire Dashboard. El panel de Aspire recibe datos a través de un recopilador de OpenTelemetry, que puede agregar al proveedor de seguimiento de la siguiente manera:

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource(SourceName)
    .AddSource("*Microsoft.Extensions.AI") // Listen to the Experimental.Microsoft.Extensions.AI source for chat client telemetry
    .AddSource("*Microsoft.Extensions.Agents*") // Listen to the Experimental.Microsoft.Extensions.Agents source for agent telemetry
    .AddOtlpExporter(options => options.Endpoint = new Uri("http://localhost:4317"))
    .Build();

Cómo empezar

Consulte un ejemplo completo de un agente con OpenTelemetry habilitado en el repositorio de Agent Framework.

Dependencias

Paquetes incluidos

Para habilitar la observabilidad en la aplicación de Python, los siguientes paquetes de OpenTelemetry se instalan de forma predeterminada:

• opentelemetry-api
• opentelemetry-sdk
• opentelemetry-semantic-conventions-ai

Exportadores

De forma predeterminada , no instalamos exportadores para evitar dependencias innecesarias y posibles problemas con la instrumentación automática. Hay una gran variedad de exportadores disponibles para diferentes back-end, por lo que puede elegir los que mejor se adapten a sus necesidades.

Algunos exportadores comunes que puede querer instalar en función de sus necesidades:

• Para obtener compatibilidad con el protocolo gRPC: instalar opentelemetry-exporter-otlp-proto-grpc
• Para obtener compatibilidad con el protocolo HTTP: instalar opentelemetry-exporter-otlp-proto-http
• Para Azure Application Insights: instalación azure-monitor-opentelemetry

Use el Registro de OpenTelemetry para buscar más exportadores y paquetes de instrumentación.

Habilitación de la observabilidad (Python)

Cinco patrones para configurar la observabilidad

Hemos identificado varias maneras de configurar la observabilidad en la aplicación, en función de sus necesidades:

1. Variables de entorno OpenTelemetry estándar (recomendado)

El enfoque más sencillo: configurar todo a través de variables de entorno:

from agent_framework.observability import configure_otel_providers

# Reads OTEL_EXPORTER_OTLP_* environment variables automatically
configure_otel_providers()

O bien, si solo desea exportadores de consola:

from agent_framework.observability import configure_otel_providers

configure_otel_providers(enable_console_exporters=True)

2. Exportadores personalizados

Para obtener más control sobre los exportadores, créelos usted mismo y páselos a configure_otel_providers():

from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.exporter.otlp.proto.grpc._log_exporter import OTLPLogExporter
from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter
from agent_framework.observability import configure_otel_providers

# Create custom exporters with specific configuration
exporters = [
    OTLPSpanExporter(endpoint="http://localhost:4317", compression=Compression.Gzip),
    OTLPLogExporter(endpoint="http://localhost:4317"),
    OTLPMetricExporter(endpoint="http://localhost:4317"),
]

# These will be added alongside any exporters from environment variables
configure_otel_providers(exporters=exporters, enable_sensitive_data=True)

3. Configuración de terceros

Muchos paquetes openTelemetry de terceros tienen sus propios métodos de configuración. Puede usar primero esos métodos y, a continuación, llamar enable_instrumentation() a para activar las rutas de código de instrumentación de Agent Framework:

from azure.monitor.opentelemetry import configure_azure_monitor
from agent_framework.observability import create_resource, enable_instrumentation

# Configure Azure Monitor first
configure_azure_monitor(
    connection_string="InstrumentationKey=...",
    resource=create_resource(),  # Uses OTEL_SERVICE_NAME, etc.
    enable_live_metrics=True,
)

# Then activate Agent Framework's telemetry code paths
# This is optional if ENABLE_INSTRUMENTATION and/or ENABLE_SENSITIVE_DATA are set in env vars
enable_instrumentation(enable_sensitive_data=False)

Para Langfuse:

from agent_framework.observability import enable_instrumentation
from langfuse import get_client

langfuse = get_client()

# Verify connection
if langfuse.auth_check():
    print("Langfuse client is authenticated and ready!")

# Then activate Agent Framework's telemetry code paths
enable_instrumentation(enable_sensitive_data=False)

4. Configuración manual

Para un control completo, puede configurar manualmente exportadores, proveedores e instrumentación. Use la función create_resource() auxiliar para crear un recurso con el nombre de servicio y la versión adecuados. Consulte la documentación de Python de OpenTelemetry para obtener instrucciones detalladas sobre la instrumentación manual.

5. Instrumentación automática (código cero)

Use la herramienta de la CLI de OpenTelemetry para instrumentar automáticamente la aplicación sin cambios en el código:

opentelemetry-instrument \
    --traces_exporter console,otlp \
    --metrics_exporter console \
    --service_name your-service-name \
    --exporter_otlp_endpoint 0.0.0.0:4317 \
    python agent_framework_app.py

Consulte la documentación de Python de código cero de OpenTelemetry para obtener más información.

Uso de seguimientos y medidores

Una vez configurada la observabilidad, puede crear intervalos o métricas personalizados:

from agent_framework.observability import get_tracer, get_meter

tracer = get_tracer()
meter = get_meter()
with tracer.start_as_current_span("my_custom_span"):
    # do something
    pass
counter = meter.create_counter("my_custom_counter")
counter.add(1, {"key": "value"})

Estos son contenedores de la API de OpenTelemetry que devuelven un seguimiento o medidor del proveedor global, con agent_framework establecido como nombre de la biblioteca de instrumentación de forma predeterminada.

Variables de entorno

Las siguientes variables de entorno controlan la observabilidad de Agent Framework:

• ENABLE_INSTRUMENTATION - El valor predeterminado es false, establecido en true para habilitar la instrumentación de OpenTelemetry.
• ENABLE_SENSITIVE_DATA - El valor predeterminado es false, establecido en true para habilitar el registro de datos confidenciales (avisos, respuestas, argumentos de llamada de función y resultados). Tenga cuidado con esta configuración, ya que puede exponer datos confidenciales.
• ENABLE_CONSOLE_EXPORTERS - El valor predeterminado es false, establecido en true para habilitar la salida de la consola para la telemetría.
• VS_CODE_EXTENSION_PORT - Puerto para AI Toolkit o integración de la extensión de VS Code de Azure AI Foundry.

Variables de entorno de OpenTelemetry estándar

La configure_otel_providers() función lee automáticamente las variables de entorno estándar de OpenTelemetry:

Configuración de OTLP (para Aspire Dashboard, Jaeger, etc.):

• OTEL_EXPORTER_OTLP_ENDPOINT - Punto de conexión base para todas las señales (por ejemplo, http://localhost:4317)
• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT - Punto de conexión específico de seguimiento (invalida la base)
• OTEL_EXPORTER_OTLP_METRICS_ENDPOINT - Punto de conexión específico de métricas (invalida la base)
• OTEL_EXPORTER_OTLP_LOGS_ENDPOINT - Punto de conexión específico de los registros (invalida la base)
• OTEL_EXPORTER_OTLP_PROTOCOL - Protocolo para usar (grpc o http, valor predeterminado: grpc)
• OTEL_EXPORTER_OTLP_HEADERS - Encabezados para todas las señales (por ejemplo, key1=value1,key2=value2)

Identificación del servicio:

• OTEL_SERVICE_NAME - Nombre del servicio (valor predeterminado: agent_framework)
• OTEL_SERVICE_VERSION - Versión del servicio (valor predeterminado: versión del paquete)
• OTEL_RESOURCE_ATTRIBUTES - Atributos de recursos adicionales

Consulte la especificación de OpenTelemetry para obtener más detalles.

Configuración de Microsoft Foundry

Microsoft Foundry tiene compatibilidad integrada con el seguimiento con la visualización de los intervalos.

Asegúrese de que ha configurado Foundry con una instancia de Azure Monitor, consulte los detalles.

Instala el paquete azure-monitor-opentelemetry:

pip install azure-monitor-opentelemetry

Configure la observabilidad directamente desde AzureAIClient:

En el caso de los proyectos de Azure AI Foundry, puede configurar la observabilidad directamente desde :AzureAIClient

from agent_framework.azure import AzureAIClient
from azure.ai.projects.aio import AIProjectClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with (
        AzureCliCredential() as credential,
        AIProjectClient(endpoint="https://<your-project>.foundry.azure.com", credential=credential) as project_client,
        AzureAIClient(project_client=project_client) as client,
    ):
        # Automatically configures Azure Monitor with connection string from project
        await client.configure_azure_monitor(enable_live_metrics=True)

Configure Azure Monitor y, opcionalmente, habilite la instrumentación:

Para proyectos que no son de Azure AI con Application Insights, asegúrese de configurar un agente personalizado en Foundry, consulte los detalles.

A continuación, ejecute el agente con el mismo identificador de agente de OpenTelemetry que se registró en Foundry y configure Azure Monitor de la siguiente manera:

from azure.monitor.opentelemetry import configure_azure_monitor
from agent_framework.observability import create_resource, enable_instrumentation

configure_azure_monitor(
    connection_string="InstrumentationKey=...",
    resource=create_resource(),
    enable_live_metrics=True,
)
# optional if you do not have ENABLE_INSTRUMENTATION in env vars
enable_instrumentation()

# Create your agent with the same OpenTelemetry agent ID as registered in Foundry
agent = ChatAgent(
    chat_client=...,
    name="My Agent",
    instructions="You are a helpful assistant.",
    id="<OpenTelemetry agent ID>"
)
# use the agent as normal

Panel de Aspire

Para el desarrollo local sin configuración de Azure, puede usar el panel Aspire que se ejecuta localmente a través de Docker y proporciona una excelente experiencia de visualización de telemetría.

Configuración de Aspire Dashboard con Docker

# Pull and run the Aspire Dashboard container
docker run --rm -it -d \
    -p 18888:18888 \
    -p 4317:18889 \
    --name aspire-dashboard \
    mcr.microsoft.com/dotnet/aspire-dashboard:latest

Esto iniciará el panel con:

• Interfaz de usuario web: disponible en http://localhost:18888
• Punto de conexión de OTLP: disponible en http://localhost:4317 para que las aplicaciones envíen datos de telemetría

Configuración de la aplicación

Establezca estas variables de entorno:

ENABLE_INSTRUMENTATION=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

También puede incluirlos en el .env archivo y ejecutar el ejemplo.

Una vez que el ejemplo termine de ejecutarse, vaya a http://localhost:18888 en un explorador web para ver los datos de telemetría. Siga la guía de exploración del panel aspire para autenticarse en el panel y empezar a explorar los seguimientos, los registros y las métricas.

Intervalos y métricas

Una vez configurado todo, comenzará a ver intervalos y métricas que se crean automáticamente, los intervalos son:

• invoke_agent <agent_name>: este es el intervalo de nivel superior para cada invocación de agente, contendrá todos los demás intervalos como elementos secundarios.
• chat <model_name>: este intervalo se crea cuando el agente llama al modelo de chat subyacente, contendrá el mensaje y la respuesta como atributos, si enable_sensitive_data se establece Trueen .
• execute_tool <function_name>: este intervalo se crea cuando el agente llama a una herramienta de función, contendrá los argumentos de función y el resultado como atributos, si enable_sensitive_data se establece Trueen .

Las métricas que se crean son:

• Para el cliente de chat y chat las operaciones:

  • gen_ai.client.operation.duration (histograma): esta métrica mide la duración de cada operación, en segundos.
  • gen_ai.client.token.usage (histograma): esta métrica mide el uso del token, en número de tokens.

• Para la invocación de funciones durante las execute_tool operaciones:

  • agent_framework.function.invocation.duration (histograma): esta métrica mide la duración de cada ejecución de función, en segundos.

Salida de seguimiento de ejemplo

Al ejecutar un agente con observabilidad habilitada, verá datos de seguimiento similares a la salida de la consola siguiente:

{
    "name": "invoke_agent Joker",
    "context": {
        "trace_id": "0xf2258b51421fe9cf4c0bd428c87b1ae4",
        "span_id": "0x2cad6fc139dcf01d",
        "trace_state": "[]"
    },
    "kind": "SpanKind.CLIENT",
    "parent_id": null,
    "start_time": "2025-09-25T11:00:48.663688Z",
    "end_time": "2025-09-25T11:00:57.271389Z",
    "status": {
        "status_code": "UNSET"
    },
    "attributes": {
        "gen_ai.operation.name": "invoke_agent",
        "gen_ai.system": "openai",
        "gen_ai.agent.id": "Joker",
        "gen_ai.agent.name": "Joker",
        "gen_ai.request.instructions": "You are good at telling jokes.",
        "gen_ai.response.id": "chatcmpl-CH6fgKwMRGDtGNO3H88gA3AG2o7c5",
        "gen_ai.usage.input_tokens": 26,
        "gen_ai.usage.output_tokens": 29
    }
}

Este seguimiento muestra:

• Identificadores de seguimiento y intervalo: para correlacionar operaciones relacionadas
• Información de tiempo: cuándo se inició y finalizó la operación
• Metadatos del agente: id. de agente, nombre e instrucciones
• Información del modelo: el sistema de IA usado (OpenAI) y el identificador de respuesta
• Uso de tokens: recuentos de tokens de entrada y salida para el seguimiento de costos

Samples

Tenemos una serie de ejemplos en nuestro repositorio que muestran estas funcionalidades, consulte la carpeta de ejemplos de observabilidad en Github. Esto incluye ejemplos para usar también telemetría de código cero.