tencent cloud

Cloud Log Service

Agent Traceフィールド定義の説明

ダウンロード
フォーカスモード
フォントサイズ
最終更新日: 2026-10-12 15:13:58
AI翻訳
本文書は、Agent可観測性シナリオ向けのTrace統一セマンティクス仕様であり、フィールドの意味、データ型、例、およびサードパーティ接続時のフィールド要件を規定するために使用されます。現在、OneSuite-Pilotは本仕様に従ってAgent Traceデータを報告します。
説明:
本セマンティクス仕様はOpenTelemetry GenAIセマンティクス仕様に基づいて拡張されています。OpenTelemetry GenAIセマンティクス仕様は現在も修正および改善が行われており、今後のメンテナンス過程で調整される可能性があります。

データモデル

Onesuite-PilotはAI CodingアクティビティをOpenTelemetry Traceに変換し、CLS Trace Topicを通じて報告します。各ログにはTraceトップレベルフィールド、Resourceフィールド、Span Attributesフィールドが含まれます。
CLSのLogJsonでは、attributeとresourceはJSONエンコード文字列として保存され、解析後はそれぞれJSONオブジェクトになります。
{
"traceID": "<32桁の16進数Trace ID>"、
"spanID": "<16桁の16進数Span ID>"、
"parentSpanID": "<親Span ID>"、
"name": "chat <model>",
"kind": "client",
"start": "<Unixナノ秒タイムスタンプ>"、
"end": "<Unixナノ秒タイムスタンプ>"、
"duration": "<ナノ秒>"、
"statusCode": "OK",
"resource": {
"service.name": "codebuddy",
"host.name": "<ホスト名>"
},
"attribute": {
"gen_ai.span.kind": "chat",
"gen_ai.operation.name": "chat",
"gen_ai.agent.type": "codebuddy",
"gen_ai.session.id": "<セッションID>"、
"gen_ai.turn.id": "<ターンID>"、
"gen_ai.request.model": "<リクエストモデル>"、
"gen_ai.usage.input_tokens": 1000,
"gen_ai.usage.output_tokens": 200
}
}

Spanタイプと操作タイプ

gen_ai.span.kind
gen_ai.operation.name
説明
entry
enter_application
AI Coding アプリケーションエントリ
agent
invoke_agent
Agent呼び出し
step
react
ReActによる推論と行動のラウンド
chat
chat
モデル対話呼び出し
tool
execute_tool
ツール呼び出し

CLS Traceトップレベルフィールド

フィールド名
タイプ
説明
例
収集条件
traceID
string
トレースの一意の識別子であり、同一リクエストチェーン内の複数のSpanを関連付けるために使用されます。
17b5f957568ecb90b5b5b58d6bb56cbe
必須
spanID
string
現在のSpanの一意の識別子です。
66dbc3146404b6b2
必須
parentSpanID
string
現在のSpanの親Span識別子です。ルートSpanは通常空です。
4523b3266604f28c
必須
name
string
Span名は、現在の操作を表示するために使用されます。
chat <model>
必須
kind
string
OpenTelemetry Spanタイプ。
client
必須
start
string
Span開始時間、単位はナノ秒です。
1787150761999000000
必須
end
string
Span終了時間、単位はナノ秒です。
1787150802462000000
必須
duration
string
Spanの継続時間で、単位はナノ秒です。通常はend - startとなります。
40463000000
必須
statusCode
string
Span実行ステータス。
OK
必須
statusMessage
string
Spanステータスの補足説明。
tool execution failed
ステータス説明が発生した場合に収集します。
attribute
JSON string
Spanビジネス属性セットです。解析後はJSONオブジェクトになります。
{"gen_ai.span.kind":"chat"}
必須
resource
JSON string
Spanが属するサービスと実行環境の属性セットで、解析後はJSONオブジェクトになります。
{"service.name":"codebuddy"}
必須
traceState
string
W3C Trace Contextの拡張情報。
``
任意
links
JSON string
現在のSpanに関連付けられた他のTraceまたはSpanのリンクです。
[]
関連付けが存在する場合に収集します。
logs
JSON string
Spanに関連するログまたはイベント情報。
[]
イベントが存在する場合に収集します。

Resourceフィールド

フィールド名
タイプ
説明
例
収集条件
service.name
string
Traceデータを生成するアプリケーションまたはAgentサービスの名前です。
codebuddy
必須
host.name
string
データを生成するホストの名前。
VM-138-200-tencentos
必須
deployment.environment.name
string
アプリケーション実行環境の名前。
production
実行環境が構成されている場合に収集します。

共通IDおよびコンテキストフィールド

フィールド名
タイプ
説明
例
収集条件
gen_ai.span.kind
string
現在のSpanのビジネスタイプ。
chat
必須
gen_ai.operation.name
string
現在のSpanの具体的な操作名。
chat、execute_tool
必須
gen_ai.agent.type
string
データを生成するAI Coding Agentのタイプです。
codebuddy、workbuddy
必須
gen_ai.agent.id
string
現在のモデルまたはツール呼び出しに関連付けられたAgent識別子です。具体的な生成ルールは実際のバージョンに準じます。
<agent-id>
Chat、Tool Spanでは条件に応じて収集します。
gen_ai.agent.name
string
Agent名。
main
Agent Spanが名前を提供する場合に収集します。
gen_ai.session.id
string
AI Codingセッションの一意の識別子であり、同一セッション内の複数のSpanを関連付けるために使用されます。
<session-id>
必須
gen_ai.turn.id
string
セッション内の特定のユーザーリクエストまたはAgent処理ターンの識別子。
<session-id>:t73
必須
gen_ai.step.id
string
ReActまたはAgent処理ステップの識別子。
<session-id>:t73:s4
Step、Chat、Tool Spanでは条件に応じて収集します。
gen_ai.user.id
string
AI Codingデータが属するユーザーの識別子。
122855467
必須
gen_ai.user.name
string
AI Codingデータが属するユーザーの表示名。
user-name
必須
gen_ai.entry.type
string
AIアプリケーションエントリタイプ。
cli
Entry Span時に収集します。

LLM Chatフィールド

フィールド名
タイプ
説明
例
収集条件
gen_ai.provider.name
string
モデルサービスプロバイダー名。
anthropic
取得できる場合に収集します。
gen_ai.request.model
string
リクエスト時に指定されたモデル名。
claude-opus-5
Chat、Tool Spanで取得できる場合に収集します。
gen_ai.response.model
string
実際に返された結果で使用されたモデル名。
claude-opus-5
取得できる場合に収集します。
gen_ai.response.finish_reasons
string[]
モデル生成終了理由。
["stop"]
Chat Spanで取得できる場合に収集します。
gen_ai.chat.duration_ms
integer
Chat操作自体の所要時間で、単位はミリ秒です。
16010
Chat Spanで取得できる場合に収集します。
gen_ai.input.messages
JSON array
モデルまたはAgentに送信される入力メッセージのリスト。
[{"role":"user","parts":[...]}]
メッセージ内容の収集を有効にした場合、またはメッセージデータが発生した場合に収集します。
gen_ai.input.messages.hash
string
入力メッセージ内容のハッシュ値で、関連付けまたは重複排除に使用されます。
<32 位ハッシュ>
ハッシュ値が生成された場合に収集します。
gen_ai.input.messages_delta
JSON array
入力メッセージの増分変更情報。
[{"type":"append",...}]
増分情報が発生した場合に収集します。
gen_ai.output.messages
JSON array
モデルまたはAgentが返す出力メッセージのリスト。
[{"role":"assistant","parts":[...]}]
出力メッセージが発生した場合に収集します。

Token使用量フィールド

フィールド名
タイプ
説明
例
収集条件
gen_ai.usage.input_tokens
integer
モデル入力で消費されるToken数。
1000
取得できる場合に収集します。
gen_ai.usage.output_tokens
integer
モデル出力で消費されるToken数。
200
取得できる場合に収集します。
gen_ai.usage.total_tokens
integer
入力と出力で消費される合計Token数。
1200
取得できる場合に収集します。
gen_ai.usage.cache_read.input_tokens
integer
モデルプロバイダーのキャッシュから読み取られる入力Token数。
500
取得できる場合に収集します。
gen_ai.usage.cache_creation.input_tokens
integer
モデルプロバイダーのキャッシュに書き込まれる入力Token数。
100
取得できる場合に収集します。
gen_ai.usage.cache_miss.input_tokens
integer
キャッシュにヒットしなかった入力Token数。
50
取得できる場合に収集します。
gen_ai.usage.reasoning_output_tokens
integer
推論プロセスで生成される出力Token数。
0
取得できる場合に収集します。

Agentフィールド

フィールド名
タイプ
説明
例
収集条件
gen_ai.agent.message_count
integer
Agent Spanに含まれるメッセージの数。
13
Agent Spanで取得できる場合に収集します。
gen_ai.agent.tool_call_count
integer
Agent Span内で開始されたツール呼び出しの回数。
10
Agent Spanで取得できる場合に収集します。
gen_ai.agent.name
string
Agent名。
main
Agent Spanが名前を提供する場合に収集します。
gen_ai.agent.id
string
現在のモデルまたはツール呼び出しに関連付けられたAgent識別子です。
<agent-id>
Chat、Tool Spanでは条件に応じて収集します。

Toolフィールド

以下のフィールドは主にgen_ai.span.kind=tool、gen_ai.operation.name=execute_toolのSpanに出現します。
フィールド名
タイプ
説明
例
収集条件
gen_ai.tool.call.id
string
1回のツール呼び出しの一意の識別子です。
call_<id>
Tool Span時に収集します。
gen_ai.tool.name
string
呼び出されたツールの名前です。
Bash、execute_command
Tool Span時に収集します。
gen_ai.tool.type
string
ツールタイプです。
function
Tool Span時に収集します。
gen_ai.tool.call.arguments
JSON object / string
ツール呼び出しの入力パラメータです。
{"command":"<masked>"}
Tool Spanで取得できる場合に収集します。
gen_ai.tool.call.result
JSON object / string
ツール呼び出しの戻り値です。
{"status":"success"}
Tool Spanで取得できる場合に収集します。
gen_ai.tool.call.duration_ms
integer
ツール呼び出しの所要時間で、単位はミリ秒です。
44
Tool Span時に収集します。
gen_ai.tool.error.type
string
ツール呼び出し失敗時のエラータイプです。
tool_error
ツール呼び出し失敗時に収集します。
error.type
string
現在のSpanまたは操作のエラータイプです。
tool_error
エラー発生時に収集します。
説明:
gen_ai.tool.call.argumentsとgen_ai.tool.call.resultは、JSONオブジェクトまたはJSON文字列として出現する可能性があります。使用時は両方の形式に対応してください。

ReAct Stepフィールド

フィールド名
タイプ
説明
例
収集条件
gen_ai.react.round
integer
ReActの反復ラウンド数であり、通常は1から増加します。
8
関連するSpanで取得できる場合に収集します。
gen_ai.react.finish_reason
string
ReActまたはモデル呼び出しの終了理由。
tool_calls、stop
取得できる場合に収集します。
gen_ai.step.id
string
現在の推論および行動ステップの一意の識別子です。
<session-id>:t73:s4
Step、Chat、Tool Spanでは条件に応じて収集します。

CodeBuddy、WorkBuddy およびコードコンテキストフィールド

フィールド名
タイプ
説明
例
収集条件
agent.codebuddy.cwd
string
CodeBuddy セッションの現在の作業ディレクトリです。
/workspace/project
CodeBuddyシーンで収集します。
agent.workbuddy.cwd
string
WorkBuddy セッションの現在の作業ディレクトリです。
/workspace/project
WorkBuddyシーンで収集します。
git.domain
string
現在のコードリポジトリが存在するGitサービスのドメイン名です。
git.example.com
取得できる場合に収集します。
git.repo
string
現在のコードリポジトリ識別子です。
team/project
取得できる場合に収集します。
git.branch
string
現在のコードブランチです。
main
取得できる場合に収集します。
observed_time_unix_nano
string
データが観測または処理された時刻です。単位はナノ秒です。
1787197097104000000
実際に該当フィールドが生成された時に収集します。

互換性に関する説明

本文書が定義するのは、Agent可観測性Traceの統一セマンティクスです。異なるAgent、モデル、Spanタイプには、その一部のフィールドのみが適用される場合があります。具体的なフィールド要件は、対応するフィールド表の収集条件を基準としてください。OpenTelemetry GenAIセマンティクス仕様は現在も進化を続けているため、今後のフィールド定義とセマンティクスは仕様バージョンに応じて調整され、バージョン説明で同期して更新されます。
関連するインストール方法については、AI Coding Agentデータの接続(Onesuite-Pilot)を参照してください。

ヘルプとサポート

この記事はお役に立ちましたか?

フィードバック