التسجيل المهيكل

التسجيل المهيكل — Structured Logging

التسجيل العادي (fmt.Println أو log.Println) لا يكفي في الإنتاج. تحتاج تسجيلاً مهيكلاً — بيانات مُنظّمة يمكن البحث فيها وتحليلها.

منذ Go 1.21، المكتبة القياسية تحتوي log/slog — تسجيل مهيكل احترافي بدون مكتبات خارجية.

المشكلة مع التسجيل العادي

main.go

package main

import (
    "fmt"
    "log"
    "time"
)

func main() {
    // التسجيل العادي — Regular logging
    log.Println("المستخدم سجّل دخوله")
    log.Printf("خطأ: فشل الاتصال بقاعدة البيانات (محاولة %d)", 3)

    fmt.Println("\n❌ المشاكل:")
    fmt.Println("1. لا مستويات (info vs error)")
    fmt.Println("2. لا بنية — نص حر يصعب تحليله")
    fmt.Println("3. لا بيانات إضافية مُنظّمة")
    fmt.Println("4. لا يعمل مع أدوات المراقبة (Grafana, ELK)")

    fmt.Println("\n✅ الحل: log/slog")
    fmt.Println(`slog.Info("المستخدم سجّل دخوله",
    "user_id", 42,
    "ip", "192.168.1.1",
    "duration_ms", 150,
)`)
    fmt.Println("\n→ يُنتج JSON أو نص مُنظّم يمكن تحليله")
}

Output:

أساسيات slog

main.go

package main

import (
    "log/slog"
    "os"
)

func main() {
    // المُسجّل الافتراضي — Default logger (text format)
    slog.Info("بدء التطبيق", "version", "1.0.0", "env", "production")
    slog.Warn("الذاكرة منخفضة", "available_mb", 128)
    slog.Error("فشل الاتصال", "host", "db.example.com", "error", "connection refused")

    // تنسيق JSON — JSON format
    jsonLogger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
    jsonLogger.Info("طلب HTTP",
        "method", "GET",
        "path", "/api/users",
        "status", 200,
        "duration_ms", 45,
    )
}

Output:

مستويات التسجيل — Log Levels

main.go

package main

import (
    "log/slog"
    "os"
)

func main() {
    // إعداد المستوى الأدنى — Set minimum level
    handler := slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
        Level: slog.LevelInfo, // تجاهل Debug — Ignore Debug
    })
    logger := slog.New(handler)

    logger.Debug("تفاصيل تصحيح", "key", "value")  // ⬜ لن يظهر
    logger.Info("معلومة عامة", "user", "أحمد")       // ✅ يظهر
    logger.Warn("تحذير", "disk_usage", "85%")         // ✅ يظهر
    logger.Error("خطأ!", "err", "timeout")             // ✅ يظهر

    slog.Info("\nالمستويات:", "Debug", -4, "Info", 0, "Warn", 4, "Error", 8)
}

Output:

المجموعات والسمات — Groups & Attributes

main.go

package main

import (
    "log/slog"
    "os"
)

func main() {
    logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))

    // مجموعة — Group
    logger.Info("طلب HTTP",
        slog.Group("request",
            slog.String("method", "POST"),
            slog.String("path", "/api/users"),
            slog.Int("size", 256),
        ),
        slog.Group("response",
            slog.Int("status", 201),
            slog.Int("duration_ms", 89),
        ),
    )

    // مُسجّل فرعي مع سمات ثابتة — Sub-logger with fixed attributes
    reqLogger := logger.With("request_id", "req-abc-123", "user_id", 42)
    reqLogger.Info("بدء المعالجة")
    reqLogger.Info("استعلام قاعدة البيانات", "query", "SELECT *", "rows", 15)
    reqLogger.Info("انتهاء المعالجة")
}

Output:

معرّف الطلب — Request ID / Correlation ID

main.go

package main

import (
    "fmt"
    "math/rand"
    "time"
)

// توليد معرّف طلب — Generate request ID
func generateRequestID() string {
    const chars = "abcdefghijklmnopqrstuvwxyz0123456789"
    b := make([]byte, 8)
    for i := range b {
        b[i] = chars[rand.Intn(len(chars))]
    }
    return fmt.Sprintf("req-%s", string(b))
}

func main() {
    // محاكاة طلبات — Simulate requests
    for i := 0; i < 3; i++ {
        reqID := generateRequestID()
        start := time.Now()

        // كل رسالة تسجيل تحمل نفس المعرّف
        fmt.Printf("[%s] → بدء الطلب\n", reqID)
        time.Sleep(time.Duration(50+rand.Intn(100)) * time.Millisecond)
        fmt.Printf("[%s] → استعلام قاعدة البيانات\n", reqID)
        time.Sleep(time.Duration(20+rand.Intn(50)) * time.Millisecond)
        fmt.Printf("[%s] → انتهى (%v)\n", reqID, time.Since(start).Round(time.Millisecond))
        fmt.Println()
    }

    fmt.Println("💡 المعرّف يسمح بتتبع طلب واحد عبر كل الطبقات")
    fmt.Println("   في أدوات مثل Grafana/Kibana، ابحث بـ request_id")
}

Output:

مُسجّل مخصص للإنتاج

main.go

package main

import (
    "log/slog"
    "os"
)

func main() {
    // إعداد احترافي — Production setup
    var handler slog.Handler

    env := "production"

    if env == "production" {
        // JSON في الإنتاج — JSON in production
        handler = slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
            Level:     slog.LevelInfo,
            AddSource: true, // أضف اسم الملف ورقم السطر
        })
    } else {
        // نص مقروء في التطوير — Human-readable in development
        handler = slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
            Level: slog.LevelDebug,
        })
    }

    logger := slog.New(handler)
    slog.SetDefault(logger) // اجعله الافتراضي — Set as default

    slog.Info("التطبيق بدأ",
        "env", env,
        "port", 8080,
        "version", "2.1.0",
    )

    slog.Error("مثال خطأ",
        "error", "connection timeout",
        "host", "db.example.com",
        "retry_in", "5s",
    )
}

Output:

مقارنة مكتبات التسجيل

المكتبة	المميزات	متى تستخدمها
`log/slog`	مدمجة، مهيكلة، كافية	معظم المشاريع
`zerolog`	سريعة جداً، صفر تخصيص	أداء حرج
`zap`	من Uber، مرنة، سريعة	مشاريع كبيرة

تحدي — Challenge

package main

import (
    "log/slog"
    "os"
)

func main() {
    handler := slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
        Level: slog.LevelInfo,
        ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
            if a.Key == slog.TimeKey {
                return slog.Attr{}
            }
            return a
        },
    })
    logger := slog.New(handler)

    // سجّل رسالة Info مع port و env، ورسالة Error مع host و error
    // اكتب الكود هنا
    _ = logger
}