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

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

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

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

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

Prerequisites

• Visual Studio Code 搭配目前公開的 Foundry Toolkit 擴充功能。 請參閱 安裝 Foundry 工具包。
• 一個你可以在本地執行的應用程式，並且已經設定好模型和工具連線。
• 第一個範例為 Microsoft Agent Framework Python 應用程式及其所選的 Python 環境。 其他 SDK 請使用 Python 或 JavaScript 和 TypeScript 的設定。
• 對於雲端追蹤，您需要有已部署的代理程式，以及已連線到其 Foundry 專案的 Application Insights 資源，或具備連線或建立該資源的權限。
• 對於雲端查詢，在已連線的 Application Insights 資源上需具有 Log Analytics Reader 角色。 對於 受保護的資料表，也指派 特權監控資料讀取器（Privileged Monitoring Data Reader）角色。 請參閱 Foundry 的追蹤先決條件。

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

收集本機追蹤資料

本地收集器透過 OpenTelemetry 協定（OTLP）接收遙測資料。 它不會自動為應用程式進行插裝。 你的框架或檢測程式庫必須建立 span，並將其匯出至收集器。

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 應用程式。 讓代理程式和收集器在同一個本機環境中完成此逐步解說。

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)
   

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

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

5. 以正常入口點執行應用程式，並發送一個可觸發代理程式的請求。 先讓請求完成，並給匯出器時間傳送遙測資料，再停止程序。

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

代理框架為支援的模型客戶端、代理及工作流程操作提供監測支援。 其他框架可能需要監測程式庫。 OTLP 相容性讓收集器能接收資料，而發射屬性與 生成式 AI 語意慣例則 決定檢視器顯示的內容。

對於其他 SDK 或語言，請使用以下設定，而非 Agent Framework 設定。 先啟動收集器，先設定監測程式，再建立客戶端，然後執行應用程式並刷新追蹤清單。

收集器端點

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

出口商	終點
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，並自行附加訊號路徑。 依照匯出器的設定操作，而不是附加路徑兩次。 有些插樁函式庫以日誌記錄形式傳送訊息內容，因此僅匯出 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 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 代理程式檢測，OpenAI 代理程式追蹤。

此範例在加入 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 註冊 instrumentation。 此範例使用 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，OpenAIinstrumentation。

在匯入或 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 之後載入 instrumentation 可能會使呼叫未經插樁。 關閉時，在請求完成後等待 provider.shutdown()，以匯出已緩衝的 spans。

Important

這些範例會關閉所列的 GenAI 插樁程式的訊息內容擷取。 這並非一般性的編修遮蔽保證。 在分享資料前，請先審查其他匯出器、SDK 日誌、span 屬性和自訂插樁。 請查看連結的 instrumentor 文件，了解支援的套件和 API。

檢查並管理本地追蹤

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

1. 選擇一個緩慢或失敗的 span。
2. 檢查其持續時間與狀態。
3. 當儀器提供時，開啟 Input + Output 以查看記錄的訊息，或開啟 Metadata 以查看 span 屬性。

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

對於受控的代理框架開發測試，應將現有設定中的 enable_sensitive_data=True 設為記錄支援的提示詞、回應及工具內容。 測試完成後，將其還原為 False。 其他檢測工具有自己的內容設定。

Caution

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

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

選擇 停止 收集器以停止本地收款。 你的代理人及其模範通話會繼續進行。 要移除本地紀錄，請在列表中選擇追蹤項目並選擇 刪除。

本地儲存與應用洞察是分開的。 刪除本地追蹤不會移除雲端遙測，清除 Inspector 中的對話也不會刪除任一個儲存位置。

查看託管代理追蹤

部署後，利用雲端追蹤來調查 Foundry 中執行的代理程式，而非本地程序。 工具包查詢專案連結的 Application Insights 資源。 它不會上傳你本地的追蹤資料庫。

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

連結 Application Insights 並檢視請求

使用代理的 追蹤 索引標籤來連線到 Application Insights，並尋找已部署代理程式的要求。

1. 在 Foundry 工具包側邊欄，打開 「我的資源>代理人」。 選擇「 託管代理人 」標籤，然後選擇代理人名稱。

2. 選擇追蹤。 如果專案沒有連結資源，請選擇 啟用應用程式洞察。

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 的追蹤指引，關於 安全與隱私 及 資料保存與成本。 在生產識別、網路隔離及下游存取方面，請遵循 託管代理程式的安全與資料處理。 不要把本地憑證當作已部署代理的權限。

Troubleshooting

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

相關內容

• 使用 Agent Inspector 為代理程式除錯。
• 代理追蹤概念。
• 設定用戶端追蹤。