مقاييس Prometheus

يمكن لـ 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.

البدء السريع

تثبيت Plugin

openclaw plugins install clawhub:@openclaw/diagnostics-prometheus

تمكين Plugin

الإعداد
CLI

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

openclaw plugins enable diagnostics-prometheus

إعادة تشغيل Gateway

يُسجَّل مسار HTTP عند بدء تشغيل Plugin، لذا أعد التحميل بعد تمكينه.

جمع البيانات من المسار المحمي

أرسل مصادقة Gateway نفسها التي تستخدمها برامج المشغّل العميلة:

curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus

ربط 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؛ ولا تضبطها على false إلا في البيئات شديدة التقييد. إذا كانت false، فسيظل 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_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`	مقياس آني	لا شيء

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

تسميات محدودة ومنخفضة التنوّع

تظل تسميات Prometheus محدودة ومنخفضة التنوّع. لا يصدر المُصدِّر معرّفات التشخيص الأولية مثل runId أو sessionKey أو sessionId أو callId أو toolCallId أو معرّفات الرسائل أو معرّفات المحادثات أو معرّفات طلبات المزوّد.تُنقَّح قيم التسميات، ويجب أن تتوافق مع سياسة OpenClaw للحروف منخفضة التنوّع. تُستبدل القيم التي لا تتوافق مع السياسة بـ unknown أو other أو none، وفقًا للمقياس. كما تُستبدل التسميات التي تبدو كمفاتيح جلسات وكيل ذات نطاق بـ unknown.

الحد الأقصى للسلاسل واحتساب التجاوز

يحدد المُصدِّر الحد الأقصى للسلاسل الزمنية المحتفَظ بها في الذاكرة عند 2048 سلسلة إجمالًا عبر العدادات والمقاييس والمدرّجات التكرارية. تُسقط السلاسل الجديدة التي تتجاوز هذا الحد، وتزداد قيمة openclaw_prometheus_series_dropped_total بمقدار واحد في كل مرة.راقب هذا العداد بوصفه إشارة قاطعة إلى أن إحدى السمات في المراحل السابقة تُسرِّب قيمًا عالية التعددية. لا يرفع المُصدِّر الحد تلقائيًا مطلقًا؛ فإذا ارتفعت قيمة العداد، فأصلح المصدر بدلًا من تعطيل الحد.

ما لا يظهر مطلقًا في مخرجات Prometheus

نص المطالبة، ونص الاستجابة، ومدخلات الأدوات، ومخرجات الأدوات، ومطالبات النظام
نصوص محادثات Talk، وحمولات الصوت، ومعرّفات المكالمات، ومعرّفات الغرف، ورموز التسليم، ومعرّفات الأدوار، ومعرّفات الجلسات الأولية
معرّفات طلبات المزوّد الأولية (تظهر فقط بصمات محدودة، عند الاقتضاء، في الامتدادات — ولا تظهر مطلقًا في المقاييس)
مفاتيح الجلسات ومعرّفات الجلسات
أسماء المضيفين، ومسارات الملفات، والقيم السرية

وصفات PromQL

# الرموز المميزة في الدقيقة، مقسّمة حسب المزوّد
sum by (provider) (rate(openclaw_model_tokens_total[1m]))

# الإنفاق (بالدولار الأمريكي) خلال الساعة الماضية، حسب النموذج
sum by (model) (increase(openclaw_model_cost_usd_total[1h]))

# المئين الخامس والتسعون لمدة تشغيل النموذج
histogram_quantile(
  0.95,
  sum by (le, provider, model)
    (rate(openclaw_run_duration_seconds_bucket[5m]))
)

# هدف مستوى الخدمة لوقت انتظار قائمة الانتظار (المئين 95 أقل من ثانيتين)
histogram_quantile(
  0.95,
  sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))
) < 2

# استخدام المهارات، مقسّم حسب المصدر المحدود
sum by (skill, source) (increase(openclaw_skill_used_total[24h]))

# سلاسل Prometheus المُسقطة (إنذار التعددية)
increase(openclaw_prometheus_series_dropped_total[15m]) > 0

فضّل gen_ai_client_token_usage للوحات المعلومات المشتركة بين المزوّدين: فهو يتبع الاصطلاحات الدلالية للذكاء الاصطناعي التوليدي في OpenTelemetry ويتسق مع المقاييس الصادرة عن خدمات الذكاء الاصطناعي التوليدي غير التابعة لـ OpenClaw.

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

يدعم OpenClaw كلا الوجهتين بصورة مستقلة. يمكنك تشغيل إحداهما أو كلتيهما أو عدم تشغيل أي منهما.

diagnostics-prometheus
diagnostics-otel

نموذج السحب: يجمع Prometheus البيانات من /api/diagnostics/prometheus.
لا يلزم جامع خارجي.
تتم المصادقة عبر مصادقة Gateway المعتادة.
تقتصر الوجهة على المقاييس فقط (من دون تتبعات أو سجلات).
الأنسب للمنظومات الموحّدة مسبقًا على Prometheus وGrafana.

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

ذو صلة

تصدير التشخيصات — ملف تشخيصات مضغوط محلي لحزم الدعم
الصحة والجاهزية — مجسّا /healthz و/readyz
التسجيل — تسجيل قائم على الملفات
تصدير OpenTelemetry — دفع OTLP للتتبعات والمقاييس والسجلات

Gateway

Remote access

Security

Nodes and media

Web interfaces

مقاييس Prometheus

البدء السريع

المقاييس المُصدَّرة

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

وصفات PromQL

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

استكشاف الأخطاء وإصلاحها

ذو صلة

​البدء السريع

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

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

​وصفات PromQL

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

​استكشاف الأخطاء وإصلاحها

​ذو صلة

البدء السريع

المقاييس المُصدَّرة

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

وصفات PromQL

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

استكشاف الأخطاء وإصلاحها

ذو صلة