Langsung ke konten utama

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw dapat mengekspos metrik diagnostik melalui Plugin resmi 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. Scrape melalui jalur autentikasi yang sama 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 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 diatur. Tanpanya, Plugin tetap mendaftarkan rute HTTP tetapi tidak ada peristiwa diagnostik yang mengalir ke eksportir, sehingga responsnya kosong.

​
Metrik yang diekspor

MetrikTipeLabel
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_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_recovery_totalcounteraction, active_work_kind, state, status
openclaw_session_recovery_age_secondshistogramaction, active_work_kind, state, status
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. Eksportir tidak memancarkan pengenal diagnostik mentah seperti runId, sessionKey, sessionId, callId, toolCallId, ID pesan, ID chat, 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, bergantung pada metrik.
Pengekspor membatasi deret waktu yang disimpan dalam memori hingga 2048 seri untuk gabungan penghitung, gauge, dan histogram. Seri baru di luar batas tersebut akan dibuang, dan openclaw_prometheus_series_dropped_total bertambah satu setiap kali.Pantau penghitung ini sebagai sinyal kuat 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
  • nama host, 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

# Dropped Prometheus series (cardinality alarm)
increase(openclaw_prometheus_series_dropped_total[15m]) > 0
Utamakan gen_ai_client_token_usage untuk dasbor lintas penyedia: 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 tarik: Prometheus mengambil /api/diagnostics/prometheus.
  • Tidak memerlukan kolektor eksternal.
  • Diautentikasi melalui autentikasi Gateway normal.
  • Permukaan hanya berupa metrik (tanpa trace atau log).
  • Paling cocok untuk stack yang sudah distandarkan pada Prometheus + Grafana.

​
Pemecahan masalah

  • Periksa diagnostics.enabled: true dalam konfigurasi.
  • Pastikan Plugin diaktifkan dan dimuat dengan openclaw plugins list --enabled.
  • Buat sejumlah traffic; penghitung 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 melebihi batas 2048 seri. Periksa metrik terbaru untuk label dengan kardinalitas tinggi yang tidak terduga dan perbaiki di sumbernya. Pengekspor sengaja membuang seri baru alih-alih diam-diam menulis ulang label.
Plugin hanya menyimpan status dalam memori. Setelah Gateway dimulai ulang, penghitung diatur ulang ke nol dan gauge dimulai ulang pada nilai berikutnya yang dilaporkan. Gunakan PromQL rate() dan increase() untuk menangani pengaturan ulang dengan bersih.

​
Terkait