الانتقال إلى المحتوى الرئيسي

Documentation Index

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

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

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

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

أرسل مصادقة 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_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_tool_execution_totalعدّادerror_category, outcome, params_kind, tool
openclaw_tool_execution_duration_secondsمدرّج تكراريerror_category, outcome, params_kind, tool
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_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_recovery_totalعدّادaction, active_work_kind, state, status
openclaw_session_recovery_age_secondsمدرّج تكراريaction, active_work_kind, state, status
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، وفقًا للمقياس.
يحدّ المصدّر السلاسل الزمنية المحتفَظ بها في الذاكرة عند 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

# 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 للتعامل مع عمليات إعادة التعيين بسلاسة.

​
ذات صلة