編輯

AI Toolkit 中的追蹤

Name: Visual Studio Code
Author: Microsoft

AI Toolkit 提供追蹤功能，幫助您監控和分析 AI 應用程式的效能。您可以追蹤 AI 應用程式的執行情況，包括與生成式 AI 模型的互動，從而深入瞭解它們的行為和效能。

AI Toolkit 託管一個本地 HTTP 和 gRPC 伺服器來收集追蹤資料。收集器伺服器與 OTLP (OpenTelemetry Protocol) 相容，大多數語言模型 SDK 要麼直接支援 OTLP，要麼擁有非 Microsoft 的檢測庫來支援它。使用 AI Toolkit 視覺化收集到的檢測資料。

所有支援 OTLP 並遵循生成式 AI 系統語義約定的框架或 SDK 均受支援。下表包含經過相容性測試的常見 AI SDK。

	Azure AI 推理	Azure AI Foundry 代理服務	Anthropic	Gemini	LangChain	OpenAI SDK ₃	OpenAI 代理 SDK
Python	✅	✅	✅ (traceloop)_1,2	✅	✅ (LangSmith)_1,2	✅ (opentelemetry-python-contrib)₁	✅ (Logfire)_1,2
TS/JS	✅	✅	✅ (traceloop)_1,2	❌	✅ (traceloop)_1,2	✅ (traceloop)_1,2	❌

括號中的 SDK 是非 Microsoft 工具，它們添加了 OTLP 支援，因為官方 SDK 不支援 OTLP。

這些工具不完全遵循 OpenTelemetry 生成式 AI 系統的規則。

對於 OpenAI SDK，僅支援聊天完成 API。尚不支援響應 API。

如何開始追蹤

透過在樹檢視中選擇追蹤來開啟追蹤 webview。
選擇啟動收集器按鈕以啟動本地 OTLP 追蹤收集器伺服器。
使用程式碼片段啟用檢測。有關不同語言和 SDK 的程式碼片段，請參閱設定檢測部分。
透過執行您的應用程式生成追蹤資料。
在追蹤 webview 中，選擇重新整理按鈕以檢視新的追蹤資料。

設定檢測

在您的 AI 應用程式中設定追蹤以收集追蹤資料。以下程式碼片段展示瞭如何為不同的 SDK 和語言設定追蹤。

所有 SDK 的過程都相似

將追蹤新增到您的 LLM 或代理應用程式中。
設定 OTLP 追蹤匯出器以使用 AITK 本地收集器。

Azure AI 推理 SDK - Python

安裝

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http azure-ai-inference[opentelemetry]

設定

import os
os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "true"
os.environ["AZURE_SDK_TRACING_IMPLEMENTATION"] = "opentelemetry"

from opentelemetry import trace, _events
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk._logs import LoggerProvider
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk._events import EventLoggerProvider
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter

resource = Resource(attributes={
    "service.name": "opentelemetry-instrumentation-azure-ai-agents"
})
provider = TracerProvider(resource=resource)
otlp_exporter = OTLPSpanExporter(
    endpoint="https://:4318/v1/traces",
)
processor = BatchSpanProcessor(otlp_exporter)
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

logger_provider = LoggerProvider(resource=resource)
logger_provider.add_log_record_processor(
    BatchLogRecordProcessor(OTLPLogExporter(endpoint="https://:4318/v1/logs"))
)
_events.set_event_logger_provider(EventLoggerProvider(logger_provider))

from azure.ai.inference.tracing import AIInferenceInstrumentor
AIInferenceInstrumentor().instrument(True)

Azure AI 推理 SDK - TypeScript/JavaScript

安裝

npm install @azure/opentelemetry-instrumentation-azure-sdk @opentelemetry/api @opentelemetry/exporter-trace-otlp-proto @opentelemetry/instrumentation @opentelemetry/resources @opentelemetry/sdk-trace-node

設定

const { context } = require('@opentelemetry/api');
const { resourceFromAttributes } = require('@opentelemetry/resources');
const {
  NodeTracerProvider,
  SimpleSpanProcessor
} = require('@opentelemetry/sdk-trace-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-proto');

const exporter = new OTLPTraceExporter({
  url: 'https://:4318/v1/traces'
});
const provider = new NodeTracerProvider({
  resource: resourceFromAttributes({
    'service.name': 'opentelemetry-instrumentation-azure-ai-inference'
  }),
  spanProcessors: [new SimpleSpanProcessor(exporter)]
});
provider.register();

const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const {
  createAzureSdkInstrumentation
} = require('@azure/opentelemetry-instrumentation-azure-sdk');

registerInstrumentations({
  instrumentations: [createAzureSdkInstrumentation()]
});

Azure AI Foundry 代理服務 - Python

安裝

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http azure-ai-inference[opentelemetry]

設定

import os
os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "true"
os.environ["AZURE_SDK_TRACING_IMPLEMENTATION"] = "opentelemetry"

from opentelemetry import trace, _events
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk._logs import LoggerProvider
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk._events import EventLoggerProvider
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter

resource = Resource(attributes={
    "service.name": "opentelemetry-instrumentation-azure-ai-agents"
})
provider = TracerProvider(resource=resource)
otlp_exporter = OTLPSpanExporter(
    endpoint="https://:4318/v1/traces",
)
processor = BatchSpanProcessor(otlp_exporter)
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

logger_provider = LoggerProvider(resource=resource)
logger_provider.add_log_record_processor(
    BatchLogRecordProcessor(OTLPLogExporter(endpoint="https://:4318/v1/logs"))
)
_events.set_event_logger_provider(EventLoggerProvider(logger_provider))

from azure.ai.agents.telemetry import AIAgentsInstrumentor
AIAgentsInstrumentor().instrument(True)

Azure AI Foundry 代理服務 - TypeScript/JavaScript

安裝

npm install @azure/opentelemetry-instrumentation-azure-sdk @opentelemetry/api @opentelemetry/exporter-trace-otlp-proto @opentelemetry/instrumentation @opentelemetry/resources @opentelemetry/sdk-trace-node

設定

const { context } = require('@opentelemetry/api');
const { resourceFromAttributes } = require('@opentelemetry/resources');
const {
  NodeTracerProvider,
  SimpleSpanProcessor
} = require('@opentelemetry/sdk-trace-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-proto');

const exporter = new OTLPTraceExporter({
  url: 'https://:4318/v1/traces'
});
const provider = new NodeTracerProvider({
  resource: resourceFromAttributes({
    'service.name': 'opentelemetry-instrumentation-azure-ai-inference'
  }),
  spanProcessors: [new SimpleSpanProcessor(exporter)]
});
provider.register();

const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const {
  createAzureSdkInstrumentation
} = require('@azure/opentelemetry-instrumentation-azure-sdk');

registerInstrumentations({
  instrumentations: [createAzureSdkInstrumentation()]
});

Anthropic - Python

安裝

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http opentelemetry-instrumentation-anthropic

設定

from opentelemetry import trace, _events
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk._logs import LoggerProvider
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk._events import EventLoggerProvider
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter

resource = Resource(attributes={
    "service.name": "opentelemetry-instrumentation-anthropic-traceloop"
})
provider = TracerProvider(resource=resource)
otlp_exporter = OTLPSpanExporter(
    endpoint="https://:4318/v1/traces",
)
processor = BatchSpanProcessor(otlp_exporter)
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

logger_provider = LoggerProvider(resource=resource)
logger_provider.add_log_record_processor(
    BatchLogRecordProcessor(OTLPLogExporter(endpoint="https://:4318/v1/logs"))
)
_events.set_event_logger_provider(EventLoggerProvider(logger_provider))

from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor
AnthropicInstrumentor().instrument()

Anthropic - TypeScript/JavaScript

安裝

npm install @traceloop/node-server-sdk

設定

const { initialize } = require('@traceloop/node-server-sdk');
const { trace } = require('@opentelemetry/api');

initialize({
  appName: 'opentelemetry-instrumentation-anthropic-traceloop',
  baseUrl: 'https://:4318',
  disableBatch: true
});

Google Gemini - Python

安裝

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http opentelemetry-instrumentation-google-genai

設定

from opentelemetry import trace, _events
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk._logs import LoggerProvider
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk._events import EventLoggerProvider
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter

resource = Resource(attributes={
    "service.name": "opentelemetry-instrumentation-google-genai"
})
provider = TracerProvider(resource=resource)
otlp_exporter = OTLPSpanExporter(
    endpoint="https://:4318/v1/traces",
)
processor = BatchSpanProcessor(otlp_exporter)
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

logger_provider = LoggerProvider(resource=resource)
logger_provider.add_log_record_processor(
    BatchLogRecordProcessor(OTLPLogExporter(endpoint="https://:4318/v1/logs"))
)
_events.set_event_logger_provider(EventLoggerProvider(logger_provider))

from opentelemetry.instrumentation.google_genai import GoogleGenAiSdkInstrumentor
GoogleGenAiSdkInstrumentor().instrument(enable_content_recording=True)

LangChain - Python

安裝

pip install langsmith[otel]

設定

import os
os.environ["LANGSMITH_OTEL_ENABLED"] = "true"
os.environ["LANGSMITH_TRACING"] = "true"
os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "https://:4318"

LangChain - TypeScript/JavaScript

安裝

npm install @traceloop/node-server-sdk

設定

const { initialize } = require('@traceloop/node-server-sdk');
initialize({
  appName: 'opentelemetry-instrumentation-langchain-traceloop',
  baseUrl: 'https://:4318',
  disableBatch: true
});

OpenAI - Python

安裝

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http opentelemetry-instrumentation-openai-v2

設定

from opentelemetry import trace, _events
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk._logs import LoggerProvider
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk._events import EventLoggerProvider
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor
import os

os.environ["OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"] = "true"

# Set up resource
resource = Resource(attributes={
    "service.name": "opentelemetry-instrumentation-openai"
})

# Set up tracer provider
trace.set_tracer_provider(TracerProvider(resource=resource))

# Configure OTLP exporter
otlp_exporter = OTLPSpanExporter(
    endpoint="https://:4318/v1/traces"
)

# Add span processor
trace.get_tracer_provider().add_span_processor(
    BatchSpanProcessor(otlp_exporter)
)

# Set up logger provider
logger_provider = LoggerProvider(resource=resource)
logger_provider.add_log_record_processor(
    BatchLogRecordProcessor(OTLPLogExporter(endpoint="https://:4318/v1/logs"))
)
_events.set_event_logger_provider(EventLoggerProvider(logger_provider))

# Enable OpenAI instrumentation
OpenAIInstrumentor().instrument()

OpenAI - TypeScript/JavaScript

安裝

npm install @traceloop/instrumentation-openai @traceloop/node-server-sdk

設定

const { initialize } = require('@traceloop/node-server-sdk');
initialize({
  appName: 'opentelemetry-instrumentation-openai-traceloop',
  baseUrl: 'https://:4318',
  disableBatch: true
});

OpenAI 代理 SDK - Python

安裝

pip install logfire

設定

import logfire
import os

os.environ["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"] = "https://:4318/v1/traces"

logfire.configure(
    service_name="opentelemetry-instrumentation-openai-agents-logfire",
    send_to_logfire=False,
)
logfire.instrument_openai_agents()

示例：使用 Azure AI 推理 SDK 設定追蹤

以下端到端示例使用 Python 中的 Azure AI 推理 SDK，並展示瞭如何設定追蹤提供程式和檢測。

先決條件

要執行此示例，您需要以下先決條件

設定您的開發環境

使用以下說明部署包含執行此示例所需所有依賴項的預配置開發環境。

設定 GitHub 個人訪問令牌

使用免費的GitHub 模型作為示例模型。

開啟GitHub 開發人員設定並選擇生成新令牌。

重要
令牌需要models:read許可權，否則將返回未經授權。令牌將傳送到 Microsoft 服務。
建立環境變數

建立環境變數以使用以下程式碼片段之一將您的令牌設定為客戶端程式碼的金鑰。將<your-github-token-goes-here>替換為您的實際 GitHub 令牌。

bash
```
export GITHUB_TOKEN="<your-github-token-goes-here>"
```
powershell
```
$Env:GITHUB_TOKEN="<your-github-token-goes-here>"
```
Windows 命令提示符
```
set GITHUB_TOKEN=<your-github-token-goes-here>
```

安裝 Python 包

以下命令安裝使用 Azure AI 推理 SDK 進行追蹤所需的 Python 包

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http azure-ai-inference[opentelemetry]

設定追蹤
1. 在您的計算機上為專案建立一個新的本地目錄。
```
mkdir my-tracing-app
```
2. 導航到您建立的目錄。
```
cd my-tracing-app
```
3. 在該目錄中開啟 Visual Studio Code
```
code .
```

建立 Python 檔案

在my-tracing-app目錄中，建立一個名為main.py的 Python 檔案。

您將新增程式碼來設定追蹤並與 Azure AI 推理 SDK 進行互動。

將以下程式碼新增到main.py並儲存檔案

import os

### Set up for OpenTelemetry tracing ###
os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "true"
os.environ["AZURE_SDK_TRACING_IMPLEMENTATION"] = "opentelemetry"

from opentelemetry import trace, _events
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk._logs import LoggerProvider
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk._events import EventLoggerProvider
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter

github_token = os.environ["GITHUB_TOKEN"]

resource = Resource(attributes={
    "service.name": "opentelemetry-instrumentation-azure-ai-inference"
})
provider = TracerProvider(resource=resource)
otlp_exporter = OTLPSpanExporter(
    endpoint="https://:4318/v1/traces",
)
processor = BatchSpanProcessor(otlp_exporter)
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

logger_provider = LoggerProvider(resource=resource)
logger_provider.add_log_record_processor(
    BatchLogRecordProcessor(OTLPLogExporter(endpoint="https://:4318/v1/logs"))
)
_events.set_event_logger_provider(EventLoggerProvider(logger_provider))

from azure.ai.inference.tracing import AIInferenceInstrumentor
AIInferenceInstrumentor().instrument()
### Set up for OpenTelemetry tracing ###

from azure.ai.inference import ChatCompletionsClient
from azure.ai.inference.models import UserMessage
from azure.ai.inference.models import TextContentItem
from azure.core.credentials import AzureKeyCredential

client = ChatCompletionsClient(
    endpoint = "https://models.inference.ai.azure.com",
    credential = AzureKeyCredential(github_token),
    api_version = "2024-08-01-preview",
)

response = client.complete(
    messages = [
        UserMessage(content = [
            TextContentItem(text = "hi"),
        ]),
    ],
    model = "gpt-4.1",
    tools = [],
    response_format = "text",
    temperature = 1,
    top_p = 1,
)

print(response.choices[0].message.content)

執行程式碼
1. 在 Visual Studio Code 中開啟一個新終端。
2. 在終端中，使用命令python main.py執行程式碼。
在 AI Toolkit 中檢查追蹤資料

執行程式碼並重新整理追蹤 webview 後，列表中會有一個新的追蹤。

選擇追蹤以開啟追蹤詳細資訊 webview。

在左側的 span 樹檢視中檢查應用程式的完整執行流。

在右側的 span 詳細資訊檢視中選擇一個 span，以在輸入 + 輸出選項卡中檢視生成式 AI 訊息。

選擇元資料選項卡以檢視原始元資料。

您學到了什麼

在本文中，您學習瞭如何

使用 Azure AI 推理 SDK 和 OpenTelemetry 在您的 AI 應用程式中設定追蹤。
配置 OTLP 追蹤匯出器以將追蹤資料傳送到本地收集器伺服器。
執行您的應用程式以生成追蹤資料並在 AI Toolkit webview 中檢視追蹤。
透過 OTLP 使用多種 SDK 和語言（包括 Python 和 TypeScript/JavaScript）以及非 Microsoft 工具的追蹤功能。
使用提供的程式碼片段檢測各種 AI 框架（Anthropic、Gemini、LangChain、OpenAI 等）。
使用追蹤 webview UI，包括啟動收集器和重新整理按鈕，管理追蹤資料。
設定您的開發環境，包括環境變數和包安裝，以啟用追蹤。
使用 span 樹和詳細資訊檢視分析應用程式的執行流，包括生成式 AI 訊息流和元資料。

07/29/2025