Langsung ke konten utama
OpenClaw dapat mengekspos metrik diagnostik melalui plugin resmi diagnostics-prometheus. Plugin ini mendengarkan diagnostik tepercaya beserta peristiwa stabilitas gateway yang dipancarkan core, lalu merender endpoint teks Prometheus di: 
GET /api/diagnostics/prometheus
Jenis kontennya adalah text/plain; version=0.0.4; charset=utf-8, format eksposisi Prometheus standar.
Rute ini menggunakan autentikasi Gateway (cakupan operator). Jangan mengeksposnya sebagai endpoint /metrics publik tanpa autentikasi. Scrape rute ini melalui jalur autentikasi yang sama dengan yang Anda gunakan untuk API operator lainnya.
Untuk trace, log, push OTLP, dan atribut semantik OpenTelemetry GenAI, lihat Ekspor OpenTelemetry.

​
Mulai cepat

1

Instal plugin

openclaw plugins install clawhub:@openclaw/diagnostics-prometheus
2

Aktifkan plugin

{
  plugins: {
    allow: ["diagnostics-prometheus"],
    entries: {
      "diagnostics-prometheus": { enabled: true },
    },
  },
  diagnostics: {
    enabled: true,
  },
}
3

Mulai ulang Gateway

Rute HTTP didaftarkan saat plugin dimulai, jadi muat ulang setelah mengaktifkannya.
4

Scrape rute terlindungi

Kirim autentikasi gateway yang sama seperti yang digunakan klien operator Anda:
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus
5

Hubungkan Prometheus

# prometheus.yml
scrape_configs:
  - job_name: openclaw
    scrape_interval: 30s
    metrics_path: /api/diagnostics/prometheus
    authorization:
      credentials_file: /etc/prometheus/openclaw-gateway-token
    static_configs:
      - targets: ["openclaw-gateway:18789"]
diagnostics.enabled: true wajib diaktifkan. Tanpanya, Plugin tetap mendaftarkan rute HTTP tetapi tidak ada peristiwa diagnostik yang mengalir ke pengekspor, sehingga responsnya kosong.

​
Metrik yang diekspor

MetrikJenisLabel
openclaw_run_completed_totalcounterchannel, model, outcome, provider, trigger
openclaw_run_duration_secondshistogramchannel, model, outcome, provider, trigger
openclaw_model_call_totalcounterapi, error_category, model, outcome, provider, transport
openclaw_model_call_duration_secondshistogramapi, error_category, model, outcome, provider, transport
openclaw_model_failover_totalcounterfrom_model, from_provider, lane, reason, suspended, to_model, to_provider
openclaw_model_tokens_totalcounteragent, channel, model, provider, token_type
openclaw_gen_ai_client_token_usagehistogrammodel, provider, token_type
openclaw_model_cost_usd_totalcounteragent, channel, model, provider
openclaw_skill_used_totalcounteractivation, agent, skill, source
openclaw_tool_execution_totalcountererror_category, outcome, params_kind, tool, tool_owner, tool_source
openclaw_tool_execution_duration_secondshistogramerror_category, outcome, params_kind, tool, tool_owner, tool_source
openclaw_tool_execution_blocked_totalcounterdenied_reason, params_kind, tool, tool_owner, tool_source
openclaw_harness_run_totalcounterchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_harness_run_duration_secondshistogramchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_webhook_received_totalcounterchannel, webhook
openclaw_webhook_error_totalcounterchannel, webhook
openclaw_webhook_duration_secondshistogramchannel, webhook
openclaw_message_received_totalcounterchannel, source
openclaw_message_dispatch_started_totalcounterchannel, source
openclaw_message_dispatch_completed_totalcounterchannel, outcome, reason, source
openclaw_message_dispatch_duration_secondshistogramchannel, outcome, reason, source
openclaw_message_processed_totalcounterchannel, outcome, reason
openclaw_message_processed_duration_secondshistogramchannel, outcome, reason
openclaw_message_delivery_started_totalcounterchannel, delivery_kind
openclaw_message_delivery_totalcounterchannel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_secondshistogramchannel, delivery_kind, error_category, outcome
openclaw_talk_event_totalcounterbrain, event_type, mode, provider, transport
openclaw_talk_event_duration_secondshistogrambrain, event_type, mode, provider, transport
openclaw_talk_audio_byteshistogrambrain, event_type, mode, provider, transport
openclaw_queue_lane_sizegaugelane
openclaw_queue_lane_wait_secondshistogramlane
openclaw_session_state_totalcounterreason, state
openclaw_session_queue_depthgaugestate
openclaw_session_turn_created_totalcounteragent, channel, trigger
openclaw_session_stuck_totalcounterreason, state
openclaw_session_stuck_age_secondshistogramreason, state
openclaw_session_recovery_totalcounteraction, active_work_kind, state, status
openclaw_session_recovery_age_secondshistogramaction, active_work_kind, state, status
openclaw_liveness_warning_totalcounterreason
openclaw_liveness_sessionsgaugestate
openclaw_liveness_event_loop_delay_p99_secondshistogramreason
openclaw_liveness_event_loop_delay_max_secondshistogramreason
openclaw_liveness_event_loop_utilization_ratiohistogramreason
openclaw_liveness_cpu_core_ratiohistogramreason
openclaw_payload_large_totalcounteraction, channel, plugin, reason, surface
openclaw_payload_large_byteshistogramaction, channel, plugin, reason, surface
openclaw_memory_bytesgaugekind
openclaw_memory_rss_byteshistogramtidak ada
openclaw_memory_pressure_totalcounterlevel, reason
openclaw_telemetry_exporter_totalcounterexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalcountertidak ada

​
Kebijakan label

Label Prometheus tetap terbatas dan berkardinalitas rendah. Pengekspor tidak memancarkan pengidentifikasi diagnostik mentah seperti runId, sessionKey, sessionId, callId, toolCallId, ID pesan, ID obrolan, atau ID permintaan penyedia.Nilai label disunting dan harus cocok dengan kebijakan karakter berkardinalitas rendah OpenClaw. Nilai yang gagal memenuhi kebijakan diganti dengan unknown, other, atau none, tergantung metriknya. Label yang terlihat seperti kunci sesi agen bercakupan juga diganti dengan unknown.
Pengekspor membatasi seri waktu yang disimpan di memori hingga 2048 seri untuk gabungan counter, gauge, dan histogram. Seri baru di luar batas tersebut dibuang, dan openclaw_prometheus_series_dropped_total bertambah satu setiap kali.Pantau counter ini sebagai sinyal tegas bahwa atribut di hulu membocorkan nilai berkardinalitas tinggi. Pengekspor tidak pernah menaikkan batas secara otomatis; jika nilainya naik, perbaiki sumbernya alih-alih menonaktifkan batas.
  • teks prompt, teks respons, input alat, output alat, prompt sistem
  • transkrip Talk, payload audio, id panggilan, id ruang, token handoff, id giliran, dan id sesi mentah
  • ID permintaan penyedia mentah (hanya hash terbatas, jika berlaku, pada span — tidak pernah pada metrik)
  • kunci sesi dan ID sesi
  • hostname, jalur file, nilai rahasia

​
Resep PromQL

# Tokens per minute, split by provider
sum by (provider) (rate(openclaw_model_tokens_total[1m]))

# Spend (USD) over the last hour, by model
sum by (model) (increase(openclaw_model_cost_usd_total[1h]))

# 95th percentile model run duration
histogram_quantile(
  0.95,
  sum by (le, provider, model)
    (rate(openclaw_run_duration_seconds_bucket[5m]))
)

# Queue wait time SLO (95p under 2s)
histogram_quantile(
  0.95,
  sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))
) < 2

# Skill usage, split by bounded source
sum by (skill, source) (increase(openclaw_skill_used_total[24h]))

# Dropped Prometheus series (cardinality alarm)
increase(openclaw_prometheus_series_dropped_total[15m]) > 0
Utamakan gen_ai_client_token_usage untuk dasbor lintas penyedia: metrik ini mengikuti konvensi semantik OpenTelemetry GenAI dan konsisten dengan metrik dari layanan GenAI non-OpenClaw.

​
Memilih antara ekspor Prometheus dan OpenTelemetry

OpenClaw mendukung kedua permukaan secara independen. Anda dapat menjalankan salah satu, keduanya, atau tidak keduanya.
  • Model pull: Prometheus mengambil data dari /api/diagnostics/prometheus.
  • Tidak memerlukan kolektor eksternal.
  • Diautentikasi melalui autentikasi Gateway normal.
  • Permukaan hanya berisi metrik (tanpa trace atau log).
  • Paling cocok untuk stack yang sudah distandardisasi pada Prometheus + Grafana.

​
Pemecahan masalah

  • Periksa diagnostics.enabled: true dalam konfigurasi.
  • Pastikan Plugin diaktifkan dan dimuat dengan openclaw plugins list --enabled.
  • Hasilkan sebagian traffic; counter dan histogram hanya memancarkan baris setelah setidaknya satu peristiwa.
Endpoint memerlukan cakupan operator Gateway (auth: "gateway" dengan gatewayRuntimeScopeSurface: "trusted-operator"). Gunakan token atau kata sandi yang sama yang digunakan Prometheus untuk rute operator Gateway lainnya. Tidak ada mode publik tanpa autentikasi.
Atribut baru melampaui batas 2048 seri. Periksa metrik terbaru untuk label dengan kardinalitas yang sangat tinggi secara tidak terduga dan perbaiki di sumbernya. Eksportir sengaja membuang seri baru alih-alih diam-diam menulis ulang label.
Plugin hanya menyimpan status di memori. Setelah Gateway restart, counter direset ke nol dan gauge dimulai ulang pada nilai berikutnya yang dilaporkan. Gunakan PromQL rate() dan increase() untuk menangani reset dengan bersih.

​
Terkait