観測単位がモデル呼出しではなくRunなのはなぜか
AIエージェントの応答に20秒かかっても、モデルAPIが20秒動いていたとは限りません。モデル呼出しは2秒で終わり、検索待ちに4秒、外部ツールのタイムアウトと再試行に10秒、残りを人の承認待ちに使った可能性があります。
逆もあります。2秒以内に応答していても、古い文書を検索し、利用可能なツールから誤ったものを選び、ツールが失敗したのに成功したような最終回答を作る場合があります。このときシステム遅延とHTTP状態は正常に見えます。
したがって観測単位は個別モデル呼出しではなく、ユーザー要求の到着から最終結果の配信または処理中止までの一つのRunです。その中でRetrieval、Model Call、Tool Selection、Tool Execution、Retry、Guardrail、外部依存、費用、ユーザー結果を結び付けて初めて問題の起点を判断できます。[3]
PromptとCompletionの全文保存から始める必要もありません。先に構造と結果を記録し、原文は明確な必要性と保護方針がある場合に限定して収集します。
OTel GenAI規約は現在Stableか
2026年8月27日時点で、OpenTelemetryのコアSemantic Conventions文書は1.44.0です。[7] ただしGenAI規約はコア文書から独立したsemantic-conventions-genaiリポジトリへ移りました。[6] そこではGenAI全体、モデル・クライアントSpan、エージェント・フレームワークSpan、Metrics、EventsのすべてがDevelopment状態です。Eventsには言語別実装がまだない場合もあります。
OpenTelemetryを避けるという意味ではありません。invoke_agent、plan、retrieval、execute_toolなど、異なるランタイムの作業名をそろえる出発点として有用です。[1] ただし二点が必要です。Telemetry Schema VersionとInstrumentation Versionを併記すること、実験的Attribute名へ運用ダッシュボードや分析を直接結び付けず、内部Canonical Schemaで一度正規化することです。規約が変わっても過去と新規Runを比較できる必要があります。
監視から復旧・改善までつながる運用 — サービス指標とアラートを基準に対応し、変更履歴と事後報告を次の改善につなげます。
Session・Run・Span・Eventはどう違うか
主要ランタイムは名称が違っても似た構造を持ちます。OpenAI Agents SDKは会話をgroup_idでまとめ、作業をTrace、内部の生成・ツール・GuardrailをSpanで記録します。Google ADKはSession内のユーザー要求をinvocation_idでまとめ、モデル・ツール呼出しや状態変更をEventにします。Amazon Bedrock AgentCoreはSession下に要求・応答単位のTraceを置き、内部処理と外部呼出しをSpanに分けます。LangSmithは個別作業をRun、その木構造をTrace、複数Traceの会話をThreadと呼びます。表はこれをランタイムに依存せず整理したものです。
session_idとrun_idを同じ値にすると複数Turnの問題を分析しにくくなります。逆にモデル呼出しごとにRunを作ると、一つの要求が独立作業に分散します。Session下にRun / Traceを置き、その中のRetrieval、Plan / Tool Selection、Model Call、Tool ExecutionをSpanにします。Tool Execution下にはHTTP / DB / Queue / External API Spanを付けます。Retry / Loop Event、Guardrail / Policy Event、Human Intervention、User Outcomeも同じRunに置きます。[2]
非同期作業、Queue Worker、別Agent、外部Toolへ処理が移っても、同じTrace Contextを渡すかSpan Linkで接続します。そうしないとToolを呼んだ事実しか分からず、どの外部システムで時間を使ったかを追えません。
階層 | 意味 | 答える質問 |
|---|---|---|
| Session | 複数Turnが続く会話・業務の文脈 | 同じユーザーの複数要求で問題が累積したか |
| Run・Trace | 一つの要求から最終結果まで | 要求全体は成功し、どれだけ時間がかかったか |
| Span | 開始と終了のある個別作業 | Retrieval・モデル・Tool・外部APIのどこで遅延・失敗したか |
| Event | ある時点の判断や状態変更 | Tool選択・Retry発生・承認要求はいつ、なぜ起きたか |
Telemetry Modelには何を含めるか
表のモデルは、現在のOpenTelemetry GenAI規約と主要ランタイムの共通構造を正規化した提案です。OpenTelemetryの確定済みStable Schemaではありません。identity、request、executionのSpan（model・retrieval・tool・dependency）、events、usage_and_cost、outcome、privacyの七グループで構成します。
全組織が一度に全Fieldを実装する必要はありません。ただし最初から可能な限り残す情報があります。session_id、run_id、trace_id、Agent・Workflow・Prompt・Tool・Data SourceのVersion、段階別開始・終了時刻と状態、Model Call・Tool Call・Retry回数、最初と最後のエラーの区別です。Token Usageと費用算定基準、Human Interventionと待機時間、技術的成功とユーザー業務成功、Content Capture Modeも含めます。
run_idやsession_idのように値の種類が増え続ける識別子は個別Trace・Logに置き、集計MetricのLabelには使わない方が適切です。一意IDをMetric AttributeにするとCardinalityと保存費用が急増します。
グループ | Field | 答える質問 |
|---|---|---|
| identity | trace_id · run_id · session_id · parent_run_id · workflow_name · workflow_version · agent_name · agent_version · telemetry_schema_version · instrumentation_name · instrumentation_version · environment | どのAgent・Workflow・Schema VersionがRunを生成したか |
| request | started_at · channel · use_case · turn_number · prompt_template_id · prompt_template_version · input_size_bytes · input_language · input_content_ref | 流入経路・Turn番号・Prompt Templateは何か |
| execution.spans | span_id · parent_span_id · stage(retrieval, plan, model_call, tool_selection, tool_execution, guardrail, human_wait, external_dependency) · sequence_no · attempt_no · loop_iteration · started_at · ended_at · duration_ms · wait_duration_ms · status(ok, error, cancelled, interrupted) · error_type · recovered | どの段階で時間・失敗が生じ、復旧したか |
| execution.spans.model | provider · requested_model · response_model · time_to_first_chunk_ms · input_tokens · output_tokens · cache_read_tokens · finish_reason | Provider待ちか、生成遅延か、Output制限か |
| execution.spans.retrieval | data_source_id · data_source_version · query_fingerprint · top_k · result_count · document_refs · score_summary | どのData Source・Versionで実際に結果が得られたか |
| execution.spans.tool | available_toolset_version · selection_source · selected_tool · tool_name · tool_version · tool_call_id · argument_schema_valid · side_effect_class · result_status · argument_content_ref · result_content_ref | どのToolが提供・選択・実行され、結果は何か |
| execution.spans.dependency | service_name · operation · protocol_status · timeout | Agent外のどの依存先がCritical Pathにあったか |
| events | event_id · span_id · occurred_at · event_type(tool_selected, retry_scheduled, loop_detected, guardrail_decision, policy_decision, human_approval_requested, human_approved, human_rejected, run_resumed, state_changed, output_delivered) · reason_code · policy_name · policy_version · decision | いつ、どの決定・状態変更が起きたか |
| usage_and_cost | model_call_count · tool_call_count · retry_count · total_input_tokens · total_output_tokens · estimated_cost · actual_cost · currency · price_book_version · priced_at · cost_is_estimate | 費用はいくらで、推定か実費か |
| outcome | terminal_state(completed, partial, failed, cancelled, abandoned, awaiting_human) · technical_success · task_success · final_output_present · user_visible_latency_ms · human_intervention_required · human_wait_duration_ms · user_feedback · user_corrected_result · user_undid_action · business_outcome_ref | ユーザーは実際の目的を達したか |
| privacy | capture_mode(metadata_only, redacted, external_reference, temporary_debug) · data_classes_detected(pii, secret, customer_data, untrusted_instruction) · redaction_profile_version · content_storage · retention_class · expires_at | 原文をどの範囲で、いつまで保存するか |
Retrievalで検索時間だけを見るのではなぜ足りないか
Retrieval Spanには遅延だけでなく、どのData Sourceをどの条件で検索したかを残します。現在のOpenTelemetry GenAI規約はdata_source.id、top_k、取得文書のIDとScoreを表現できます。[1] ただし文書一覧とQuery TextはOpt-Inで、Query Textに機密情報が入り得ると警告しています。
運用の基本項目はData Source IDとIndex・Snapshot Version、要求top_k、実際の返却文書数、非識別ReferenceとScore要約、Filter適用と結果数、Cache Hitです。Retrieval Latency、Empty Result、Queryの長さ・言語・分類などの派生情報を加え、必要な場合だけ原文Queryへの別Content Referenceを付けます。
全文をSpanへ複写しなくても、配備後に特定Data Sourceの結果が空になったか、誤ったIndex Versionを選んだか、検索成功でも関連度が低かったかを判断できます。異なるRetrieverやEmbedding ModelのScoreをそのまま比較してはいけません。意味は検索器とIndex構成に依存するため、Data Source Version・Retriever Versionと併せて解釈します。
Tool選択とTool実行を別段階にするのはなぜか
誤ったツールを選んだ問題と、正しいツールを選んだが実行に失敗した問題では、修正箇所が異なります。
Tool Selectionでは、利用可能Tool SetのVersionまたはHash、選択Tool、選択主体（Model、Plan、Rule、Human）を記録します。未選択の状態、tool_call_id、GuardrailやApprovalによる拒否・変更も残します。
Tool Executionでは、Tool名・Version、同じtool_call_id、Argument Schema Validation結果、開始・終了時刻、実行状態とerror_type、実際に呼んだ外部サービス・Operationを記録します。結果なし・部分処理、Side Effect、Retry、重複実行も含めます。
OpenTelemetryはexecute_tool SpanにTool Name、Tool Type、Tool Call ID、エラー種別を定義しています。[6] ArgumentとResultはOpt-Inで機密情報を含み得ます。自動計測から漏れるToolはアプリ側で計測する必要があります。選択理由を説明するためにモデルの内部推論全文を保存する必要はありません。提供Tool Set、選択結果、政策判断、実行結果を構造化すれば、運用診断に必要な大部分を得られます。
RetryとLoopに別Eventが必要なのはなぜか
現在のOpenTelemetryモデルSpan規約は、一時障害による自動再試行を含めて一つの論理Operation Durationを記録するよう勧めています。[1] 最終遅延には有用ですが、各試行の失敗原因まで自動的に分かるわけではありません。
Retry診断にはEventまたは子Spanを加えます。attempt_no、再試行理由、Backoff時間、前回error_type、同じProvider・Model・Toolの再呼出しか、前試行が外部システムへ到達した可能性、再試行後に復旧したか、Runを終わらせた最終失敗かを記録します。
Loopは単純Retryと分けます。Retryは一時失敗した同じ作業の再試行、Loopは状態が十分進まずModel Call・Tool Callを繰り返す現象です。Run当たりの両呼出数、同じToolと類似Argument、同一Retrieval Query、State Fingerprintの反復が役立ちます。Token・費用だけ増えてOutcomeが変わらない状態、最大Iteration到達、Human Intervention、強制終了も見ます。現在のGenAI MetricsにはAgent Invocation当たりInference Call数・Tool Call数、Agent Duration、Tool Execution Durationも提案されています。[6]
GuardrailとPolicyは何を一緒に残すか
Guardrailは実行の事実だけでは不十分です。どの段階で何を決定し、最終結果にどう影響したかを残します。最低限、検査時点（Input、Retrieval、Model Output、Tool Selection、Tool Result）、Policy・Rule名とVersion、決定（Allow、Block、Modify、Retry、Escalate）、違反Category、検査Latencyを記録します。Human Reviewへの移行、最終Run完了、原文の代わりとなる非識別Content Referenceの有無も含めます。
要求を遮断したGuardrailはセキュリティ上正常でも、ユーザーが理由を理解できず業務を完了できなければUser Outcomeは失敗または部分成功です。Policy DecisionとUser Outcomeを別々に記録します。
本稿の範囲はPolicy・Authorizationの結果の観測までです。MCP Token Audience、Token Passthrough、Tool Allowlist、Secret Boundary、Tenant Isolation、Revocationの設計は別のSecurity Control課題です。[4]
Human Interventionは遅延か正常フローか
人の承認待ちはModel LatencyでもTool Latencyでもありません。分離しなければ体感遅延の全体をAgent性能問題として集計してしまいます。承認要求時刻、対象作業とtool_call_id、承認・拒否・修正・期限切れ、役割ベースのReviewer識別子、待機時間、Run再開時刻、再開後の最終結果、人による直接修正を記録します。
OpenAI Agents SDKのHITLもTool Call前にRunを停止し、Pending ApprovalをInterruptionとして示します。直列化したRun Stateで承認・拒否した後、元のRunを再開します。この流れではHuman Waitを独立段階にします。
Human Intervention Rateが高くても常に悪いわけではありません。危険なSide Effectへの承認が意図した設計なら正常です。代わりに、承認待ちがユーザージャーニー目標を超えるか、不要な承認が反復するか、人が結果を頻繁に修正するかを確認します。
段階別にどの信号と診断質問を置くか
表はSession・Run開始からCostまでの十四段階について、残すSignal、代表的Failure Example、Diagnostic Questionをまとめています。各行の質問に答える信号がなければ、その段階の問題はユーザー申告でしか発見できません。
Stage | Signal | Failure Example | Diagnostic Question |
|---|---|---|---|
| Session・Run開始 | session_id、run_id、Agent・Workflow Version | 一要求が複数の独立Traceに分散 | 同じユーザー業務の全段階が一Runに接続されたか |
| Retrieval | Data Source Version、top_k、Result Count、Score Summary、Latency | 古いIndexから無関係文書を検索 | どのData Source・Versionを使い、実結果があったか |
| Plan | Plan Span、Agent Version、Child Model Call | 計画反復で実行へ進まない | 何回計画を作り、前回から何が変わったか |
| Model Call | Provider、Requested・Response Model、TTFC、Duration、Token、Finish Reason | 開始遅延や長さ制限による中断 | Provider待ちか生成遅延かOutput制限か |
| Tool Selection | Tool Set Version、Selected Tool、tool_call_id、Selection Source | 検索Toolではなくデータ変更Toolを選択 | 何を提供し、何を選択・拒否したか |
| Tool Execution | Tool Version、Schema Validation、Duration、Status、Dependency Span | 正しいToolが外部API Timeoutで失敗 | 選択は正しく実行が失敗したのか |
| Retry | Attempt、Reason、Backoff、Recovered | Providerエラーを三回再試行し遅延増 | 何回目にどのエラーが起き、復旧したか |
| Loop | Iteration、Repeated State、Model・Tool Call Count | 同じ検索・Tool Callを反復して費用増 | 状態が進まない反復はどこから始まったか |
| Guardrail・Policy | Policy Version、Stage、Decision、Category、Latency | 正常要求を反復遮断、または検査時間急増 | どの政策がどの段階で結果を変えたか |
| Human Intervention | Request・Decision Time、Wait Duration、Resume Result | Agentは速いが承認待ちに数十分 | 実実行と人待ちはそれぞれ何分か |
| External Dependency | Service、Operation、Status、Timeout、Trace Context | Toolは成功に見えるが下位DBが遅延 | Agent外のどの依存先がCritical Pathか |
| Failure | First Error、Terminal Error、Recovered、User-visible Failure | 中間エラーは復旧したが最終結果は部分完了 | 最初と最後の失敗は同じか |
| User Outcome | Technical Success、Task Success、Feedback、Correction、Undo | HTTP 200と回答があってもユーザーが再作業 | ユーザーは実際の目的を達したか |
| Cost | Usage、Estimated・Actual Cost、Price Book Version | 失敗Runが成功Runより多くのToken・Tool費用を消費 | どの段階で費用が増え、成功結果につながったか |
遅いAgentでCritical Pathから調べるのはなぜか
一つのRunで複数Toolが並列実行されるため、Child Span Duration合計はユーザー待機時間と一致しません。要求から初応答、最初のChunkから最終応答、実実行時間を分けます。Queue・Backoff・Rate Limit待ち、Human Approval待ち、並列作業の最長Critical Path、結果配信後の非同期作業時間も区別します。
現在のOpenTelemetry GenAI Metricsは、Model Operation全体のDurationだけでなくStreamingのTime to First Chunkと後続Chunk間時間を区別します。[6] Agent・Workflow単位のEnd-to-End Durationも個別Model Callとは別に提案されています。「回答が出始めるまで遅い」と「すぐ始まるが終わらない」を同じ平均Latencyへまとめてはいけません。
誤動作したAgentをOutcomeから逆に追うのはなぜか
最終文字列を生成しても業務成功とは限りません。少なくともtechnical_successとtask_successを分けます。前者はRunがエラーなく終了してFinal Outputを生成した状態、後者はユーザーの実際の目的を完了した状態です。
Task Successは用途別に定義します。支援Agentなら問い合わせ解決、運用Agentなら変更適用と検証、文書Agentなら必要ファイルの作成・配信です。購買Agentなら正しい対象・条件での注文、分析Agentなら結果採用です。Feedbackだけで判断しにくければ、Business Event、後続修正、Undo、再質問、Human Review、Evaluation Scoreを同じRun IDに結びます。LangSmithはFeedbackをRun IDに接続し、Google ADKは実際のTool TrajectoryとResponseを評価できます。
誤った結果はOutcomeから逆順に調べます。実際のTask Successが失敗したか、Final Outputが根拠と一致したか、Tool Execution結果を正しく反映したか、正しいToolを選んだか、Retrievalが適切かつ最新だったか、どのModel・Prompt・Agent・Tool Versionを使ったか、の順です。
Token数と費用が同じ意味ではないのはなぜか
Token Usageは費用計算の重要な入力ですが、実費そのものではありません。Provider、Model、Input・Output区分、Cache Read・Write、利用時価格、割引・契約条件、Tool・Retrievalの別料金で変わります。
RunにはProvider返却使用量、Input・Output・Cache別Token、要求別使用量、Tool・Retrievalの別Usageを区別して残します。Price Book Versionと適用時点、推定費用、請求データで確認した実費、EstimateかActualかも記録します。OpenTelemetryは使用量とBillable Tokenの両方を返すシステムではBillable Tokenを報告するよう定義しています。[1] OpenAI Agents SDKもRun全体と要求別Token Usageを別に保持します。
運用指標はRun当たり費用で止めません。成功業務当たり、人の修正不要な結果当たり、完了ユーザージャーニー当たりへ結び付けて、費用増が実際の価値に達したかを判断します。
原文を基本収集対象にしないのはなぜか
原文はデバッグを助けますが、名前・メール・電話番号などのPII、認証情報・API Key・Session Token、顧客データ・営業秘密、内部System Instruction、Tool Schema・内部API構造もTelemetry Backendへ入り得ます。Tool Argument・Result、Retrieval Query・原文文書、外部文書内のPrompt Injection Payloadも同様です。
OpenTelemetryはModel Instruction、User Message、Model Outputを既定で記録せずOpt-Inにするよう勧めています。[1] 運用で機密情報や保存量が問題なら、Contentを別保存しSpanにはReferenceだけを置く方法を推奨します。Tool Argument・ResultとRetrieval Queryも機密情報を含むOpt-In項目です。表に四つの推奨収集段階を示します。
フレームワークの既定値が組織方針と同じとは限りません。OpenTelemetryは原文未収集を基本としますが、OpenAI Agents SDKのtrace_include_sensitive_dataは現在trueです。Microsoftは開発・デバッグ時のContent Recording有効化と運用時の無効化を案内しています。Google ADKもPrompt、Tool Argument、Session Stateを含むDebug Outputを機密情報として扱い、PIIをSpan Attributeへ付けない設定を示しています。計測有効化と原文収集許可は、別の設定・承認手順にする必要があります。
段階 | 主な用途 | 収集範囲 |
|---|---|---|
| Metadata Only | 運用の基本値 | ID、Version、サイズ、遅延、状態、Token、Error、Outcome |
| Redacted・Derived | 限定的な原因分析 | 言語、長さ、Schema適合、PII・Secret検知Category、非識別Fingerprint |
| External Reference | 運用の詳細分析 | 別保護ストレージのContent Reference、アクセス権・保存期間を分離 |
| Temporary Debug | 一時的な再現 | 明示承認、限定対象、短いTTL、アクセス監査、終了後削除 |
Telemetry内のPrompt Injectionを信頼できるか
外部文書やTool Resultの悪意ある指示は、Retrieval・Tool Result・Prompt・Completionと一緒にTelemetryへ複写されます。別のAI Assistantが障害分析でそのLogを読むと、Telemetryが新たな間接Prompt Injection入力になります。
OWASPは、AIが読むLog・Link・External Referenceを非信頼入力として扱うよう指摘しています。[4] 一般Logging Guidanceも、外部Trust Zoneから来たEvent Dataを検証し、CR・LF・区切り文字を処理してLog Injectionを防ぐよう勧めています。
原文Telemetryには次の原則を適用します。実行可能なInstructionではなく非信頼データと表示し、Dashboard・Viewerで適切にEscape・Encodeします。外部LinkやActive Contentを自動実行せず、別Agentへ渡すときは原文と運用Instructionを分離します。Security Event分析Payloadには別保管方針を設け、Debug終了時にTemporary Captureを自動終了します。これはMCP Authorization設計ではなく、Telemetryが第二の保存先・入力経路になるという観測データ管理の問題です。
ダッシュボードをModelよりユーザー結果中心にするのはなぜか
平均Model Latencyと総Tokenだけを最初に置くと、ユーザー影響が後回しになります。先にRun単位のTask Success Rate、Partial・Failed・Abandoned Run Rate、体感End-to-End Latencyを見ます。続いてHuman Intervention Rate・Human Wait、Retry・Loop Rate、Run当たりModel Call・Tool Call数を置きます。Guardrail Block・Modify・Escalate Rate、External Dependency Error Contribution、成功業務当たり費用、ユーザー修正・Undo・再実行率も含めます。その後、Agent・Workflow・Prompt・Model・Tool・Data Source Version、配備環境別に分解します。
全Agentに共通の閾値は設けません。数秒以内に答える対話型Agentと、数分かけるバックグラウンド分析Agentは同じLatency基準を使えません。SLIは、そのAgentが支えるCritical User Journeyから選びます。[5]
安全な実装順序は何か
最初から全Prompt・Tool Resultを収集せず、上記八段階に沿います。Runの開始・終了定義とContext伝播の二段階がなければ、後の詳細計測を一つの実行経路へ組み立てられません。原文なしでSpan Coverageを作り、Retry・Loop・Human WaitをEventに加え、User Outcomeと費用モデルを結びます。その後にContent Capture PolicyとSchema Adapterを別途承認して設けます。
- 1. Runの開始と終了を定義する
- 要求の開始、完了・部分完了・失敗・中止を定義します。非同期で後から届く結果も元のRunへ結び付けます。
- 2. Session・Run・Trace Contextを伝播する
- API、Queue、Worker、別Agent、Retrieval System、Tool、外部サービスまで渡します。これがなければ詳細計測を一つの実行経路へ組み立てられません。
- 3. 原文なしでSpan Coverageを作る
- Retrieval、Model Call、Tool Selection、Tool Execution、Guardrail、外部依存をSpanに分け、Version、Duration、Status、Error Type、Call IDを残します。
- 4. Retry・Loop・Human WaitをEventに加える
- 自動計測では見えないAttempt、Backoff、反復状態、承認待ちを構造化します。
- 5. User Outcomeを接続する
- Final Output生成と実Task Successを分け、Feedback、Business Event、Correction、Undo、Human ReviewをRunへ結びます。
- 6. Usageと費用モデルを加える
- Token Usage、Tool Usage、Price Book Version、Estimate・Actualを分けます。費用は成功したユーザー結果と読みます。
- 7. Content Capture Policyを別途承認する
- 開発・運用環境、データ等級、Sampling、Redaction、アクセス権、TTL、削除手順を決め、フレームワーク設定を明示的に上書きします。
- 8. Schema Adapterと回帰検証を置く
- GenAI規約とRuntime TelemetryがDevelopment状態であることを踏まえ、内部Canonical SchemaとMapping Versionを設けます。SDK・計測ライブラリ更新後のField欠落や改名をテストします。
観測性の目的は全内容の保存か
良いAgent Observabilityは三つの質問に答えます。このRunで実際に何が起きたか。最初に遅延した、または誤った経路へ入った段階はどこか。その結果ユーザーは目的を達し、時間と費用はいくらかかったか。答えられるなら、全Prompt・Completion・Tool Argumentを原文保存する必要はありません。
逆にモデル呼出時間とToken数だけでは、システムが遅かったこと以外は分かりません。Retrievalが空か、誤ったToolを選んだか、Retry Loopか、Guardrail遮断か、人が未承認か、ユーザーの問題が本当に解決したかを判断できません。
AIエージェントの観測性は、モデルを詳しく見ることではありません。一つのRun内の判断・行動・待機・費用とユーザー結果を、一つの実行経路へ結び付けることです。
