在 Microsoft Foundry 工具包中收集並檢查追蹤

使用 Microsoft Foundry Toolkit for Visual Studio Code 來收集本地追蹤或查看部署至 Microsoft Foundry 的代理程式的遙測資料。 追蹤會將某個要求所記錄的作業分組。 每個作業都是一個跨度,包含計時、狀態,以及檢測所提供的任何屬性或是事件。

本文先介紹本地收集,接著是部署代理的雲端追蹤。 選擇與您調查作業相符的資料來源:

Approach 使用目的 資料與職責
代理程式檢查器 發送本地請求、檢視即時回應與工具事件,或在中斷點暫停程式碼。 伺服器提供協定事件與開發診斷。 此方法不需要 OTLP 收集器,也不會建立雲端追蹤記錄。
局部追蹤 在開發期間比較所記錄的模型、工具及 Agent 跨度。 你的應用程式會將遙測資料匯出到工具包的本地收集器。 您可以設定檢測並管理所儲存的本機資料。
託管代理程式追蹤 調查由部署至 Foundry 的 Agent 所處理的要求。 這些痕跡存在於專案連接的 Application Insights 資源中。 存取權、保留和收費依照 Azure 資源配置進行。

託管代理會在 Foundry 代理服務中執行你的自訂程式碼。 Foundry 負責主機管理,但你仍需負責程式碼和相依性。 追蹤並不能取代 代理程式的建立與部署。

Prerequisites

本地收集不需要 Application Insights 或雲端遙測權限。 模型呼叫和工具執行仍可能使用遠端服務,並產生費用。

收集本機追蹤資料

本地收集器透過 OpenTelemetry 協定(OTLP)接收遙測資料。 它不會自動為應用程式進行插裝。 您的架構或檢測程式庫必須建立跨度,並將其匯出至收集器。

SDK 與語言設定

具有內建插裝的 SDK 仍然需要匯出器。 其他 SDK 則使用獨立的插樁套件。

SDK 或框架 Python JavaScript 與 TypeScript(Node.js)
Microsoft 代理程式架構 內建的 OpenTelemetry 檢測。 沒有專門的 Toolkit 設定指引。
Azure AI Inference SDK (preview) Azure SDK instrumentor. Azure SDK 檢測。
Foundry Projects SDK 客戶端檢測工具(預覽)。 為底層的 OpenAI 或 Azure SDK 用戶端加入監測。
Foundry classic Agents SDK Azure SDK instrumentor. 沒有專門的 Toolkit 設定指引。
Anthropic OpenLLMetry instrumentor。 Traceloop 檢測。
Google GenAI(Gemini) Google GenAI OpenTelemetry instrumentor。 沒有專門的 Toolkit 設定指引。
LangChain OpenLLMetry instrumentor。 Traceloop 檢測。
OpenAI SDK,包括 Azure OpenAI 客戶端 OpenLLMetry instrumentor。 Traceloop 檢測。
OpenAI 智能代理 SDK OpenLLMetry 追蹤處理器。 沒有專門的 Toolkit 設定指引。

「沒有專用工具包設定指引」是指該語言沒有專門的 SDK 設定路徑,並不是說收集器會拒絕它的遙測。 收集器接受 OTLP 資料。 插樁器決定擷取哪些操作與訊息細節。

這些範例使用選定的檢測選項,並非相容程式庫的完整清單。 OpenLLMetry 和 Traceloop 檢測是非 Microsoft 程式庫。

設定檢測

請對現有的 Python Agent Framework 應用程式使用此程序。 在此逐步解說中,請將 Agent 和收集器保留在相同的本機環境中。

  1. 在活動列選擇 Foundry Toolkit ,然後選擇 開發者工具>監控>追蹤。

  2. 執行應用程式前選擇 啟動收集器 。

  3. 在應用程式的 Python 環境中,如果 gRPC 匯出器尚未在你的相依中宣告,請安裝它:

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

    參考資料:OpenTelemetry Python OTLP 匯出器。

  4. 請在應用程式啟動時設定 OpenTelemetry 一次,並在建構或執行 Agent 之前完成:

    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)
    

    參考資料: Agent Framework 可觀察性。

    如果你的應用程式或主機函式庫已經設定了 OpenTelemetry 提供者,請設定其現有的匯出器,而不是新增其他提供者設定。 訊號專屬 OTEL_EXPORTER_OTLP_*_ENDPOINT 變數可以覆蓋基底端點。 檢查是否有指向其他位置的現有追蹤、記錄或計量設定。

  5. 使用應用程式的正常進入點執行應用程式,並傳送會觸發 Agent 的要求。 先讓請求完成,並給匯出器時間傳送遙測資料,再停止程序。

  6. 在 追蹤中,選擇 重新整理,然後選擇新的追蹤以檢查其 span。

Agent Framework 會檢測支援的模型用戶端、Agent 及工作流程作業。 其他架構可能需要檢測程式庫。 OTLP 相容性讓收集器能接收資料,而發射屬性與 生成式 AI 語意慣例則 決定檢視器顯示的內容。

對於其他 SDK 或語言,請使用以下設定,而非 Agent Framework 設定。 請先啟動收集器,在建立用戶端之前設定檢測,然後執行您的應用程式並重新整理追蹤清單。

本地 OTLP 收集器運行中的截圖,包含 gRPC 和 HTTP 端點,以及已填充的追蹤清單。

收集器端點

將匯出器協定與收集端匹配。 工具包在本地主機上以以下預設值監聽:

出口商 終點
OTLP gRPC http://localhost:4317
OTLP HTTP trace exporter http://localhost:4318/v1/traces
OTLP HTTP 日誌匯出器 http://localhost:4318/v1/logs

部分 HTTP 匯出工具會接受http://localhost:4318,並自行附加訊號路徑。 依照匯出器的設定操作,而不是附加路徑兩次。 部分檢測程式庫會將訊息內容以記錄形式傳送,因此僅匯出跨度可能無法提供輸入與輸出詳細資料。

這些埠口與代理的 HTTP 伺服器及除錯器埠口無關。 在容器或遠端開發環境中,localhost是指該環境本身。 建立與收集器之間的適當連線,不要假設它指的是您的桌面。

Python SDK 設定

以下範例假設您的應用程式已經擁有其模型 SDK、憑證和模型設定。 從下表安裝共用相依性,以及您 SDK 的其他套件:

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

參考資料:OpenTelemetry Python SDK,OTLP 匯出器。

在應用程式啟動時新增此共用設定一次,接著新增其中一個表格資料列的檢測。 請勿將其與其他程式庫的提供者設定合併使用。

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 與跨度處理器 , 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 classic Agents 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 Inference SDK (preview) 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 客戶端。 此指引與 經典的 Agents 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 Agents 檢測、OpenAI Agents 追蹤。

此範例在加入 OpenTelemetry 處理器前,先替換現有的追蹤處理器。 若沒有該替代方案,SDK 也能將追蹤資料匯出到預設後端。 如果您需要現有的處理器,請先檢閱追蹤目的地,再進行變更。 保持啟用 SDK 追蹤,讓 OpenTelemetry 處理器能接收事件。

短期的應用程式完成其要求後,請在結束前呼叫provider.force_flush(),以傳送緩衝的跨度。 若需協助調整這些片段,請使用工具包的 追蹤程式碼生成工具。

匯出訊息日誌記錄

有些檢測器會將訊息內容以 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 日誌 SDK,OTLPLogExporter。

結束短期的應用程式之前,請呼叫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 檢測。

請在匯入或 require 您的模型 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 operations, including Azure AI Inference @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 記錄、跨度屬性和自訂檢測。 請查看連結的 instrumentor 文件,了解支援的套件和 API。

檢查並管理本地追蹤

利用 span tree 來追蹤請求從代理協調到模型與工具操作的流程。

  1. 選取緩慢或失敗的跨度。
  2. 檢查其持續時間與狀態。
  3. 開啟輸入 + 輸出,以查看所記錄的訊息(由檢測提供時),或開啟中繼資料,以查看跨度屬性。

這些範例會讓敏感內容擷取維持關閉。 沒有訊息的時序資料可能是預期結果。

如需進行受控的 Agent Framework 開發測試,請在其現有設定中設定enable_sensitive_data=True,以記錄支援的提示、回應及工具內容。 測試完成後,將其還原為 False。 其他檢測工具有各自的內容設定。

Caution

內容錄製可以捕捉個人資料、機密、工具參數及結果。 使用非敏感測試資料,並在進入遙測數據前將內容最小化或遮蔽。 不要只是為了填滿空白的輸入和輸出視圖而開啟正式環境內容記錄。

本地工作流程 span 樹截圖及所選 span 的中繼資料分頁,請求、追蹤及對話識別碼均已遮蔽。

收集的追蹤會持續存在於一個名為 traces.db 的本地 SQLite 資料庫中,位於你的使用者主資料夾下 .aitk 的子目錄 tracing 中。 關閉檢視器並不會刪除它們。

選取停止收集器,以停止本機收集。 您的 Agent 及其模型呼叫會繼續執行。 要移除本地紀錄,請在列表中選擇追蹤項目並選擇 刪除。

本機儲存體與 Application Insights 是分開的。 刪除本地追蹤不會移除雲端遙測,清除 Inspector 中的對話也不會刪除任一個儲存位置。

查看託管代理追蹤

部署之後,使用雲端追蹤來調查在 Foundry 中執行的 Agent,而不是您本機的處理程序。 工具包查詢專案連結的 Application Insights 資源。 它不會上傳你本地的追蹤資料庫。

開始之前,請先確認雲端先決條件。 僅僅存取代理程式並不表示具有查詢遙測資料的權限。

連線 Application Insights 並檢查要求

使用 Agent 的追蹤索引標籤,連線 Application Insights 並尋找已部署 Agent 的要求。

  1. 在 Foundry Toolkit 側邊欄中,依序開啟我的資源 >Agents。 選取託管 Agent 索引標籤,然後選取 Agent 的名稱。

  2. 選取追蹤。 如果專案沒有已連線的資源,請選取啟用 App Insights。

  3. 在 App Insights 設定中,選取現有的 Application Insights 資源名稱。 或者,您也可以選擇建立資源並完成所需的資源與工作區欄位。 選取提交並等候確認。

    這會改變專案共享的 Application Insights 連線,而非本地工作區偏好。 資源建立與遙測收集可能會產生 Azure 費用。 提交前請確認預期的專案與資源。

  4. 返回 Playground ,並向已部署的代理發送測試請求。

  5. 等待資料攝取完成,然後再打開 Traces。 使用時間範圍、依對話 ID 搜尋、狀態或 持續時間 篩選器來找出該請求。

    託管代理追蹤過濾器及已完成請求的截圖,資源與請求識別碼已塗黑。

  6. 選擇一條追蹤線,再選一個區間,以便在內容可用時檢視 元資料 與 輸入+輸出。

要檢查與對話相關的操作,請在追蹤列表中選擇其 對話 ID 。 對話視圖顯示操作樹和元資料。

主機代理對話截圖,包含代理、模型及工具操作與元資料,資源與對話識別碼已遮蔽。

連線 Application Insights 會啟用 Foundry 的伺服器端追蹤。 能否檢視您的模型呼叫、工具呼叫及自訂程式碼,也取決於託管程式庫與架構檢測。 請參閱在 Foundry 中設定追蹤,以進行服務端收集及其他的用戶端檢測。

Toolkit 的追蹤詳細資料查詢目前涵蓋過去七天。 這是查詢視窗,不是保留設定。 如需較舊的資料,請使用 Foundry 入口網站或 Azure 監視器,實際可用範圍取決於已連線工作區的保留設定。

資料、存取、保存期間與成本

在啟用內容擷取或連接雲端資源之前,先決定遙測數據應該放在哪裡。 同一個要求可能會產生本機跨度、雲端遙測,以及傳送給模型或工具提供者的資料。

數據源 Responsibilities
本機追蹤 保護對本地資料庫及複製資料的存取。 停止收集器並不會停止你應用程式中設定的其他匯出器。
雲端追蹤 Application Insights 和 Log Analytics 會控制存取權、保留期及遙測費用。 Toolkit 篩選條件不會變更那些原則。
模型與工具呼叫 本機收集不會阻止要求離開您的電腦。 檢視所有連接服務的資料處理,包括非 Microsoft 工具。

請參考 Foundry 的追蹤指引,關於 安全與隱私 及 資料保存與成本。 如需生產環境身分識別、網路隔離及下游存取,請遵循受託 Agent 的安全性與資料處理。 不要把本地憑證當作已部署代理的權限。

Troubleshooting

Issue 要檢查的事項
追蹤未提供於側邊欄中。 確認目前的擴充功能已安裝,並在您執行它的環境中啟用。 本地追蹤需要載入其原生 SQLite 元件。
收集器未啟動。 檢查是否有其他程序使用 4317 或 4318 埠,並檢視 Toolkit 輸出。 避免在相同連接埠上使用彼此競爭的收集器。
本地請求成功,但沒有任何追蹤資訊出現。 確認檢測在要求之前執行、收集器正在執行,且匯出工具使用正確的通訊協定與端點。 檢查端點覆寫、匯出器錯誤和緩衝遙測,然後選擇 刷新。
跨度出現,但沒有訊息。 請檢查內容錄製設定及受支援的屬性。 有些函式庫還需要日誌匯出器。 缺少內容不一定代表收集失敗。
雲端追蹤是空的。 確認專案與 Application Insights 的連線,產生新流量,擴大時間範圍,並允許擷取延遲。
雲端查詢會因授權錯誤而失敗。 請使用服務先決條件,檢查 Application Insights 和 Log Analytics 的讀取存取權,包括受保護的資料表。
較舊的追蹤在 Toolkit 中沒有詳細資料。 明細查詢涵蓋七天。 在 Foundry 或 Azure 監視器 查詢較舊的保留紀錄。