English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Gateway

Ekspor OpenTelemetry

OpenClaw mengekspor diagnostik melalui Plugin resmi diagnostics-otel menggunakan OTLP/HTTP (protobuf). Kolektor atau backend apa pun yang menerima OTLP/HTTP berfungsi tanpa perubahan kode. Untuk log file lokal dan cara membacanya, lihat Logging.

Cara semuanya terhubung

  • Peristiwa diagnostik adalah rekaman terstruktur dalam proses yang dipancarkan oleh Gateway dan Plugin bawaan untuk eksekusi model, alur pesan, sesi, antrean, dan exec.
  • Plugin diagnostics-otel berlangganan ke peristiwa tersebut dan mengekspornya sebagai metrik, trace, dan log OpenTelemetry melalui OTLP/HTTP.
  • Panggilan penyedia menerima header W3C traceparent dari konteks span panggilan model tepercaya milik OpenClaw ketika transport penyedia menerima header kustom. Konteks trace yang dipancarkan Plugin tidak dipropagasikan.
  • Eksportir hanya terpasang ketika permukaan diagnostik dan Plugin sama-sama diaktifkan, sehingga biaya dalam proses tetap mendekati nol secara default.

Mulai cepat

Untuk instalasi paket, instal Plugin terlebih dahulu:

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,
    },
  },
}

Anda juga dapat mengaktifkan Plugin dari CLI:

openclaw plugins enable diagnostics-otel

Sinyal yang diekspor

Sinyal Isi di dalamnya
Metrik Counter dan histogram untuk penggunaan token, biaya, durasi eksekusi, alur pesan, peristiwa Talk, jalur antrean, status/pemulihan sesi, exec, dan tekanan memori.
Trace Span untuk penggunaan model, panggilan model, siklus hidup harness, eksekusi alat, exec, pemrosesan webhook/pesan, penyusunan konteks, dan loop alat.
Log Rekaman logging.file terstruktur yang diekspor melalui OTLP ketika diagnostics.otel.logs diaktifkan.

Aktifkan/nonaktifkan traces, metrics, dan logs secara independen. Ketiganya aktif secara default ketika diagnostics.otel.enabled bernilai true.

Referensi konfigurasi

{
  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 is ignored
      serviceName: "openclaw-gateway",
      headers: { "x-collector-token": "..." },
      traces: true,
      metrics: true,
      logs: true,
      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,
      },
    },
  },
}

Variabel lingkungan

Variabel Tujuan
OTEL_EXPORTER_OTLP_ENDPOINT Mengganti diagnostics.otel.endpoint. Jika nilainya sudah berisi /v1/traces, /v1/metrics, atau /v1/logs, nilai tersebut digunakan apa adanya.
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT / OTEL_EXPORTER_OTLP_METRICS_ENDPOINT / OTEL_EXPORTER_OTLP_LOGS_ENDPOINT Penggantian endpoint khusus sinyal yang digunakan ketika kunci konfigurasi diagnostics.otel.*Endpoint yang sesuai belum diatur. Konfigurasi khusus sinyal mengungguli env khusus sinyal, yang mengungguli endpoint bersama.
OTEL_SERVICE_NAME Mengganti diagnostics.otel.serviceName.
OTEL_EXPORTER_OTLP_PROTOCOL Mengganti protokol wire (hanya http/protobuf yang dihormati saat ini).
OTEL_SEMCONV_STABILITY_OPT_IN Atur ke gen_ai_latest_experimental untuk memancarkan atribut span GenAI eksperimental terbaru (gen_ai.provider.name) alih-alih gen_ai.system lama. Metrik GenAI selalu menggunakan atribut semantik berbatas dan berkardinalitas rendah.
OPENCLAW_OTEL_PRELOADED Atur ke 1 ketika preload atau proses host lain sudah mendaftarkan SDK OpenTelemetry global. Plugin kemudian melewati siklus hidup NodeSDK miliknya sendiri tetapi tetap memasang listener diagnostik dan menghormati traces/metrics/logs.

Privasi dan pengambilan konten

Konten mentah model/alat tidak diekspor secara default. Span membawa pengidentifikasi berbatas (channel, penyedia, model, kategori error, id permintaan hanya hash) dan tidak pernah menyertakan teks prompt, teks respons, input alat, output alat, atau kunci sesi. Metrik Talk hanya mengekspor metadata peristiwa berbatas seperti mode, transport, penyedia, dan jenis peristiwa. Metrik tersebut tidak menyertakan transkrip, payload audio, id sesi, id giliran, id panggilan, id ruang, atau token handoff.

Permintaan model keluar dapat menyertakan header W3C traceparent. Header tersebut dibuat hanya dari konteks trace diagnostik milik OpenClaw untuk panggilan model aktif. Header traceparent yang sudah dipasok pemanggil diganti, sehingga Plugin atau opsi penyedia kustom tidak dapat memalsukan asal-usul trace lintas layanan.

Atur diagnostics.otel.captureContent.* ke true hanya ketika kolektor dan kebijakan retensi Anda disetujui untuk teks prompt, respons, alat, atau system-prompt. Setiap subkunci bersifat ikut serta secara independen:

  • inputMessages - konten prompt pengguna.
  • outputMessages - konten respons model.
  • toolInputs - payload argumen alat.
  • toolOutputs - payload hasil alat.
  • systemPrompt - prompt sistem/developer yang dirangkai.

Ketika salah satu subkunci diaktifkan, span model dan alat mendapatkan atribut openclaw.content.* berbatas dan disunting hanya untuk kelas tersebut.

Sampling dan flushing

  • Trace: diagnostics.otel.sampleRate (hanya root-span, 0.0 membuang semua, 1.0 menyimpan semua).
  • Metrik: diagnostics.otel.flushIntervalMs (minimum 1000).
  • Log: Log OTLP menghormati logging.level (level log file). Log tersebut menggunakan jalur redaksi rekaman log diagnostik, bukan pemformatan konsol. Instalasi bervolume tinggi sebaiknya memilih sampling/filtering kolektor OTLP dibanding sampling lokal.
  • Korelasi log file: Log file JSONL menyertakan traceId, spanId, parentSpanId, dan traceFlags tingkat atas ketika panggilan log membawa konteks trace diagnostik yang valid, sehingga pemroses log dapat menggabungkan baris log lokal dengan span yang diekspor.
  • Korelasi permintaan: Permintaan HTTP Gateway dan frame WebSocket membuat cakupan trace permintaan internal. Log dan peristiwa diagnostik di dalam cakupan tersebut mewarisi trace permintaan secara default, sementara span eksekusi agen dan panggilan model dibuat sebagai anak sehingga header traceparent penyedia tetap berada pada trace yang sama.

Metrik yang diekspor

Penggunaan model

  • openclaw.tokens (counter, attrs: openclaw.token, openclaw.channel, openclaw.provider, openclaw.model, openclaw.agent)
  • openclaw.cost.usd (counter, attrs: openclaw.channel, openclaw.provider, openclaw.model)
  • openclaw.run.duration_ms (histogram, attrs: openclaw.channel, openclaw.provider, openclaw.model)
  • openclaw.context.tokens (histogram, attrs: openclaw.context, openclaw.channel, openclaw.provider, openclaw.model)
  • gen_ai.client.token.usage (histogram, metrik konvensi semantik GenAI, attrs: gen_ai.token.type = input/output, gen_ai.provider.name, gen_ai.operation.name, gen_ai.request.model)
  • gen_ai.client.operation.duration (histogram, detik, metrik konvensi semantik GenAI, attrs: gen_ai.provider.name, gen_ai.operation.name, gen_ai.request.model, opsional error.type)
  • openclaw.model_call.duration_ms (histogram, attrs: openclaw.provider, openclaw.model, openclaw.api, openclaw.transport, plus openclaw.errorCategory dan openclaw.failureKind pada error yang diklasifikasikan)
  • openclaw.model_call.request_bytes (histogram, ukuran byte UTF-8 dari payload permintaan model final; tanpa konten payload mentah)
  • openclaw.model_call.response_bytes (histogram, ukuran byte UTF-8 dari peristiwa respons model streaming; tanpa konten respons mentah)
  • openclaw.model_call.time_to_first_byte_ms (histogram, waktu berlalu sebelum peristiwa respons streaming pertama)

Alur pesan

  • openclaw.webhook.received (counter, attrs: openclaw.channel, openclaw.webhook)
  • openclaw.webhook.error (counter, attrs: openclaw.channel, openclaw.webhook)
  • openclaw.webhook.duration_ms (histogram, attrs: openclaw.channel, openclaw.webhook)
  • openclaw.message.queued (counter, attrs: openclaw.channel, openclaw.source)
  • openclaw.message.processed (counter, attrs: openclaw.channel, openclaw.outcome)
  • openclaw.message.duration_ms (histogram, attrs: openclaw.channel, openclaw.outcome)
  • openclaw.message.delivery.started (counter, attrs: openclaw.channel, openclaw.delivery.kind)
  • openclaw.message.delivery.duration_ms (histogram, attrs: openclaw.channel, openclaw.delivery.kind, openclaw.outcome, openclaw.errorCategory)

Talk

  • openclaw.talk.event (counter, attrs: openclaw.talk.event_type, openclaw.talk.mode, openclaw.talk.transport, openclaw.talk.brain, openclaw.talk.provider)
  • openclaw.talk.event.duration_ms (histogram, attrs: sama seperti openclaw.talk.event; dipancarkan ketika peristiwa Talk melaporkan durasi)
  • openclaw.talk.audio.bytes (histogram, attrs: sama seperti openclaw.talk.event; dipancarkan untuk peristiwa frame audio Talk yang melaporkan panjang byte)

Antrean dan sesi

  • openclaw.queue.lane.enqueue (penghitung, atribut: openclaw.lane)
  • openclaw.queue.lane.dequeue (penghitung, atribut: openclaw.lane)
  • openclaw.queue.depth (histogram, atribut: openclaw.lane atau openclaw.channel=heartbeat)
  • openclaw.queue.wait_ms (histogram, atribut: openclaw.lane)
  • openclaw.session.state (penghitung, atribut: openclaw.state, openclaw.reason)
  • openclaw.session.stuck (penghitung, atribut: openclaw.state; dipancarkan hanya untuk pencatatan sesi usang tanpa pekerjaan aktif)
  • openclaw.session.stuck_age_ms (histogram, atribut: openclaw.state; dipancarkan hanya untuk pencatatan sesi usang tanpa pekerjaan aktif)
  • openclaw.session.recovery.requested (penghitung, atribut: openclaw.state, openclaw.action, openclaw.active_work_kind, openclaw.reason)
  • openclaw.session.recovery.completed (penghitung, atribut: openclaw.state, openclaw.action, openclaw.status, openclaw.active_work_kind, openclaw.reason)
  • openclaw.session.recovery.age_ms (histogram, atribut: sama seperti penghitung pemulihan yang cocok)
  • openclaw.run.attempt (penghitung, atribut: openclaw.attempt)

Telemetri keaktifan sesi

diagnostics.stuckSessionWarnMs adalah ambang usia tanpa progres untuk diagnostik keaktifan sesi. Sesi processing tidak bertambah usianya menuju ambang ini saat OpenClaw mengamati progres runtime balasan, alat, status, blok, atau ACP. Keepalive pengetikan tidak dihitung sebagai progres, sehingga model atau harness yang senyap tetap dapat dideteksi.

OpenClaw mengklasifikasikan sesi berdasarkan pekerjaan yang masih dapat diamatinya:

  • session.long_running: pekerjaan tertanam aktif, panggilan model, atau panggilan alat masih membuat progres.
  • session.stalled: pekerjaan aktif ada, tetapi run aktif belum melaporkan progres terbaru. Run tertanam yang macet pada awalnya tetap hanya diamati, lalu abort-drain setelah diagnostics.stuckSessionAbortMs tanpa progres agar giliran antrean di belakang lane dapat dilanjutkan. Jika tidak disetel, ambang pembatalan default ke jendela diperpanjang yang lebih aman, yaitu setidaknya 10 menit dan 5x diagnostics.stuckSessionWarnMs.
  • session.stuck: pencatatan sesi usang tanpa pekerjaan aktif. Ini segera melepaskan lane sesi yang terdampak.

Pemulihan memancarkan peristiwa session.recovery.requested dan session.recovery.completed terstruktur. Status sesi diagnostik ditandai idle hanya setelah hasil pemulihan yang mengubah status (aborted atau released) dan hanya jika generasi processing yang sama masih berlaku saat ini.

Hanya session.stuck yang memancarkan penghitung openclaw.session.stuck, histogram openclaw.session.stuck_age_ms, dan span openclaw.session.stuck. Diagnostik session.stuck berulang melakukan backoff saat sesi tetap tidak berubah, sehingga dasbor sebaiknya memberi peringatan pada peningkatan yang berkelanjutan, bukan pada setiap tick Heartbeat. Untuk knob konfigurasi dan default, lihat Referensi konfigurasi.

Siklus hidup harness

  • openclaw.harness.duration_ms (histogram, atribut: openclaw.harness.id, openclaw.harness.plugin, openclaw.outcome, openclaw.harness.phase pada error)

Exec

  • openclaw.exec.duration_ms (histogram, atribut: openclaw.exec.target, openclaw.exec.mode, openclaw.outcome, openclaw.failureKind)

Internal diagnostik (memori dan loop alat)

  • openclaw.memory.heap_used_bytes (histogram, atribut: openclaw.memory.kind)
  • openclaw.memory.rss_bytes (histogram)
  • openclaw.memory.pressure (penghitung, atribut: openclaw.memory.level)
  • openclaw.tool.loop.iterations (penghitung, atribut: openclaw.toolName, openclaw.outcome)
  • openclaw.tool.loop.duration_ms (histogram, atribut: openclaw.toolName, openclaw.outcome)

Span yang diekspor

  • openclaw.model.usage
    • openclaw.channel, openclaw.provider, openclaw.model
    • openclaw.tokens.* (input/output/cache_read/cache_write/total)
    • gen_ai.system secara default, atau gen_ai.provider.name saat konvensi semantik GenAI terbaru diikutsertakan
    • 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 secara default, atau gen_ai.provider.name saat konvensi semantik GenAI terbaru diikutsertakan
    • gen_ai.request.model, gen_ai.operation.name, openclaw.provider, openclaw.model, openclaw.api, openclaw.transport
    • openclaw.errorCategory dan openclaw.failureKind opsional pada error
    • openclaw.model_call.request_bytes, openclaw.model_call.response_bytes, openclaw.model_call.time_to_first_byte_ms
    • openclaw.provider.request_id_hash (hash terbatas berbasis SHA dari id permintaan penyedia upstream; id mentah tidak diekspor)
  • openclaw.harness.run
    • openclaw.harness.id, openclaw.harness.plugin, openclaw.outcome, openclaw.provider, openclaw.model, openclaw.channel
    • Saat selesai: openclaw.harness.result_classification, openclaw.harness.yield_detected, openclaw.harness.items.started, openclaw.harness.items.completed, openclaw.harness.items.active
    • Saat error: openclaw.harness.phase, openclaw.errorCategory, openclaw.harness.cleanup_failed opsional
  • openclaw.tool.execution
    • gen_ai.tool.name, openclaw.toolName, openclaw.errorCategory, openclaw.tool.params.*
  • openclaw.exec
    • openclaw.exec.target, openclaw.exec.mode, openclaw.outcome, openclaw.failureKind, openclaw.exec.command_length, openclaw.exec.exit_code, 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 (tanpa konten prompt, riwayat, respons, atau kunci sesi)
  • openclaw.tool.loop
    • openclaw.toolName, openclaw.outcome, openclaw.iterations, openclaw.errorCategory (tanpa pesan loop, parameter, atau keluaran alat)
  • openclaw.memory.pressure
    • openclaw.memory.level, openclaw.memory.heap_used_bytes, openclaw.memory.rss_bytes

Saat penangkapan konten diaktifkan secara eksplisit, span model dan alat juga dapat menyertakan atribut openclaw.content.* yang terbatas dan disamarkan untuk kelas konten spesifik yang Anda ikutsertakan.

Katalog peristiwa diagnostik

Peristiwa di bawah ini mendukung metrik dan span di atas. Plugin juga dapat berlangganan langsung ke peristiwa tersebut tanpa ekspor OTLP.

Penggunaan model

  • model.usage - token, biaya, durasi, konteks, penyedia/model/channel, id sesi. usage adalah akuntansi penyedia/giliran untuk biaya dan telemetri; context.used adalah snapshot prompt/konteks saat ini dan dapat lebih rendah daripada usage.total penyedia saat input yang di-cache atau panggilan loop alat terlibat.

Alur pesan

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

Antrean dan sesi

  • queue.lane.enqueue / queue.lane.dequeue
  • session.state / session.long_running / session.stalled / session.stuck
  • run.attempt / run.progress
  • diagnostic.heartbeat (penghitung agregat: webhook/antrean/sesi)

Siklus hidup harness

  • harness.run.started / harness.run.completed / harness.run.error - siklus hidup per run untuk harness agen. Mencakup harnessId, pluginId opsional, penyedia/model/channel, dan id run. Penyelesaian menambahkan durationMs, outcome, resultClassification opsional, yieldDetected, dan jumlah itemLifecycle. Error menambahkan phase (prepare/start/send/resolve/cleanup), errorCategory, dan cleanupFailed opsional.

Exec

  • exec.process.completed - hasil terminal, durasi, target, mode, kode keluar, dan jenis kegagalan. Teks perintah dan direktori kerja tidak disertakan.

Tanpa exporter

Anda dapat menjaga peristiwa diagnostik tetap tersedia untuk Plugin atau sink khusus tanpa menjalankan diagnostics-otel:

{
  diagnostics: { enabled: true },
}

Untuk keluaran debug tertarget tanpa menaikkan logging.level, gunakan flag diagnostik. Flag tidak peka huruf besar/kecil dan mendukung wildcard (misalnya telegram.* atau *):

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

Atau sebagai override env sekali pakai:

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway

Keluaran flag masuk ke file log standar (logging.file) dan tetap disamarkan oleh logging.redactSensitive. Panduan lengkap: Flag diagnostik.

Nonaktifkan

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

Anda juga dapat mengeluarkan diagnostics-otel dari plugins.allow, atau menjalankan openclaw plugins disable diagnostics-otel.

Terkait