可易

用 OpenTelemetry 导出托管智能体遥测

可易团队阅读约 8 分钟

本文说明如何用环境变量把 Foundry 托管智能体的追踪、日志和指标导出到 Application Insights 或任意 OTLP 端点，并保管密钥、处理排障。

目录

#用 OpenTelemetry 导出托管智能体遥测

配置托管智能体，以 OpenTelemetry 格式导出其追踪、日志和指标数据。托管智能体的遥测来自协议运行时（Responses 或 Invocations 服务器）以及你的智能体代码。默认情况下，智能体把这些遥测发到 Foundry 关联到你项目的 Application Insights 资源。你也可以用 OpenTelemetry 语义，把同一份数据导出到任何其他符合 OpenTelemetry 的端点，或自托管的 OpenTelemetry Collector。

用 OpenTelemetry 导出托管智能体遥测时，你会得到这些好处：

  • 把协议运行时和智能体代码两边的追踪与日志关联起来。
  • 以一致的、基于标准的方式生成可导出遥测。
  • 与任何消费符合 OpenTelemetry 数据的可观测性提供者集成。

请记住这些考量：

  • 遥测导出完全通过智能体版本上的环境变量配置。你不必新增或修改插桩代码。协议运行时在启动时自动检测配置。
  • 环境变量按版本设置，版本一旦创建就不可变。要更改导出目的地，就创建新的智能体版本。
  • 你可以同时启用 Application Insights 和一个 OTLP 导出器。两者都配置时，智能体把遥测发到两个目的地。

先决条件

  • 一个已部署托管智能体的 Foundry 项目。要创建一个，见部署托管智能体。
  • 如果导出到 Application Insights 以外的提供者，需要一个符合 OpenTelemetry 的端点。从提供者文档取得端点 URL 和任何必需的身份验证头。

托管智能体如何发出 OpenTelemetry

每种托管智能体协议（Responses、Invocations）都使用一个轻量库，处理 HTTP 或 WebSocket 服务器、健康检查，以及 OpenTelemetry 集成。这些库捆绑了 OpenTelemetry 发行版，因此智能体无需在代码里做任何遥测设置，就能发出追踪、日志和指标。运行时根据启动时检测到的环境变量选择导出器：

  • 当平台注入的 APPLICATIONINSIGHTS_CONNECTION_STRING 设置存在时，运行时导出到 Application Insights。项目监控启用时，Foundry 会自动注入这个设置。
  • 当 OTEL_EXPORTER_OTLP_ENDPOINT 存在时，运行时也通过 OTLP（OpenTelemetry Protocol）导出到该端点。

因为两个导出器使用彼此独立的设置，你可以把遥测发到 Application Insights、发到一个 OTLP 端点，或同时发到两边。

注意

APPLICATIONINSIGHTS_CONNECTION_STRING 是平台保留设置，由 Foundry 注入容器——你不能在 agent.yaml 里设置或覆盖它。只有在项目上配置了监控时，Foundry 才会注入它。要停止向 Application Insights 发送遥测，应在项目级禁用监控，而不是试图从智能体上删掉这个设置。

配置导出目的地

根据你希望遥测发往何处，在智能体上配置环境变量。下面分别说明每个目的地的设置。

Application Insights 是默认目的地，智能体上无需配置。项目监控启用时，Foundry 把一个 Application Insights 资源关联到项目，并把连接字符串注入每个托管智能体容器。

APPLICATIONINSIGHTS_CONNECTION_STRING：所关联 Application Insights 资源的连接字符串。Foundry 自动设置这个值。它是保留的，不能在 agent.yaml 里覆盖。

遥测出现在所关联的 Application Insights 资源中，位置是 调查（Investigate） > 事务搜索（Transaction search），或 调查（Investigate） > 性能（Performance）。分析指导见在项目中启用追踪。

托管智能体支持把 OpenTelemetry 数据导出到任何符合 OTLP 的端点。具体取值取决于你选择的可观测性提供者或自托管收集器。

多数提供者需要：

OTEL_EXPORTER_OTLP_ENDPOINT：可观测性后端提供的 OTLP 端点 URL——例如 https://otlp.example-provider.com。端点 URL 不是密钥。

OTEL_EXPORTER_OTLP_PROTOCOL：要使用的 OTLP 传输。除非提供者另有要求，使用 http/protobuf（基于 HTTP 的 OTLP）——这是向外部端点发送遥测时支持最广的选项。导出器也支持 grpc（基于 gRPC 的 OTLP），但 gRPC 的可用性因提供者而异（有些只接受 HTTP），因此选择之前先确认后端支持它。协议要与端点期望的一致。

许多提供者也需要：

OTEL_EXPORTER_OTLP_HEADERS：用于身份验证凭据的头，例如 API 密钥。这个头遵循 OpenTelemetry 对 OTLP 后端做身份验证的标准机制，多数 SaaS 提供者都支持。值是逗号分隔的 key=value 列表——例如 api-key=<your-key>，或 x-provider-team=<token>,x-provider-dataset=<name>。记住这些格式规则：

  • 头名称和格式必须与提供者文档完全一致。多余的空格或逗号是静默身份验证失败的常见原因。
  • 对使用 HTTP 基本身份验证的提供者，OpenTelemetry OTLP 导出器会原样传递头，不会替你构造 Authorization 头。你要自己对凭据做 Base64 编码，并传入 Authorization=Basic <base64-encoded-credentials>。
  • 对包含保留字符的值做 URL 编码。
  • 若不同信号要用不同的头，改为设置按信号的变体：OTEL_EXPORTER_OTLP_TRACES_HEADERS、OTEL_EXPORTER_OTLP_LOGS_HEADERS 和 OTEL_EXPORTER_OTLP_METRICS_HEADERS。OTEL_EXPORTER_OTLP_HEADERS 作用于全部信号。

因为头的值是密钥，把它存在连接里，而不是放进 agent.yaml。见把 OTLP 身份验证头存在连接中。

托管智能体支持 OpenTelemetry SDK 配置文档中定义的标准环境变量。你需要的具体变量和取值因提供者而异。查阅可观测性提供者的文档，了解：

  • 必需的端点 URL 和身份验证方法。
  • 推荐的配置设置。
  • 提供者特定的环境变量。
  • 任何额外的设置步骤。

在智能体上设置环境变量

把导出设置加到智能体 agent.yaml 文件的 environment_variables 节。用 azd 部署时，这些值会应用到新的智能体版本。

environment_variables:
  - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
    value: gpt-5-mini
  # Export OpenTelemetry traces, logs, and metrics over OTLP.
  - name: OTEL_EXPORTER_OTLP_ENDPOINT
    value: https://<your-provider-otlp-endpoint>     # not secret
  - name: OTEL_EXPORTER_OTLP_PROTOCOL
    value: http/protobuf

除非你在项目级禁用监控，遥测会继续流向 Application Insights，因此这份配置会把数据发到两个目的地。若只发到 OTLP 端点，请在项目级禁用监控。

提示

如果你自己的基础设施提供端点（例如与智能体一起部署的 OpenTelemetry Collector），用部署输出引用该端点——例如 value: ${OTEL_EXPORTER_OTLP_ENDPOINT}——这样 Foundry 会在部署时解析该值，而不是把它写死。

把 OTLP 身份验证头存在连接中

OTLP 端点 URL 不是密钥，但身份验证头通常是。把密钥放在 Foundry 的自定义密钥（Custom keys）项目连接里，并用占位符引用，使密钥不进入 agent.yaml。

  1. 在项目上创建一个自定义密钥（Custom keys）（CustomKeys）连接。在 Foundry 门户中，进入管理（Manage） > 项目详细信息（Project details） > 已连接资源（Connected resources） > 添加连接（Add connection） > 自定义密钥（Custom keys），或用基础设施即代码（Infrastructure as Code）创建连接。添加一个保存完整 OTLP 头字符串的字段——例如名为 otlp_headers 的字段，值设为 <header-name>=<secret>。确切的头名称和格式来自提供者文档。
  1. 在 agent.yaml 里用占位符引用连接字段：
environment_variables:
  - name: OTEL_EXPORTER_OTLP_ENDPOINT
    value: https://<your-provider-otlp-endpoint>     # not secret
  - name: OTEL_EXPORTER_OTLP_PROTOCOL
    value: http/protobuf
  - name: OTEL_EXPORTER_OTLP_HEADERS
    value: ${{connections.otel-secrets.credentials.otlp_headers}}   # secret via connection

Foundry 在会话沙箱启动时解析占位符，并把该值作为普通环境变量注入。更多信息见在环境变量中引用项目连接。

使用连接时请记住：

  • 在部署智能体版本之前创建连接。如果沙箱启动时连接缺失，占位符会解析为空值。
  • 密钥是只写的。读取连接会返回 credentials: null，因此要在运行中的容器内部读取环境变量来核验取值，而不是去检查连接。
  • 占位符路径必须与连接字段名完全一致。请自己记下字段名，因为读取连接时不会返回它。

同时把遥测发到 Application Insights 和 OTLP 端点

因为两个导出器使用彼此独立的设置，同时使用两者不需要额外配置。当平台注入的 APPLICATIONINSIGHTS_CONNECTION_STRING 和你在智能体上设置的 OTEL_EXPORTER_OTLP_ENDPOINT 都存在时，智能体把遥测并行发到两个目的地。这样你可以保留内置的 Application Insights 体验，同时把数据转发到现有的可观测性后端。

若只把遥测发到你的 OTLP 端点，请在项目级禁用监控，使 Foundry 不注入 Application Insights 连接字符串。

服务名称

托管智能体在固定为智能体名称的 service.name 下报告遥测——在 Application Insights 中显示为 cloud_RoleName，在 OTLP 后端中显示为服务/资源名称。这适用于两种导出，并由平台设置。

标准环境变量 OTEL_SERVICE_NAME 对托管智能体没有作用；平台会覆盖它。要使用不同的服务名称，就相应地为智能体命名。

调整导出器行为

你可以用标准 OpenTelemetry 环境变量调整导出器行为——例如用 OTEL_TRACES_SAMPLER 做追踪采样。这些变量提供跨语言、跨运行时控制行为的一致方式。追踪采样只影响跨度；日志记录无论如何都会导出。平台会自行设置某些值（例如 service.name），因此通过环境变量设置的资源属性可能被覆盖。支持的变量完整列表见 OpenTelemetry SDK 配置文档。

OpenTelemetry 的考量

用 OpenTelemetry 导出数据时，请记住这些考量：

  • 不可变版本：按智能体版本设置环境变量。创建版本后不能更改。要更改导出目的地或头，就创建新的智能体版本。
  • 保留的 Application Insights 设置：不能在 agent.yaml 里设置或覆盖 APPLICATIONINSIGHTS_CONNECTION_STRING。通过项目监控来控制它。
  • 第三方数据流：导出到非 Microsoft 的可观测性提供者时，遥测（依你的插桩，可能包含提示、工具和响应内容）会流向该提供者。审阅提供者的数据处理、保留和位置策略，并确认该数据流符合组织的合规与地域要求。更多信息见安全与数据处理。
  • 批量导出：遥测按批导出，因此调用智能体后要等几秒，数据才会出现在后端。

排查

用 OpenTelemetry 导出数据时，请记住这些常见问题及解决办法。

OTLP 端点没有出现遥测

确认已部署的智能体设置了端点，且导出配置正确：

  • 核验已部署的智能体版本上设置了 OTEL_EXPORTER_OTLP_ENDPOINT，并且指向正确的 URL。
  • 确认 OTEL_EXPORTER_OTLP_PROTOCOL 与端点期望的一致（http/protobuf 或 grpc）。
  • 调用智能体以生成遥测，然后为批量导出留出几秒。

OTLP 端点上的身份验证失败

如果端点以身份验证错误拒绝连接：

  • 确认 CustomKeys 连接存在，并且是在智能体版本部署之前创建的。
  • 核验 agent.yaml 中的占位符路径与连接字段名完全一致。
  • 确认头字符串格式与提供者文档一致（例如 api-key=<value>）。
  • 因为密钥是只写的，通过在运行中的容器内部读取 OTEL_EXPORTER_OTLP_HEADERS 来核验解析后的值，而不是通过读取连接。

配置 OTLP 之后遥测仍流向 Application Insights

配置 OTLP 导出器并不会禁用 Application Insights——两者都配置时，两个目的地都会收到遥测。要停止向 Application Insights 发送遥测，请在项目级禁用监控，使 Foundry 不注入 APPLICATIONINSIGHTS_CONNECTION_STRING。

PRIMARY_SOURCE: https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/configure-hosted-agent-telemetry

  • #OpenTelemetry
  • #Foundry
  • #托管智能体
  • #OTLP
  • #Application Insights

继续阅读