Structure the tech specs directory (#836)

Tech spec some subdirectories for different languages

docs/tech-specs/ar/logging-strategy.ar.md

@@ -0,0 +1,358 @@
+---
+layout: default
+title: "استراتيجية تسجيل الأحداث في TrustGraph"
+parent: "Arabic (Beta)"
+---
+
+# استراتيجية تسجيل الأحداث في TrustGraph
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## نظرة عامة
+
+تستخدم TrustGraph الوحدة `logging` المضمنة في Python لجميع عمليات التسجيل، مع تكوين مركزي ودمج اختياري مع Loki لتجميع السجلات. يوفر هذا نهجًا موحدًا ومرنًا لتسجيل الأحداث عبر جميع مكونات النظام.
+
+## التكوين الافتراضي
+
+### مستوى التسجيل
+**المستوى الافتراضي**: `INFO`
+**يمكن تكوينه عبر**: وسيط سطر الأوامر `--log-level`
+**الخيارات**: `DEBUG`، `INFO`، `WARNING`، `ERROR`، `CRITICAL`
+
+### وجهات الإخراج
+1. **وحدة التحكم (stdout)**: مفعل دائمًا - يضمن التوافق مع البيئات الحاويات.
+2. **Loki**: تجميع سجلات مركزي اختياري (مفعل افتراضيًا، ويمكن تعطيله).
+
+## وحدة التسجيل المركزية
+
+تتم إدارة جميع تكوينات التسجيل بواسطة الوحدة `trustgraph.base.logging`، والتي توفر:
+`add_logging_args(parser)` - يضيف وسيطات سطر الأوامر القياسية لتسجيل الأحداث.
+`setup_logging(args)` - يقوم بتكوين التسجيل من الوسائط التي تم تحليلها.
+
+يتم استخدام هذا الوحدة بواسطة جميع المكونات من جانب الخادم:
+الخدمات القائمة على AsyncProcessor
+بوابة API
+خادم MCP
+
+## إرشادات التنفيذ
+
+### 1. تهيئة المسجل
+
+يجب على كل وحدة إنشاء مسجل خاص بها باستخدام وحدة `__name__` الخاصة بالوحدة:
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+```
+
+اسم المسجل يُستخدم تلقائيًا كعلامة في Loki لتصفية البحث.
+
+### 2. تهيئة الخدمة
+
+تتلقى جميع الخدمات من جهة الخادم تلقائيًا تكوين التسجيل من خلال الوحدة المركزية:
+
+```python
+from trustgraph.base import add_logging_args, setup_logging
+import argparse
+
+def main():
+    parser = argparse.ArgumentParser()
+
+    # Add standard logging arguments (includes Loki configuration)
+    add_logging_args(parser)
+
+    # Add your service-specific arguments
+    parser.add_argument('--port', type=int, default=8080)
+
+    args = parser.parse_args()
+    args = vars(args)
+
+    # Setup logging early in startup
+    setup_logging(args)
+
+    # Rest of your service initialization
+    logger = logging.getLogger(__name__)
+    logger.info("Service starting...")
+```
+
+### 3. وسيطات سطر الأوامر
+
+تدعم جميع الخدمات وسيطات التسجيل التالية:
+
+**مستوى التسجيل:**
+```bash
+--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
+```
+
+**تكوين لوكي:**
+```bash
+--loki-enabled              # Enable Loki (default)
+--no-loki-enabled           # Disable Loki
+--loki-url URL              # Loki push URL (default: http://loki:3100/loki/api/v1/push)
+--loki-username USERNAME    # Optional authentication
+--loki-password PASSWORD    # Optional authentication
+```
+
+**أمثلة:**
+```bash
+# Default - INFO level, Loki enabled
+./my-service
+
+# Debug mode, console only
+./my-service --log-level DEBUG --no-loki-enabled
+
+# Custom Loki server with auth
+./my-service --loki-url http://loki.prod:3100/loki/api/v1/push \
+             --loki-username admin --loki-password secret
+```
+
+### 4. متغيرات البيئة
+
+تدعم إعدادات Loki استخدام متغيرات البيئة كبدائل:
+
+```bash
+export LOKI_URL=http://loki.prod:3100/loki/api/v1/push
+export LOKI_USERNAME=admin
+export LOKI_PASSWORD=secret
+```
+
+تتجاوز وسائط سطر الأوامر قيم المتغيرات البيئية.
+
+### 5. أفضل الممارسات في التسجيل.
+
+#### استخدام مستويات التسجيل.
+**DEBUG**: معلومات تفصيلية لتشخيص المشكلات (قيم المتغيرات، دخول/خروج الدالة).
+**INFO**: رسائل معلومات عامة (بدء الخدمة، تحميل التكوين، مراحل المعالجة).
+**WARNING**: رسائل تحذيرية لحالات قد تكون ضارة (ميزات مهملة، أخطاء قابلة للاسترداد).
+**ERROR**: رسائل خطأ للمشاكل الخطيرة (عمليات فاشلة، استثناءات).
+**CRITICAL**: رسائل حرجة لأعطال النظام التي تتطلب اهتمامًا فوريًا.
+
+#### تنسيق الرسالة.
+```python
+# Good - includes context
+logger.info(f"Processing document: {doc_id}, size: {doc_size} bytes")
+logger.error(f"Failed to connect to database: {error}", exc_info=True)
+
+# Avoid - lacks context
+logger.info("Processing document")
+logger.error("Connection failed")
+```
+
+#### اعتبارات الأداء
+```python
+# Use lazy formatting for expensive operations
+logger.debug("Expensive operation result: %s", expensive_function())
+
+# Check log level for very expensive debug operations
+if logger.isEnabledFor(logging.DEBUG):
+    debug_data = compute_expensive_debug_info()
+    logger.debug(f"Debug data: {debug_data}")
+```
+
+### 6. التسجيل المنظم باستخدام لوكي
+
+بالنسبة للبيانات المعقدة، استخدم التسجيل المنظم مع علامات إضافية لـ Loki:
+
+```python
+logger.info("Request processed", extra={
+    'tags': {
+        'request_id': request_id,
+        'user_id': user_id,
+        'status': 'success'
+    }
+})
+```
+
+تصبح هذه العلامات تصنيفات قابلة للبحث في Loki، بالإضافة إلى التصنيفات التلقائية:
+`severity` - مستوى التسجيل (DEBUG، INFO، WARNING، ERROR، CRITICAL)
+`logger` - اسم الوحدة (من `__name__`)
+
+### 7. تسجيل الاستثناءات
+
+قم دائمًا بتضمين تتبعات المكدس للاستثناءات:
+
+```python
+try:
+    process_data()
+except Exception as e:
+    logger.error(f"Failed to process data: {e}", exc_info=True)
+    raise
+```
+
+### 8. اعتبارات التسجيل غير المتزامن
+
+يستخدم نظام التسجيل معالجات غير متزامنة ومخزنة مؤقتًا لـ Loki:
+الإخراج إلى وحدة التحكم متزامن (سريع)
+يتم تخزين إخراج Loki في قائمة انتظار مع مخزن مؤقت مكون من 500 رسالة
+يقوم خيط الخلفية بمعالجة إرسال Loki
+لا يوجد حظر لرمز التطبيق الرئيسي
+
+```python
+import asyncio
+import logging
+
+async def async_operation():
+    logger = logging.getLogger(__name__)
+    # Logging is thread-safe and won't block async operations
+    logger.info(f"Starting async operation in task: {asyncio.current_task().get_name()}")
+```
+
+## التكامل مع Loki
+
+### البنية التحتية
+
+يستخدم نظام التسجيل وظائف `QueueHandler` و `QueueListener` المضمنة في Python للتكامل غير المتزامن مع Loki:
+
+1. **QueueHandler**: يتم وضع السجلات في قائمة انتظار تحتوي على 500 رسالة (غير متزامنة).
+2. **Background Thread**: يرسل QueueListener السجلات إلى Loki بشكل غير متزامن.
+3. **Graceful Degradation**: إذا كان Loki غير متاح، يستمر التسجيل في وحدة التحكم.
+
+### التسميات التلقائية
+
+تتضمن كل سجل يتم إرساله إلى Loki:
+`processor`: هوية المعالج (مثل `config-svc`، `text-completion`، `embeddings`).
+`severity`: مستوى السجل (DEBUG، INFO، إلخ).
+`logger`: اسم الوحدة (مثل `trustgraph.gateway.service`، `trustgraph.agent.react.service`).
+
+### التسميات المخصصة
+
+أضف تسميات مخصصة عبر المعامل `extra`:
+
+```python
+logger.info("User action", extra={
+    'tags': {
+        'user_id': user_id,
+        'action': 'document_upload',
+        'collection': collection_name
+    }
+})
+```
+
+### الاستعلام عن السجلات في Loki
+
+```logql
+# All logs from a specific processor (recommended - matches Prometheus metrics)
+{processor="config-svc"}
+{processor="text-completion"}
+{processor="embeddings"}
+
+# Error logs from a specific processor
+{processor="config-svc", severity="ERROR"}
+
+# Error logs from all processors
+{severity="ERROR"}
+
+# Logs from a specific processor with text filter
+{processor="text-completion"} |= "Processing"
+
+# All logs from API gateway
+{processor="api-gateway"}
+
+# Logs from processors matching pattern
+{processor=~".*-completion"}
+
+# Logs with custom tags
+{processor="api-gateway"} | json | user_id="12345"
+```
+
+### التدهور الأنيق
+
+إذا كان Loki غير متاح أو لم يتم تثبيت `python-logging-loki`:
+يتم طباعة رسالة تحذير على وحدة التحكم.
+يستمر تسجيل الأحداث في وحدة التحكم بشكل طبيعي.
+يستمر التطبيق في العمل.
+لا توجد آلية لإعادة المحاولة لاتصال Loki (الفشل السريع، والتدهور الأنيق).
+
+## الاختبار
+
+أثناء الاختبار، ضع في اعتبارك استخدام تكوين تسجيل مختلف:
+
+```python
+# In test setup
+import logging
+
+# Reduce noise during tests
+logging.getLogger().setLevel(logging.WARNING)
+
+# Or disable Loki for tests
+setup_logging({'log_level': 'WARNING', 'loki_enabled': False})
+```
+
+## التكامل مع نظام المراقبة
+
+### التنسيق القياسي
+جميع السجلات تستخدم تنسيقًا متسقًا:
+```
+2025-01-09 10:30:45,123 - trustgraph.gateway.service - INFO - Request processed
+```
+
+مكونات التنسيق:
+الطابع الزمني (بتنسيق ISO مع أجزاء من الثانية)
+اسم المسجل (مسار الوحدة)
+مستوى التسجيل
+الرسالة
+
+### استعلامات Loki للمراقبة
+
+استعلامات مراقبة شائعة:
+
+```logql
+# Error rate by processor
+rate({severity="ERROR"}[5m]) by (processor)
+
+# Top error-producing processors
+topk(5, count_over_time({severity="ERROR"}[1h]) by (processor))
+
+# Recent errors with processor name
+{severity="ERROR"} | line_format "{{.processor}}: {{.message}}"
+
+# All agent processors
+{processor=~".*agent.*"} |= "exception"
+
+# Specific processor error count
+count_over_time({processor="config-svc", severity="ERROR"}[1h])
+```
+
+## اعتبارات الأمان
+
+**لا تقم أبدًا بتسجيل معلومات حساسة** (كلمات المرور، مفاتيح API، البيانات الشخصية، الرموز)
+**قم بتنظيف مدخلات المستخدم** قبل التسجيل
+**استخدم قيمًا محجوزة** للحقول الحساسة: `user_id=****1234`
+**مصادقة Loki**: استخدم `--loki-username` و `--loki-password` للنشر الآمن
+**نقل آمن**: استخدم HTTPS لعنوان URL الخاص بـ Loki في بيئة الإنتاج: `https://loki.prod:3100/loki/api/v1/push`
+
+## التبعيات
+
+يتطلب وحدة التسجيل المركزية ما يلي:
+`python-logging-loki` - لتكامل Loki (اختياري، مع إمكانية التراجع الآمن في حالة عدم وجوده)
+
+تم تضمينها بالفعل في `trustgraph-base/pyproject.toml` و `requirements.txt`.
+
+## مسار الترحيل
+
+بالنسبة للكود الحالي:
+
+1. **الخدمات التي تستخدم بالفعل AsyncProcessor**: لا توجد تغييرات مطلوبة، دعم Loki تلقائي
+2. **الخدمات التي لا تستخدم AsyncProcessor** (api-gateway, mcp-server): تم تحديثها بالفعل
+3. **أدوات سطر الأوامر (CLI)**: خارج نطاق العمل - استمر في استخدام print() أو التسجيل البسيط
+
+### من print() إلى التسجيل:
+```python
+# Before
+print(f"Processing document {doc_id}")
+
+# After
+logger = logging.getLogger(__name__)
+logger.info(f"Processing document {doc_id}")
+```
+
+## ملخص الإعدادات
+
+| الوسيط | القيمة الافتراضية | متغير البيئة | الوصف |
+|----------|---------|---------------------|-------------|
+| `--log-level` | `INFO` | - | مستوى تسجيل وحدة التحكم و Loki |
+| `--loki-enabled` | `True` | - | تمكين تسجيل Loki |
+| `--loki-url` | `http://loki:3100/loki/api/v1/push` | `LOKI_URL` | نقطة النهاية لدفع البيانات إلى Loki |
+| `--loki-username` | `None` | `LOKI_USERNAME` | اسم المستخدم للمصادقة في Loki |
+| `--loki-password` | `None` | `LOKI_PASSWORD` | كلمة المرور للمصادقة في Loki |