Langsung ke konten utama
OpenClaw dapat mengekspos metrik diagnostik melalui Plugin bawaan diagnostics-prometheus. Plugin ini mendengarkan diagnostik internal tepercaya dan merender endpoint teks Prometheus di: 
GET /api/diagnostics/prometheus
Tipe 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. Lakukan scrape melalui jalur autentikasi yang sama yang Anda gunakan untuk API operator lainnya.
Untuk trace, log, push OTLP, dan atribut semantik OpenTelemetry GenAI, lihat OpenTelemetry export.

​
Mulai cepat

1

Aktifkan Plugin

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

Mulai ulang Gateway

Rute HTTP didaftarkan saat startup Plugin, jadi lakukan reload setelah mengaktifkannya.
3

Scrape rute yang dilindungi

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
4

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 exporter, sehingga respons kosong.

​
Metrik yang diekspor

MetricTipeLabel
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_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_tool_execution_totalcountererror_category, outcome, params_kind, tool
openclaw_tool_execution_duration_secondshistogramerror_category, outcome, params_kind, tool
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_message_processed_totalcounterchannel, outcome, reason
openclaw_message_processed_duration_secondshistogramchannel, outcome, reason
openclaw_message_delivery_totalcounterchannel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_secondshistogramchannel, delivery_kind, error_category, outcome
openclaw_queue_lane_sizegaugelane
openclaw_queue_lane_wait_secondshistogramlane
openclaw_session_state_totalcounterreason, state
openclaw_session_queue_depthgaugestate
openclaw_memory_bytesgaugekind
openclaw_memory_rss_byteshistogramnone
openclaw_memory_pressure_totalcounterlevel, reason
openclaw_telemetry_exporter_totalcounterexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalcounternone

​
Kebijakan label

Label Prometheus dijaga tetap terbatas dan berkardinalitas rendah. Exporter tidak mengeluarkan pengenal diagnostik mentah seperti runId, sessionKey, sessionId, callId, toolCallId, ID pesan, ID chat, atau ID permintaan provider.Nilai label disamarkan dan harus cocok dengan kebijakan karakter berkardinalitas rendah milik OpenClaw. Nilai yang gagal memenuhi kebijakan diganti dengan unknown, other, atau none, tergantung metriknya.
Exporter membatasi seri waktu yang dipertahankan di memori hingga 2048 seri untuk gabungan counter, gauge, dan histogram. Seri baru di luar batas itu akan dibuang, dan openclaw_prometheus_series_dropped_total bertambah satu setiap kali hal itu terjadi.Pantau counter ini sebagai sinyal keras bahwa sebuah atribut di upstream membocorkan nilai berkardinalitas tinggi. Exporter tidak pernah menaikkan batas secara otomatis; jika nilainya naik, perbaiki sumbernya alih-alih menonaktifkan batas.
  • teks prompt, teks respons, input tool, output tool, system prompt
  • ID permintaan provider mentah (hanya hash terbatas, bila berlaku, pada span — tidak pernah pada metrik)
  • kunci sesi dan ID sesi
  • hostname, path file, nilai secret

​
Resep PromQL

# Token per menit, dipisah menurut provider
sum by (provider) (rate(openclaw_model_tokens_total[1m]))

# Pengeluaran (USD) selama satu jam terakhir, menurut model
sum by (model) (increase(openclaw_model_cost_usd_total[1h]))

# Persentil ke-95 durasi proses model
histogram_quantile(
  0.95,
  sum by (le, provider, model)
    (rate(openclaw_run_duration_seconds_bucket[5m]))
)

# SLO waktu tunggu antrean (95p di bawah 2 detik)
histogram_quantile(
  0.95,
  sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))
) < 2

# Seri Prometheus yang dibuang (alarm kardinalitas)
increase(openclaw_prometheus_series_dropped_total[15m]) > 0
Sebaiknya gunakan gen_ai_client_token_usage untuk dashboard lintas provider: metrik ini mengikuti konvensi semantik OpenTelemetry GenAI dan konsisten dengan metrik dari layanan GenAI non-OpenClaw.

​
Memilih antara Prometheus dan OpenTelemetry export

OpenClaw mendukung kedua permukaan ini secara independen. Anda dapat menjalankan salah satunya, keduanya, atau tidak sama sekali.
  • Model pull: Prometheus melakukan scrape ke /api/diagnostics/prometheus.
  • Tidak memerlukan kolektor eksternal.
  • Diautentikasi melalui autentikasi Gateway normal.
  • Permukaannya hanya metrik (tanpa trace atau log).
  • Paling cocok untuk stack yang sudah distandardisasi pada Prometheus + Grafana.

​
Pemecahan masalah

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

​
Terkait