OpenTelemetry エクスポート

• 診断イベントは、モデル実行、メッセージフロー、セッション、キュー、 exec について Gateway およびバンドルされたプラグインが生成する、構造化されたプロセス内レコードです。
• diagnostics-otel はこれらのイベントをサブスクライブし、OTLP/HTTP 経由で OpenTelemetry のメトリクス、トレース、ログとしてエクスポートします。また、 ログレコードを stdout JSONL にミラーリングできます。
• プロバイダー呼び出しでは、プロバイダーのトランスポートがカスタムヘッダーを受け付ける場合、 OpenClaw の信頼されたモデル呼び出しスパンコンテキストから W3C traceparent ヘッダーを受け取ります。 Plugin が生成したトレースコンテキストは伝播されません。
• エクスポーターは、診断サーフェスと Plugin の両方が有効な場合にのみ接続されるため、 デフォルトではプロセス内コストがほぼゼロに保たれます。

​

クイックスタート

openclaw plugins install clawhub:@openclaw/diagnostics-otel

{
  plugins: {
    allow: ["diagnostics-otel"],
    entries: {
      "diagnostics-otel": { enabled: true },
    },
  },
  diagnostics: {
    enabled: true,
    otel: {
      enabled: true,
      endpoint: "http://otel-collector:4318",
      protocol: "http/protobuf",
      serviceName: "openclaw-gateway",
      traces: true,
      metrics: true,
      logs: true,
      sampleRate: 0.2,
      flushIntervalMs: 60000,
    },
  },
}

​

エクスポートされるシグナル

​

設定リファレンス

{
  diagnostics: {
    enabled: true,
    otel: {
      enabled: true,
      endpoint: "http://otel-collector:4318",
      tracesEndpoint: "http://otel-collector:4318/v1/traces",
      metricsEndpoint: "http://otel-collector:4318/v1/metrics",
      logsEndpoint: "http://otel-collector:4318/v1/logs",
      protocol: "http/protobuf", // grpc は OTLP エクスポートを無効にする
      serviceName: "openclaw-gateway", // 未設定の場合は OTEL_SERVICE_NAME、次に "openclaw" にフォールバックする
      headers: { "x-collector-token": "..." },
      traces: true,
      metrics: true,
      logs: true,
      logsExporter: "otlp", // otlp | stdout | both
      sampleRate: 0.2, // ルートスパンのサンプラー、0.0..1.0
      flushIntervalMs: 60000, // メトリクスのエクスポート間隔（最小 1000ms）
      captureContent: {
        enabled: false,
        inputMessages: false,
        outputMessages: false,
        toolInputs: false,
        toolOutputs: false,
        systemPrompt: false,
        toolDefinitions: false,
      },
    },
  },
}

​

環境変数

​

プライバシーとコンテンツキャプチャ

• inputMessages - ユーザープロンプトの内容。
• outputMessages - モデル応答の内容。
• toolInputs - ツール引数のペイロード。
• toolOutputs - ツール結果のペイロード。
• systemPrompt - 組み立てられたシステム/開発者プロンプト。
• toolDefinitions - モデルツールの名前、説明、スキーマ。

​

サンプリングとフラッシュ

• トレース: diagnostics.otel.sampleRate はルートスパンのみに TraceIdRatioBasedSampler を設定します（0.0 はすべて破棄し、1.0 はすべて保持します）。未設定の場合は OpenTelemetry SDK のデフォルト（常時オン）を使用します。
• メトリクス: diagnostics.otel.flushIntervalMs（最小値 1000 に制限）。未設定の場合は SDK の定期エクスポートのデフォルトを使用します。
• ログ: OTLP ログは logging.level（ファイルログレベル）に従い、 コンソールの書式設定ではなく、診断ログレコードの秘匿化パスを使用します。大量のログが発生する インストール環境では、ローカルサンプリングよりも OTLP コレクターのサンプリングやフィルタリングを 優先してください。プラットフォームがすでに stdout/stderr をログプロセッサーへ 送信しており、OTLP ログコレクターがない場合は diagnostics.otel.logsExporter: "stdout" を設定します。 stdout レコードは、ts、signal、 service.name、重大度、本文、秘匿化された属性、および利用可能な場合は信頼済みのトレース フィールドを含む、1 行につき 1 つの JSON オブジェクトです。
• ファイルログの相関: JSONL ファイルログには、ログ呼び出しに有効な 診断トレースコンテキストが含まれる場合、トップレベルの traceId、 spanId、parentSpanId、および traceFlags が含まれます。これにより、ログプロセッサーはローカルのログ行を エクスポートされたスパンと結合できます。
• リクエストの相関: Gateway の HTTP リクエストと WebSocket フレームは、 内部リクエストトレーススコープを作成します。そのスコープ内のログと診断イベントは デフォルトでリクエストトレースを継承し、エージェント実行とモデル呼び出しの スパンは子として作成されるため、プロバイダーの traceparent ヘッダーは同じ トレース上に維持されます。
• モデル呼び出しの相関: openclaw.model.call スパンには、デフォルトで安全なプロンプト コンポーネントサイズが含まれ、プロバイダーの結果で使用量が公開される場合は呼び出しごとのトークン属性も含まれます。 openclaw.model.usage は、コスト、コンテキスト、およびチャンネルのダッシュボードを集計するための実行レベルの 会計スパンとして引き続き使用され、イベントを発行するランタイムに信頼済みの トレースコンテキストがある場合は同じ診断トレース上に維持されます。

​

モデル呼び出しの観測単位

• request - 観測可能な 1 回のモデル／プロバイダーリクエスト。ネイティブの組み込みモデル 呼び出しはこの単位を使用し、古い発行元または外部の発行元との互換性のため、 値がない場合、エクスポーターは request として扱います。
• turn - 非公開のモデルリクエスト、再試行、ツール処理、またはバックグラウンド処理を含む可能性がある、不透明な 1 回のエージェント CLI ターン。 Claude Code CLI と Codex app-server の呼び出しはこの単位を使用します。

​

Claude Code CLI のモデル呼び出し忠実度

• stdio - 1 回限りのローカル Claude Code プロセス。
• stdio-live - 管理対象の永続 Claude stdio セッション上の 1 ターン。
• paired-node-cli - ペアリング済みの Node に委任された 1 回限りの Claude Code 実行。

• openclaw.model_call.request_bytes は、1 回限りの stdin/argv を介して送信されたプロンプト値、 または管理対象 stdio の JSONL ユーザーエンベロープの UTF-8 サイズです。 Claude Code の非公開モデルリクエストのサイズではありません。
• openclaw.model_call.response_bytes は、ターン中に観測された Claude CLI stdout の UTF-8 サイズです。Anthropic HTTP 応答のサイズではありません。
• openclaw.model_call.time_to_first_byte_ms は、観測可能な最初の Claude CLI stdout または stderr 出力までの時間です。ネットワーク TTFB ではありません。

​

エクスポートされるメトリクス

​

モデル使用量

• openclaw.tokens（カウンター、属性: openclaw.token、openclaw.channel、openclaw.provider、openclaw.model、openclaw.agent）
• openclaw.cost.usd（カウンター、属性: openclaw.channel、openclaw.provider、openclaw.model）
• openclaw.run.duration_ms（ヒストグラム、属性: openclaw.channel、openclaw.provider、openclaw.model）
• openclaw.context.tokens（ヒストグラム、属性: openclaw.context、openclaw.channel、openclaw.provider、openclaw.model）
• gen_ai.client.token.usage（ヒストグラム、GenAI セマンティック規約メトリクス、属性: gen_ai.token.type = input/output、gen_ai.provider.name、gen_ai.operation.name、gen_ai.request.model）
• gen_ai.client.operation.duration（ヒストグラム、秒、モデルリクエストおよび合成エージェントターン用の GenAI セマンティック規約メトリクス。属性: gen_ai.provider.name、gen_ai.operation.name、gen_ai.request.model、任意の error.type。ターンの観測では gen_ai.operation.name = invoke_agent を使用）
• openclaw.model_call.duration_ms（ヒストグラム、属性: openclaw.provider、openclaw.model、openclaw.api、openclaw.transport、openclaw.model_call.observation_unit、さらに分類済みエラーでは openclaw.errorCategory および openclaw.failureKind）
• openclaw.model_call.request_bytes（ヒストグラム、最終モデルリクエストペイロードの UTF-8 バイトサイズ。Claude Code CLI の場合は前述の観測可能なプロンプト入力／エンベロープ。生のペイロードコンテンツは含まれません）
• openclaw.model_call.response_bytes（ヒストグラム、ストリーミング応答チャンクペイロードの UTF-8 バイトサイズ。高頻度のテキスト、思考、およびツール呼び出しの差分では、増分の delta バイトのみを計上。Claude Code CLI の場合は観測された stdout バイト。生の応答コンテンツは含まれません）
• openclaw.model_call.time_to_first_byte_ms（ヒストグラム、最初のストリーミング応答イベントまでの経過時間。Claude Code CLI の場合はネットワーク TTFB ではなく、観測可能な最初の CLI 出力）
• openclaw.model.failover（カウンター、属性: openclaw.provider、openclaw.model、openclaw.failover.to_provider、openclaw.failover.to_model、openclaw.failover.reason、openclaw.failover.suspended、openclaw.lane）
• openclaw.skill.used（カウンター、属性: openclaw.skill.name、openclaw.skill.source、openclaw.skill.activation、任意の openclaw.agent、任意の openclaw.toolName）

​

メッセージフロー

• openclaw.webhook.received（カウンター、属性: openclaw.channel、openclaw.webhook）
• openclaw.webhook.error（カウンター、属性: openclaw.channel、openclaw.webhook）
• openclaw.webhook.duration_ms（ヒストグラム、属性: openclaw.channel、openclaw.webhook）
• openclaw.message.queued（カウンター、属性: openclaw.channel、openclaw.source）
• openclaw.message.received（カウンター、属性: openclaw.channel、openclaw.source）
• openclaw.message.dispatch.started（カウンター、属性: openclaw.channel、openclaw.source）
• openclaw.message.dispatch.completed（カウンター、属性: openclaw.channel、openclaw.outcome、openclaw.reason、openclaw.source）
• openclaw.message.dispatch.duration_ms（ヒストグラム、属性: openclaw.channel、openclaw.outcome、openclaw.reason、openclaw.source）
• openclaw.message.processed（カウンター、属性: openclaw.channel、openclaw.outcome）
• openclaw.message.duration_ms（ヒストグラム、属性: openclaw.channel、openclaw.outcome）
• openclaw.message.delivery.started（カウンター、属性: openclaw.channel、openclaw.delivery.kind）
• openclaw.message.delivery.duration_ms（ヒストグラム、属性: openclaw.channel、openclaw.delivery.kind、openclaw.outcome、openclaw.errorCategory）

​

Talk

• openclaw.talk.event（カウンター、属性: openclaw.talk.event_type、openclaw.talk.mode、openclaw.talk.transport、openclaw.talk.brain、openclaw.talk.provider）
• openclaw.talk.event.duration_ms（ヒストグラム、属性: openclaw.talk.event と同じ。Talk イベントが継続時間を報告したときに発行）
• openclaw.talk.audio.bytes（ヒストグラム、属性: openclaw.talk.event と同じ。バイト長を報告する Talk 音声フレームイベントに対して発行）

​

キューとセッション

• openclaw.queue.lane.enqueue（カウンター、属性: openclaw.lane）
• openclaw.queue.lane.dequeue（カウンター、属性: openclaw.lane）
• openclaw.queue.depth（ヒストグラム、属性: openclaw.lane または openclaw.channel=heartbeat）
• openclaw.queue.wait_ms（ヒストグラム、属性: openclaw.lane）
• openclaw.session.state（カウンター、属性: openclaw.state、openclaw.reason）
• openclaw.session.stuck（カウンター、属性: openclaw.state。回復可能な古いセッション管理情報に対して発行）
• openclaw.session.stuck_age_ms（ヒストグラム、属性: openclaw.state。回復可能な古いセッション管理情報に対して発行）
• openclaw.session.turn.created（カウンター、属性: openclaw.agent、openclaw.channel、openclaw.trigger）
• openclaw.session.recovery.requested（カウンター、属性: openclaw.state、openclaw.action、openclaw.active_work_kind、openclaw.reason）
• openclaw.session.recovery.completed（カウンター、属性: openclaw.state、openclaw.action、openclaw.status、openclaw.active_work_kind、openclaw.reason）
• openclaw.session.recovery.age_ms（ヒストグラム、属性: 対応する回復カウンターと同じ）
• openclaw.run.attempt（カウンター、属性: openclaw.attempt）

​

セッションの生存性テレメトリ

• session.long_running: アクティブな組み込み処理、モデル呼び出し、またはツール呼び出しが 引き続き進行しています。所有者のいる無応答のモデル呼び出しも、組み込みの中止しきい値に達するまでは長時間実行中として報告されるため、中止を観測できる間は、低速または非ストリーミングのモデルプロバイダーが停止した Gateway セッションと見なされることはありません。
• session.stalled: アクティブな処理は存在しますが、アクティブな実行から 最近の進行が報告されていません。所有者のいるモデル呼び出しは、組み込みの中止しきい値に達するか超えると session.long_running から session.stalled に切り替わります。所有者がなく 古くなったモデルまたはツールのアクティビティは、無害な長時間実行処理とは見なされません。 停止した組み込み実行は、最初は観測のみに留まり、その後、 進行がないまま中止しきい値を超えると中止後の排出処理を行い、レーンの後ろで待機しているターンを再開できるようにします。
• session.stuck: アクティブな処理がない古いセッション管理情報、または 所有者のない古いモデルまたはツールのアクティビティを伴う、アイドル状態のキュー済みセッションです。これにより、 回復ゲートを通過した直後に、影響を受けたセッションレーンが解放されます。

• openclaw.liveness.warning（カウンター、属性: openclaw.liveness.reason）
• openclaw.liveness.event_loop_delay_p99_ms（ヒストグラム、属性: openclaw.liveness.reason）
• openclaw.liveness.event_loop_delay_max_ms（ヒストグラム、属性: openclaw.liveness.reason）
• openclaw.liveness.event_loop_utilization（ヒストグラム、属性: openclaw.liveness.reason）
• openclaw.liveness.cpu_core_ratio（ヒストグラム、属性: openclaw.liveness.reason）

​

ハーネスのライフサイクル

• openclaw.harness.duration_ms（ヒストグラム、属性: openclaw.harness.id、openclaw.harness.plugin、openclaw.outcome、エラー時は openclaw.harness.phase）

​

ツールの実行とループ検出

• openclaw.tool.execution.duration_ms（ヒストグラム、属性: gen_ai.tool.name、openclaw.toolName、openclaw.tool.source、openclaw.tool.owner、openclaw.tool.params.kind、およびエラー時は openclaw.errorCategory）
• openclaw.tool.execution.blocked（カウンター、属性: gen_ai.tool.name、openclaw.toolName、openclaw.tool.source、openclaw.tool.owner、openclaw.tool.params.kind、openclaw.deniedReason）
• openclaw.tool.loop（カウンター、属性: openclaw.toolName、openclaw.loop.level、openclaw.loop.action、openclaw.loop.detector、openclaw.loop.count、任意の openclaw.loop.paired_tool。反復的なツール呼び出しループが検出されたときに発行）

​

Exec

• openclaw.exec.duration_ms（ヒストグラム、属性: openclaw.exec.target、openclaw.exec.mode、openclaw.outcome、openclaw.failureKind）

​

診断の内部情報（メモリ、ペイロード、エクスポーターの状態）

• openclaw.payload.large（カウンター、属性: openclaw.payload.surface、openclaw.payload.action、openclaw.channel、openclaw.plugin、openclaw.reason）
• openclaw.payload.large_bytes（ヒストグラム、属性: openclaw.payload.large と同じ）
• openclaw.memory.rss_bytes / openclaw.memory.heap_used_bytes / openclaw.memory.heap_total_bytes / openclaw.memory.external_bytes / openclaw.memory.array_buffers_bytes（ヒストグラム、属性なし。プロセスメモリのサンプル）
• openclaw.memory.pressure（カウンター、属性: openclaw.memory.level、openclaw.memory.reason）
• openclaw.diagnostic.async_queue.dropped（カウンター、属性: openclaw.diagnostic.async_queue.drop_class。内部診断キューのバックプレッシャーによる破棄）
• openclaw.telemetry.exporter.events（カウンター、属性: openclaw.exporter、openclaw.signal、openclaw.status、任意の openclaw.reason、任意の openclaw.errorCategory。エクスポーターのライフサイクルおよび障害に関する自己テレメトリ）

​

エクスポートされるスパン

• openclaw.model.usage
  • openclaw.channel、openclaw.provider、openclaw.model
  • openclaw.tokens.*（input/output/cache_read/cache_write/total）
  • デフォルトでは gen_ai.system、最新の GenAI セマンティック規約をオプトインした場合は gen_ai.provider.name
  • gen_ai.request.model、gen_ai.operation.name、gen_ai.usage.*
• openclaw.run
  • openclaw.outcome、openclaw.channel、openclaw.provider、openclaw.model、openclaw.errorCategory
• openclaw.model.call
  • デフォルトでは gen_ai.system、最新の GenAI セマンティック規約をオプトインした場合は gen_ai.provider.name
  • gen_ai.request.model、gen_ai.operation.name、openclaw.provider、openclaw.model、openclaw.api、openclaw.transport、openclaw.model_call.observation_unit（request または turn）
  • openclaw.errorCategory、error.type、およびエラー時の任意の openclaw.failureKind
  • openclaw.model_call.request_bytes、openclaw.model_call.response_bytes、openclaw.model_call.time_to_first_byte_ms
  • openclaw.model_call.prompt.input_messages_count、openclaw.model_call.prompt.input_messages_chars、openclaw.model_call.prompt.system_prompt_chars、openclaw.model_call.prompt.tool_definitions_count、openclaw.model_call.prompt.tool_definitions_chars、openclaw.model_call.prompt.total_chars（安全なコンポーネントサイズのみ。プロンプトテキストは含まない）
  • 結果に該当リクエストまたは集約ターンの使用量が含まれる場合は、openclaw.model_call.usage.* および gen_ai.usage.*
  • アップストリームプロバイダーの結果でリクエスト ID が公開されている場合、属性 openclaw.upstreamRequestIdHash（上限付き、ハッシュベース）を持つスパンイベント openclaw.provider.request。生の ID は決してエクスポートされません
  • OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental を使用すると、リクエストスパンでは最新の GenAI 推論スパン名 {gen_ai.operation.name} {gen_ai.request.model} が使用されます。OpenClaw は不透明な CLI 境界からネイティブのエージェント名を推定しないため、ターンスパンでは invoke_agent が使用されます。どちらも openclaw.model.call ではなく、スパン種別 CLIENT を使用します。
• openclaw.harness.run
  • openclaw.harness.id、openclaw.harness.plugin、openclaw.outcome、openclaw.provider、openclaw.model、openclaw.channel
  • 完了時: openclaw.harness.result_classification、openclaw.harness.yield_detected、openclaw.harness.items.started、openclaw.harness.items.completed、openclaw.harness.items.active
  • エラー時: openclaw.harness.phase、openclaw.errorCategory、任意の openclaw.harness.cleanup_failed
• openclaw.tool.execution
  • gen_ai.tool.name、gen_ai.operation.name（execute_tool）、openclaw.toolName、openclaw.tool.source、任意の gen_ai.tool.call.id、openclaw.tool.owner、openclaw.tool.params.*
  • エラー時の任意の openclaw.errorCategory/openclaw.errorCode、ポリシーまたはサンドボックスにより拒否された場合の openclaw.deniedReason および openclaw.outcome=blocked
• openclaw.exec
  • openclaw.exec.target、openclaw.exec.mode、openclaw.outcome、openclaw.failureKind、openclaw.exec.command_length、openclaw.exec.exit_code、openclaw.exec.exit_signal、openclaw.exec.timed_out
• openclaw.webhook.processed
  • openclaw.channel、openclaw.webhook
• openclaw.webhook.error
  • openclaw.channel、openclaw.webhook、openclaw.error
• openclaw.message.processed
  • openclaw.channel、openclaw.outcome、openclaw.reason
• openclaw.message.delivery
  • openclaw.channel、openclaw.delivery.kind、openclaw.outcome、openclaw.errorCategory、openclaw.delivery.result_count
• openclaw.session.stuck
  • openclaw.state、openclaw.ageMs、openclaw.queueDepth
• openclaw.context.assembled
  • openclaw.prompt.size、openclaw.history.size、openclaw.context.tokens、openclaw.errorCategory（プロンプト、履歴、応答、セッションキーの内容は含まない）
• openclaw.tool.loop
  • openclaw.toolName、openclaw.loop.level、openclaw.loop.action、openclaw.loop.detector、openclaw.loop.count、任意の openclaw.loop.paired_tool（ループメッセージ、パラメーター、ツール出力は含まない）
• openclaw.memory.pressure
  • openclaw.memory.level、openclaw.memory.reason、openclaw.memory.rss_bytes、openclaw.memory.heap_used_bytes、openclaw.memory.heap_total_bytes、openclaw.memory.external_bytes、openclaw.memory.array_buffers_bytes、任意の openclaw.memory.threshold_bytes/openclaw.memory.rss_growth_bytes/openclaw.memory.window_ms

​

診断イベントカタログ

• model.usage - トークン、コスト、所要時間、コンテキスト、プロバイダー/モデル/チャンネル、 セッション ID。usage はコストとテレメトリに使用するプロバイダー/ターンのアカウンティングです。 context.used は現在のプロンプト/コンテキストのスナップショットであり、 キャッシュ済み入力またはツールループ呼び出しが関係する場合、プロバイダーの usage.total より小さくなることがあります。

• webhook.received / webhook.processed / webhook.error
• message.queued / message.processed
• message.delivery.started / message.delivery.completed / message.delivery.error

• queue.lane.enqueue / queue.lane.dequeue
• session.state / session.long_running / session.stalled / session.stuck
• run.attempt / run.progress
• run.execution_phase（公開される、セッションに関連付けられた組み込みランナーの起動マイルストーン）
• diagnostic.heartbeat（集約カウンター: Webhook/キュー/セッション）

• harness.run.started / harness.run.completed / harness.run.error - エージェントハーネスの実行ごとのライフサイクル。harnessId、任意の pluginId、プロバイダー/モデル/チャンネル、および実行 ID を含みます。完了時には durationMs、outcome、任意の resultClassification、yieldDetected、 および itemLifecycle のカウントが追加されます。エラー時には phase （prepare/start/send/resolve/cleanup）、errorCategory、および 任意の cleanupFailed が追加されます。

• exec.process.completed - ターミナルの結果、所要時間、ターゲット、モード、終了 コード、失敗の種類。コマンドテキストと作業ディレクトリは 含まれません。
• exec.approval.followup_suppressed - セッションの再バインド後に破棄された 古い承認のフォローアップ。approvalId、reason （session_rebound）、phase（direct_delivery または gateway_preflight）、 およびディスパッチャーのタイムスタンプが含まれます。セッションキー、ルート、コマンドテキストは 含まれません。

​

エクスポーターを使用しない場合

{
  diagnostics: { enabled: true },
}

{
  diagnostics: { flags: ["telegram.http"] },
}

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway

​

無効化

{
  diagnostics: { otel: { enabled: false } },
}

​

関連項目

• ロギング - ファイルログ、コンソール出力、CLI の追尾、Control UI の Logs タブ
• Gateway ロギングの内部構造 - WS ログのスタイル、サブシステムのプレフィックス、コンソールキャプチャ
• 診断フラグ - 対象を絞ったデバッグログ用フラグ
• 診断エクスポート - オペレーター向けサポートバンドルツール（OTEL エクスポートとは別）
• 設定リファレンス - diagnostics.* フィールドの完全なリファレンス