OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

Metrik Prometheus

OpenClaw dapat mengekspos metrik diagnostik melalui plugin resmi diagnostics-prometheus. Plugin ini menerima diagnostik tepercaya serta peristiwa diagnostik yang diberi tag secara internal dan dimiliki dispatcher (sinyal antrean, memori, dan pemulihan sesi), lalu menyajikan endpoint teks Prometheus di:

text
GET /api/diagnostics/prometheus

Tipe kontennya adalah text/plain; version=0.0.4; charset=utf-8, yaitu format eksposisi standar Prometheus.

Untuk pelacakan, log, pengiriman OTLP, dan atribut semantik OpenTelemetry GenAI, lihat Ekspor OpenTelemetry.

Mulai cepat

  • Instal plugin

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

  • Aktifkan plugin

    Konfigurasi

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

    CLI

    bash
    openclaw plugins enable diagnostics-prometheus

  • Mulai ulang Gateway

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

  • Ambil metrik dari rute yang dilindungi

    Kirim autentikasi Gateway yang sama dengan yang digunakan klien operator Anda:

    bash
    curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \  http://127.0.0.1:18789/api/diagnostics/prometheus

  • Hubungkan Prometheus

    yaml
    # prometheus.ymlscrape_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"]

    • Metrik yang diekspor

    Metrik Jenis Label
    openclaw_run_completed_total pencacah channel, model, outcome, provider, trigger
    openclaw_run_duration_seconds histogram channel, model, outcome, provider, trigger
    openclaw_model_call_total pencacah api, error_category, model, outcome, provider, transport
    openclaw_model_call_duration_seconds histogram api, error_category, model, outcome, provider, transport
    openclaw_model_failover_total pencacah from_model, from_provider, lane, reason, suspended, to_model, to_provider
    openclaw_model_tokens_total pencacah agent, channel, model, provider, token_type
    openclaw_gen_ai_client_token_usage histogram model, provider, token_type
    openclaw_model_cost_usd_total pencacah agent, channel, model, provider
    openclaw_model_usage_duration_seconds histogram agent, channel, model, provider
    openclaw_skill_used_total pencacah activation, agent, skill, source
    openclaw_tool_execution_total pencacah error_category, outcome, params_kind, tool, tool_owner, tool_source
    openclaw_tool_execution_duration_seconds histogram error_category, outcome, params_kind, tool, tool_owner, tool_source
    openclaw_tool_execution_blocked_total pencacah denied_reason, params_kind, tool, tool_owner, tool_source
    openclaw_harness_run_total pencacah channel, error_category, harness, model, outcome, phase, plugin, provider
    openclaw_harness_run_duration_seconds histogram channel, error_category, harness, model, outcome, phase, plugin, provider
    openclaw_webhook_received_total pencacah channel, webhook
    openclaw_webhook_error_total pencacah channel, webhook
    openclaw_webhook_duration_seconds histogram channel, webhook
    openclaw_message_received_total pencacah channel, source
    openclaw_message_dispatch_started_total pencacah channel, source
    openclaw_message_dispatch_completed_total pencacah channel, outcome, reason, source
    openclaw_message_dispatch_duration_seconds histogram channel, outcome, reason, source
    openclaw_message_processed_total pencacah channel, outcome, reason
    openclaw_message_processed_duration_seconds histogram channel, outcome, reason
    openclaw_message_delivery_started_total pencacah channel, delivery_kind
    openclaw_message_delivery_total pencacah channel, delivery_kind, error_category, outcome
    openclaw_message_delivery_duration_seconds histogram channel, delivery_kind, error_category, outcome
    openclaw_talk_event_total pencacah brain, event_type, mode, provider, transport
    openclaw_talk_event_duration_seconds histogram brain, event_type, mode, provider, transport
    openclaw_talk_audio_bytes histogram brain, event_type, mode, provider, transport
    openclaw_queue_lane_size pengukur lane
    openclaw_queue_lane_wait_seconds histogram lane
    openclaw_session_state_total pencacah reason, state
    openclaw_session_queue_depth pengukur state
    openclaw_session_turn_created_total pencacah agent, channel, trigger
    openclaw_session_stuck_total pencacah reason, state
    openclaw_session_stuck_age_seconds histogram reason, state
    openclaw_session_recovery_total pencacah action, active_work_kind, state, status
    openclaw_session_recovery_age_seconds histogram action, active_work_kind, state, status
    openclaw_liveness_warning_total pencacah reason
    openclaw_liveness_sessions pengukur state
    openclaw_liveness_event_loop_delay_p99_seconds histogram reason
    openclaw_liveness_event_loop_delay_max_seconds histogram reason
    openclaw_liveness_event_loop_utilization_ratio histogram reason
    openclaw_liveness_cpu_core_ratio histogram reason
    openclaw_payload_large_total pencacah action, channel, plugin, reason, surface
    openclaw_payload_large_bytes histogram action, channel, plugin, reason, surface
    openclaw_memory_bytes pengukur kind
    openclaw_memory_rss_bytes histogram tidak ada
    openclaw_memory_pressure_total pencacah level, reason
    openclaw_telemetry_exporter_total pencacah exporter, reason, signal, status
    openclaw_prometheus_series_dropped_total pencacah tidak ada
    openclaw_diagnostic_async_queue_dropped_total pencacah drop_class
    openclaw_diagnostic_async_queue_length pengukur tidak ada

    Kebijakan label

    Label terbatas dengan kardinalitas rendah

    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 sesuai dengan kebijakan karakter berkardinalitas rendah OpenClaw. Nilai yang tidak memenuhi kebijakan diganti dengan unknown, other, atau none, bergantung pada metriknya. Label yang terlihat seperti kunci sesi agen bercakupan juga diganti dengan unknown.

    Batas seri dan penghitungan kelebihan

    Eksportir membatasi seri waktu yang dipertahankan dalam memori hingga 2048 seri secara gabungan di seluruh penghitung, gauge, dan histogram. Seri baru yang melampaui batas tersebut dibuang, dan openclaw_prometheus_series_dropped_total bertambah satu setiap kali hal itu terjadi.

    Pantau penghitung ini sebagai sinyal tegas bahwa suatu atribut di hulu membocorkan nilai berkardinalitas tinggi. Eksportir tidak pernah menaikkan batas secara otomatis; jika penghitung ini meningkat, perbaiki sumbernya alih-alih menonaktifkan batas tersebut.

    Yang tidak pernah muncul dalam keluaran Prometheus
    • teks prompt, teks respons, masukan alat, keluaran alat, prompt sistem
    • transkrip Talk, muatan audio, ID panggilan, ID ruang, token serah terima, 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 berkas, nilai rahasia

    Resep PromQL

    promql
    # Token per menit, dipisahkan berdasarkan penyediasum by (provider) (rate(openclaw_model_tokens_total[1m])) # Pengeluaran (USD) selama satu jam terakhir, berdasarkan modelsum by (model) (increase(openclaw_model_cost_usd_total[1h])) # Persentil ke-95 durasi eksekusi modelhistogram_quantile(  0.95,  sum by (le, provider, model)    (rate(openclaw_run_duration_seconds_bucket[5m]))) # SLO waktu tunggu antrean (persentil ke-95 di bawah 2 dtk)histogram_quantile(  0.95,  sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))) < 2 # Penggunaan Skill, dipisahkan berdasarkan sumber terbatassum by (skill, source) (increase(openclaw_skill_used_total[24h])) # Seri Prometheus yang dibuang (alarm kardinalitas)increase(openclaw_prometheus_series_dropped_total[15m]) > 0

    Memilih antara ekspor Prometheus dan OpenTelemetry

    OpenClaw mendukung kedua antarmuka secara independen. Anda dapat menjalankan salah satunya, keduanya, atau tidak keduanya.

    diagnostics-prometheus

    • Model tarik: Prometheus mengambil data dari /api/diagnostics/prometheus.
    • Tidak memerlukan kolektor eksternal.
    • Diautentikasi melalui autentikasi Gateway normal.
    • Antarmuka hanya mencakup metrik (tanpa pelacakan atau log).
    • Paling sesuai untuk tumpukan yang sudah distandardisasi pada Prometheus + Grafana.

    diagnostics-otel

    • Model dorong: OpenClaw mengirimkan OTLP/HTTP ke kolektor atau backend yang kompatibel dengan OTLP.
    • Antarmuka mencakup metrik, pelacakan, dan log.
    • Terhubung ke Prometheus melalui OpenTelemetry Collector (eksportir prometheus atau prometheusremotewrite) ketika Anda memerlukan keduanya.
    • Lihat Ekspor OpenTelemetry untuk katalog lengkap.

    Pemecahan masalah

    Isi respons kosong
    • Periksa bahwa diagnostics.enabled tidak ditetapkan ke false dalam konfigurasi (nilai bawaannya adalah true).
    • Pastikan Plugin diaktifkan dan dimuat dengan openclaw plugins list --enabled.
    • Hasilkan sejumlah lalu lintas; penghitung dan histogram hanya menghasilkan baris setelah setidaknya satu peristiwa.
    401 / tidak diotorisasi

    Titik akhir memerlukan cakupan operator Gateway (auth: "gateway" dengan gatewayRuntimeScopeSurface: "trusted-operator"). Gunakan token atau kata sandi yang sama dengan yang digunakan Prometheus untuk rute operator Gateway lainnya. Tidak ada mode publik tanpa autentikasi.

    `openclaw_prometheus_series_dropped_total` terus meningkat

    Atribut baru melampaui batas 2048 seri. Periksa metrik terkini untuk menemukan label dengan kardinalitas tinggi yang tidak terduga, lalu perbaiki pada sumbernya. Eksportir sengaja membuang seri baru alih-alih secara diam-diam menulis ulang label.

    Prometheus menampilkan seri usang setelah dimulai ulang

    Plugin hanya menyimpan status dalam memori. Setelah Gateway dimulai ulang, penghitung diatur ulang ke nol dan gauge dimulai kembali pada nilai berikutnya yang dilaporkan. Gunakan rate() dan increase() PromQL untuk menangani pengaturan ulang dengan baik.

    Terkait

    Was this useful?
    On this page

    On this page