Gateway

مقاييس Prometheus

يمكن لـ OmeniaClaw كشف مقاييس التشخيصات عبر 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

OmeniaClaw plugins install clawhub:@OmeniaClaw/diagnostics-prometheus

فعّل Plugin

الإعداد

json5

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

CLI

bash

OmeniaClaw plugins enable diagnostics-prometheus

أعد تشغيل Gateway

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

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

أرسل مصادقة gateway نفسها التي يستخدمها عملاء المشغّل لديك:

bash

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

اربط Prometheus

yaml

# prometheus.ymlscrape_configs:  - job_name: OmeniaClaw    scrape_interval: 30s    metrics_path: /api/diagnostics/prometheus    authorization:      credentials_file: /etc/prometheus/OmeniaClaw-gateway-token    static_configs:      - targets: ["OmeniaClaw-gateway:18789"]

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

المقياس	النوع	التسميات
`OmeniaClaw_run_completed_total`	عدّاد	`channel`, `model`, `outcome`, `provider`, `trigger`
`OmeniaClaw_run_duration_seconds`	مدرّج تكراري	`channel`, `model`, `outcome`, `provider`, `trigger`
`OmeniaClaw_model_call_total`	عدّاد	`api`, `error_category`, `model`, `outcome`, `provider`, `transport`
`OmeniaClaw_model_call_duration_seconds`	مدرّج تكراري	`api`, `error_category`, `model`, `outcome`, `provider`, `transport`
`OmeniaClaw_model_tokens_total`	عدّاد	`agent`, `channel`, `model`, `provider`, `token_type`
`OmeniaClaw_gen_ai_client_token_usage`	مدرّج تكراري	`model`, `provider`, `token_type`
`OmeniaClaw_model_cost_usd_total`	عدّاد	`agent`, `channel`, `model`, `provider`
`OmeniaClaw_tool_execution_total`	عدّاد	`error_category`, `outcome`, `params_kind`, `tool`
`OmeniaClaw_tool_execution_duration_seconds`	مدرّج تكراري	`error_category`, `outcome`, `params_kind`, `tool`
`OmeniaClaw_harness_run_total`	عدّاد	`channel`, `error_category`, `harness`, `model`, `outcome`, `phase`, `plugin`, `provider`
`OmeniaClaw_harness_run_duration_seconds`	مدرّج تكراري	`channel`, `error_category`, `harness`, `model`, `outcome`, `phase`, `plugin`, `provider`
`OmeniaClaw_message_processed_total`	عدّاد	`channel`, `outcome`, `reason`
`OmeniaClaw_message_processed_duration_seconds`	مدرّج تكراري	`channel`, `outcome`, `reason`
`OmeniaClaw_message_delivery_started_total`	عدّاد	`channel`, `delivery_kind`
`OmeniaClaw_message_delivery_total`	عدّاد	`channel`, `delivery_kind`, `error_category`, `outcome`
`OmeniaClaw_message_delivery_duration_seconds`	مدرّج تكراري	`channel`, `delivery_kind`, `error_category`, `outcome`
`OmeniaClaw_talk_event_total`	عدّاد	`brain`, `event_type`, `mode`, `provider`, `transport`
`OmeniaClaw_talk_event_duration_seconds`	مدرّج تكراري	`brain`, `event_type`, `mode`, `provider`, `transport`
`OmeniaClaw_talk_audio_bytes`	مدرّج تكراري	`brain`, `event_type`, `mode`, `provider`, `transport`
`OmeniaClaw_queue_lane_size`	مقياس	`lane`
`OmeniaClaw_queue_lane_wait_seconds`	مدرّج تكراري	`lane`
`OmeniaClaw_session_state_total`	عدّاد	`reason`, `state`
`OmeniaClaw_session_queue_depth`	مقياس	`state`
`OmeniaClaw_session_recovery_total`	عدّاد	`action`, `active_work_kind`, `state`, `status`
`OmeniaClaw_session_recovery_age_seconds`	مدرّج تكراري	`action`, `active_work_kind`, `state`, `status`
`OmeniaClaw_memory_bytes`	مقياس	`kind`
`OmeniaClaw_memory_rss_bytes`	مدرّج تكراري	لا شيء
`OmeniaClaw_memory_pressure_total`	عدّاد	`level`, `reason`
`OmeniaClaw_telemetry_exporter_total`	عدّاد	`exporter`, `reason`, `signal`, `status`
`OmeniaClaw_prometheus_series_dropped_total`	عدّاد	لا شيء

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

تسميات محدودة ومنخفضة الكاردينالية

تبقى تسميات Prometheus محدودة ومنخفضة الكاردينالية. لا يصدر المصدّر معرّفات تشخيصية خامًا مثل runId أو sessionKey أو sessionId أو callId أو toolCallId أو معرّفات الرسائل أو معرّفات الدردشة أو معرّفات طلبات المزوّد.

تُنقّح قيم التسميات ويجب أن تطابق سياسة OmeniaClaw للأحرف منخفضة الكاردينالية. تُستبدل القيم التي تفشل في السياسة بـ unknown أو other أو none، وفقًا للمقياس.

سقف السلاسل الزمنية واحتساب التجاوز

يحدّ المصدّر السلاسل الزمنية المحتفَظ بها في الذاكرة عند 2048 سلسلة عبر العدادات والمقاييس والمدرجات التكرارية مجتمعة. تُسقَط السلاسل الجديدة التي تتجاوز هذا السقف، ويزداد OmeniaClaw_prometheus_series_dropped_total بمقدار واحد في كل مرة.

راقب هذا العداد بوصفه إشارة حاسمة إلى أن سمةً في المنبع تسرّب قيماً عالية التعددية. لا يرفع المصدّر السقف تلقائياً أبداً؛ إذا أخذ بالارتفاع، فأصلح المصدر بدلاً من تعطيل السقف.

ما لا يظهر أبداً في مخرجات Prometheus

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

وصفات PromQL

promql

# Tokens per minute, split by providersum by (provider) (rate(OmeniaClaw_model_tokens_total[1m])) # Spend (USD) over the last hour, by modelsum by (model) (increase(OmeniaClaw_model_cost_usd_total[1h])) # 95th percentile model run durationhistogram_quantile(  0.95,  sum by (le, provider, model)    (rate(OmeniaClaw_run_duration_seconds_bucket[5m]))) # Queue wait time SLO (95p under 2s)histogram_quantile(  0.95,  sum by (le, lane) (rate(OmeniaClaw_queue_lane_wait_seconds_bucket[5m]))) < 2 # Dropped Prometheus series (cardinality alarm)increase(OmeniaClaw_prometheus_series_dropped_total[15m]) > 0

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

يدعم OmeniaClaw السطحين كليهما بشكل مستقل. يمكنك تشغيل أحدهما، أو كليهما، أو عدم تشغيل أي منهما.

diagnostics-prometheus

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

diagnostics-otel

نموذج الدفع: يرسل OmeniaClaw‏ OTLP/HTTP إلى مجمّع أو واجهة خلفية متوافقة مع OTLP.
يشمل السطح المقاييس والامتدادات والسجلات.
يربط إلى Prometheus عبر OpenTelemetry Collector (مصدّر prometheus أو prometheusremotewrite) عندما تحتاج إلى كليهما.
راجع تصدير OpenTelemetry للاطلاع على الكتالوج الكامل.

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

نص استجابة فارغ

تحقق من diagnostics.enabled: true في الإعدادات.
تأكد من أن Plugin مفعّل ومحمّل باستخدام OmeniaClaw plugins list --enabled.
أنشئ بعض الحركة؛ لا تصدر العدادات والمدرجات التكرارية أسطراً إلا بعد وقوع حدث واحد على الأقل.

401 / غير مصرح

تتطلب نقطة النهاية نطاق مشغّل Gateway (auth: "gateway" مع gatewayRuntimeScopeSurface: "trusted-operator"). استخدم نفس الرمز أو كلمة المرور التي يستخدمها Prometheus لأي مسار مشغّل Gateway آخر. لا يوجد وضع عام بلا مصادقة.

`OmeniaClaw_prometheus_series_dropped_total` آخذ في الارتفاع

تتجاوز سمة جديدة سقف السلاسل البالغ 2048. افحص المقاييس الأخيرة بحثاً عن تسمية ذات تعددية عالية على نحو غير متوقع وأصلحها في المصدر. يسقط المصدّر السلاسل الجديدة عمداً بدلاً من إعادة كتابة التسميات بصمت.

يعرض Prometheus سلاسل قديمة بعد إعادة التشغيل

يحتفظ Plugin بالحالة في الذاكرة فقط. بعد إعادة تشغيل Gateway، تُعاد العدادات إلى الصفر وتبدأ المقاييس من جديد عند القيمة التالية المبلّغ عنها. استخدم rate() وincrease() في PromQL للتعامل مع عمليات إعادة التعيين بسلاسة.

مقاييس Prometheus

البدء السريع

ثبّت Plugin

فعّل Plugin

الإعداد

CLI

أعد تشغيل Gateway

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

اربط Prometheus

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

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

وصفات PromQL

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

diagnostics-prometheus

diagnostics-otel

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

ذات صلة

On this page

Molty