# التسجيل

تسجّل Queuety كل أحداث المهام ومسارات العمل في جدول قاعدة البيانات `queuety_logs`. لا توجد ملفات سجل. ويمكن الاستعلام عن جميع الإدخالات عبر PHP وAPI وCLI.

## أنواع الأحداث

يتضمن كل إدخال في السجل نوع حدث من التعداد `LogEvent`:

| الحدث | الوصف |
|---|---|
| `started` | بدء تنفيذ المهمة |
| `completed` | اكتمال المهمة بنجاح |
| `failed` | حدث استثناء أثناء محاولة وسيُعاد تنفيذها (تسجّل المحاولة الأخيرة `buried` فقط) |
| `buried` | استنفدت المهمة جميع محاولات إعادة التنفيذ |
| `retried` | جدولة المهمة لإعادة المحاولة |
| `workflow_started` | إرسال سير العمل |
| `workflow_completed` | اكتمال جميع خطوات سير العمل |
| `workflow_failed` | إخفاق خطوة سير العمل نهائيًا |
| `workflow_paused` | إيقاف سير العمل مؤقتًا |
| `workflow_resumed` | استئناف سير العمل |
| `workflow_cancelled` | إلغاء سير العمل |
| `workflow_rewound` | إعادة سير العمل إلى خطوة سابقة |
| `workflow_forked` | تفريع سير العمل إلى سير عمل جديد |
| `workflow_deadline_exceeded` | فوات الموعد النهائي لـ`must_complete_within()` في سير العمل |
| `debug` | رسالة بمستوى التصحيح (عند تفعيل `QUEUETY_DEBUG`) |

## حقول السجل

يحتوي كل إدخال في السجل على:

| الحقل | الوصف |
|---|---|
| `id` | معرّف يتزايد تلقائيًا |
| `event` | سلسلة نوع الحدث |
| `handler` | اسم المعالج أو فئته |
| `job_id` | معرّف المهمة المرتبطة (يقبل قيمة فارغة) |
| `workflow_id` | معرّف سير العمل المرتبط (يقبل قيمة فارغة) |
| `step_index` | فهرس خطوة سير العمل (يقبل قيمة فارغة) |
| `attempt` | رقم المحاولة |
| `duration_ms` | مدة التنفيذ بالمللي ثانية |
| `error_message` | رسالة الخطأ عند الإخفاق |
| `created_at` | الطابع الزمني |

## الاستعلام عن السجلات عبر PHP

```php
$logger = Queuety::logger();

// Logs for a specific job
$logs = $logger->for_job( 42 );

// Logs for a specific workflow
$logs = $logger->for_workflow( 7 );

// Logs for a specific handler
$logs = $logger->for_handler( 'send_email', 50 );

// Logs for a specific event type
$logs = $logger->for_event( \Queuety\Enums\LogEvent::Failed, 50 );

// Logs since a datetime
$logs = $logger->since( new \DateTimeImmutable( '-1 hour' ), 100 );
```

## الاستعلام عن السجلات عبر CLI

```bash
# Recent logs (last 24 hours)
wp queuety log

# Logs for a specific job
wp queuety log --job=42

# Logs for a specific workflow
wp queuety log --workflow=7

# Logs for a handler
wp queuety log --handler=send_email

# Logs for an event type
wp queuety log --event=failed

# Logs since a datetime
wp queuety log --since="2025-01-01 00:00:00"

# Custom limit and format
wp queuety log --limit=100 --format=json
```

## الاحتفاظ بالسجلات

تظل السجلات محفوظة إلى أن تمسحها. يقرأ `QUEUETY_LOG_RETENTION_DAYS` الثابت `Config::log_retention_days()`، لكن لا شيء يستخدمه حتى الآن، لذا فهو لا يمسح أي شيء ([#15](https://github.com/inline0/queuety/issues/15)). كما يتعذر الوصول إلى الأمر الفرعي `wp queuety log purge` ([#11](https://github.com/inline0/queuety/issues/11)).

امسح السجلات من PHP، مثلًا عبر مهمة مجدولة خاصة بك أو باستخدام `wp eval`:

```php
$count = Queuety::logger()->purge( 30 );
```