Foundry Toolkitでのトレース

Name: Visual Studio Code
Author: Microsoft

Foundry Toolkitは、AIアプリケーションのパフォーマンスを監視および分析するのに役立つトレース機能を提供します。生成AIモデルとのインタラクションを含むAIアプリケーションの実行をトレースして、その動作とパフォーマンスに関する洞察を得ることができます。

Foundry Toolkitは、トレースデータを収集するためにローカルのHTTPおよびgRPCサーバーをホストします。このコレクターサーバーはOTLP (OpenTelemetry Protocol) と互換性があり、ほとんどの言語モデルSDKはOTLPを直接サポートするか、またはそれをサポートするための非Microsoftインストゥルメンテーションライブラリを持っています。Foundry Toolkitを使用して、収集されたインストゥルメンテーションデータを視覚化します。

OTLPをサポートし、生成AIシステムのセマンティック規約に従うすべてのフレームワークまたはSDKがサポートされています。以下の表には、互換性がテストされた一般的なAI SDKが含まれています。

	Azure AI 推論	Foundry Agent Service	Anthropic	Gemini	LangChain	OpenAI SDK ₃	OpenAI Agents SDK
Python	✅	✅	✅ (traceloop, monocle)_1,2	✅ (monocle)	✅ (LangSmith, monocle)_1,2	✅ (opentelemetry-python-contrib, monocle)₁	✅ (Logfire, monocle)_1,2
TS/JS	✅	✅	✅ (traceloop)_1,2	❌	✅ (traceloop)_1,2	✅ (traceloop)_1,2	❌

括弧内のSDKは、公式SDKがOTLPをサポートしていないため、OTLPサポートを追加する非Microsoftツールです。

これらのツールは、生成AIシステムに対するOpenTelemetryの規則を完全に遵守していません。

OpenAI SDKでは、Chat Completions APIのみがサポートされています。Responses APIはまだサポートされていません。

トレースを開始する方法

ツリービューでTracingを選択して、トレースウェブビューを開きます。
Start Collectorボタンを選択して、ローカルのOTLPトレースコレクターサーバーを開始します。
コードスニペットでインストゥルメンテーションを有効にします。異なる言語とSDKのコードスニペットについては、「インストゥルメンテーションのセットアップ」セクションを参照してください。
アプリを実行してトレースデータを生成します。
トレースウェブビューで、Refreshボタンを選択して新しいトレースデータを表示します。

インストゥルメンテーションのセットアップ

AIアプリケーションでトレースをセットアップしてトレースデータを収集します。以下のコードスニペットは、異なるSDKと言語でトレースをセットアップする方法を示しています。

プロセスはすべてのSDKで類似しています。

LLMまたはエージェントアプリにトレースを追加します。
AITKローカルコレクターを使用するようにOTLPトレースエクスポーターをセットアップします。

Azure AI Inference 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 Inference 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()]
});

Foundry Agent Service - 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)

Foundry Agent Service - 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

OpenTelemetry

インストール

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()

Monocle

インストール

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http monocle_apptrace

セットアップ

from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

# Import monocle_apptrace
from monocle_apptrace import setup_monocle_telemetry

# Setup Monocle telemetry with OTLP span exporter for traces
setup_monocle_telemetry(
    workflow_name="opentelemetry-instrumentation-anthropic",
    span_processors=[
        BatchSpanProcessor(
            OTLPSpanExporter(endpoint="https://:4318/v1/traces")
        )
    ]
)

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

OpenTelemetry

インストール

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)

Monocle

インストール

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http monocle_apptrace

セットアップ

from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

# Import monocle_apptrace
from monocle_apptrace import setup_monocle_telemetry

# Setup Monocle telemetry with OTLP span exporter for traces
setup_monocle_telemetry(
    workflow_name="opentelemetry-instrumentation-google-genai",
    span_processors=[
        BatchSpanProcessor(
            OTLPSpanExporter(endpoint="https://:4318/v1/traces")
        )
    ]
)

LangChain - Python

LangSmith

インストール

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"

Monocle

インストール

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http monocle_apptrace

セットアップ

from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

# Import monocle_apptrace
from monocle_apptrace import setup_monocle_telemetry

# Setup Monocle telemetry with OTLP span exporter for traces
setup_monocle_telemetry(
    workflow_name="opentelemetry-instrumentation-langchain",
    span_processors=[
        BatchSpanProcessor(
            OTLPSpanExporter(endpoint="https://:4318/v1/traces")
        )
    ]
)

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

OpenTelemetry

インストール

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"
})

# Create 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()

Monocle

インストール

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http monocle_apptrace

セットアップ

from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

# Import monocle_apptrace
from monocle_apptrace import setup_monocle_telemetry

# Setup Monocle telemetry with OTLP span exporter for traces
setup_monocle_telemetry(
    workflow_name="opentelemetry-instrumentation-openai",
    span_processors=[
        BatchSpanProcessor(
            OTLPSpanExporter(endpoint="https://:4318/v1/traces")
        )
    ]
)

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 Agents SDK - Python

Logfire

インストール

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()

Monocle

インストール

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http monocle_apptrace

セットアップ

from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

# Import monocle_apptrace
from monocle_apptrace import setup_monocle_telemetry

# Setup Monocle telemetry with OTLP span exporter for traces
setup_monocle_telemetry(
    workflow_name="opentelemetry-instrumentation-openai-agents",
    span_processors=[
        BatchSpanProcessor(
            OTLPSpanExporter(endpoint="https://:4318/v1/traces")
        )
    ]
)

例 1: Opentelemetry を使用して Azure AI Inference SDK でトレースをセットアップする

以下のエンドツーエンドの例では、PythonのAzure AI Inference SDKを使用し、トレースプロバイダーとインストゥルメンテーションをセットアップする方法を示します。

前提条件

この例を実行するには、以下の前提条件が必要です。

開発環境のセットアップ

この例を実行するために必要なすべての依存関係を含む、事前に構成された開発環境をデプロイするには、以下の手順を使用してください。

GitHub 個人アクセストークンのセットアップ

例のモデルとして、無料のGitHub モデルを使用します。

GitHub Developer Settingsを開き、Generate new tokenを選択します。

重要
トークンには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 Inference 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 Inference 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を使用してコードを実行します。
Foundry Toolkitでトレースデータを確認する

コードを実行し、トレースウェブビューを更新すると、リストに新しいトレースが表示されます。

トレースを選択して、トレース詳細ウェブビューを開きます。

左側のスパンツリービューで、アプリの完全な実行フローを確認します。

右側のスパン詳細ビューでスパンを選択すると、Input + Outputタブに生成AIメッセージが表示されます。

Metadataタブを選択して、生のメタデータを表示します。

例 2: Monocle を使用して OpenAI Agents SDK でトレースをセットアップする

以下のエンドツーエンドの例では、PythonのOpenAI Agents SDKとMonocleを使用し、マルチエージェントの旅行予約システムでトレースをセットアップする方法を示します。

前提条件

この例を実行するには、以下の前提条件が必要です。

開発環境のセットアップ

この例を実行するために必要なすべての依存関係を含む、事前に構成された開発環境をデプロイするには、以下の手順を使用してください。

環境変数の作成

以下のいずれかのコードスニペットを使用して、OpenAI APIキーの環境変数を作成します。<your-openai-api-key>を実際のOpenAI APIキーに置き換えてください。

bash
```
export OPENAI_API_KEY="<your-openai-api-key>"
```
powershell
```
$Env:OPENAI_API_KEY="<your-openai-api-key>"
```
Windows コマンドプロンプト
```
set OPENAI_API_KEY=<your-openai-api-key>
```
または、プロジェクトディレクトリに.envファイルを作成します。
```
OPENAI_API_KEY=<your-openai-api-key>
```
Python パッケージのインストール

以下の内容でrequirements.txtファイルを作成します。
```
opentelemetry-sdk
opentelemetry-exporter-otlp-proto-http
monocle_apptrace
openai-agents
python-dotenv
```
次を使用してパッケージをインストールします。
```
pip install -r requirements.txt
```
トレースのセットアップ
1. プロジェクト用にコンピューター上に新しいローカルディレクトリを作成します。
```
mkdir my-agents-tracing-app
```
2. 作成したディレクトリに移動します。
```
cd my-agents-tracing-app
```
3. そのディレクトリでVisual Studio Codeを開きます。
```
code .
```

Python ファイルの作成

my-agents-tracing-appディレクトリに、main.pyという名前のPythonファイルを作成します。

Monocleでトレースをセットアップし、OpenAI Agents SDKと対話するためのコードを追加します。

以下のコードをmain.pyに追加してファイルを保存します。

import os

from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()

from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

# Import monocle_apptrace
from monocle_apptrace import setup_monocle_telemetry

# Setup Monocle telemetry with OTLP span exporter for traces
setup_monocle_telemetry(
    workflow_name="opentelemetry-instrumentation-openai-agents",
    span_processors=[
        BatchSpanProcessor(
            OTLPSpanExporter(endpoint="https://:4318/v1/traces")
        )
    ]
)

from agents import Agent, Runner, function_tool

# Define tool functions
@function_tool
def book_flight(from_airport: str, to_airport: str) -> str:
    """Book a flight between airports."""
    return f"Successfully booked a flight from {from_airport} to {to_airport} for 100 USD."

@function_tool
def book_hotel(hotel_name: str, city: str) -> str:
    """Book a hotel reservation."""
    return f"Successfully booked a stay at {hotel_name} in {city} for 50 USD."

@function_tool
def get_weather(city: str) -> str:
    """Get weather information for a city."""
    return f"The weather in {city} is sunny and 75°F."

# Create specialized agents
flight_agent = Agent(
    name="Flight Agent",
    instructions="You are a flight booking specialist. Use the book_flight tool to book flights.",
    tools=[book_flight],
)

hotel_agent = Agent(
    name="Hotel Agent",
    instructions="You are a hotel booking specialist. Use the book_hotel tool to book hotels.",
    tools=[book_hotel],
)

weather_agent = Agent(
    name="Weather Agent",
    instructions="You are a weather information specialist. Use the get_weather tool to provide weather information.",
    tools=[get_weather],
)

# Create a coordinator agent with tools
coordinator = Agent(
    name="Travel Coordinator",
    instructions="You are a travel coordinator. Delegate flight bookings to the Flight Agent, hotel bookings to the Hotel Agent, and weather queries to the Weather Agent.",
    tools=[
        flight_agent.as_tool(
            tool_name="flight_expert",
            tool_description="Handles flight booking questions and requests.",
        ),
        hotel_agent.as_tool(
            tool_name="hotel_expert",
            tool_description="Handles hotel booking questions and requests.",
        ),
        weather_agent.as_tool(
            tool_name="weather_expert",
            tool_description="Handles weather information questions and requests.",
        ),
    ],
)

# Run the multi-agent workflow
if __name__ == "__main__":
    import asyncio

    result = asyncio.run(
        Runner.run(
            coordinator,
            "Book me a flight today from SEA to SFO, then book the best hotel there and tell me the weather.",
        )
    )
    print(result.final_output)

コードの実行
1. Visual Studio Codeで新しいターミナルを開きます。
2. ターミナルで、コマンドpython main.pyを使用してコードを実行します。
Foundry Toolkitでトレースデータを確認する

コードを実行し、トレースウェブビューを更新すると、リストに新しいトレースが表示されます。

トレースを選択して、トレース詳細ウェブビューを開きます。

左側のスパンツリービューで、エージェントの呼び出し、ツール呼び出し、エージェントの委任を含む、アプリの完全な実行フローを確認します。

右側のスパン詳細ビューでスパンを選択すると、Input + Outputタブに生成AIメッセージが表示されます。

Metadataタブを選択して、生のメタデータを表示します。

学んだこと

この記事では、以下の方法を学びました。

Azure AI Inference SDKとOpenTelemetryを使用して、AIアプリケーションにトレースをセットアップします。
OTLPトレースエクスポーターを構成して、トレースデータをローカルコレクターサーバーに送信します。
アプリケーションを実行してトレースデータを生成し、Foundry Toolkitウェブビューでトレースを表示します。
PythonやTypeScript/JavaScriptなどの複数のSDKと言語、およびOTLPを介した非Microsoftツールでトレース機能を使用します。
提供されたコードスニペットを使用して、様々なAIフレームワーク（Anthropic、Gemini、LangChain、OpenAIなど）をインストゥルメントします。
Start CollectorボタンやRefreshボタンを含むトレースウェブビューUIを使用して、トレースデータを管理します。
環境変数やパッケージのインストールなど、トレースを有効にするための開発環境をセットアップします。
スパンツリーと詳細ビューを使用して、生成AIメッセージフローやメタデータを含むアプリの実行フローを分析します。

10/03/2025