代理可观测性

可观测性是构建可靠且可维护的系统的关键方面。代理框架为可观测性提供内置支持，使你能够监视代理的行为。

本指南将指导你完成使用 Agent Framework 启用可观测性的步骤，以帮助你了解代理如何执行和诊断可能出现的任何问题。

OpenTelemetry 集成

Agent Framework 与 OpenTelemetry 集成，更具体地说，Agent Framework 会根据 OpenTelemetry GenAI 语义约定发出跟踪、日志和指标。

启用可观测性（C#）

若要为聊天客户端启用可观测性，需要按如下所示构建聊天客户端：

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

若要为代理启用可观测性，需要按如下所示生成代理：

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

重要

为聊天客户端和代理启用可观测性时，可能会看到重复的信息，尤其是在启用敏感数据时。聊天上下文（包括聊天客户端和代理捕获的提示和响应）将同时包含在这两个范围中。根据你的需求，可以选择仅在聊天客户端上启用可观测性，或仅启用代理来避免重复。有关为 LLM 和代理捕获的属性的更多详细信息，请参阅 GenAI 语义约定。

注释

仅在开发或测试环境中启用敏感数据，因为它可能会在生产日志和跟踪中公开用户信息。敏感数据包括提示、响应、函数调用参数和结果。

配置

现在已检测聊天客户端和代理，可以配置 OpenTelemetry 导出程序以将遥测数据发送到所需的后端。

跟踪

若要将跟踪导出到所需的后端，可以在应用程序启动代码中配置 OpenTelemetry SDK。例如，若要将跟踪导出到 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();

小窍门

根据后端的不同，可以使用不同的导出程序，有关详细信息，请参阅 OpenTelemetry .NET 文档。对于本地开发，请考虑使用 Aspire 仪表板。

Metrics

同样，若要将指标导出到所需的后端，可以在应用程序启动代码中配置 OpenTelemetry SDK。例如，若要将指标导出到 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();

日志

日志是通过所使用的日志记录框架捕获的，例如 Microsoft.Extensions.Logging。若要将日志导出到 Azure Monitor 资源，可以在应用程序启动代码中配置日志记录提供程序：

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

Aspire 仪表板

请考虑将 Aspire 仪表板用作在开发过程中可视化跟踪和指标的快速方法。若要了解详细信息，请参阅 Aspire 仪表板文档。 Aspire 仪表板通过 OpenTelemetry 收集器接收数据，可按如下所示添加到跟踪提供程序：

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

入门指南

请参阅在 Agent Framework 存储库中启用了 OpenTelemetry 的代理的完整示例。

启用可观测性（Python）

若要在 Python 应用程序中启用可观测性，在大多数情况下，无需安装任何额外的内容，默认情况下会安装以下包：

"opentelemetry-api",
"opentelemetry-sdk",
"opentelemetry-exporter-otlp-proto-grpc",
"opentelemetry-semantic-conventions-ai",

启用可观测性的最简单方法是使用以下环境变量进行设置。设置这些设置后，只需在程序开始时调用：

from agent_framework.observability import setup_observability

setup_observability()

这将考虑环境变量并相应地设置可观测性，它将设置全局跟踪提供程序和计量提供程序，以便你可以立即开始使用它，例如创建自定义范围或指标：

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

这些是 OpenTelemetry API 的包装器，它将从全局提供程序返回跟踪器或计量，但设置为 agent_framework 检测库名称，除非重写名称。

因此 otlp_endpoints，这些将创建为 OTLPExporter，每个 OTLPExporter 用于范围、指标和日志。 connection_string For Application Insights 将用于创建 AzureMonitorTraceExporter、AzureMonitorMetricExporter 和 AzureMonitorLogExporter。

环境变量

为应用程序启用可观测性的最简单方法是设置以下环境变量：

ENABLE_OTEL默认值设置为falsetrue启用 OpenTelemetry 这是基本设置所必需的，但也可用于可视化工作流。
ENABLE_SENSITIVE_DATA默认值 false设置为 true 启用敏感数据日志记录，例如提示、响应、函数调用参数和结果。如果要在跟踪中看到实际提示和响应，则需要这样做。请谨慎使用此设置，因为它可能会在日志中公开敏感数据。
OTLP_ENDPOINT默认值 None设置为主机，通常为 http://localhost:4317 ：这可用于任何合规的 OTLP 终结点，例如 OpenTelemetry Collector、 Aspire Dashboard 或任何其他符合 OTLP 的终结点。
APPLICATIONINSIGHTS_CONNECTION_STRING默认值 None设置为 Application Insights 连接字符串，以导出到 Azure Monitor。可以在 Azure 门户中的 Application Insights 资源的“概述”部分找到连接字符串。这将要求 azure-monitor-opentelemetry-exporter 安装包。
VS_CODE_EXTENSION_PORT默认值 4317设置为 AI 工具包或 AzureAI Foundry VS Code 扩展正在运行的端口。

编程设置

如果希望以编程方式设置可观测性，可以通过使用所需配置选项调用 setup_observability 函数来执行此作：

from agent_framework.observability import setup_observability

setup_observability(
    enable_sensitive_data=True,
    otlp_endpoint="http://localhost:4317",
    applicationinsights_connection_string="InstrumentationKey=your_instrumentation_key",
    vs_code_extension_port=4317
)

这将采用提供的配置选项并相应地设置可观测性。它将假定你意味着启用跟踪，因此 enable_otel 隐式设置为 True。如果还具有通过环境变量设置的终结点或连接字符串，也会创建这些终结点，并且我们检查是否有翻倍。

自定义导出程序

如果想要具有不同的导出程序，则上述标准导出程序，或者想要进一步自定义设置，可以通过创建自己的跟踪提供程序和计量提供程序，然后将这些 setup_observability 导出程序传递给函数，例如：

from agent_framework.observability import setup_observability
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter

custom_span_exporter = OTLPSpanExporter(endpoint="http://localhost:4317", timeout=5, compression=Compression.Gzip)

setup_observability(exporters=[custom_span_exporter])

Azure AI Foundry 设置

Azure AI Foundry 提供对跟踪的内置支持，具有非常出色的跨度可视化效果。

使用 Application Insights 资源设置 Azure AI Foundry 项目时，可以执行以下作：

安装 azure-monitor-opentelemetry-exporter 包：

pip install azure-monitor-opentelemetry-exporter>=1.0.0b41 --pre

然后，可以为 Azure AI Foundry 项目设置可观测性，如下所示：

from agent_framework.azure import AzureAIAgentClient
from agent_framework.observability import setup_observability
from azure.ai.projects.aio import AIProjectClient
from azure.identity import AzureCliCredential

async def main():
     async with AIProjectClient(credential=AzureCliCredential(), project_endpoint="https://<your-project>.foundry.azure.com") as project_client:
        try:
            conn_string = await project_client.telemetry.get_application_insights_connection_string()
            setup_observability(applicationinsights_connection_string=conn_string, enable_sensitive_data=True)
        except ResourceNotFoundError:
            print("No Application Insights connection string found for the Azure AI Project.")

这是一种方便的方法，它将使用项目客户端来获取 Application Insights 连接字符串，然后使用该连接字符串进行调用 setup_observability ，并重写通过环境变量设置的任何现有连接字符串。

零代码检测

由于我们使用标准 OpenTelemetry SDK，因此还可以使用零代码检测来检测应用程序，请运行如下所示的代码：

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

有关所用环境变量的详细信息和详细信息，请参阅 OpenTelemetry Zero-code Python 文档。

跨度和指标

设置所有内容后，你将开始看到自动创建的跨度和指标，范围是：

invoke_agent <agent_name>：这是每个代理调用的顶级范围，它将包含所有其他范围作为子级。
chat <model_name>：当代理调用基础聊天模型时，会创建此范围，如果 enable_sensitive_data 设置为 True，它将包含提示和响应作为属性。
execute_tool <function_name>：当代理调用函数工具时，将创建此范围，如果设置为 enable_sensitive_data，True它将包含函数参数和结果作为属性。

创建的指标包括：

对于聊天客户端和 chat 作：
- gen_ai.client.operation.duration （直方图）：此指标以秒为单位测量每个作的持续时间。
- gen_ai.client.token.usage （直方图）：此指标以令牌数度量令牌使用情况。
对于作过程中 execute_tool 的函数调用：
- agent_framework.function.invocation.duration （直方图）：此指标度量每个函数执行的持续时间（以秒为单位）。

跟踪输出示例

运行启用了可观测性的代理时，会看到类似于以下控制台输出的跟踪数据：

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

此跟踪显示：

跟踪和跨度标识符：用于关联相关作
计时信息：作启动和结束时间
代理元数据：代理 ID、名称和说明
模型信息：使用的 AI 系统（OpenAI）和响应 ID
令牌使用情况：用于成本跟踪的输入和输出令牌计数

Samples

存储库中有一些演示这些功能的示例，请参阅 Github 上的可观测性示例文件夹。这包括使用零代码遥测的示例。

后续步骤

后台响应

反馈

此页面是否有帮助？

Last updated on 2025-11-19