السجلات

يسجل Mayros في مكانين:

  • سجلات الملفات (سطور JSON) مكتوبة بواسطة Gateway.
  • مخرجات وحدة التحكم معروضة في الطرفيات وواجهة التحكم.

تشرح هذه الصفحة أين تعيش السجلات، وكيفية قراءتها، وكيفية تكوين مستويات السجل والتنسيقات.

أين تعيش السجلات

افتراضيًا، يكتب Gateway ملف سجل متجدد تحت:

/tmp/mayros/mayros-YYYY-MM-DD.log

يستخدم التاريخ المنطقة الزمنية المحلية لمضيف البوابة.

يمكنك تجاوز هذا في ~/.mayros/mayros.json:

json
{
  "logging": {
    "file": "/path/to/mayros.log"
  }
}

كيفية قراءة السجلات

CLI: تتبع مباشر (موصى به)

استخدم CLI لتتبع ملف سجل البوابة عبر RPC:

bash
mayros logs --follow

أوضاع الإخراج:

  • جلسات TTY: سطور سجل منظمة وملونة وجميلة.
  • جلسات غير TTY: نص عادي.
  • --json: JSON محدد بسطور (حدث سجل واحد لكل سطر).
  • --plain: فرض النص العادي في جلسات TTY.
  • --no-color: تعطيل ألوان ANSI.

في وضع JSON، يصدر CLI كائنات موسومة بـ type:

  • meta: بيانات تعريفية للتدفق (ملف، مؤشر، حجم)
  • log: إدخال سجل مُحلل
  • notice: تلميحات الاقتطاع / الدوران
  • raw: سطر سجل غير مُحلل

إذا كان Gateway غير قابل للوصول، يطبع CLI تلميحًا قصيرًا لتشغيل:

bash
mayros doctor

واجهة التحكم (الويب)

تتبع علامة التبويب السجلات في واجهة التحكم نفس الملف باستخدام logs.tail. راجع /web/control-ui لكيفية فتحها.

سجلات القناة فقط

لتصفية نشاط القناة (WhatsApp/Telegram/إلخ)، استخدم:

bash
mayros channels logs --channel whatsapp

تنسيقات السجل

سجلات الملفات (JSONL)

كل سطر في ملف السجل هو كائن JSON. يقوم CLI وواجهة التحكم بتحليل هذه الإدخالات لعرض مخرجات منظمة (الوقت، المستوى، النظام الفرعي، الرسالة).

مخرجات وحدة التحكم

سجلات وحدة التحكم مدركة لـ TTY ومنسقة للقراءة:

  • بادئات النظام الفرعي (مثل gateway/channels/whatsapp)
  • تلوين المستوى (info/warn/error)
  • وضع مضغوط أو JSON اختياري

يتم التحكم في تنسيق وحدة التحكم بواسطة logging.consoleStyle.

تكوين السجلات

يعيش كل تكوين السجلات تحت logging في ~/.mayros/mayros.json.

json
{
  "logging": {
    "level": "info",
    "file": "/tmp/mayros/mayros-YYYY-MM-DD.log",
    "consoleLevel": "info",
    "consoleStyle": "pretty",
    "redactSensitive": "tools",
    "redactPatterns": ["sk-.*"]
  }
}

مستويات السجل

  • logging.level: مستوى سجلات الملفات (JSONL).
  • logging.consoleLevel: مستوى تفصيل وحدة التحكم.

--verbose يؤثر فقط على مخرجات وحدة التحكم؛ لا يغير مستويات سجل الملفات.

أنماط وحدة التحكم

logging.consoleStyle:

  • pretty: صديق للإنسان، ملون، مع طوابع زمنية.
  • compact: مخرجات أضيق (الأفضل للجلسات الطويلة).
  • json: JSON لكل سطر (لمعالجات السجل).

الحذف

يمكن لملخصات الأدوات حذف الرموز الحساسة قبل وصولها إلى وحدة التحكم:

  • logging.redactSensitive: off | tools (افتراضي: tools)
  • logging.redactPatterns: قائمة سلاسل regex لتجاوز المجموعة الافتراضية

يؤثر الحذف على مخرجات وحدة التحكم فقط ولا يغير سجلات الملفات.

التشخيصات + OpenTelemetry

التشخيصات هي أحداث منظمة وقابلة للقراءة آليًا لتشغيل النموذج و قياس تدفق الرسائل (webhooks، قائمة الانتظار، حالة الجلسة). لا تحل محل السجلات؛ فهي موجودة لتغذية المقاييس والتتبعات والمصدرين الآخرين.

يتم إصدار أحداث التشخيص في العملية، لكن المصدرين يرتبطون فقط عندما يتم تمكين التشخيصات + إضافة المصدر.

OpenTelemetry مقابل OTLP

  • OpenTelemetry (OTel): نموذج البيانات + SDKs للتتبعات والمقاييس والسجلات.
  • OTLP: بروتوكول السلك المستخدم لتصدير بيانات OTel إلى جامع/خلفية.
  • يصدر Mayros عبر OTLP/HTTP (protobuf) اليوم.

الإشارات المُصدّرة

  • المقاييس: العدادات + الرسوم البيانية (استخدام الرموز، تدفق الرسائل، قائمة الانتظار).
  • التتبعات: نطاقات لاستخدام النموذج + معالجة webhook/الرسائل.
  • السجلات: مُصدّرة عبر OTLP عند تمكين diagnostics.otel.logs. حجم السجل يمكن أن يكون مرتفعًا؛ ضع في اعتبارك logging.level ومرشحات المصدر.

كتالوج أحداث التشخيص

استخدام النموذج:

  • model.usage: الرموز، التكلفة، المدة، السياق، الموفر/النموذج/القناة، معرفات الجلسة.

تدفق الرسائل:

  • webhook.received: دخول webhook لكل قناة.
  • webhook.processed: webhook معالج + المدة.
  • webhook.error: أخطاء معالج webhook.
  • message.queued: رسالة مُدرجة في قائمة الانتظار للمعالجة.
  • message.processed: النتيجة + المدة + خطأ اختياري.

قائمة الانتظار + الجلسة:

  • queue.lane.enqueue: إدراج مسار قائمة انتظار الأوامر + العمق.
  • queue.lane.dequeue: إخراج مسار قائمة انتظار الأوامر + وقت الانتظار.
  • session.state: انتقال حالة الجلسة + السبب.
  • session.stuck: تحذير الجلسة العالقة + العمر.
  • run.attempt: بيانات تعريفية لإعادة المحاولة/المحاولة.
  • diagnostic.heartbeat: عدادات إجمالية (webhooks/queue/session).

تمكين التشخيصات (بدون مصدر)

استخدم هذا إذا كنت تريد أحداث التشخيص متاحة للإضافات أو المصارف المخصصة:

json
{
  "diagnostics": {
    "enabled": true
  }
}

أعلام التشخيص (سجلات مستهدفة)

استخدم الأعلام لتشغيل سجلات تصحيح إضافية ومستهدفة دون رفع logging.level. الأعلام غير حساسة لحالة الأحرف وتدعم أحرف البدل (مثل telegram.* أو *).

json
{
  "diagnostics": {
    "flags": ["telegram.http"]
  }
}

تجاوز Env (لمرة واحدة):

MAYROS_DIAGNOSTICS=telegram.http,telegram.payload

ملاحظات:

  • تذهب سجلات العلم إلى ملف السجل القياسي (نفس logging.file).
  • المخرجات لا تزال محذوفة وفقًا لـ logging.redactSensitive.
  • الدليل الكامل: /diagnostics/flags.

التصدير إلى OpenTelemetry

يمكن تصدير التشخيصات عبر إضافة diagnostics-otel (OTLP/HTTP). هذا يعمل مع أي جامع/خلفية OpenTelemetry تقبل OTLP/HTTP.

json
{
  "plugins": {
    "allow": ["diagnostics-otel"],
    "entries": {
      "diagnostics-otel": {
        "enabled": true
      }
    }
  },
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "http://otel-collector:4318",
      "protocol": "http/protobuf",
      "serviceName": "mayros-gateway",
      "traces": true,
      "metrics": true,
      "logs": true,
      "sampleRate": 0.2,
      "flushIntervalMs": 60000
    }
  }
}

ملاحظات:

  • يمكنك أيضًا تمكين الإضافة باستخدام mayros plugins enable diagnostics-otel.
  • protocol يدعم حاليًا http/protobuf فقط. يتم تجاهل grpc.
  • تتضمن المقاييس استخدام الرموز، التكلفة، حجم السياق، مدة التشغيل، وعدادات/رسوم بيانية تدفق الرسائل (webhooks، قائمة الانتظار، حالة الجلسة، عمق قائمة الانتظار/الانتظار).
  • يمكن تبديل التتبعات/المقاييس باستخدام traces / metrics (افتراضي: تشغيل). التتبعات تتضمن نطاقات استخدام النموذج بالإضافة إلى نطاقات معالجة webhook/الرسائل عند التمكين.
  • قم بتعيين headers عندما يتطلب جامعك المصادقة.
  • متغيرات البيئة المدعومة: OTEL_EXPORTER_OTLP_ENDPOINT، OTEL_SERVICE_NAME، OTEL_EXPORTER_OTLP_PROTOCOL.

المقاييس المُصدّرة (الأسماء + الأنواع)

استخدام النموذج:

  • mayros.tokens (عداد، attrs: mayros.token، mayros.channel، mayros.provider، mayros.model)
  • mayros.cost.usd (عداد، attrs: mayros.channel، mayros.provider، mayros.model)
  • mayros.run.duration_ms (رسم بياني، attrs: mayros.channel، mayros.provider، mayros.model)
  • mayros.context.tokens (رسم بياني، attrs: mayros.context، mayros.channel، mayros.provider، mayros.model)

تدفق الرسائل:

  • mayros.webhook.received (عداد، attrs: mayros.channel، mayros.webhook)
  • mayros.webhook.error (عداد، attrs: mayros.channel، mayros.webhook)
  • mayros.webhook.duration_ms (رسم بياني، attrs: mayros.channel، mayros.webhook)
  • mayros.message.queued (عداد، attrs: mayros.channel، mayros.source)
  • mayros.message.processed (عداد، attrs: mayros.channel، mayros.outcome)
  • mayros.message.duration_ms (رسم بياني، attrs: mayros.channel، mayros.outcome)

قوائم الانتظار + الجلسات:

  • mayros.queue.lane.enqueue (عداد، attrs: mayros.lane)
  • mayros.queue.lane.dequeue (عداد، attrs: mayros.lane)
  • mayros.queue.depth (رسم بياني، attrs: mayros.lane أو mayros.channel=heartbeat)
  • mayros.queue.wait_ms (رسم بياني، attrs: mayros.lane)
  • mayros.session.state (عداد، attrs: mayros.state، mayros.reason)
  • mayros.session.stuck (عداد، attrs: mayros.state)
  • mayros.session.stuck_age_ms (رسم بياني، attrs: mayros.state)
  • mayros.run.attempt (عداد، attrs: mayros.attempt)

النطاقات المُصدّرة (الأسماء + السمات الرئيسية)

  • mayros.model.usage
    • mayros.channel، mayros.provider، mayros.model
    • mayros.sessionKey، mayros.sessionId
    • mayros.tokens.* (input/output/cache_read/cache_write/total)
  • mayros.webhook.processed
    • mayros.channel، mayros.webhook، mayros.chatId
  • mayros.webhook.error
    • mayros.channel، mayros.webhook، mayros.chatId، mayros.error
  • mayros.message.processed
    • mayros.channel، mayros.outcome، mayros.chatId، mayros.messageId، mayros.sessionKey، mayros.sessionId، mayros.reason
  • mayros.session.stuck
    • mayros.state، mayros.ageMs، mayros.queueDepth، mayros.sessionKey، mayros.sessionId

العينات + التنظيف

  • عينات التتبع: diagnostics.otel.sampleRate (0.0–1.0، نطاقات الجذر فقط).
  • فاصل تصدير المقاييس: diagnostics.otel.flushIntervalMs (دقيقة 1000ms).

ملاحظات البروتوكول

  • يمكن تعيين نقاط نهاية OTLP/HTTP عبر diagnostics.otel.endpoint أو OTEL_EXPORTER_OTLP_ENDPOINT.
  • إذا كانت نقطة النهاية تحتوي بالفعل على /v1/traces أو /v1/metrics، يتم استخدامها كما هي.
  • إذا كانت نقطة النهاية تحتوي بالفعل على /v1/logs، يتم استخدامها كما هي للسجلات.
  • diagnostics.otel.logs يمكّن تصدير سجل OTLP لمخرجات المسجل الرئيسي.

سلوك تصدير السجل

  • تستخدم سجلات OTLP نفس السجلات المنظمة المكتوبة إلى logging.file.
  • احترام logging.level (مستوى سجل الملف). حذف وحدة التحكم لا ينطبق على سجلات OTLP.
  • يجب أن تفضل التثبيتات عالية الحجم أخذ عينات/تصفية جامع OTLP.

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

  • Gateway غير قابل للوصول؟ قم بتشغيل mayros doctor أولاً.
  • السجلات فارغة؟ تحقق من أن Gateway يعمل ويكتب إلى مسار الملف في logging.file.
  • هل تحتاج إلى مزيد من التفاصيل؟ قم بتعيين logging.level إلى debug أو trace وأعد المحاولة.