Skip to main content

Documentation Index

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

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

OpenClaw สามารถเปิดเผยเมตริกการวินิจฉัยผ่าน Plugin ทางการ diagnostics-prometheus ได้ โดยจะฟังการวินิจฉัยภายในที่เชื่อถือได้และแสดง endpoint ข้อความ Prometheus ที่: 
GET /api/diagnostics/prometheus
ชนิดเนื้อหาคือ text/plain; version=0.0.4; charset=utf-8 ซึ่งเป็นรูปแบบ exposition มาตรฐานของ Prometheus
เส้นทางนี้ใช้การยืนยันตัวตนของ Gateway (ขอบเขต operator) อย่าเปิดเผยเป็น endpoint /metrics สาธารณะที่ไม่ต้องยืนยันตัวตน ให้ scrape ผ่านเส้นทาง auth เดียวกับที่คุณใช้สำหรับ API operator อื่นๆ
สำหรับ traces, logs, OTLP push และแอตทริบิวต์เชิงความหมาย OpenTelemetry GenAI โปรดดู การส่งออก OpenTelemetry

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

1

ติดตั้ง Plugin

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

เปิดใช้ Plugin

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

รีสตาร์ท Gateway

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

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

ส่ง gateway auth เดียวกับที่ไคลเอนต์ operator ของคุณใช้:
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus
5

เชื่อมต่อ 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 หากไม่มี คำตอบจะว่างเปล่าเพราะ Plugin ยังลงทะเบียนเส้นทาง HTTP อยู่ แต่ไม่มี event การวินิจฉัยไหลเข้าสู่ exporter

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

เมตริกประเภทป้ายกำกับ
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_byteshistogramไม่มี
openclaw_memory_pressure_totalcounterlevel, reason
openclaw_telemetry_exporter_totalcounterexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalcounterไม่มี

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

ป้ายกำกับ Prometheus ยังคงมีขอบเขตจำกัดและมีคาร์ดินาลิตีต่ำ exporter จะไม่ปล่อยตัวระบุการวินิจฉัยดิบ เช่น runId, sessionKey, sessionId, callId, toolCallId, ID ข้อความ, ID แชต หรือ ID คำขอของ providerค่าป้ายกำกับจะถูกปกปิดข้อมูลและต้องตรงกับนโยบายอักขระคาร์ดินาลิตีต่ำของ OpenClaw ค่าที่ไม่ผ่านนโยบายจะถูกแทนที่ด้วย unknown, other หรือ none ขึ้นอยู่กับเมตริก
ตัวส่งออกจำกัดซีรีส์เวลาที่เก็บไว้ในหน่วยความจำไว้ที่ 2048 ซีรีส์ รวมทั้งตัวนับ เกจ และฮิสโตแกรม ซีรีส์ใหม่ที่เกินเพดานนั้นจะถูกทิ้ง และ openclaw_prometheus_series_dropped_total จะเพิ่มขึ้นหนึ่งทุกครั้งเฝ้าดูตัวนับนี้เป็นสัญญาณชัดเจนว่าแอตทริบิวต์ต้นทางกำลังรั่วค่าที่มีคาร์ดินาลิตีสูง ตัวส่งออกจะไม่ยกเพดานให้โดยอัตโนมัติ หากค่านี้เพิ่มขึ้น ให้แก้ที่ต้นทางแทนการปิดเพดาน
  • ข้อความพรอมป์ ข้อความคำตอบ อินพุตของเครื่องมือ เอาต์พุตของเครื่องมือ พรอมป์ระบบ
  • บันทึกข้อความ Talk เพย์โหลดเสียง ID การโทร ID ห้อง โทเคนส่งต่อ ID เทิร์น และ ID เซสชันดิบ
  • ID คำขอผู้ให้บริการแบบดิบ (มีเฉพาะแฮชที่มีขอบเขตจำกัดเมื่อใช้ได้ บนสแปนเท่านั้น — ไม่อยู่บนเมตริก)
  • คีย์เซสชันและ ID เซสชัน
  • ชื่อโฮสต์ พาธไฟล์ ค่าความลับ

​
สูตร 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
ควรใช้ gen_ai_client_token_usage สำหรับแดชบอร์ดข้ามผู้ให้บริการ: ค่านี้ทำตามแบบแผนเชิงความหมาย OpenTelemetry GenAI และสอดคล้องกับเมตริกจากบริการ GenAI ที่ไม่ใช่ OpenClaw

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

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

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

  • ตรวจสอบ diagnostics.enabled: true ในการกำหนดค่า
  • ยืนยันว่า Plugin เปิดใช้และโหลดแล้วด้วย openclaw plugins list --enabled
  • สร้างทราฟฟิกบางส่วน ตัวนับและฮิสโตแกรมจะปล่อยบรรทัดหลังจากมีเหตุการณ์อย่างน้อยหนึ่งเหตุการณ์เท่านั้น
เอ็นด์พอยต์นี้ต้องใช้ขอบเขตผู้ปฏิบัติการ Gateway (auth: "gateway" พร้อม gatewayRuntimeScopeSurface: "trusted-operator") ใช้โทเคนหรือรหัสผ่านเดียวกับที่ Prometheus ใช้สำหรับเส้นทางผู้ปฏิบัติการ Gateway อื่น ๆ ไม่มีโหมดสาธารณะที่ไม่ต้องยืนยันตัวตน
แอตทริบิวต์ใหม่กำลังเกินเพดาน 2048 ซีรีส์ ตรวจสอบเมตริกล่าสุดเพื่อหาป้ายกำกับที่มีคาร์ดินาลิตีสูงผิดคาด และแก้ที่ต้นทาง ตัวส่งออกตั้งใจทิ้งซีรีส์ใหม่แทนการเขียนป้ายกำกับใหม่แบบเงียบ ๆ
Plugin เก็บสถานะไว้ในหน่วยความจำเท่านั้น หลังรีสตาร์ท Gateway ตัวนับจะรีเซ็ตเป็นศูนย์ และเกจจะเริ่มใหม่ที่ค่าถัดไปที่ถูกรายงาน ใช้ PromQL rate() และ increase() เพื่อจัดการการรีเซ็ตอย่างสะอาด

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