Gateway

เมตริก Prometheus

OpenClaw สามารถเปิดเผยเมตริกการวินิจฉัยผ่าน Plugin ทางการ diagnostics-prometheus ได้ โดยจะรับฟังการวินิจฉัยที่เชื่อถือได้รวมถึงเหตุการณ์ความเสถียรของ Gateway ที่ core ส่งออกมา จากนั้นเรนเดอร์ endpoint ข้อความ Prometheus ที่:

text

GET /api/diagnostics/prometheus

ชนิดเนื้อหาคือ text/plain; version=0.0.4; charset=utf-8 ซึ่งเป็นรูปแบบ exposition มาตรฐานของ Prometheus

สำหรับ traces, logs, OTLP push และแอตทริบิวต์เชิงความหมาย OpenTelemetry GenAI โปรดดู การส่งออก OpenTelemetry

เริ่มต้นอย่างรวดเร็ว

ติดตั้ง Plugin

bash

openclaw plugins install clawhub:@openclaw/diagnostics-prometheus

เปิดใช้งาน Plugin

การกำหนดค่า

json5

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

CLI

bash

openclaw plugins enable diagnostics-prometheus

รีสตาร์ท Gateway

เส้นทาง HTTP จะถูกลงทะเบียนเมื่อ Plugin เริ่มทำงาน ดังนั้นให้โหลดใหม่หลังจากเปิดใช้งาน

Scrape เส้นทางที่ได้รับการป้องกัน

ส่ง gateway auth เดียวกับที่ไคลเอนต์ operator ของคุณใช้:

bash

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

เชื่อมต่อ 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"]

เมตริกที่ส่งออก

เมตริก	ประเภท	ป้ายกำกับ
`openclaw_run_completed_total`	counter	`channel`, `model`, `outcome`, `provider`, `trigger`
`openclaw_run_duration_seconds`	histogram	`channel`, `model`, `outcome`, `provider`, `trigger`
`openclaw_model_call_total`	counter	`api`, `error_category`, `model`, `outcome`, `provider`, `transport`
`openclaw_model_call_duration_seconds`	histogram	`api`, `error_category`, `model`, `outcome`, `provider`, `transport`
`openclaw_model_failover_total`	counter	`from_model`, `from_provider`, `lane`, `reason`, `suspended`, `to_model`, `to_provider`
`openclaw_model_tokens_total`	counter	`agent`, `channel`, `model`, `provider`, `token_type`
`openclaw_gen_ai_client_token_usage`	histogram	`model`, `provider`, `token_type`
`openclaw_model_cost_usd_total`	counter	`agent`, `channel`, `model`, `provider`
`openclaw_skill_used_total`	counter	`activation`, `agent`, `skill`, `source`
`openclaw_tool_execution_total`	counter	`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`	counter	`denied_reason`, `params_kind`, `tool`, `tool_owner`, `tool_source`
`openclaw_harness_run_total`	counter	`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`	counter	`channel`, `webhook`
`openclaw_webhook_error_total`	counter	`channel`, `webhook`
`openclaw_webhook_duration_seconds`	histogram	`channel`, `webhook`
`openclaw_message_received_total`	counter	`channel`, `source`
`openclaw_message_dispatch_started_total`	counter	`channel`, `source`
`openclaw_message_dispatch_completed_total`	counter	`channel`, `outcome`, `reason`, `source`
`openclaw_message_dispatch_duration_seconds`	histogram	`channel`, `outcome`, `reason`, `source`
`openclaw_message_processed_total`	counter	`channel`, `outcome`, `reason`
`openclaw_message_processed_duration_seconds`	histogram	`channel`, `outcome`, `reason`
`openclaw_message_delivery_started_total`	counter	`channel`, `delivery_kind`
`openclaw_message_delivery_total`	counter	`channel`, `delivery_kind`, `error_category`, `outcome`
`openclaw_message_delivery_duration_seconds`	histogram	`channel`, `delivery_kind`, `error_category`, `outcome`
`openclaw_talk_event_total`	counter	`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`	gauge	`lane`
`openclaw_queue_lane_wait_seconds`	histogram	`lane`
`openclaw_session_state_total`	counter	`reason`, `state`
`openclaw_session_queue_depth`	gauge	`state`
`openclaw_session_turn_created_total`	counter	`agent`, `channel`, `trigger`
`openclaw_session_stuck_total`	counter	`reason`, `state`
`openclaw_session_stuck_age_seconds`	histogram	`reason`, `state`
`openclaw_session_recovery_total`	counter	`action`, `active_work_kind`, `state`, `status`
`openclaw_session_recovery_age_seconds`	histogram	`action`, `active_work_kind`, `state`, `status`
`openclaw_liveness_warning_total`	counter	`reason`
`openclaw_liveness_sessions`	gauge	`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`	counter	`action`, `channel`, `plugin`, `reason`, `surface`
`openclaw_payload_large_bytes`	histogram	`action`, `channel`, `plugin`, `reason`, `surface`
`openclaw_memory_bytes`	gauge	`kind`
`openclaw_memory_rss_bytes`	histogram	none
`openclaw_memory_pressure_total`	counter	`level`, `reason`
`openclaw_telemetry_exporter_total`	counter	`exporter`, `reason`, `signal`, `status`
`openclaw_prometheus_series_dropped_total`	counter	none

นโยบายป้ายกำกับ

ป้ายกำกับที่มีขอบเขตและมีคาร์ดินาลิตีต่ำ

ป้ายกำกับ Prometheus ยังคงมีขอบเขตและมีคาร์ดินาลิตีต่ำ exporter จะไม่ส่งตัวระบุการวินิจฉัยดิบ เช่น runId, sessionKey, sessionId, callId, toolCallId, ID ข้อความ, ID แชต หรือ ID คำขอของผู้ให้บริการ

ค่าป้ายกำกับจะถูกปกปิดและต้องตรงกับนโยบายอักขระคาร์ดินาลิตีต่ำของ OpenClaw ค่าที่ไม่ผ่านนโยบายจะถูกแทนที่ด้วย unknown, other หรือ none ตามเมตริก ป้ายกำกับที่ดูเหมือนคีย์เซสชันเอเจนต์แบบมีขอบเขตจะถูกแทนที่ด้วย unknown เช่นกัน

ขีดจำกัดซีรีส์และการนับส่วนเกิน

exporter จำกัด time series ที่เก็บไว้ในหน่วยความจำไว้ที่ 2048 ซีรีส์ รวมทั้ง counter, gauge และ histogram ซีรีส์ใหม่ที่เกินขีดจำกัดนั้นจะถูกทิ้ง และ openclaw_prometheus_series_dropped_total จะเพิ่มขึ้นหนึ่งทุกครั้ง

เฝ้าดู counter นี้เป็นสัญญาณชัดเจนว่าแอตทริบิวต์ upstream กำลังรั่วค่าที่มีคาร์ดินาลิตีสูง exporter จะไม่ยกเลิกขีดจำกัดโดยอัตโนมัติ หากค่านี้เพิ่มขึ้น ให้แก้ที่ต้นทางแทนการปิดใช้ขีดจำกัด

What never appears in Prometheus output

ข้อความพรอมป์, ข้อความคำตอบ, อินพุตของเครื่องมือ, เอาต์พุตของเครื่องมือ, พรอมป์ระบบ
ทรานสคริปต์การสนทนา, เพย์โหลดเสียง, ID การโทร, ID ห้อง, โทเค็นการส่งต่อ, ID รอบการสนทนา และ ID เซสชันดิบ
ID คำขอของผู้ให้บริการแบบดิบ (มีเฉพาะแฮชที่มีขอบเขต เมื่อใช้ได้ บน span เท่านั้น — ไม่อยู่ในเมตริกเด็ดขาด)
คีย์เซสชันและ ID เซสชัน
ชื่อโฮสต์, พาธไฟล์, ค่าลับ

สูตร PromQL

promql

# Tokens per minute, split by providersum by (provider) (rate(openclaw_model_tokens_total[1m])) # Spend (USD) over the last hour, by modelsum by (model) (increase(openclaw_model_cost_usd_total[1h])) # 95th percentile model run durationhistogram_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 sourcesum by (skill, source) (increase(openclaw_skill_used_total[24h])) # Dropped Prometheus series (cardinality alarm)increase(openclaw_prometheus_series_dropped_total[15m]) > 0

การเลือกระหว่างการส่งออก Prometheus และ OpenTelemetry

OpenClaw รองรับพื้นผิวทั้งสองแบบแยกกัน คุณสามารถเรียกใช้อย่างใดอย่างหนึ่ง ทั้งสองอย่าง หรือไม่ใช้อย่างใดเลยก็ได้

diagnostics-prometheus

โมเดลแบบ Pull: Prometheus scrape /api/diagnostics/prometheus
ไม่ต้องใช้ collector ภายนอก
ยืนยันตัวตนผ่านการยืนยันตัวตน Gateway ตามปกติ
พื้นผิวนี้เป็นเมตริกเท่านั้น (ไม่มี trace หรือ log)
เหมาะที่สุดสำหรับสแตกที่ได้มาตรฐานบน Prometheus + Grafana อยู่แล้ว

diagnostics-otel

โมเดลแบบ Push: OpenClaw ส่ง OTLP/HTTP ไปยัง collector หรือ backend ที่เข้ากันได้กับ OTLP
พื้นผิวนี้มีเมตริก, trace และ log
เชื่อมต่อไปยัง Prometheus ผ่าน OpenTelemetry Collector (exporter prometheus หรือ prometheusremotewrite) เมื่อคุณต้องการทั้งสองอย่าง
ดู การส่งออก OpenTelemetry สำหรับแคตตาล็อกฉบับเต็ม

การแก้ไขปัญหา

Empty response body

ตรวจสอบ diagnostics.enabled: true ในคอนฟิก
ยืนยันว่า Plugin เปิดใช้งานและโหลดแล้วด้วย openclaw plugins list --enabled
สร้างทราฟฟิกบางส่วน; counter และ histogram จะปล่อยบรรทัดหลังจากมีเหตุการณ์อย่างน้อยหนึ่งครั้งเท่านั้น

401 / unauthorized

เอนด์พอยต์นี้ต้องใช้ขอบเขตผู้ปฏิบัติการ Gateway (auth: "gateway" พร้อม gatewayRuntimeScopeSurface: "trusted-operator") ใช้โทเค็นหรือรหัสผ่านเดียวกับที่ Prometheus ใช้สำหรับเส้นทางผู้ปฏิบัติการ Gateway อื่น ๆ ไม่มีโหมดสาธารณะที่ไม่ต้องยืนยันตัวตน

`openclaw_prometheus_series_dropped_total` is climbing

แอตทริบิวต์ใหม่กำลังเกินขีดจำกัด 2048 series ตรวจสอบเมตริกล่าสุดเพื่อหา label ที่มี cardinality สูงผิดคาดและแก้ไขที่ต้นทาง exporter ตั้งใจทิ้ง series ใหม่แทนที่จะเขียน label ใหม่แบบเงียบ ๆ

Prometheus shows stale series after a restart

Plugin เก็บสถานะไว้ในหน่วยความจำเท่านั้น หลังจากรีสตาร์ต Gateway แล้ว counter จะรีเซ็ตเป็นศูนย์ และ gauge จะเริ่มใหม่ที่ค่าถัดไปที่รายงาน ใช้ PromQL rate() และ increase() เพื่อจัดการการรีเซ็ตอย่างเรียบร้อย

ที่เกี่ยวข้อง

การส่งออกข้อมูลวินิจฉัย — zip ข้อมูลวินิจฉัยในเครื่องสำหรับชุดข้อมูลสนับสนุน
สุขภาพและความพร้อม — probe /healthz และ /readyz
การบันทึก log — การบันทึก log แบบอิงไฟล์
การส่งออก OpenTelemetry — การ push ด้วย OTLP สำหรับ trace, เมตริก และ log

Was this useful?

เมตริก Prometheus

เริ่มต้นอย่างรวดเร็ว

ติดตั้ง Plugin

เปิดใช้งาน Plugin

การกำหนดค่า

CLI

รีสตาร์ท Gateway

Scrape เส้นทางที่ได้รับการป้องกัน

เชื่อมต่อ Prometheus

เมตริกที่ส่งออก

นโยบายป้ายกำกับ

สูตร PromQL

การเลือกระหว่างการส่งออก Prometheus และ OpenTelemetry

diagnostics-prometheus

diagnostics-otel

การแก้ไขปัญหา

ที่เกี่ยวข้อง

On this page

Molty