OpenClawDocs
في هذه الصفحة

في هذه الصفحة

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

مقاييس Prometheus

يمكن لـ OpenClaw عرض مقاييس التشخيص من خلال Plugin diagnostics-prometheus الرسمي. ويستمع إلى بيانات التشخيص الموثوقة، بالإضافة إلى أحداث التشخيص الموسومة داخليًا والمملوكة للموزّع (إشارات قائمة الانتظار والذاكرة واسترداد الجلسة)، ويعرض نقطة نهاية نصية بتنسيق Prometheus على:

text
GET /api/diagnostics/prometheus

نوع المحتوى هو text/plain; version=0.0.4; charset=utf-8، وهو تنسيق العرض القياسي لـ Prometheus.

للاطلاع على آثار التتبّع والسجلات والدفع عبر OTLP والسمات الدلالية لـ OpenTelemetry GenAI، راجع التصدير عبر OpenTelemetry.

البدء السريع

  • تثبيت Plugin

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

  • تمكين Plugin

    الإعداد

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

    CLI

    bash
    openclaw plugins enable diagnostics-prometheus

  • إعادة تشغيل Gateway

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

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

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

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

  • ربط Prometheus

    yaml
    # prometheus.ymlscrape_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"]

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

    المقياس النوع التسميات
    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

    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

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

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

    diagnostics-prometheus

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

    diagnostics-otel

    • نموذج الدفع: يرسل 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 للتعامل مع عمليات إعادة الضبط بسلاسة.

    ذو صلة

    Was this useful?