你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

在 Microsoft Foundry 中设置跟踪

重要

本文中标记为（预览）的项目目前以公共预览版提供。 此预览版在没有服务级别协议的情况下提供，不建议将其用于生产工作负荷。 某些功能可能不受支持，或者可能具有受限功能。 有关详细信息，请参阅 Microsoft Azure 预览版的使用条款。

注意

跟踪仅对提示智能体正式发布。 工作流、托管代理和自定义代理处于预览状态。

使用追踪来调试 AI 代理，并监控它们在生产中的行为。 跟踪捕获详细的遥测数据（包括延迟、异常、提示内容和检索操作），以便更快地识别和修复问题。

先决条件

将 Application Insights 连接到 Foundry 项目

Foundry 使用 OpenTelemetry 语义约定将跟踪存储在 Application Insights 中。

  1. 登录到 Microsoft Foundry。 确保New Foundry开关处于打开状态。 这些步骤适用于 Foundry（新版）。
  2. 打开 Foundry 项目。
  3. 在左侧导航中，选择 “代理”。
  4. 在顶部，选择 “跟踪”。
  5. 在右侧，选择 “连接”以创建或连接 Application Insights 资源：
    • 若要连接现有资源，请选择该资源，然后选择“ 连接”。
    • 若要创建新资源，请选择“ 新建 ”并完成向导。

“代理”选项卡的屏幕截图，其中显示了跟踪和连接按钮。

连接成功后，将显示一条确认消息。

连接资源后，项目即可使用跟踪。

如果未看到消息栏或“连接”按钮，下面是启用 Azure Monitor Application Insights 的替代方法。

  1. 从项目名称的下拉菜单中选择项目详细信息。 项目名称菜单的屏幕截图，其中突出显示了项目详细信息。
  2. 导航到 “已连接资源 ”选项卡，然后选择“ 添加连接”。 项目详细信息的屏幕截图，已选择“已连接资源”选项卡，突出显示“添加连接”。
  3. 在“选择连接”菜单中选择 Application Insights。 “选择连接”的屏幕截图，其中突出显示了 Application Insights。

重要

请确保拥有查询遥测所需的权限。

调试 AI 代理

选择与生成和运行代理的方式匹配的方法。

Foundry 门户中的服务器端跟踪

从服务器端跟踪开始。 Foundry 无需更改代码，即可记录常见代理和工作流场景的日志跟踪。

  • Foundry 会在 Foundry 门户中自动记录 Prompt 代理、Host 代理和工作流的服务器端跟踪。 在 Foundry 项目中启用跟踪后，您将能够访问过去 90 天内的内置跟踪。
  • Foundry 还允许与顶级代理框架轻松 集成 。

使用 Microsoft Foundry SDK 进行客户端追踪（Python）

使用以下命令安装 OpenTelemetry 和Azure SDK跟踪插件：

pip install azure-ai-projects azure-identity opentelemetry-sdk azure-core-tracing-opentelemetry

重要

在应用程序中使用项目的终结点需要配置Microsoft Entra ID。 如果未配置 Microsoft Entra ID，请使用 Application Insights 连接字符串。

运行代理后，可以在 Foundry 门户中开始查看和分析跟踪。

有关详细说明和特定于 SDK 的代码示例，请参阅使用 azure-ai-projects（Python SDK）进行追踪和代理的遥测示例。

在 VS Code 中使用 Foundry Toolkit 进行本地跟踪

Foundry Toolkit 允许使用本地 OTLP 兼容的收集器在 VS Code 中进行本地跟踪，是开发和调试过程中的理想选择。

该工具包通过 OpenTelemetry 支持 Foundry 智能体服务、OpenAI、Anthropic 和 LangChain 等 AI 框架。 可以在 VS Code 中即时查看跟踪，而无需云访问。

有关详细的设置说明和 SDK 特定代码示例，请参阅 Foundry Toolkit 中的跟踪。

查看和分析跟踪数据

在 Foundry 门户中查看跟踪

在 Foundry 项目中，转到代理或工作流中的 “跟踪 ”选项卡。 可以对过去 90 天内引入的跟踪进行搜索、筛选或排序。

选择一个跟踪，逐步浏览每个跨度，识别问题，并观察应用程序的响应方式。 这有助于调试和查明应用程序中的问题。

在 Azure Monitor 中查看跟踪

您的跟踪信息将发送到 Azure Monitor Application Insights，您可以在那里查看。

有关如何将跟踪发送到Azure Monitor和创建Azure Monitor资源的详细信息，请参阅 Azure Monitor OpenTelemetry 文档。

查看对话结果

对话是用户和代理之间端到端对话历史记录的持久上下文。 在 Foundry 门户中，可以查看智能体运行的现成“对话”结果以及“跟踪”页上的跟踪。

你可以选择对话搜索响应 ID，或通过映射到此对话的跟踪 ID 搜索。 然后，选择 “对话 ID ”以查看对话：

  • 对话历史记录详细信息
  • 运行中的响应信息和令牌
  • 有序操作、运行步骤和工具调用
  • 用户和代理之间的输入和输出

Foundry 中“对话详细信息”窗格的屏幕截图，其中显示了包含跟踪时间线和运行步骤详细信息的对话 ID。

验证跟踪功能是否正常

  1. 确认项目已连接到 Application Insights。 如果需要，请遵循 将 Application Insights 连接到 Foundry 项目的步骤。

  2. 至少运行一次代理或工作流（例如，使用门户或应用）。

  3. 在 Foundry 项目中，打开 “踪迹” 视图并确认新踪迹出现。

    跟踪正常工作时，会看到包含时间戳、持续时间和状态指示器的最新跟踪的列表。 选择一个跟踪以查看其跨度详细信息。

如果未看到新跟踪，请等待几分钟并刷新，然后查看 故障排除。

安全和隐私

跟踪可以捕获敏感信息（例如用户输入、模型输出以及工具参数和结果）。 使用以下做法来降低风险：

  • 不要在提示、工具参数或跨属性中存储机密、凭据或令牌。
  • 在遥测中显示个人数据之前，请对个人数据和其他敏感内容进行修订或最小化。
  • 将跟踪数据视为生产遥测数据，并应用用于日志和指标的相同访问控制和保留策略。

有关更多指导，请参阅 安全和隐私。

数据保留和成本

Foundry 将跟踪信息存储于连接到您项目的 Application Insights 资源中。 数据保留和计费遵循 Application Insights 和 Log Analytics 配置。

故障 排除

问题 原因 分辨率
您在 Foundry 平台上看不到任何记录 跟踪未连接，近期没有任何流量，或者引入存在延迟 确认 Application Insights 连接、生成新的代理流量，并在几分钟后刷新。
查询或查看遥测时看到授权错误 Application Insights 或 Log Analytics 缺少 RBAC 权限 请确认对 访问控制（IAM） 中连接的资源的访问。 对于日志查询，请分配 Log Analytics 读取者角色。
客户端跟踪未显示 未安装或配置仪表设备 重新检查包安装，并按照使用 Microsoft Foundry SDK (Python) 的客户端跟踪中链接的 SDK 指南执行操作。
敏感内容出现在跟踪记录中 提示、工具参数或输出包含敏感数据 在输入遥测数据之前，请对敏感数据进行修订，并遵循 安全和隐私方面的指导。

相关内容

设置跟踪后，请浏览这些资源，加深理解并扩展可观测性功能：

  • Last updated on