मुख्य सामग्री पर जाएं
OpenClaw आधिकारिक diagnostics-prometheus plugin के माध्यम से diagnostics metrics उजागर कर सकता है। यह विश्वसनीय diagnostics और core-emitted gateway stability events को सुनता है, फिर इस पते पर Prometheus text endpoint प्रस्तुत करता है: 
GET /api/diagnostics/prometheus
Content type text/plain; version=0.0.4; charset=utf-8 है, जो मानक Prometheus exposition format है।
यह route Gateway authentication (operator scope) का उपयोग करता है। इसे public unauthenticated /metrics endpoint के रूप में expose न करें। इसे उसी auth path के माध्यम से scrape करें जिसका उपयोग आप अन्य operator APIs के लिए करते हैं।
Traces, logs, OTLP push, और OpenTelemetry GenAI semantic attributes के लिए, OpenTelemetry export देखें।

​
त्वरित शुरुआत

1

Plugin install करें

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

Plugin enable करें

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

Gateway restart करें

HTTP route plugin startup पर register होता है, इसलिए enable करने के बाद reload करें।
4

Protected route scrape करें

वही gateway auth भेजें जिसका उपयोग आपके operator clients करते हैं:
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 route पंजीकृत करता है, लेकिन कोई diagnostic events exporter में प्रवाहित नहीं होते, इसलिए response खाली होता है।

​
निर्यात किए गए metrics

MetricTypeLabels
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_failover_totalcounterfrom_model, from_provider, lane, reason, suspended, to_model, to_provider
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_skill_used_totalcounteractivation, agent, skill, source
openclaw_tool_execution_totalcountererror_category, outcome, params_kind, tool, tool_owner, tool_source
openclaw_tool_execution_duration_secondshistogramerror_category, outcome, params_kind, tool, tool_owner, tool_source
openclaw_tool_execution_blocked_totalcounterdenied_reason, params_kind, tool, tool_owner, tool_source
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_webhook_received_totalcounterchannel, webhook
openclaw_webhook_error_totalcounterchannel, webhook
openclaw_webhook_duration_secondshistogramchannel, webhook
openclaw_message_received_totalcounterchannel, source
openclaw_message_dispatch_started_totalcounterchannel, source
openclaw_message_dispatch_completed_totalcounterchannel, outcome, reason, source
openclaw_message_dispatch_duration_secondshistogramchannel, outcome, reason, source
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_turn_created_totalcounteragent, channel, trigger
openclaw_session_stuck_totalcounterreason, state
openclaw_session_stuck_age_secondshistogramreason, state
openclaw_session_recovery_totalcounteraction, active_work_kind, state, status
openclaw_session_recovery_age_secondshistogramaction, active_work_kind, state, status
openclaw_liveness_warning_totalcounterreason
openclaw_liveness_sessionsgaugestate
openclaw_liveness_event_loop_delay_p99_secondshistogramreason
openclaw_liveness_event_loop_delay_max_secondshistogramreason
openclaw_liveness_event_loop_utilization_ratiohistogramreason
openclaw_liveness_cpu_core_ratiohistogramreason
openclaw_payload_large_totalcounteraction, channel, plugin, reason, surface
openclaw_payload_large_byteshistogramaction, channel, plugin, reason, surface
openclaw_memory_bytesgaugekind
openclaw_memory_rss_byteshistogramnone
openclaw_memory_pressure_totalcounterlevel, reason
openclaw_telemetry_exporter_totalcounterexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalcounternone

​
Label नीति

Prometheus labels सीमित और कम-cardinality रहते हैं। exporter कच्चे diagnostic identifiers जैसे runId, sessionKey, sessionId, callId, toolCallId, message IDs, chat IDs, या provider request IDs emit नहीं करता।Label values को redact किया जाता है और उन्हें OpenClaw की कम-cardinality character policy से मेल खाना चाहिए। जो values policy में fail होती हैं, उन्हें metric के आधार पर unknown, other, या none से बदल दिया जाता है। scoped agent session keys जैसी दिखने वाली labels को भी unknown से बदल दिया जाता है।
exporter counters, gauges, और histograms को मिलाकर memory में retained time series को 2048 series पर cap करता है। उस cap से आगे की नई series drop कर दी जाती हैं, और हर बार openclaw_prometheus_series_dropped_total एक से increment होता है।इस counter को इस hard signal के रूप में देखें कि upstream attribute high-cardinality values leak कर रहा है। exporter कभी भी cap को अपने-आप नहीं बढ़ाता; अगर यह बढ़ता है, तो cap disable करने के बजाय source को fix करें।
  • प्रॉम्प्ट टेक्स्ट, प्रतिक्रिया टेक्स्ट, टूल इनपुट, टूल आउटपुट, सिस्टम प्रॉम्प्ट
  • Talk ट्रांसक्रिप्ट, ऑडियो पेलोड, कॉल आईडी, रूम आईडी, हैंडऑफ टोकन, टर्न आईडी, और कच्चे सेशन आईडी
  • कच्चे प्रदाता अनुरोध आईडी (जहां लागू हो, केवल spans पर सीमित हैश — metrics पर कभी नहीं)
  • सेशन कुंजियां और सेशन आईडी
  • होस्टनाम, फाइल पाथ, गुप्त मान

​
PromQL recipes

# 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

# Skill usage, split by bounded source
sum by (skill, source) (increase(openclaw_skill_used_total[24h]))

# Dropped Prometheus series (cardinality alarm)
increase(openclaw_prometheus_series_dropped_total[15m]) > 0
क्रॉस-प्रदाता डैशबोर्ड के लिए gen_ai_client_token_usage को प्राथमिकता दें: यह OpenTelemetry GenAI semantic conventions का पालन करता है और गैर-OpenClaw GenAI सेवाओं की metrics के अनुरूप है।

​
Prometheus और OpenTelemetry निर्यात के बीच चयन

OpenClaw दोनों surfaces को स्वतंत्र रूप से समर्थन देता है। आप इनमें से किसी एक को, दोनों को, या किसी को भी नहीं चला सकते हैं।
  • Pull मॉडल: Prometheus /api/diagnostics/prometheus को scrape करता है।
  • किसी बाहरी collector की आवश्यकता नहीं है।
  • सामान्य Gateway auth के माध्यम से प्रमाणित।
  • Surface केवल metrics है (traces या logs नहीं)।
  • उन stacks के लिए सर्वोत्तम जो पहले से Prometheus + Grafana पर मानकीकृत हैं।

​
समस्या निवारण

  • config में diagnostics.enabled: true जांचें।
  • पुष्टि करें कि Plugin सक्षम है और openclaw plugins list --enabled के साथ लोड है।
  • कुछ traffic जनरेट करें; counters और histograms कम से कम एक event के बाद ही lines emit करते हैं।
Endpoint को Gateway operator scope (auth: "gateway" के साथ gatewayRuntimeScopeSurface: "trusted-operator") की आवश्यकता होती है। वही token या password उपयोग करें जो Prometheus किसी अन्य Gateway operator route के लिए उपयोग करता है। कोई सार्वजनिक unauthenticated mode नहीं है।
कोई नया attribute 2048-series cap से अधिक हो रहा है। अनपेक्षित रूप से high-cardinality label के लिए हाल की metrics का निरीक्षण करें और उसे source पर ठीक करें। Exporter labels को चुपचाप rewrite करने के बजाय जानबूझकर नई series drop करता है।
Plugin state को केवल memory में रखता है। Gateway restart के बाद, counters शून्य पर reset हो जाते हैं और gauges अपनी अगली reported value से restart होते हैं। resets को साफ़ तरह से संभालने के लिए PromQL rate() और increase() का उपयोग करें।

​
संबंधित