Observability

A observabilidade é um aspeto fundamental da construção de sistemas confiáveis e fáceis de manter. O Agent Framework fornece suporte interno para observabilidade, permitindo que você monitore o comportamento de seus agentes.

Este guia orientará você pelas etapas para habilitar a observabilidade com o Agent Framework para ajudá-lo a entender o desempenho de seus agentes e diagnosticar quaisquer problemas que possam surgir.

Integração OpenTelemetry

O Agent Framework integra-se ao OpenTelemetry e, mais especificamente, o Agent Framework emite rastreamentos, logs e métricas de acordo com as Convenções Semânticas do OpenTelemetry GenAI.

Ativar a 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 para seu 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

Importante

Quando você habilita a observabilidade para seus clientes e agentes de chat, você pode ver informações duplicadas, especialmente quando dados confidenciais estão habilitados. O contexto do chat (incluindo prompts e respostas) capturado pelo cliente de chat e pelo agente será incluído em ambas as faixas. Dependendo de suas necessidades, você pode optar por habilitar a observabilidade apenas no cliente de chat ou apenas no agente para evitar duplicação. Consulte as Convenções Semânticas do GenAI para obter mais detalhes sobre os atributos capturados para LLM e Agentes.

Observação

Habilite apenas dados confidenciais em ambientes de desenvolvimento ou teste, pois podem expor informações do usuário em logs e rastreamentos de produção. Dados confidenciais incluem prompts, respostas, argumentos de chamada de função e resultados.

Configuração

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

Rastreios

Para exportar rastreamentos para o back-end desejado, você pode configurar o SDK 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();

Sugestão

Dependendo do seu back-end, você pode usar exportadores diferentes, consulte a documentação do OpenTelemetry .NET para obter mais informações. Para o desenvolvimento local, considere a utilização do Painel de Controlo da Aspir.

Metrics

Da mesma forma, para exportar métricas para o back-end desejado, você pode configurar o SDK 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();

Registos

Os logs são capturados por meio da estrutura de registro 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 de Controlo do Aspire

Considere a utilização do Painel de Controlo do Aspire como uma forma rápida de visualizar os seus rastreios e métricas durante o desenvolvimento. Para saber mais, consulte a documentação do Painel do Aspire . O Painel do Aspire recebe dados através de um OpenTelemetry Collector, que pode adicionar ao seu fornecedor de rastreadores da seguinte forma:

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 ativado no repositório do Agent Framework.

Dependências

Pacotes incluídos

Para permitir a observabilidade na sua aplicação Python, os seguintes pacotes OpenTelemetry são instalados por defeito:

Exportadores

Não instalamos exportadores por defeito para evitar dependências desnecessárias e potenciais problemas com a instrumentação automática. Existe uma grande variedade de exportadores disponíveis para diferentes backends, por isso pode escolher aqueles que melhor se adequem às suas necessidades.

Alguns exportadores comuns que pode querer instalar consoante as suas necessidades:

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

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

Ativar Observabilidade (Python)

Cinco padrões para configurar a observabilidade

Identificámos várias formas de configurar a observabilidade na sua aplicação, dependendo das suas necessidades:

1. Variáveis padrão do ambiente OpenTelemetry (Recomendado)

A abordagem mais simples – configurar tudo através 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 só quiseres exportadores para consolas:

from agent_framework.observability import configure_otel_providers

configure_otel_providers(enable_console_exporters=True)

2. Exportadores Alfandegários

Para maior controlo sobre os exportadores, crie-os você mesmo e transmita-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 os seus próprios métodos de configuração. Podes usar esses métodos primeiro e depois ligar enable_instrumentation() para ativar os 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 controlo total, pode configurar manualmente exportadores, fornecedores e instrumentação. Use a função create_resource() auxiliar para criar um recurso com o nome e a versão do serviço apropriados. Consulte a documentação do OpenTelemetry Python para orientações detalhadas sobre instrumentação manual.

5. Auto-instrumentação (código zero)

Use a ferramenta de CLI OpenTelemetry para instrumentar automaticamente a sua aplicação sem alterações no 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 OpenTelemetry Zero-code Python para mais informações.

Utilização de traçadores e medidores

Uma vez configurada a observabilidade, pode criar abrangências 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 traçador ou medidor do fornecedor global, com agent_framework definido como nome da biblioteca de instrumentação por defeito.

Variáveis de ambiente

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

ENABLE_INSTRUMENTATION - O padrão é false, definido para true permitir a instrumentação OpenTelemetry.
ENABLE_SENSITIVE_DATA - O padrão é false, definido para true permitir o registo de dados sensíveis (prompts, respostas, argumentos de chamada de função e resultados). Tenha cuidado com esta definição, pois pode expor dados sensíveis.
ENABLE_CONSOLE_EXPORTERS - O padrão é false, definido para true permitir a saída da consola para telemetria.
VS_CODE_EXTENSION_PORT - Port para integração com a extensão do AI Toolkit ou Azure AI Foundry VS Code.

Observação

Informação sensível inclui prompts, respostas e mais, e só deve ser ativada em ambientes de desenvolvimento ou teste. Não é recomendado ativar isto em produção, pois pode expor dados sensíveis.

Variáveis padrão do ambiente OpenTelemetry

A configure_otel_providers() função lê automaticamente as variáveis padrão do ambiente OpenTelemetr:

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

OTEL_EXPORTER_OTLP_ENDPOINT - Ponto final base para todos os sinais (por exemplo, http://localhost:4317)
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT - Endpoint específico de traços (sobrepõe a base)
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT - Endpoint específico de métricas (substitui base)
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT - Endpoint específico de logs (substitui a base)
OTEL_EXPORTER_OTLP_PROTOCOL - Protocolo a usar (grpc ou http, por defeito: grpc)
OTEL_EXPORTER_OTLP_HEADERS - Cabeçalhos para todos os sinais (por exemplo, key1=value1,key2=value2)

Identificação do Serviço:

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

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

Configuração do Microsoft Foundry

O Microsoft Foundry tem suporte integrado para traçado com visualização dos seus spans.

Certifica-te de que tens o teu Foundry configurado com uma instância Azure Monitor, vê os detalhes

Instale o pacote `azure-monitor-opentelemetry`:

pip install azure-monitor-opentelemetry

Configurar a observabilidade diretamente a partir do `AzureAIClient`:

Para projetos Azure AI Foundry, pode configurar a observabilidade diretamente a partir 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)

Sugestão

Os argumentos para client.configure_azure_monitor() são passados para a função subjacente configure_azure_monitor() a partir do azure-monitor-opentelemetry pacote, veja a documentação para detalhes, tratamos da definição da string de ligação e do recurso.

Configure o monitor Azure e, opcionalmente, ative a instrumentação:

Para projetos de IA não Azure com Application Insights, certifique-se de configurar um agente personalizado no Foundry, veja os detalhes.

Depois executa o teu agente com o mesmo ID de agente OpenTelemetry registado no Foundry, e configura o monitor Azure da seguinte forma:

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 de Controlo do Aspire

Para desenvolvimento local sem configuração Azure, pode usar o Aspire Dashboard , que corre localmente via Docker e oferece uma excelente experiência de visualização em telemetria.

Configurar o Aspire Dashboard 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

Isto começará o painel com:

Web UI: Disponível em http://localhost:18888
Endpoint OTLP: Disponível em http://localhost:4317 para as suas aplicações enviarem dados de telemetria

Configuração da sua aplicação

Defina as seguintes variáveis de ambiente:

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

Ou inclua-os no seu .env ficheiro e faça a sua amostra.

Quando a sua amostra terminar de funcionar, navegue num http://localhost:18888 navegador web para ver os dados de telemetria. Siga o guia de exploração do Aspire Dashboard para autenticar-se no painel e comece a explorar os seus rastos, registos e métricas.

Espadas e métricas

Quando tudo estiver configurado, você começará a ver extensões e métricas sendo criadas automaticamente para você, as extensões são:

invoke_agent <agent_name>: Este é o período de nível superior para cada invocação de agente, ele conterá todos os outros vãos como filhos.
chat <model_name>: Essa extensão é criada quando o agente chama o modelo de chat subjacente, ele conterá o prompt e a resposta como atributos, se enable_sensitive_data estiver definido como True.
execute_tool <function_name>: Essa extensão é criada quando o agente chama uma ferramenta de função, ela conterá os argumentos da função e o resultado como atributos, se enable_sensitive_data estiver definido como True.

As métricas que são criadas são:

Para o cliente de chat e chat operações:
- gen_ai.client.operation.duration (histograma): Esta métrica mede a duração de cada operação, em segundos.
- gen_ai.client.token.usage (histograma): Esta 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): Esta métrica mede a duração da execução de cada 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 rastreio mostra:

Identificadores de rastreamento e extensão: para correlacionar operações relacionadas
Informações de tempo: Quando a operação começou e terminou
Metadados do agente: ID do agente, nome e instruções
Informações do modelo: O sistema de IA usado (OpenAI) e ID de resposta
Uso de token: contagens de token de entrada e saída para rastreamento de custos

Samples

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

Feedback

Esta página foi útil?

Last updated on 2025-12-17

Partilhar via

Observability

Integração OpenTelemetry

Ativar a Observabilidade (C#)

Configuração

Rastreios

Metrics

Registos

Painel de Controlo do Aspire

Como Começar

Dependências

Pacotes incluídos

Exportadores

Ativar Observabilidade (Python)

Cinco padrões para configurar a observabilidade

1. Variáveis padrão do ambiente OpenTelemetry (Recomendado)

2. Exportadores Alfandegários

3. Configuração de terceiros

4. Configuração manual

5. Auto-instrumentação (código zero)

Utilização de traçadores e medidores

Variáveis de ambiente

Variáveis padrão do ambiente OpenTelemetry

Configuração do Microsoft Foundry

Instale o pacote azure-monitor-opentelemetry:

Configurar a observabilidade diretamente a partir do AzureAIClient:

Configure o monitor Azure e, opcionalmente, ative a instrumentação:

Painel de Controlo do Aspire

Configurar o Aspire Dashboard com o Docker

Configuração da sua aplicação

Espadas e métricas

Exemplo de saída de rastreamento

Samples

Feedback

Recursos adicionais

Instale o pacote `azure-monitor-opentelemetry`:

Configurar a observabilidade diretamente a partir do `AzureAIClient`: