LLM トレーススパンとフィールドセマンティクスの理解 - CMS

Alibaba Cloud は、OpenTelemetry オープン標準と LLM アプリケーションドメインの概念に基づいて、大規模言語モデル (LLM) のトレースフィールドを定義しています。Attributes、Resource、Event を拡張することにより、これらのフィールドは LLM アプリケーションの呼び出しチェーンデータのセティクスを記述します。LLM の入出力リクエストやトークン消費などの主要な操作をキャプチャします。これらのフィールドは、Completion、Chat、検索拡張生成 (RAG)、Agent、Tool などのシナリオに対して、コンテキストを意識した豊富なセマンティックデータを提供し、データ追跡とレポート作成を簡素化します。これらのセマンティックフィールドは、コミュニティの進化に伴い、継続的に更新および最適化されます。

レベル 1 のスパンフィールドの定義は、OpenTelemetry オープン標準に基づいています。Alibaba Cloud Managed Service for OpenTelemetry に保存されている基礎となるレベル 1 のトレースフィールドの詳細については、「トレース分析パラメーター」をご参照ください。

説明

LLM 関連の SpanKind は属性であり、OpenTelemetry トレースで定義されている Span kind とは異なります。

共通フィールド

属性

属性キー	説明	タイプ	例	要件レベル
`gen_ai.session.id`	セッション ID。	文字列	`ddde34343-f93a-4477-33333-sdfsdaf`	条件付きで必須
`gen_ai.user.id`	アプリケーションのエンドユーザーの ID。	文字列	`u-lK8JddD`	条件付きで必須
`gen_ai.span.kind`	操作タイプ。	文字列	LLM Span Kind をご参照ください	必須
`gen_ai.framework`	使用されるフレームワークのタイプ。	文字列	`langchain`; `llama_index`	条件付きで必須

リソース

リソースキー	説明	タイプ	例	要件レベル
`service.name`	アプリケーション名。	文字列	`test-easy-rag`	必須

Chain

Chain は、LLM を他の複数のコンポーネントと接続して複雑なタスクを実行するためのツールです。ネストすることができ、Retrieval、Embedding、および LLM の呼び出しを含む場合があります。

属性

属性キー	説明	タイプ	例	要件レベル
`gen_ai.span.kind`	操作タイプ。これは LLM SpanKind に固有の列挙です。Chain の場合、値は必ず `CHAIN` でなければなりません。	文字列	`CHAIN`	必須
`gen_ai.operation.name`	操作のサブタイプ。	文字列	`WORKFLOW`; `TASK`	条件付きで必須
`input.value`	入力内容。	文字列	`Who Are You!`	推奨
`output.value`	返される内容。	文字列	`I am ChatBot`	推奨
`gen_ai.user.time_to_first_token`	最初のトークンまでの時間 (TTFT)。これは、クエリに対する全体的な応答の最初のパケットのレイテンシーです。サーバーがユーザーリクエストを受信してから最初のパケットが返されるまでの時間を測定します。単位はナノ秒です。	整数	1000000	推奨

Retriever

Retriever は通常、ベクターストアまたはデータベースにアクセスしてデータを取得します。このデータは、LLM の応答の精度と効率を向上させるためにコンテキストを補足するために使用されます。

属性

属性キー	説明	タイプ	例	要件レベル
`gen_ai.span.kind`	操作タイプ。これは LLM SpanKind に固有の列挙です。Retriever の場合、値は必ず `RETRIEVER` でなければなりません。	文字列	`RETRIEVER`	必須
`retrieval.query`	取得のための短いクエリ文字列。	文字列	`what is the topic in xxx?`	推奨
`retrieval.document`	取得されたドキュメントのリスト。	JSON 配列	`[{"document":{"content":"This is a sample document content.","metadata":{"source":"https://aliyun.com/xxx/wiki","title":"How LLM Works"},"score":0.7680862242896571,"id":"7af0e529-2531-42d9-bf3a-d5074a73c184"}}]`	必須

Reranker

Reranker は、クエリ内容との関連性に基づいて複数の入力ドキュメントをソートし、LLM のために上位 K 個のドキュメントを返すことがあります。

属性

属性キー	説明	タイプ	例	要件レベル
`gen_ai.span.kind`	操作タイプ。これは LLM SpanKind に固有の列挙です。Reranker の場合、値は必ず `RERANKER` でなければなりません。	文字列	`RERANKER`	必須
`reranker.query`	Reranker リクエストの入力パラメーター。	文字列	`How to format timestamp?`	任意
`reranker.model_name`	Reranker が使用するモデルの名前。	文字列	`cross-encoder/ms-marco-MiniLM-L-12-v2`	任意
`reranker.top_k`	リランキング後のランク。	整数	`3`	任意
`reranker.input_document`	リランキングのための入力ドキュメントに関連するメタデータ。これは JSON 配列です。メタデータには、パス、ファイル名、ソースなどの基本的なドキュメント情報が含まれます。	文字列	-	必須
`reranker.output_document`	リランキング後の出力ドキュメントに関連するメタデータ。これは JSON 配列です。メタデータには、パス、ファイル名、ソースなどの基本的なドキュメント情報が含まれます。	文字列	-	必須

LLM

LLM スパンは、SDK または OpenAPI を使用した推論やテキスト生成のリクエストなど、大規模モデルへの呼び出しを識別します。

属性

属性キー	説明	タイプ	例	要件レベル
`gen_ai.span.kind`	操作タイプ。これは LLM SpanKind に固有の列挙です。LLM の場合、値は必ず `LLM` でなければなりません。	文字列	`LLM`	必須
`gen_ai.operation.name`	操作のサブタイプ。	文字列	`チャット`; `補完`	任意
`gen_ai.prompt_template.template`	プロンプトテンプレート。	文字列	`{date} の {city} の天気予報`	任意
`gen_ai.prompt_template.variables`	プロンプトテンプレートの特定の値。	文字列	`{ context: "<取得からのコンテキスト>", subject: "math" }`	任意
`gen_ai.prompt_template.version`	プロンプトテンプレートのバージョン番号。	文字列	`1.0`	任意
`gen_ai.system`	large モデルのプロバイダー。	文字列	`openai`	必須
`gen_ai.request.parameters`	LLM 呼び出しの入力パラメーター。	文字列	`{"temperature": 0.7}`	任意
`gen_ai.model_name`	モデル名。	文字列	`gpt-4`	任意
`gen_ai.conversation.id`	会話の一意の ID。イベントトラッキングでセッション ID を容易に取得できる場合は、これを収集すべきです。	文字列	`conv_5j66UpCpwteGg4YSxUnt7lPY`	条件付きで必須
`gen_ai.output.type`	LLM リクエストで指定された出力タイプ。これが利用可能で、リクエストが出力フォーマットなどのタイプを指定する場合、収集されるべきです。	文字列	`text`;`json`;`image`;`audio`	条件付き必須
`gen_ai.request.choice.count`	LLM にリクエストされた候補生成の数。	整数	`3`	条件が満たされ、値が 1 ではない場合に必須です
`gen_ai.request.model`	LLM リクエストで指定されたモデル名。	文字列	`gpt-4`	必須
`gen_ai.request.seed`	LLM リクエストで指定されたシード。	文字列	`gpt-4`	条件付き必須
`gen_ai.request.frequency_penalty`	LLM リクエストで設定された頻度ペナルティ。	浮動小数点	`0.1`	推奨
`gen_ai.request.max_tokens`	LLM リクエストで指定されたトークンの最大数。	整数	`100`	推奨
`gen_ai.request.presence_penalty`	LLM リクエストで設定された存在ペナルティ。	浮動小数点	`0.1`	推奨
`gen_ai.request.temperature`	LLM リクエストで指定された温度。	浮動小数点	`0.1`	推奨
`gen_ai.request.top_p`	LLM リクエストで指定された top_p 値。	浮動小数点	`1.0`	推奨
`gen_ai.request.top_k`	LLM リクエストで指定された top_k 値。	フロート	`1.0`	推奨
`gen_ai.request.is_stream`	応答がストリーミングされるかどうかを示します。この属性が存在しない場合、値は false と見なされます。	ブール値	`false`	推奨
`gen_ai.request.stop_sequences`	LLM の停止シーケンスです。	String[]	`["stop"]`	推奨
`gen_ai.request.tool_calls`	ツールの呼び出しの内容。	文字列	`[{"tool_call.function.name": "get_current_weather"}]`	推奨
`gen_ai.response.id`	LLM によって生成された一意の ID。	文字列	`gpt-4-0613`	推奨
`gen_ai.response.model`	LLM 生成に使用されるモデル名。	文字列	`gpt-4-0613`	推奨
`gen_ai.response.finish_reason`	LLM が生成を停止した理由。	String[]	`["stop"]`	推奨
`gen_ai.response.time_to_first_token`	ストリーミングシナリオにおける大規模モデル自体の最初のトークンまでの時間です。これは、サーバーがユーザーリクエストを受信してから最初のパケットが返されるまでの、クエリに対する全体的な応答の最初のパケットのレイテンシを表します。単位はナノ秒です。	整数	`1000000`	推奨
`gen_ai.response.reasoning_time`	推論モデルの推論時間。応答推論プロセスの所要時間を表します。単位はミリ秒です。	整数	`1248`	推奨
`gen_ai.usage.input_tokens`	入力に使用されたトークンの数です。	整数	`100`	推奨
`gen_ai.usage.output_tokens`	出力に使用されるトークンの数です。	整数	`200`	推奨
`gen_ai.usage.total_tokens`	使用されたトークンの総数。	整数	`300`	推奨
`gen_ai.input.messages_ref`	モデルの入力コンテンツへのリンク。	文字列	`s3://acme.prod.support_bot.chats.2025/conv_1234/run_42.json`	推奨
`gen_ai.output.messages_ref`	モデルの出力コンテンツへのリンク。	文字列	`s3://acme.prod.support_bot.chats.2025/conv_1234/run_42.json`	推奨
`gen_ai.system.instructions_ref`	システムプロンプトのコンテンツへのリンクです。これは、システムプロンプト (/system 命令) のコンテンツへの外部リンクを個別に記録するために使用されます。システムプロンプトのコンテンツを個別に取得できる場合は、このフィールドを使用して記録します。システムプロンプトのコンテンツがモデル呼び出しの一部である場合は、`gen_ai.input.messages_ref` 属性に対応するリンクに記録します。	文字列	`s3://acme.prod.support_bot.chats.2025/conv_1234/invocation_42.json`	利用できる場合は推奨
`gen_ai.input.messages`	モデルの入力内容。メッセージは、モデルまたはエージェントに送信された順序で提供されなければなりません。デフォルトでは、ユーザーが明示的にそれを有効にしない限り、この情報は収集されるべきではありません。	文字列	`[{"role": "user", "parts": [{"type": "text", "content": "Weather in Paris?"}]}, {"role": "assistant", "parts": [{"type": "tool_call", "id": "call_VSPygqKTWdrhaFErNvMV18Yl", "name":"get_weather", "arguments":{"location":"Paris"}}]}, {"role": "tool", "parts": [{"type": "tool_call_response", "id":" call_VSPygqKTWdrhaFErNvMV18Yl", "result":"rainy, 57°F"}]}]`	任意
`gen_ai.output.messages`	モデルの出力内容。メッセージは、モデルまたはエージェントに送信された順序で提供する必要があります。デフォルトでは、ユーザーが明示的に有効にしない限り、この情報は収集されるべきではありません。	文字列	`[{"role":"assistant","parts":[{"type":"text","content":"パリの天気は現在雨で、気温は 57°F です。"}],"finish_reason":"stop"}]`	任意
`gen_ai.system.instructions`	システムプロンプトのコンテンツです。これは、システムプロンプト (/system 命令) のコンテンツを JSON 文字列として個別にレコードするために使用されます。システムプロンプトのコンテンツを個別に取得できる場合は、このフィールドを使用してレコードします。システムプロンプトのコンテンツがモデル呼び出しの一部である場合は、`gen_ai.input.messages` 属性にレコードします。デフォルトでは、ユーザーが明示的に有効にしない限り、この情報は収集してはいけません。	文字列	`{"ロール": "system", "メッセージ": {"type": "text", "content": "あなたは役に立つアシスタントです"}}`	任意
`gen_ai.response.reasoning_content`	推論モデルからの推論コンテンツです。これは、応答推論プロセスのコンテンツを表します。デフォルトの長さは 1,024 文字に制限されています。この制限を超えるコンテンツは切り捨てられます。	文字列	`はい、xxx に関するこの質問に取り組みましょう。`	任意

Embedding

Embedding スパンは、テキスト埋め込みモデルでの操作など、埋め込みプロセスを識別します。この埋め込みは、後で類似性クエリに基づいて質問を最適化するために使用できます。

属性

属性キー	説明	タイプ	例	要件レベル
`gen_ai.span.kind`	操作タイプ。これは LLM SpanKind に固有の列挙です。Embedding の場合、値は必ず `EMBEDDING` でなければなりません。	文字列	`EMBEDDING`	必須
`gen_ai.usage.input_tokens`	入力テキストのトークン消費量。	整数	`10`	任意
`gen_ai.usage.total_tokens`	埋め込みの合計トークン消費量。	整数	`10`	任意
`embedding.model_name`	埋め込みモデルの名前。	文字列	`text-embedding-v1`	任意
`embedding.embedding_output`	埋め込み結果。	文字列	-	任意

Tool

Tool スパンは、電卓の呼び出しや天気 API から最新の気象条件をリクエストするなど、外部ツールへの呼び出しを識別します。

属性

属性キー	説明	タイプ	例	要件レベル
`gen_ai.span.kind`	操作タイプ。これは LLM SpanKind に固有の列挙です。Tool の場合、値は必ず `TOOL` でなければなりません。	文字列	`TOOL`	必須
`tool.name`	ツール名。	文字列	`WeatherAPI`	必須
`tool.description`	ツールの説明。	文字列	`An API to get weather data.`	必須
`tool.parameters`	ツールの入力パラメーター。	文字列	`{'a': 'int' }`	必須

Agent

Agent はエージェントシナリオを表します。これは、LLM の推論結果に基づいて次のステップを決定する、より複雑な Chain です。たとえば、LLM と Tool への複数の呼び出しを含み、最終的な回答を生成するために段階的に決定を下す場合があります。

属性

属性キー	説明	タイプ	例	要件レベル
`gen_ai.span.kind`	操作タイプ。これは LLM SpanKind に固有の列挙です。Agent の場合、値は必ず `AGENT` でなければなりません。	文字列	`AGENT`	必須
`input.value`	入力パラメーター。元の入力を記録します。	文字列	`Please help me plan xxxx`	必須
`input.mime_type`	入力の MIME タイプです。	文字列	`text/plain`; `application/json`	任意
`output.value`	返される結果。最終的な出力を返します。	文字列	`プランニングが完了しました。結果 xxx を確認してください。`	必須
`output.mime_type`	出力の MIME タイプです。	文字列	`text/plain`; `application/json`	任意
`gen_ai.response.time_to_first_token`	エージェントの最初のトークンまでの時間です。これは、サーバーがユーザーリクエストを受信してから、クエリに対する応答全体の最初のパケットが返されるまでの遅延時間(レイテンシー)を表します。単位はナノ秒です。	整数	`1000000`	推奨

Task

Task スパンは、カスタムロジックを適用するためにローカル関数を呼び出すなど、内部のカスタムメソッドを識別します。

属性

属性キー	説明	タイプ	例	要件レベル
`gen_ai.span.kind`	操作タイプ。これは LLM SpanKind に固有の列挙型です。Task の場合、値は必ず `TASK` でなければなりません。	文字列	`タスク`	必須
`input.value`	入力パラメーター。	文字列	カスタム JSON フォーマット	任意
`input.mime_type`	入力の MIME タイプです。	文字列	`text/plain`; `application/json`	任意
`output.mime_type`	出力の MIME タイプです。	文字列	`text/plain`; `application/json`	任意