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

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

1

فعّل Plugin

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

أعد تشغيل Gateway

يتم تسجيل مسار HTTP عند بدء تشغيل Plugin، لذا أعد التحميل بعد التفعيل.
3

اجمع المسار المحمي

أرسل مصادقة gateway نفسها التي يستخدمها عملاء المشغّل لديك:
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus
4

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

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

المقياسالنوعlabels
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_totalcounterchannel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_secondshistogramchannel, delivery_kind, error_category, outcome
openclaw_queue_lane_sizegaugelane
openclaw_queue_lane_wait_secondshistogramlane
openclaw_session_state_totalcounterreason, state
openclaw_session_queue_depthgaugestate
openclaw_memory_bytesgaugekind
openclaw_memory_rss_byteshistogramnone
openclaw_memory_pressure_totalcounterlevel, reason
openclaw_telemetry_exporter_totalcounterexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalcounternone

​
سياسة labels

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

​
وصفات PromQL

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

# الإنفاق (USD) خلال الساعة الماضية، حسب model
sum by (model) (increase(openclaw_model_cost_usd_total[1h]))

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

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

# سلاسل Prometheus المسقطة (إنذار الكاردينالية)
increase(openclaw_prometheus_series_dropped_total[15m]) > 0
فضّل gen_ai_client_token_usage في لوحات المعلومات المشتركة بين providers: فهو يتبع الاتفاقيات الدلالية لـ OpenTelemetry GenAI ويتسق مع المقاييس القادمة من خدمات GenAI غير التابعة لـ OpenClaw.

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

يدعم OpenClaw كلا السطحين بشكل مستقل. يمكنك تشغيل أحدهما، أو كليهما، أو لا شيء منهما.
  • نموذج سحب: يقوم Prometheus بجمع /api/diagnostics/prometheus.
  • لا حاجة إلى مجمّع خارجي.
  • تتم المصادقة عبر مصادقة Gateway العادية.
  • السطح يقتصر على المقاييس فقط (من دون تتبعات أو سجلات).
  • الأفضل للحِزم التي تعتمد أصلًا على Prometheus + Grafana.

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

  • تحقّق من diagnostics.enabled: true في الإعدادات.
  • أكّد أن Plugin مفعّل ومحمّل عبر openclaw plugins list --enabled.
  • أنشئ بعض الحركة؛ فلا تصدر counters وhistograms أي أسطر إلا بعد حدث واحد على الأقل.
تتطلب نقطة النهاية نطاق مشغّل Gateway (auth: "gateway" مع gatewayRuntimeScopeSurface: "trusted-operator"). استخدم الرمز المميز أو كلمة المرور نفسها التي يستخدمها Prometheus لأي مسار آخر خاص بمشغّل Gateway. لا يوجد وضع عام غير موثّق.
تتجاوز سمة جديدة الحد الأقصى 2048 للسلاسل. افحص المقاييس الحديثة بحثًا عن label عالية الكاردينالية بشكل غير متوقع وأصلحها من المصدر. يقوم المُصدِّر عمدًا بإسقاط السلاسل الجديدة بدلًا من إعادة كتابة labels بصمت.
يحتفظ Plugin بحالته في الذاكرة فقط. بعد إعادة تشغيل Gateway، تعود counters إلى الصفر وتُعاد gauges من قيمتها التالية المُبلَّغ عنها. استخدم rate() وincrease() في PromQL للتعامل مع إعادة الضبط بشكل صحيح.

​
ذو صلة