Observability

Habilitar Observabilidade (C#)

Para habilitar a observabilidade para seu cliente de chat, você precisa criar o cliente de chat da seguinte maneira:

// 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 a observabilidade do agente, você precisa criar o agente da seguinte maneira:

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

Configuração

Agora que seu cliente de chat e agente estão instrumentados, você pode configurar os exportadores OpenTelemetry para enviar os dados de telemetria para o back-end desejado.

Vestígios

Para exportar rastreamentos para o back-end desejado, você pode configurar o SDK do OpenTelemetry no código de inicialização do aplicativo. Por exemplo, para exportar rastreamentos para um recurso do 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();

Métricas

Da mesma forma, para exportar métricas para o back-end desejado, você pode configurar o SDK do OpenTelemetry no código de inicialização do aplicativo. Por exemplo, para exportar métricas para um recurso do 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();

Logs

Os logs são capturados por meio da estrutura de log que você está usando, por exemplo Microsoft.Extensions.Logging. Para exportar logs para um recurso do Azure Monitor, você pode configurar o provedor de log no código de inicialização do aplicativo:

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>();

Painel do Aspire

Considere usar o Painel do Aspire como uma maneira rápida de visualizar seus rastreamentos e métricas durante o desenvolvimento. Para saber mais, confira a documentação do Painel do Aspire. O Painel do Aspire recebe dados por meio de um Coletor OpenTelemetry, que você pode adicionar ao seu provedor de rastreamento da seguinte maneira:

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();

Como começar

Veja um exemplo completo de um agente com OpenTelemetry habilitado no repositório do Agent Framework.

Dependências

Pacotes incluídos

Para habilitar a observabilidade em seu aplicativo Python, os seguintes pacotes OpenTelemetry são instalados por padrão:

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

Exportadores

Não instalamos exportadores por padrão para evitar dependências desnecessárias e possíveis problemas com a instrumentação automática. Há uma grande variedade de exportadores disponíveis para back-ends diferentes, para que você possa escolher os que melhor atendem às suas necessidades.

Alguns exportadores comuns que talvez você queira instalar com base em suas necessidades:

• Para obter suporte ao protocolo gRPC: instalar opentelemetry-exporter-otlp-proto-grpc
• Para suporte ao protocolo HTTP: instalar opentelemetry-exporter-otlp-proto-http
• Para o Azure Application Insights: instalar azure-monitor-opentelemetry

Use o Registro OpenTelemetry para encontrar mais exportadores e pacotes de instrumentação.

Habilitar a Observabilidade (Python)

Cinco padrões para configurar a observabilidade

Identificamos várias maneiras de configurar a observabilidade em seu aplicativo, dependendo de suas necessidades:

1. Variáveis de ambiente OpenTelemetry Padrão (Recomendado)

A abordagem mais simples – configurar tudo por meio de variáveis de ambiente:

from agent_framework.observability import configure_otel_providers

# Reads OTEL_EXPORTER_OTLP_* environment variables automatically
configure_otel_providers()

Ou se você quiser apenas exportadores de console:

from agent_framework.observability import configure_otel_providers

configure_otel_providers(enable_console_exporters=True)

2. Exportadores Personalizados

Para obter mais controle sobre os exportadores, crie-os por conta própria e passe-os para 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. Configuração de terceiros

Muitos pacotes OpenTelemetry de terceiros têm seus próprios métodos de instalação. Você pode usar esses métodos primeiro e, em seguida, chamar enable_instrumentation() para ativar caminhos de código de instrumentação do 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. Configuração manual

Para controle completo, você pode configurar manualmente exportadores, provedores e instrumentação. Use a função create_resource() auxiliar para criar um recurso com o nome e a versão de serviço apropriados. Consulte a documentação do OpenTelemetry Python para obter diretrizes detalhadas sobre instrumentação manual.

5. Instrumentação automática (código zero)

Use a ferramenta CLI do OpenTelemetry para instrumentar automaticamente seu aplicativo sem alterações de 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 a documentação do Python opentelemetry de código zero para obter mais informações.

Usando rastreamentos e medidores

Depois que a observabilidade estiver configurada, você poderá criar intervalos ou métricas personalizadas:

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"})

Estes são wrappers da API OpenTelemetry que retornam um rastreador ou medidor do provedor global, com agent_framework definido como o nome da biblioteca de instrumentação por padrão.

Variáveis de ambiente

As seguintes variáveis de ambiente controlam a observabilidade do Agent Framework:

• ENABLE_INSTRUMENTATION – O padrão é false, definido para habilitar a true instrumentação OpenTelemetry.
• ENABLE_SENSITIVE_DATA – O padrão é false, definido para habilitar o true registro em log de dados confidenciais (prompts, respostas, argumentos de chamada de função e resultados). Tenha cuidado com essa configuração, pois ela pode expor dados confidenciais.
• ENABLE_CONSOLE_EXPORTERS – O padrão é false, definido para habilitar a true saída do console para telemetria.
• VS_CODE_EXTENSION_PORT – Porta para kit de ferramentas de IA ou integração de extensão do VS Code do Azure AI Foundry.

Variáveis de ambiente OpenTelemetry Padrão

A configure_otel_providers() função lê automaticamente variáveis de ambiente OpenTelemetry padrão:

Configuração OTLP (para o Aspire Dashboard, Jaeger etc.):

• OTEL_EXPORTER_OTLP_ENDPOINT - Ponto de extremidade base para todos os sinais (por exemplo, http://localhost:4317)
• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT - Ponto de extremidade específico de rastreamentos (substitui a base)
• OTEL_EXPORTER_OTLP_METRICS_ENDPOINT - Ponto de extremidade específico de métricas (substitui base)
• OTEL_EXPORTER_OTLP_LOGS_ENDPOINT - Ponto de extremidade específico de logs (substitui base)
• OTEL_EXPORTER_OTLP_PROTOCOL – Protocolo a ser usado (grpc ou http, padrão: grpc)
• OTEL_EXPORTER_OTLP_HEADERS - Cabeçalhos para todos os sinais (por exemplo, key1=value1,key2=value2)

Identificação de serviço:

• OTEL_SERVICE_NAME - Nome do serviço (padrão: agent_framework)
• OTEL_SERVICE_VERSION – Versão do serviço (padrão: versão do pacote)
• OTEL_RESOURCE_ATTRIBUTES - Atributos de recursos adicionais

Consulte a especificação OpenTelemetry para obter mais detalhes.

Configuração do Microsoft Foundry

O Microsoft Foundry tem suporte interno para rastreamento com visualização para seus intervalos.

Verifique se o Foundry está configurado com uma instância do Azure Monitor, confira detalhes

Instalar o pacote azure-monitor-opentelemetry:

pip install azure-monitor-opentelemetry

Configurar a observabilidade diretamente do AzureAIClient:

Para projetos do Azure AI Foundry, você pode configurar a observabilidade diretamente do 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 o Azure Monitor e, opcionalmente, habilite a instrumentação:

Para projetos que não são de IA do Azure com o Application Insights, verifique se você configurou um agente personalizado no Foundry, confira os detalhes.

Em seguida, execute seu agente com a mesma ID do agente OpenTelemetry registrada no Foundry e configure o azure Monitor da seguinte maneira:

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

Painel do Aspire

Para desenvolvimento local sem a instalação do Azure, você pode usar o Aspire Dashboard , que é executado localmente por meio do Docker e fornece uma excelente experiência de exibição de telemetria.

Configurando o Painel do Aspire com o 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

Isso iniciará o painel com:

• Interface do usuário da Web: disponível em http://localhost:18888
• Ponto de extremidade OTLP: disponível http://localhost:4317 para seus aplicativos enviarem dados de telemetria

Configurando seu aplicativo

Defina as seguintes variáveis de ambiente:

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

Ou inclua-os no .env arquivo e execute o exemplo.

Depois que o exemplo terminar de ser executado, navegue até http://localhost:18888 um navegador da Web para ver os dados de telemetria. Siga o guia de exploração do Aspire Dashboard para autenticar no painel e começar a explorar seus rastreamentos, logs e métricas.

Intervalos e métricas

Depois que tudo estiver configurado, você começará a ver intervalos e métricas sendo criados automaticamente para você, os intervalos são:

• invoke_agent <agent_name>: este é o intervalo de nível superior para cada invocação de agente, ele conterá todos os outros intervalos como crianças.
• chat <model_name>: esse intervalo é criado quando o agente chama o modelo de chat subjacente, ele conterá o prompt e a resposta como atributos, se enable_sensitive_data for definido Truecomo .
• execute_tool <function_name>: esse intervalo é criado quando o agente chama uma ferramenta de função, ele conterá os argumentos de função e resultará como atributos, se enable_sensitive_data for definido como True.

As métricas criadas são:

• Para o cliente de chat e chat as operações:

  • gen_ai.client.operation.duration (histograma): essa métrica mede a duração de cada operação, em segundos.
  • gen_ai.client.token.usage (histograma): essa métrica mede o uso do token, em número de tokens.

• Para invocação de função durante as execute_tool operações:

  • agent_framework.function.invocation.duration (histograma): essa métrica mede a duração de cada execução de função, em segundos.

Exemplo de saída de rastreamento

Ao executar um agente com a observabilidade habilitada, você verá dados de rastreamento semelhantes à seguinte saída do console:

{
    "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 rastreamento mostra:

• Identificadores de rastreamento e intervalo: para correlacionar operações relacionadas
• Informações de tempo: quando a operação foi iniciada e encerrada
• Metadados do agente: ID do agente, nome e instruções
• Informações do modelo: o sistema de IA usado (OpenAI) e a ID de resposta
• Uso de token: contagens de token de entrada e saída para acompanhamento de custos

Samples

Temos vários exemplos em nosso repositório que demonstram esses recursos, consulte a pasta de exemplos de observabilidade no Github. Isso inclui exemplos para usar a telemetria de código zero também.