# التسجيل (Logging) 

بُنيت واجهة التسجيل في Vapor فوق [SwiftLog](https://github.com/apple/swift-log). هذا يعني أن Vapor متوافق مع جميع [تنفيذات الواجهة الخلفية](https://github.com/apple/swift-log#backends) الخاصة بـ SwiftLog.

## المُسجِّل (Logger)

تُستخدم نُسخ `Logger` لإخراج رسائل التسجيل. يوفر Vapor بضع طرق سهلة للوصول إلى مُسجِّل.

### الطلب (Request)

لكل `Request` وارد مُسجِّل فريد ينبغي لك استخدامه لأي سجلات خاصة بذلك الطلب.

```swift
app.get("hello") { req -> String in
    req.logger.info("Hello, logs!")
    return "Hello, world!"
}
```

يتضمن مُسجِّل الطلب مُعرِّف UUID فريدًا يحدد الطلب الوارد لتسهيل تتبُّع السجلات.

```
[ INFO ] Hello, logs! [request-id: C637065A-8CB0-4502-91DC-9B8615C5D315] (App/routes.swift:10)
```

!!! info "معلومة"
    ستُعرض بيانات المُسجِّل الوصفية (metadata) فقط عند مستوى تسجيل التصحيح (debug) أو أقل.

### التطبيق (Application)

لرسائل التسجيل أثناء إقلاع التطبيق وتهيئته، استخدم مُسجِّل `Application`.

```swift
app.logger.info("Setting up migrations...")
app.migrations.use(...)
```

### مُسجِّل مخصص

في المواقف التي لا يمكنك فيها الوصول إلى `Application` أو `Request`، يمكنك تهيئة `Logger` جديد.

```swift
let logger = Logger(label: "dev.logger.my")
logger.info(...)
```

بينما ستظل المُسجِّلات المخصصة تُخرِج إلى الواجهة الخلفية للتسجيل التي هيّأتها، فلن تكون لها بيانات وصفية مهمة مرفقة مثل UUID الطلب. استخدم المُسجِّلات الخاصة بالطلب أو التطبيق حيثما أمكن.

## المستوى (Level)

يدعم SwiftLog عدة مستويات تسجيل مختلفة.

|الاسم|الوصف|
|-|-|
|trace|مناسب للرسائل التي تحتوي على معلومات تكون مفيدة عادةً فقط عند تتبُّع تنفيذ برنامج ما.|
|debug|مناسب للرسائل التي تحتوي على معلومات تكون مفيدة عادةً فقط عند تصحيح برنامج ما.|
|info|مناسب للرسائل المعلوماتية.|
|notice|مناسب للحالات التي ليست حالات خطأ، لكنها قد تتطلب معالجة خاصة.|
|warning|مناسب للرسائل التي ليست حالات خطأ، لكنها أكثر خطورة من notice.|
|error|مناسب لحالات الخطأ.|
|critical|مناسب لحالات الخطأ الحرجة التي تتطلب عادةً اهتمامًا فوريًا.|

عند تسجيل رسالة `critical`، تكون الواجهة الخلفية للتسجيل حرة في تنفيذ عمليات أثقل لالتقاط حالة النظام (مثل التقاط تتبُّعات المكدس) لتسهيل التصحيح.

افتراضيًا، سيستخدم Vapor مستوى تسجيل `info`. عند التشغيل في بيئة `production`، سيُستخدم `notice` لتحسين الأداء.

### تغيير مستوى التسجيل

بغض النظر عن وضع البيئة، يمكنك تجاوز مستوى التسجيل لزيادة أو تقليل كمية السجلات المُنتجة.

الطريقة الأولى هي تمرير الراية الاختيارية `--log` عند إقلاع تطبيقك.

```sh
swift run App serve --log debug
```

الطريقة الثانية هي تعيين متغير البيئة `LOG_LEVEL`.

```sh
export LOG_LEVEL=debug
swift run App serve
```

يمكن تنفيذ كلتيهما في Xcode عن طريق تحرير مخطط (scheme) `App`.

## التهيئة (Configuration)

يُهيَّأ SwiftLog عن طريق تمهيد (bootstrapping) الـ `LoggingSystem` مرة واحدة لكل عملية. عادةً ما تقوم مشاريع Vapor بذلك في `entrypoint.swift`.

```swift
var env = try Environment.detect()
try LoggingSystem.bootstrap(from: &env)
```

`bootstrap(from:)` هي دالة مساعدة يوفرها Vapor وستهيّئ معالج التسجيل الافتراضي بناءً على معاملات سطر الأوامر ومتغيرات البيئة. يدعم معالج التسجيل الافتراضي إخراج الرسائل إلى الطرفية مع دعم ألوان ANSI.

### معالج مخصص

يمكنك تجاوز معالج التسجيل الافتراضي في Vapor وتسجيل معالجك الخاص.

```swift
import Logging

LoggingSystem.bootstrap { label in
    StreamLogHandler.standardOutput(label: label)
}
```

ستعمل جميع الواجهات الخلفية المدعومة من SwiftLog مع Vapor. غير أن تغيير مستوى التسجيل باستخدام معاملات سطر الأوامر ومتغيرات البيئة متوافق فقط مع معالج التسجيل الافتراضي في Vapor.