From 5de8773fa1b5ee5b6da85db691455774dc5db9c7 Mon Sep 17 00:00:00 2001 From: Dominik Kundel Date: Wed, 18 Jun 2025 17:18:36 -0700 Subject: [PATCH] docs(tracing): add external trace providers --- docs/src/content/docs/guides/tracing.mdx | 5 ++ docs/src/content/docs/ja/guides/tracing.mdx | 87 ++++++++++++--------- 2 files changed, 53 insertions(+), 39 deletions(-) diff --git a/docs/src/content/docs/guides/tracing.mdx b/docs/src/content/docs/guides/tracing.mdx index c2e9e66e..d1024a55 100644 --- a/docs/src/content/docs/guides/tracing.mdx +++ b/docs/src/content/docs/guides/tracing.mdx @@ -108,3 +108,8 @@ To customize this default setup, to send traces to alternative or additional bac 1. [`addTraceProcessor()`](/openai-agents-js/openai/agents-core/functions/addtraceprocessor) lets you add an **additional** trace processor that will receive traces and spans as they are ready. This lets you do your own processing in addition to sending traces to OpenAI's backend. 2. [`setTraceProcessors()`](/openai-agents-js/openai/agents-core/functions/settraceprocessors) lets you **replace** the default processors with your own trace processors. This means traces will not be sent to the OpenAI backend unless you include a `TracingProcessor` that does so. + +## External tracing processors list + +- [AgentOps](https://docs.agentops.ai/v2/usage/typescript-sdk#openai-agents-integration) +- [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agents-sdk-js) diff --git a/docs/src/content/docs/ja/guides/tracing.mdx b/docs/src/content/docs/ja/guides/tracing.mdx index 90c66994..fa58d82a 100644 --- a/docs/src/content/docs/ja/guides/tracing.mdx +++ b/docs/src/content/docs/ja/guides/tracing.mdx @@ -7,24 +7,25 @@ import { Aside, Code } from '@astrojs/starlight/components'; import customTraceExample from '../../../../../../examples/docs/custom-trace.ts?raw'; import cloudflareWorkers from '../../../../../../examples/docs/tracing/cloudflareWorkers.ts?raw'; -Agents SDK にはビルトインの トレーシング が含まれており、エージェント実行中の LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベントまで網羅的に記録します。[Traces ダッシュボード](https://platform.openai.com/traces) を使用すると、開発時や本番環境でワークフローをデバッグ、可視化、監視できます。 +Agents SDK にはトレーシング機能が組み込まれており、エージェント実行中に発生するイベント（ LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベントまで）を網羅的に記録します。 +[Traces ダッシュボード](https://platform.openai.com/traces) を使用すると、開発中および本番環境でワークフローをデバッグ・可視化・監視できます。 ## エクスポートループのライフサイクル -多くの環境では、トレースは一定間隔で自動的にエクスポートされます。ブラウザや Cloudflare Workers ではこの機能はデフォルトで無効になっています。キューに溜まりすぎた場合はエクスポートされますが、定期的にはエクスポートされません。そのため、コードのライフサイクルの一部として `getGlobalTraceProvider().forceFlush()` を呼び出して手動でエクスポートしてください。 +ほとんどの環境では、トレースは一定間隔で自動的にエクスポートされます。しかしブラウザや Cloudflare Workers では、この機能はデフォルトで無効化されています。キューに溜まり過ぎた場合にはエクスポートされますが、定期的には行われません。その場合、コードのライフサイクル内で `getGlobalTraceProvider().forceFlush()` を呼び出して手動でエクスポートしてください。 -たとえば Cloudflare Worker では、コードを `try/catch/finally` ブロックにラップし、`waitUntil` とともに force flush を呼び出して、ワーカー終了前にトレースがエクスポートされるようにします。 +たとえば Cloudflare Worker では、コードを `try/catch/finally` ブロックでラップし、`waitUntil` と併用して `forceFlush` を呼び出すことで、ワーカー終了前にトレースを確実にエクスポートできます。 ` - - `group_id`: 任意のグループ ID。同じ会話からの複数トレースをリンクするために使用。例: チャットスレッド ID - - `disabled`: `true` の場合、このトレースは記録されない - - `metadata`: トレースに付与する任意のメタデータ -- **スパン (Span)** は開始時刻と終了時刻を持つ操作を表します。スパンは以下を持ちます: +- **トレース** は 1 つの「ワークフロー」のエンドツーエンドの操作を表し、スパンで構成されます。主なプロパティは次のとおりです: + - `workflow_name` : 論理的なワークフローやアプリ名。例: "Code generation" や "Customer service" + - `trace_id` : トレースの一意 ID。指定しない場合は自動生成。形式は `trace_<32_alphanumeric>` + - `group_id` : 省略可。同一会話内の複数トレースを紐付ける ID。例としてチャットスレッド ID など + - `disabled` : `true` の場合、このトレースは記録されません + - `metadata` : トレースに付与する追加メタデータ +- **スパン** は開始時刻と終了時刻を持つ操作を表します。主なプロパティは次のとおりです: - `started_at` と `ended_at` タイムスタンプ - 所属するトレースを示す `trace_id` - - 親スパンを指す `parent_id` (存在する場合) - - スパンに関する情報を含む `span_data`。たとえば `AgentSpanData` はエージェント情報、`GenerationSpanData` は LLM 生成情報など + - 親スパンを示す `parent_id` （存在する場合） + - `span_data` : スパンに関する情報。たとえば `AgentSpanData` はエージェント情報、`GenerationSpanData` は LLM 生成情報など ## デフォルトのトレーシング -デフォルトでは SDK が次をトレースします: +デフォルトで SDK は以下をトレースします。 -- `run()` または `Runner.run()` 全体を 1 つの `Trace` でラップ +- `run()` または `Runner.run()` 全体を `Trace` でラップ - エージェントが実行されるたびに `AgentSpan` でラップ - LLM 生成を `GenerationSpan` でラップ -- 関数ツール呼び出しをそれぞれ `FunctionSpan` でラップ +- 関数ツール呼び出しを `FunctionSpan` でラップ - ガードレールを `GuardrailSpan` でラップ - ハンドオフを `HandoffSpan` でラップ -トレース名はデフォルトで "Agent workflow" です。`withTrace` を使用してこの名前を設定するか、[`RunConfig.workflowName`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#workflowname) で名前やその他のプロパティを設定できます。 +トレース名はデフォルトで "Agent workflow" です。`withTrace` を使用して名前を設定するか、[`RunConfig.workflowName`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#workflowname) で名前やその他プロパティを設定できます。 -さらに、[カスタムトレースプロセッサ](#custom-tracing-processors) を設定して、（置き換えまたは追加の送信先として）他の場所にトレースを送信できます。 +さらに、[カスタムトレーシングプロセッサー](#custom-tracing-processors) を設定して別の宛先へトレースを送信（置き換えや追加送信）することも可能です。 ### 音声エージェントのトレーシング -デフォルトの OpenAI Realtime API とともに `RealtimeAgent` と `RealtimeSession` を使用している場合、`RealtimeSession` で `tracingDisabled: true` を設定するか、`OPENAI_AGENTS_DISABLE_TRACING` 環境変数を使用して無効化しない限り、トレーシングは自動的に Realtime API 側で行われます。 +`RealtimeAgent` と `RealtimeSession` を OpenAI Realtime API のデフォルト設定で使用する場合、トレーシングは Realtime API 側で自動的に行われます。`RealtimeSession` で `tracingDisabled: true` を指定するか、環境変数 `OPENAI_AGENTS_DISABLE_TRACING` を設定すると無効化できます。 -詳細は [音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を参照してください。 +詳細は [音声エージェントの概要](/openai-agents-js/guides/voice-agents) を参照してください。 -## 高レベルのトレース +## 上位レベルのトレース -複数回の `run()` 呼び出しを 1 つのトレースにまとめたい場合があります。その場合はコード全体を `withTrace()` でラップします。 +複数回の `run()` 呼び出しを 1 つのトレースにまとめたい場合は、コード全体を `withTrace()` でラップします。 -1. 2 回の `run` 呼び出しは `withTrace()` でラップされているため、個別のトレースを作成せず全体トレースの一部になります。 +1. 2 回の `run` 呼び出しが `withTrace()` でラップされているため、それぞれが個別のトレースを作成せず、全体トレースに含まれます。 ## トレースの作成 -[`withTrace()`](/openai-agents-js/openai/agents-core/functions/withtrace/) 関数を使ってトレースを作成できます。あるいは `getGlobalTraceProvider().createTrace()` で手動で新しいトレースを作成し、それを `withTrace()` に渡すことも可能です。 +[`withTrace()`](/openai-agents-js/openai/agents-core/functions/withtrace/) 関数を使用してトレースを作成できます。あるいは `getGlobalTraceProvider().createTrace()` でトレースを手動作成し、`withTrace()` に渡すことも可能です。 -現在のトレースは [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または各環境のポリフィルを通じて追跡されます。これにより並行処理でも自動的に機能します。 +現在のトレースは [Node.js の `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage)（および各環境のポリフィル）で管理されるため、並行実行でも自動的に動作します。 ## スパンの作成 -`createGenerationSpan()` や `createFunctionSpan()` などの `create*Span()` メソッドを使ってスパンを作成できます。一般的には手動でスパンを作成する必要はありません。カスタムスパンを追跡するための [`createCustomSpan()`](/openai-agents-js/openai/agents-core/functions/createcustomspan/) も用意されています。 +`create*Span()`（例: `createGenerationSpan()`、`createFunctionSpan()` など）メソッドでスパンを作成できますが、通常は手動で作成する必要はありません。カスタムスパン情報を追跡するために [`createCustomSpan()`](/openai-agents-js/openai/agents-core/functions/createcustomspan/) も利用できます。 -スパンは自動的に現在のトレースに属し、最も近い現在のスパンの下にネストされます。これも [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または各環境のポリフィルで追跡されます。 +スパンは現在のトレースに自動的に紐付けられ、最近のスパンを親としてネストされます。この仕組みも [Node.js の `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) で実装されています。 -## 機微なデータ +## 機微データ -一部のスパンは機微なデータを記録する場合があります。 +特定のスパンでは機微データが記録される可能性があります。 -`createGenerationSpan()` は LLM 生成の入出力を、`createFunctionSpan()` は関数呼び出しの入出力を保存します。これらに機微なデータが含まれる可能性があるため、[`RunConfig.traceIncludeSensitiveData`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#traceincludesensitivedata) で記録を無効化できます。 +`createGenerationSpan()` は LLM 生成の入出力を、`createFunctionSpan()` は関数呼び出しの入出力を保存します。これらに機微データが含まれる場合は、[`RunConfig.traceIncludeSensitiveData`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#traceincludesensitivedata) で記録を無効化できます。 -## カスタムトレーシングプロセッサ +## カスタムトレーシングプロセッサー -トレーシングの高レベルアーキテクチャは次のとおりです: +トレーシングの高レベル構成は以下のとおりです。 -- 初期化時にグローバルな [`TraceProvider`](/openai-agents-js/openai/agents-core/classes/traceprovider) を作成し、これは [`getGlobalTraceProvider()`](/openai-agents-js/openai/agents-core/functions/getglobaltraceprovider/) からアクセスできます -- `TraceProvider` は [`BatchTraceProcessor`](/openai-agents-js/openai/agents-core/classes/batchtraceprocessor/) で構成され、バッチで [`OpenAITracingExporter`](/openai-agents-js/openai/agents-openai/classes/openaitracingexporter/) にトレース／スパンを送信し、OpenAI バックエンドへバッチエクスポートします +- 初期化時にグローバル [`TraceProvider`](/openai-agents-js/openai/agents-core/classes/traceprovider) を作成し、[`getGlobalTraceProvider()`](/openai-agents-js/openai/agents-core/functions/getglobaltraceprovider/) からアクセス +- `TraceProvider` には [`BatchTraceProcessor`](/openai-agents-js/openai/agents-core/classes/batchtraceprocessor/) を設定し、バッチで [`OpenAITracingExporter`](/openai-agents-js/openai/agents-openai/classes/openaitracingexporter/) にトレース／スパンを送信 +- `OpenAITracingExporter` が OpenAI バックエンドへバッチ送信 -このデフォルト設定をカスタマイズして別のバックエンドへ送信したり、エクスポータの挙動を変更したりする場合は、次の 2 つの方法があります: +このデフォルト構成をカスタマイズし、他のバックエンドへトレースを送信したりエクスポーター挙動を変更したりするには次の 2 つの方法があります。 -1. [`addTraceProcessor()`](/openai-agents-js/openai/agents-core/functions/addtraceprocessor) を使用して **追加** のトレースプロセッサを登録し、トレース／スパンを受け取って独自処理を行う（OpenAI バックエンドへの送信はそのまま） -2. [`setTraceProcessors()`](/openai-agents-js/openai/agents-core/functions/settraceprocessors) を使用してデフォルトのプロセッサを **置き換え** る。OpenAI バックエンドへ送信したい場合は、その機能を持つ `TracingProcessor` を含める必要があります +1. [`addTraceProcessor()`](/openai-agents-js/openai/agents-core/functions/addtraceprocessor) + 既存構成に **追加** でトレースプロセッサーを追加します。OpenAI バックエンドへ送信しつつ、独自処理も行いたい場合に使用します。 +2. [`setTraceProcessors()`](/openai-agents-js/openai/agents-core/functions/settraceprocessors) + デフォルトのプロセッサーを **置き換え** ます。OpenAI バックエンドへ送信したい場合は、その機能を持つ `TracingProcessor` を含めてください。 + +## 外部トレーシングプロセッサー一覧 + +- [AgentOps](https://docs.agentops.ai/v2/usage/typescript-sdk#openai-agents-integration) +- [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agents-sdk-js)