الانتقال إلى المحتوى الرئيسي
يمكن لـ OpenClaw عرض مقاييس التشخيص عبر Plugin الرسمي diagnostics-prometheus. يستمع إلى التشخيصات الموثوقة وأحداث استقرار Gateway الصادرة من النواة، ثم يعرض نقطة نهاية نصية بتنسيق Prometheus على: 
GET /api/diagnostics/prometheus
نوع المحتوى هو text/plain; version=0.0.4; charset=utf-8، وهو تنسيق العرض القياسي في Prometheus.
يستخدم المسار مصادقة Gateway (نطاق المشغّل). لا تعرضه كنقطة نهاية /metrics عامة بلا مصادقة. اجعله يُكشَط عبر مسار المصادقة نفسه الذي تستخدمه لواجهات API الأخرى الخاصة بالمشغّل.
للتتبعات والسجلات ودفع OTLP وسمات GenAI الدلالية في OpenTelemetry، راجع تصدير 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

اكشط المسار المحمي

أرسل مصادقة Gateway نفسها التي يستخدمها عملاء المشغّل لديك:
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، لكن لا تتدفق أي أحداث تشخيصية إلى أداة التصدير، لذلك تكون الاستجابة فارغة.

​
المقاييس المصدّرة

المقياسالنوعالتسميات
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, outcome, provider, transport
openclaw_model_call_duration_secondsمدرج تكراريapi, error_category, model, 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_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عدادلا شيء

​
سياسة التسميات

تبقى تسميات Prometheus محدودة ومنخفضة التعددية. لا تصدر أداة التصدير معرّفات تشخيصية خامًا مثل runId أو sessionKey أو sessionId أو callId أو toolCallId أو معرّفات الرسائل أو معرّفات المحادثات أو معرّفات طلبات المزوّدين.تُنقّح قيم التسميات ويجب أن تطابق سياسة OpenClaw للأحرف منخفضة التعددية. تُستبدل القيم التي لا تستوفي السياسة بـ unknown أو other أو none، حسب المقياس. وتُستبدل أيضًا التسميات التي تبدو كمفاتيح جلسات وكيل ذات نطاق بـ unknown.
تضع أداة التصدير حدًا أقصى للسلاسل الزمنية المحتفَظ بها في الذاكرة يبلغ 2048 سلسلة عبر العدادات والمقاييس والمدرجات التكرارية مجتمعة. تُسقَط السلاسل الجديدة التي تتجاوز هذا الحد، وتزداد قيمة openclaw_prometheus_series_dropped_total بمقدار واحد كل مرة.راقب هذا العداد كإشارة حاسمة إلى أن سمة في المصدر الأعلى تسرّب قيمًا عالية التعددية. لا ترفع أداة التصدير الحد تلقائيًا أبدًا؛ إذا بدأ بالارتفاع، فأصلح المصدر بدلًا من تعطيل الحد.
  • نص الموجه، نص الاستجابة، مدخلات الأدوات، مخرجات الأدوات، موجهات النظام
  • نصوص محادثات Talk، حمولات الصوت، معرّفات المكالمات، معرّفات الغرف، رموز التسليم، معرّفات الأدوار، ومعرّفات الجلسات الخام
  • معرّفات طلبات المزوّد الخام (تجزئات محدودة فقط، عند الاقتضاء، على المقاطع — وليس على المقاييس أبدًا)
  • مفاتيح الجلسات ومعرّفات الجلسات
  • أسماء المضيفين، مسارات الملفات، القيم السرية

​
وصفات 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

# 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 الدلالية ويتسق مع المقاييس من خدمات GenAI غير التابعة لـ OpenClaw.

​
الاختيار بين تصدير Prometheus وOpenTelemetry

يدعم OpenClaw كلا السطحين بشكل مستقل. يمكنك تشغيل أيٍّ منهما، أو كليهما، أو عدم تشغيلهما.
  • نموذج السحب: يقوم 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، تعود العدادات إلى الصفر وتُعاد مقاييس القياس عند القيمة التالية التي يتم الإبلاغ عنها. استخدم rate() وincrease() في PromQL للتعامل مع عمليات إعادة الضبط بشكل نظيف.

​
ذو صلة