在 Microsoft Foundry Toolkit 中收集和检查跟踪

使用 Microsoft Foundry Toolkit for Visual Studio Code 收集本地跟踪或查看部署到 Microsoft Foundry 的代理的遥测数据。 一个跟踪组用于记录某个请求的操作。 每个操作都是一个 span，具有计时、状态以及插桩提供的任何属性或事件。

本文首先介绍本地收集，然后介绍已部署代理的云跟踪。 选择与调查匹配的数据源：

Approach	将其用于	数据和责任
代理检查器	发送本地请求、检查实时响应和工具事件，或在断点暂停代码。	服务器提供协议事件和开发诊断。 此方法不需要 OTLP 收集器，也不会创建云跟踪历史记录。
本地跟踪	比较开发期间记录的模型、工具和代理 span。	应用程序将遥测数据导出到工具包的本地收集器。 需要配置检测并管理存储的本地数据。
托管智能体跟踪	调查部署到 Foundry 的代理处理的请求。	跟踪存储在项目所连接的 Application Insights 资源中。 访问、保留和费用遵循Azure资源配置。

托管智能体在 Foundry 智能体服务中运行你的自定义代码。 Foundry 管理托管，但你仍负责代码和依赖项。 跟踪不会取代 代理的创建和部署。

Prerequisites

• 安装了当前公开版 Foundry Toolkit 扩展的 Visual Studio Code。 请参阅 安装 Foundry 工具包。
• 可以在本地运行的应用程序，其模型和工具连接已配置。
• 第一个示例是一个基于 Python 的 Microsoft Agent Framework 应用程序及其所选的 Python 运行环境。 对于其他 SDK，请使用 Python 或 JavaScript 和 TypeScript 设置方法。
• 对于云跟踪，需要已部署的智能体以及一个已连接到其 Foundry 项目的 Application Insights 资源，或者具有连接或创建该资源的权限。
• 对于云查询，需要在已连接的 Application Insights 资源上具有Log Analytics Reader 角色。 对于 受保护的表，还分配 特权监视数据读取者角色。 请参阅 Foundry 跟踪先决条件。

本地集合不需要 Application Insights 或云遥测权限。 模型调用和工具执行仍可使用远程服务并产生费用。

收集本地跟踪

本地收集器通过 OpenTelemetry 协议（OTLP）接收遥测数据。 它不会自动对应用程序进行插桩。 框架或检测库必须创建跨度，并将其导出到收集器。

SDK 和语言设置

具有内置插桩的 SDK 仍需要导出器。 其他 SDK 使用独立的插桩软件包。

SDK 或框架	Python	JavaScript 和 TypeScript（Node.js）
Microsoft代理框架	内置 OpenTelemetry 插桩。	没有专用工具包设置指南。
Azure AI 推理 SDK（预览版）	Azure SDK 插桩器。	Azure SDK 插桩。
Foundry Projects SDK	客户端插桩工具（预览版）。	为底层 OpenAI 或 Azure SDK 客户端添加插桩。
Foundry 经典代理 SDK	Azure SDK 检测器。	没有专用工具包设置指南。
Anthropic	OpenLLMetry 检测器。	Traceloop 插桩。
Google GenAI (Gemini)	Google GenAI OpenTelemetry 检测器。	没有专用工具包设置指南。
LangChain	OpenLLMetry 检测器。	Traceloop 检测。
OpenAI SDK，包括 Azure OpenAI 客户端	OpenLLMetry 检测器。	Traceloop 插桩。
OpenAI 代理 SDK	OpenLLMetry 跟踪处理器。	没有专用工具包设置指南。

“没有专用工具包设置指南”意味着该语言没有特定于 SDK 的设置路径，而不是收集器拒绝其遥测数据。 收集器接受 OTLP 数据。 检测器决定捕获哪些操作和消息详细信息。

这些示例使用了部分选定的检测选项，并非兼容库的完整列表。 OpenLLMetry 和 Traceloop 检测均非 Microsoft 开发的库。

设置检测

将此过程与现有的 Python Agent Framework 应用程序配合使用。 在本演练中，请将代理和收集器保留在相同的本地环境中。

1. 在活动栏中选择 Foundry Toolkit，然后依次选择开发人员工具>监视器>跟踪。

2. 在运行应用程序之前，选择 “启动收集器”。

3. 在应用程序的Python环境中，如果尚未在依赖项中声明，请安装 gRPC 导出程序：

   python -m pip install opentelemetry-exporter-otlp-proto-grpc
   

   参考：OpenTelemetry Python OTLP 导出程序。

4. 请在应用程序启动时、在构建或运行智能体之前，对 OpenTelemetry 进行一次配置：

   import os
   
   os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "http://localhost:4317"
   os.environ["OTEL_EXPORTER_OTLP_PROTOCOL"] = "grpc"
   
   from agent_framework.observability import configure_otel_providers
   
   configure_otel_providers(enable_sensitive_data=False)
   

   参考： 代理框架可观测性。

   如果应用程序或托管库已配置 OpenTelemetry 提供程序，请配置其现有导出程序，而不是添加其他提供程序设置。 特定于 OTEL_EXPORTER_OTLP_*_ENDPOINT 信号的变量可以替代基本端点。 检查指向其他位置的现有跟踪、日志或指标设置。

5. 使用正常的入口点运行应用程序，并发送触发代理的请求。 让请求完成，并在停止进程之前给导出程序留出时间发送遥测数据。

6. 在跟踪中，选择刷新，然后选择新的跟踪以查看其跨度。

Agent Framework 检测支持的模型客户端、智能体和工作流操作。 其他框架可能需要检测库。 OTLP 兼容性允许收集器接收数据，同时输出的属性和 生成 AI 语义约定 决定查看器显示的内容。

对于其他 SDK 或语言，请使用下面的设置，而不是 Agent Framework 配置。 首先启动收集器，在创建客户端之前配置插桩，然后运行应用程序并刷新跟踪列表。

收集器端点

将导出程序协议与收集器终结点匹配。 工具包使用以下默认值侦听 localhost：

出口商	终结点
OTLP gRPC	http://localhost:4317
OTLP HTTP 链路追踪导出器	http://localhost:4318/v1/traces
OTLP HTTP 日志导出程序	http://localhost:4318/v1/logs

某些 HTTP 导出程序接受 http://localhost:4318 并自行附加信号路径。 请遵循导出器的配置，而不要将该路径附加两次。 某些插桩库会将消息内容作为日志记录发送，因此仅导出 span 可能无法提供输入和输出的详细信息。

这些端口与代理程序的 HTTP 服务器端口和调试器端口无关。 在容器或远程开发环境中，localhost 是指该环境。 应与正确的采集器建立连接，而不要想当然地认为它指的是你的桌面。

Python SDK 设置

以下示例假设应用程序已具有其模型 SDK、凭据和模型配置。 从下表安装 SDK 的共享依赖项和其他包：

python -m pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

参考：OpenTelemetry Python SDK、OTLP 导出程序。

在应用程序启动时将此共享配置添加一次，随后对表中的一行数据进行检测。 不要将其与另一个库的 provider 配置混用。

import os

os.environ["TRACELOOP_TRACE_CONTENT"] = "false"
os.environ["OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"] = "false"
os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "false"

from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
    OTLPSpanExporter,
)

provider = TracerProvider(
    resource=Resource.create({"service.name": "my-agent"})
)
provider.add_span_processor(BatchSpanProcessor(
    OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")
))
trace.set_tracer_provider(provider)

参考：TracerProvider 和 Span 处理器，OTLPSpanExporter。

在你选择的行中安装标有 python -m pip install <package> 的软件包。 OpenAI、Anthropic、LangChain 以及独立的 OpenAI Agents 示例使用非 Microsoft 的 OpenLLMetry 插桩。 SDK 版本和模型 API 可以生成不同的详细信息。

SDK	附加包	共享设置后检测
OpenAI，包括 Azure OpenAI 客户端	opentelemetry-instrumentation-openai	from opentelemetry.instrumentation.openai import OpenAIInstrumentor OpenAIInstrumentor().instrument()
Anthropic	opentelemetry-instrumentation-anthropic	from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor AnthropicInstrumentor().instrument()
LangChain	opentelemetry-instrumentation-langchain	from opentelemetry.instrumentation.langchain import LangchainInstrumentor LangchainInstrumentor().instrument()
Google GenAI	opentelemetry-instrumentation-google-genai	os.environ["OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"] = "NO_CONTENT" from opentelemetry.instrumentation.google_genai import GoogleGenAiSdkInstrumentor GoogleGenAiSdkInstrumentor().instrument()
Foundry Projects 客户端跟踪（预览版）	azure-core-tracing-opentelemetry，以及 azure-ai-projects	os.environ["AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING"] = "true" from azure.ai.projects.telemetry import AIProjectInstrumentor AIProjectInstrumentor().instrument(enable_content_recording=False)
Foundry 经典代理 SDK	azure-core-tracing-opentelemetry，以及 azure-ai-agents	os.environ["AZURE_SDK_TRACING_IMPLEMENTATION"] = "opentelemetry" from azure.ai.agents.telemetry import AIAgentsInstrumentor AIAgentsInstrumentor().instrument()
Azure AI 推理 SDK （预览版）	azure-core-tracing-opentelemetry，以及 azure-ai-inference	os.environ["AZURE_SDK_TRACING_IMPLEMENTATION"] = "opentelemetry" from azure.ai.inference.tracing import AIInferenceInstrumentor AIInferenceInstrumentor().instrument()

对于 Foundry 项目，请遵循客户端跟踪指南，并在完成插桩后创建其 OpenAI 客户端。 本指南不同于 经典代理 SDK。 不要同时使用 AIProjectInstrumentor 和单独的 OpenAI 插桩器对相同的 OpenAI 调用进行插桩。

对于 OpenAI Agents SDK，请安装 opentelemetry-instrumentation-openai-agents，并在共享设置之后添加以下代码：

from agents import set_trace_processors
from opentelemetry.instrumentation.openai_agents import OpenAIAgentsInstrumentor

set_trace_processors([])
OpenAIAgentsInstrumentor().instrument()

参考：OpenAI 代理埋点、OpenAI 代理追踪。

本示例会先替换现有追踪处理器，然后再添加 OpenTelemetry 处理器。 如果没有进行该替换，SDK 也可以将跟踪信息导出到其默认后端。 如果你需要使用现有的处理器，请在更改追踪目标之前先检查一下这些目标。 保持 SDK 跟踪处于启用状态，以便 OpenTelemetry 处理器接收事件。

在短生存期应用程序完成其请求后，在退出之前调用 provider.force_flush() 以发送缓冲的 Span。 有关调整这些代码片段的帮助，请使用工具包的 Tracing Code Gen 工具。

导出消息日志记录

某些插桩器将消息内容作为 OpenTelemetry 日志记录发出，而不是作为 span 属性。 如果选择在受控开发测试中记录该内容，请将此设置与前面的Python跟踪提供程序一起添加一次：

from opentelemetry import _logs
from opentelemetry.sdk._logs import LoggerProvider
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter

logger_provider = LoggerProvider(resource=provider.resource)
logger_provider.add_log_record_processor(BatchLogRecordProcessor(
    OTLPLogExporter(endpoint="http://localhost:4318/v1/logs")
))
_logs.set_logger_provider(logger_provider)

参考：OpenTelemetry Python日志记录 SDKOTLPLogExporter。

在退出短生存期应用程序之前调用 logger_provider.force_flush()。 日志导出程序本身不会启用内容捕获。 请遵循检测器的内容设置以及数据处理指南。

JavaScript 和 TypeScript SDK 设置

对于 Node.js 应用程序，请共享一个跟踪提供程序并为您的 SDK 注册插桩。 此示例使用 CommonJS 和 OpenTelemetry JavaScript 2.x 提供程序配置。 编译为 CommonJS 的 TypeScript 应用程序可以使用相同的初始化顺序。

应用程序必须已具有其模型 SDK、凭据和模型配置。 安装共享依赖项和 OpenAI 插桩器：

npm install @opentelemetry/api @opentelemetry/sdk-trace-node \
  @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-proto \
  @opentelemetry/instrumentation @traceloop/instrumentation-openai

参考：OpenTelemetry JavaScript 导出器、OpenAI 插桩。

创建 tracing.cjs：

const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { BatchSpanProcessor } = require('@opentelemetry/sdk-trace-base');
const {
  OTLPTraceExporter
} = require('@opentelemetry/exporter-trace-otlp-proto');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { OpenAIInstrumentation } = require('@traceloop/instrumentation-openai');

const provider = new NodeTracerProvider({
  spanProcessors: [
    new BatchSpanProcessor(new OTLPTraceExporter({
      url: 'http://localhost:4318/v1/traces'
    }))
  ]
});
provider.register();

registerInstrumentations({
  instrumentations: [new OpenAIInstrumentation({ traceContent: false })]
});

module.exports = provider;

参考：NodeTracerProvider、OpenAI 插桩。

在导入或调用模型 SDK 之前，请先加载此文件。 例如，对于 CommonJS 应用程序，请运行 node --require ./tracing.cjs app.cjs。 若要使用其他 SDK，请将 OpenAI 包、导入和注册代码替换为对应的行：

SDK	检测包	导入和注册条目
OpenAI，包括 Azure OpenAI 客户端	@traceloop/instrumentation-openai	const { OpenAIInstrumentation } = require('@traceloop/instrumentation-openai'); new OpenAIInstrumentation({ traceContent: false })
Anthropic	@traceloop/instrumentation-anthropic	const { AnthropicInstrumentation } = require('@traceloop/instrumentation-anthropic'); new AnthropicInstrumentation({ traceContent: false })
LangChain	@traceloop/instrumentation-langchain	const { LangChainInstrumentation } = require('@traceloop/instrumentation-langchain'); new LangChainInstrumentation({ traceContent: false })
Azure SDK 操作，包括 Azure AI 推理	@azure/opentelemetry-instrumentation-azure-sdk	const { createAzureSdkInstrumentation } = require('@azure/opentelemetry-instrumentation-azure-sdk'); createAzureSdkInstrumentation()

Traceloop 软件包属于非 Microsoft 的检测工具。 对于 Foundry Projects 应用程序，请对发出模型请求的客户端进行检测。 Azure SDK检测不会为通过 OpenAI 客户端进行的调用替换 OpenAI 检测。

对于原生 ECMAScript 模块，请遵循 OpenTelemetry 的 ESM 设置。 在目标 SDK 之后加载插桩可能会使调用未被插桩。 关机时，请在请求完成后等待 provider.shutdown()，以便导出缓冲的跨度数据。

Important

这些示例关闭列出的 GenAI 插桩器的消息内容捕获。 这并非一项普遍的删节保证。 在共享数据之前，请查看其他导出程序、SDK 日志记录、span 属性和自定义插桩。 查看链接的 instrumentor 文档，了解支持的包和 API。

检查和管理本地跟踪

使用 span 树跟踪从代理编排到模型和工具操作的请求。

1. 选择一个运行缓慢或已故障的跨段。
2. 检查其持续时间和状态。
3. 打开输入 + 输出以查看记录的消息（如由插桩提供），或打开元数据以查看跨度属性。

这些示例均禁用了敏感内容的捕获功能。 没有消息的计时数据可能是预期结果。

对于受控的 Agent Framework 开发测试，请在其现有配置中设置 enable_sensitive_data=True ，以记录支持的提示、响应和工具内容。 在测试完成后将其还原到 False。 其他检测器有各自的内容设置。

注意

内容录制可以捕获个人数据、机密、工具参数和结果。 在内容进入遥测系统之前，请使用非敏感测试数据并尽量减少内容或遮盖、删减敏感内容。 不要仅开启生产内容录制以填充空的输入和输出视图。

收集的跟踪会保存在位于用户主文件夹下 tracing 的 traces.db 子目录中、名为 .aitk 的本地 SQLite 数据库中。 关闭查看器不会删除它们。

选择停止收集器以停止本地收集。 代理及其模型调用将继续运行。 若要删除本地记录，请选择列表中的跟踪，然后选择“ 删除”。

本地存储独立于 Application Insights。 删除本地跟踪不会删除云遥测，清除 Inspector 中的会话不会删除任一存储。

查看托管代理跟踪

部署完成后，请使用云追踪来排查在 Foundry 中运行的智能体，而不是你的本地进程。 工具包查询项目的连接的 Application Insights 资源。 它不会上传你的本地跟踪数据库。

开始之前，请确认云先决条件。 仅访问智能体本身并不能授予查询遥测数据的权限。

连接 Application Insights 并检查请求

使用智能体的跟踪选项卡连接 Application Insights，并查找一个已部署智能体的请求。

1. 在 Foundry Toolkit 边栏中，打开我的资源>智能体。 选择“托管代理”选项卡，然后选择代理的名称。

2. 选择跟踪。 如果项目没有连接资源，请选择“ 启用 App Insights”。

3. 在 App Insights 设置中，选择现有的 Application Insights 资源名称。 或者，选择创建资源并完成所需的资源和工作区字段。 选择 “提交” 并等待确认。

   这会更改项目的共享 Application Insights 连接，而不是本地工作区首选项。 资源创建和遥测收集可能会产生Azure费用。 提交前请确认目标项目和资源。

4. 返回到 Playground 并向已部署的代理发送测试请求。

5. 等待数据摄取完成，然后再次打开追踪。 使用时间范围、按对话 ID 搜索、状态或持续时间筛选器进行搜索以查找请求。

   

6. 选择一个跟踪，然后选择一个跨度，以查看元数据和输入 + 输出（如有相关内容）。

若要检查与会话关联的操作，请在跟踪列表中选择其 会话 ID。 对话视图显示操作树和元数据。

连接 Application Insights 可实现 Foundry 的服务器端跟踪。 对模型调用、工具调用和自定义代码的可见性还取决于托管库和框架检测。 请参阅 在 Foundry 中设置跟踪，了解服务端收集和其他客户端插桩。

工具包的跟踪详细信息查询目前涵盖过去七天。 这是一个查询窗口，而不是保留设置。 对于较旧的数据，请使用 Foundry 门户或 Azure Monitor，具体取决于已连接工作区的保留配置。

数据、访问、保留和成本

确定在启用内容捕获或连接云资源之前，遥测应转到何处。 同一条请求可能会生成本地跨度、云遥测数据，以及发送给模型或工具提供商的数据。

数据源	Responsibilities
本地跟踪	保护对本地数据库和复制数据的访问。 停止收集器不会停止应用程序中配置的其他导出程序。
云跟踪	Application Insights 和 Log Analytics 负责控制访问、保留期和遥测费用。 工具包筛选器不会更改这些策略。
模型和工具调用	本地收集不会阻止请求离开计算机。 查看每个连接的服务的数据处理，包括非Microsoft工具。

请参考 Foundry 关于安全与隐私以及数据保留与成本的跟踪指南。 对于生产标识、网络隔离和下游访问，请遵循 托管代理安全性和数据处理。 不要将本地凭据视为已部署代理的权限。

Troubleshooting

Issue	需要检查的事项
跟踪功能在边栏中不可用。	确认当前扩展已安装并在运行该扩展的环境中启用。 本地跟踪需要加载其原生 SQLite 组件。
收集器无法启动。	检查是否有其他进程正在使用端口 4317 或 4318，并查看工具包输出。 避免多个采集器在同一端口上相互竞争。
本地请求成功，但未显示任何跟踪。	确认插桩在请求之前运行，收集器正在运行，导出程序使用正确的协议和终结点。 检查终结点覆盖、导出器错误和缓冲遥测，然后选择“刷新”。
跨度出现时没有提示信息。	检查内容录制设置和受支持的属性。 某些库还需要日志导出程序。 内容缺失并不一定意味着采集失败。
云跟踪为空。	确认项目与 Application Insights 的连接，生成新的流量，扩展时间范围，并考虑数据采集的延迟。
云查询失败并出现授权错误。	使用服务先决条件检查对 Application Insights 和Log Analytics（包括受保护表）的读取访问权限。
较旧的跟踪在 Toolkit 中没有详细信息。	明细查询可查询最近七天的数据。 在 Foundry 或 Azure Monitor 中查询较旧的保留记录。

相关内容

• 使用代理检查器调试代理。
• 代理跟踪概念。
• 配置客户端跟踪。