Gateway

เมตริก Prometheus

OpenClaw สามารถเปิดเผยเมตริกการวินิจฉัยผ่าน Plugin อย่างเป็นทางการ diagnostics-prometheus โดยรับข้อมูลการวินิจฉัยที่เชื่อถือได้ รวมถึง เหตุการณ์การวินิจฉัยที่ติดแท็กภายในและอยู่ภายใต้การจัดการของตัวกระจายงาน (สัญญาณคิว หน่วยความจำ และ การกู้คืนเซสชัน) แล้วแสดงผลปลายทางข้อความ Prometheus ที่:

text

GET /api/diagnostics/prometheus

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

สำหรับเทรซ บันทึก การพุช OTLP และแอตทริบิวต์เชิงความหมาย GenAI ของ OpenTelemetry โปรดดู การส่งออก 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 เริ่มทำงาน ดังนั้นให้โหลดใหม่หลังจากเปิดใช้งาน

ดึงข้อมูลจากเส้นทางที่มีการป้องกัน

ส่งข้อมูลการยืนยันตัวตนของ Gateway แบบเดียวกับที่ไคลเอ็นต์ผู้ปฏิบัติงานใช้:

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`	ตัวนับ	`channel`, `model`, `outcome`, `provider`, `trigger`
`openclaw_run_duration_seconds`	ฮิสโตแกรม	`channel`, `model`, `outcome`, `provider`, `trigger`
`openclaw_model_call_total`	ตัวนับ	`api`, `error_category`, `model`, `observation_unit`, `outcome`, `provider`, `transport`
`openclaw_model_call_duration_seconds`	ฮิสโตแกรม	`api`, `error_category`, `model`, `observation_unit`, `outcome`, `provider`, `transport`
`openclaw_model_failover_total`	ตัวนับ	`from_model`, `from_provider`, `lane`, `reason`, `suspended`, `to_model`, `to_provider`
`openclaw_model_tokens_total`	ตัวนับ	`agent`, `channel`, `model`, `provider`, `token_type`
`openclaw_gen_ai_client_token_usage`	ฮิสโตแกรม	`model`, `provider`, `token_type`
`openclaw_model_cost_usd_total`	ตัวนับ	`agent`, `channel`, `model`, `provider`
`openclaw_model_usage_duration_seconds`	ฮิสโตแกรม	`agent`, `channel`, `model`, `provider`
`openclaw_skill_used_total`	ตัวนับ	`activation`, `agent`, `skill`, `source`
`openclaw_tool_execution_total`	ตัวนับ	`error_category`, `outcome`, `params_kind`, `tool`, `tool_owner`, `tool_source`
`openclaw_tool_execution_duration_seconds`	ฮิสโตแกรม	`error_category`, `outcome`, `params_kind`, `tool`, `tool_owner`, `tool_source`
`openclaw_tool_execution_blocked_total`	ตัวนับ	`denied_reason`, `params_kind`, `tool`, `tool_owner`, `tool_source`
`openclaw_harness_run_total`	ตัวนับ	`channel`, `error_category`, `harness`, `model`, `outcome`, `phase`, `plugin`, `provider`
`openclaw_harness_run_duration_seconds`	ฮิสโตแกรม	`channel`, `error_category`, `harness`, `model`, `outcome`, `phase`, `plugin`, `provider`
`openclaw_webhook_received_total`	ตัวนับ	`channel`, `webhook`
`openclaw_webhook_error_total`	ตัวนับ	`channel`, `webhook`
`openclaw_webhook_duration_seconds`	ฮิสโตแกรม	`channel`, `webhook`
`openclaw_message_received_total`	ตัวนับ	`channel`, `source`
`openclaw_message_dispatch_started_total`	ตัวนับ	`channel`, `source`
`openclaw_message_dispatch_completed_total`	ตัวนับ	`channel`, `outcome`, `reason`, `source`
`openclaw_message_dispatch_duration_seconds`	ฮิสโตแกรม	`channel`, `outcome`, `reason`, `source`
`openclaw_message_processed_total`	ตัวนับ	`channel`, `outcome`, `reason`
`openclaw_message_processed_duration_seconds`	ฮิสโตแกรม	`channel`, `outcome`, `reason`
`openclaw_message_delivery_started_total`	ตัวนับ	`channel`, `delivery_kind`
`openclaw_message_delivery_total`	ตัวนับ	`channel`, `delivery_kind`, `error_category`, `outcome`
`openclaw_message_delivery_duration_seconds`	ฮิสโตแกรม	`channel`, `delivery_kind`, `error_category`, `outcome`
`openclaw_talk_event_total`	ตัวนับ	`brain`, `event_type`, `mode`, `provider`, `transport`
`openclaw_talk_event_duration_seconds`	ฮิสโตแกรม	`brain`, `event_type`, `mode`, `provider`, `transport`
`openclaw_talk_audio_bytes`	ฮิสโตแกรม	`brain`, `event_type`, `mode`, `provider`, `transport`
`openclaw_queue_lane_size`	เกจ	`lane`
`openclaw_queue_lane_wait_seconds`	ฮิสโตแกรม	`lane`
`openclaw_session_state_total`	ตัวนับ	`reason`, `state`
`openclaw_session_queue_depth`	เกจ	`state`
`openclaw_session_turn_created_total`	ตัวนับ	`agent`, `channel`, `trigger`
`openclaw_session_stuck_total`	ตัวนับ	`reason`, `state`
`openclaw_session_stuck_age_seconds`	ฮิสโตแกรม	`reason`, `state`
`openclaw_session_recovery_total`	ตัวนับ	`action`, `active_work_kind`, `state`, `status`
`openclaw_session_recovery_age_seconds`	ฮิสโตแกรม	`action`, `active_work_kind`, `state`, `status`
`openclaw_liveness_warning_total`	ตัวนับ	`reason`
`openclaw_liveness_sessions`	เกจ	`state`
`openclaw_liveness_event_loop_delay_p99_seconds`	ฮิสโตแกรม	`reason`
`openclaw_liveness_event_loop_delay_max_seconds`	ฮิสโตแกรม	`reason`
`openclaw_liveness_event_loop_utilization_ratio`	ฮิสโตแกรม	`reason`
`openclaw_liveness_cpu_core_ratio`	ฮิสโตแกรม	`reason`
`openclaw_payload_large_total`	ตัวนับ	`action`, `channel`, `plugin`, `reason`, `surface`
`openclaw_payload_large_bytes`	ฮิสโตแกรม	`action`, `channel`, `plugin`, `reason`, `surface`
`openclaw_memory_bytes`	เกจ	`kind`
`openclaw_memory_rss_bytes`	ฮิสโตแกรม	ไม่มี
`openclaw_memory_pressure_total`	ตัวนับ	`level`, `reason`
`openclaw_telemetry_exporter_total`	ตัวนับ	`exporter`, `reason`, `signal`, `status`
`openclaw_prometheus_series_dropped_total`	ตัวนับ	ไม่มี
`openclaw_diagnostic_async_queue_dropped_total`	ตัวนับ	`drop_class`
`openclaw_diagnostic_async_queue_length`	เกจ	ไม่มี

สำหรับเมตริกการเรียกโมเดล observation_unit="request" วัดคำขอไปยังผู้ให้บริการที่สังเกตได้หนึ่งครั้ง ส่วน observation_unit="turn" วัดหนึ่งรอบการทำงานของเอเจนต์ Claude Code หรือ Codex CLI แบบสังเคราะห์ ซึ่งอาจมีคำขอไปยังผู้ให้บริการที่ซ่อนอยู่หลายครั้ง ให้แยกอนุกรมเหล่านี้ออกจากกันเมื่อเปรียบเทียบเวลาแฝง

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

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

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

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

ขีดจำกัดอนุกรมและการนับส่วนที่เกิน

ตัวส่งออกจำกัดอนุกรมเวลาที่เก็บไว้ในหน่วยความจำไว้ที่ 2048 อนุกรม โดยนับรวมตัวนับ เกจ และฮิสโตแกรม อนุกรมใหม่ที่เกินขีดจำกัดนี้จะถูกทิ้ง และ openclaw_prometheus_series_dropped_total จะเพิ่มขึ้นหนึ่งทุกครั้ง

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

สิ่งที่ไม่ปรากฏในเอาต์พุต Prometheus

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

สูตร PromQL

promql

# โทเค็นต่อนาที แยกตามผู้ให้บริการsum by (provider) (rate(openclaw_model_tokens_total[1m])) # ค่าใช้จ่าย (USD) ในช่วงชั่วโมงที่ผ่านมา แยกตามโมเดลsum by (model) (increase(openclaw_model_cost_usd_total[1h])) # ระยะเวลารันโมเดลเปอร์เซ็นไทล์ที่ 95histogram_quantile(  0.95,  sum by (le, provider, model)    (rate(openclaw_run_duration_seconds_bucket[5m]))) # SLO เวลารอคิว (เปอร์เซ็นไทล์ที่ 95 ต่ำกว่า 2 วินาที)histogram_quantile(  0.95,  sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))) < 2 # การใช้งาน Skills แยกตามแหล่งที่มาที่มีขอบเขตsum by (skill, source) (increase(openclaw_skill_used_total[24h])) # อนุกรม Prometheus ที่ถูกทิ้ง (สัญญาณเตือนคาร์ดินาลิตี)increase(openclaw_prometheus_series_dropped_total[15m]) > 0

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

OpenClaw รองรับทั้งสองพื้นผิวอย่างเป็นอิสระจากกัน สามารถใช้อย่างใดอย่างหนึ่ง ใช้ทั้งคู่ หรือไม่ใช้เลยก็ได้

diagnostics-prometheus

โมเดล ดึง: Prometheus ดึงข้อมูลจาก /api/diagnostics/prometheus
ไม่จำเป็นต้องมีตัวรวบรวมภายนอก
ตรวจสอบสิทธิ์ผ่านการตรวจสอบสิทธิ์ตามปกติของ Gateway
พื้นผิวนี้มีเฉพาะเมตริกเท่านั้น (ไม่มีเทรซหรือบันทึก)
เหมาะที่สุดสำหรับสแต็กที่กำหนดมาตรฐานไว้แล้วบน Prometheus + Grafana

diagnostics-otel

โมเดล ส่ง: OpenClaw ส่ง OTLP/HTTP ไปยังตัวรวบรวมหรือแบ็กเอนด์ที่เข้ากันได้กับ OTLP
พื้นผิวนี้ประกอบด้วยเมตริก เทรซ และบันทึก
เชื่อมต่อไปยัง Prometheus ผ่าน OpenTelemetry Collector (ตัวส่งออก prometheus หรือ prometheusremotewrite) เมื่อต้องใช้ทั้งสองอย่าง
ดูแค็ตตาล็อกฉบับเต็มได้ที่ การส่งออก OpenTelemetry

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

เนื้อหาการตอบกลับว่างเปล่า

ตรวจสอบว่าไม่ได้ตั้งค่า diagnostics.enabled เป็น false ในการกำหนดค่า (ค่าเริ่มต้นคือ true)
ยืนยันว่า Plugin เปิดใช้งานและโหลดแล้วด้วย openclaw plugins list --enabled
สร้างทราฟฟิกบางส่วน ตัวนับและฮิสโตแกรมจะส่งบรรทัดออกมาหลังจากเกิดเหตุการณ์อย่างน้อยหนึ่งครั้งเท่านั้น

401 / ไม่ได้รับอนุญาต

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

`openclaw_prometheus_series_dropped_total` กำลังเพิ่มขึ้น

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

Prometheus แสดงอนุกรมเก่าหลังจากรีสตาร์ต

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

เนื้อหาที่เกี่ยวข้อง

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

Was this useful?

เมตริก Prometheus

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

ติดตั้ง Plugin

เปิดใช้งาน Plugin

การกำหนดค่า

CLI

รีสตาร์ต Gateway

ดึงข้อมูลจากเส้นทางที่มีการป้องกัน

เชื่อมต่อ Prometheus

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

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

สูตร PromQL

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

diagnostics-prometheus

diagnostics-otel

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

เนื้อหาที่เกี่ยวข้อง

On this page

Molty