OpenTelemetry エクスポート

• 診断イベントは、モデル実行、メッセージフロー、セッション、キュー、 exec のために Gateway とバンドル済み plugin が発行する、構造化された プロセス内レコードです。
• diagnostics-otel はそれらのイベントを購読し、OTLP/HTTP 経由で OpenTelemetry のメトリクス、トレース、ログとしてエクスポートし、 ログレコードを stdout JSONL にミラーリングできます。
• プロバイダー呼び出しは、プロバイダーのトランスポートがカスタムヘッダーを 受け付ける場合、OpenClaw の信頼済みモデル呼び出し span コンテキストから 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 disables OTLP export
      serviceName: "openclaw-gateway", // unset falls back to OTEL_SERVICE_NAME, then "openclaw"
      headers: { "x-collector-token": "..." },
      traces: true,
      metrics: true,
      logs: true,
      logsExporter: "otlp", // otlp | stdout | both
      sampleRate: 0.2, // root-span sampler, 0.0..1.0
      flushIntervalMs: 60000, // metric export interval (min 1000ms)
      captureContent: {
        enabled: false,
        inputMessages: false,
        outputMessages: false,
        toolInputs: false,
        toolOutputs: false,
        systemPrompt: false,
        toolDefinitions: false,
      },
    },
  },
}

​

環境変数

​

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

• inputMessages - ユーザープロンプトコンテンツ。
• outputMessages - モデル応答コンテンツ。
• toolInputs - ツール引数ペイロード。
• toolOutputs - ツール結果ペイロード。
• systemPrompt - 組み立て済み system/developer プロンプト。
• 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 レコードは、1 行につき 1 つの JSON オブジェクトで、ts、signal、 service.name、重大度、本文、リダクト済み属性、利用可能な場合は信頼済みトレース フィールドを含みます。
• ファイルログ相関: JSONL ファイルログには、ログ呼び出しが有効な 診断トレースコンテキストを持つ場合、トップレベルの traceId、 spanId、parentSpanId、traceFlags が含まれ、ログプロセッサーがローカルログ行を エクスポート済みスパンと結合できます。
• リクエスト相関: Gateway HTTP リクエストと WebSocket フレームは 内部リクエストトレーススコープを作成します。その スコープ内のログと診断イベントはデフォルトでリクエストトレースを継承し、一方でエージェント実行とモデル呼び出し スパンは子として作成されるため、プロバイダーの traceparent ヘッダーは同じトレース上に維持されます。
• モデル呼び出し相関: openclaw.model.call スパンには、デフォルトで安全なプロンプト コンポーネントサイズが含まれ、プロバイダー 結果が使用量を公開している場合は呼び出しごとのトークン属性も含まれます。openclaw.model.usage は、集計コスト、コンテキスト、チャンネルダッシュボード向けの実行レベル 会計スパンのままであり、 発行元ランタイムに信頼済みトレースコンテキストがある場合は同じ診断トレース上に残ります。

​

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

​

モデル使用量

• 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）
• openclaw.model_call.duration_ms（ヒストグラム、属性: openclaw.provider、openclaw.model、openclaw.api、openclaw.transport、分類済みエラーではさらに openclaw.errorCategory と openclaw.failureKind）
• openclaw.model_call.request_bytes（ヒストグラム、最終モデルリクエストペイロードの UTF-8 バイトサイズ。生ペイロード内容は含まない）
• openclaw.model_call.response_bytes（ヒストグラム、ストリーミングされたレスポンスチャンクペイロードの UTF-8 バイトサイズ。高頻度のテキスト、thinking、ツール呼び出しデルタは増分の delta バイトのみをカウント。生レスポンス内容は含まない）
• openclaw.model_call.time_to_first_byte_ms（ヒストグラム、最初のストリーミングレスポンスイベントまでの経過時間）
• 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（ヒストグラム、属性: 対応する recovery カウンターと同じ）
• openclaw.run.attempt（カウンター、属性: openclaw.attempt）

​

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

• session.long_running: アクティブな埋め込み作業、モデル呼び出し、またはツール呼び出しが まだ進行しています。所有されているモデル呼び出しが diagnostics.stuckSessionWarnMs を超えて無音のままでも、 diagnostics.stuckSessionAbortMs の前には long-running として報告されるため、低速または非ストリーミングのモデルプロバイダーは、 中断を観測できる間は停止した Gateway セッションのようには見えません。
• session.stalled: アクティブな作業は存在しますが、アクティブな実行が最近の 進行を報告していません。所有されているモデル呼び出しは、diagnostics.stuckSessionAbortMs 以降に session.long_running から session.stalled に切り替わります。所有者のない 古いモデル/ツールアクティビティは、無害な長時間実行作業として扱われません。 停止した埋め込み実行は最初は観測のみのままになり、その後 diagnostics.stuckSessionAbortMs を超えて進行がない場合は中断ドレインされるため、 レーンの後ろにあるキュー済みターンを再開できます。未設定の場合、中断しきい値は、 少なくとも 5 分かつ diagnostics.stuckSessionWarnMs の 3 倍という、より安全な延長ウィンドウにデフォルト設定されます。
• 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.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 では、モデル呼び出しスパンは openclaw.model.call の代わりに、最新の GenAI 推論スパン名 {gen_ai.operation.name} {gen_ai.request.model} と 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, openclaw.toolName, openclaw.tool.source, 任意の 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
• 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.* フィールドの完全なリファレンス