Serilog لـ C# (.NET): دليل شامل مع أمثلة

مقدمة في Serilog: ما هو ولماذا تحتاجه

Serilog هي مكتبة قوية ومرنة وحديثة لتسجيل السجلات المنظمة (structured logging) في بيئة .NET (C#, F#, VB.NET). على عكس أطر تسجيل السجلات التقليدية (مثل NLog أو log4net) التي تعمل مع رسائل نصية مسطحة، تم تصميم Serilog من البداية للعمل مع البيانات المنظمة.

لماذا تحتاج Serilog؟

\n
• تسجيل منظم: لا تقوم بتسجيل سلسلة نصية فقط، بل كائنات ذات خصائص مسماة. هذا يسمح بتصفية السجلات والبحث فيها وتحليلها بكفاءة في أنظمة مثل Elasticsearch و Seq و Datadog.
\n
• المرونة (المستقبلات - Sinks): يستخدم Serilog مفهوم "المستقبلات" (sinks). يمكنك إرسال السجلات إلى وحدة التحكم، ملف، قاعدة بيانات، خدمات سحابية (Azure, AWS)، Elasticsearch، Telegram، Slack ومئات الأماكن الأخرى - فقط عن طريق إضافة الحزمة المناسبة.
\n
• الأداء: تم تحسين Serilog للتطبيقات عالية التحميل. يستخدم تنسيق السلاسل المؤجل (message templates) لتجنب تخصيص الذاكرة غير الضروري إذا كان مستوى التسجيل غير نشط.
\n
• سهولة الإعداد: التكوين عبر الكود أو ملف JSON. الحد الأدنى من الكود للبدء هو بضعة أسطر فقط.
\n
• التشخيص: يسمح بإضافة معلومات سياقية بسهولة (مثل معرف المستخدم، رقم الطلب، اسم الدالة) إلى كل سجل.
\n

تثبيت Serilog

يتم توزيع Serilog عبر NuGet - مدير الحزم لـ .NET. يتم التثبيت عبر وحدة تحكم مدير الحزم (Package Manager Console) أو .NET CLI.

التثبيت عبر .NET CLI (موصى به):

dotnet add package Serilog\ndotnet add package Serilog.Sinks.Console\ndotnet add package Serilog.Sinks.File\ndotnet add package Serilog.Settings.Configuration\ndotnet add package Serilog.AspNetCore

التثبيت عبر Package Manager Console (Visual Studio):

Install-Package Serilog\nInstall-Package Serilog.Sinks.Console\nInstall-Package Serilog.Sinks.File\nInstall-Package Serilog.Settings.Configuration\nInstall-Package Serilog.AspNetCore

شرح الحزم:

\n
• Serilog - نواة المكتبة.
\n
• Serilog.Sinks.Console - مستقبل للإخراج إلى وحدة التحكم.
\n
• Serilog.Sinks.File - مستقبل للكتابة إلى الملفات.
\n
• Serilog.Settings.Configuration - يسمح بقراءة الإعدادات من appsettings.json.
\n
• Serilog.AspNetCore - التكامل مع ASP.NET Core (يضيف سياق HTTP إلى السجلات).
\n

ملاحظة لقراء PythonLib: في Python، النظير للتثبيت عبر pip هو pip install serilog (لكن Serilog هي مكتبة .NET، أما بالنسبة لـ Python فهناك أدوات خاصة بها، مثل structlog).

بداية سريعة: أول سجل خلال 30 ثانية

قم بإنشاء تطبيق وحدة تحكم .NET وأضف الكود التالي إلى Program.cs:

using Serilog;\n\n// 1. إعداد Serilog\nLog.Logger = new LoggerConfiguration()\n    .MinimumLevel.Debug()\n    .WriteTo.Console()\n    .WriteTo.File("logs/myapp.log", rollingInterval: RollingInterval.Day)\n    .CreateLogger();\n\ntry\n{\n    Log.Information("تم تشغيل التطبيق بنجاح.");\n\n    int userId = 42;\n    string userName = "Alice";\n    Log.Information("المستخدم {UserId} باسم {UserName} قام بتسجيل الدخول.", userId, userName);\n\n    // مثال مع خطأ\n    try\n    {\n        throw new InvalidOperationException("عملية غير صالحة");\n    }\n    catch (Exception ex)\n    {\n        Log.Error(ex, "حدث خطأ أثناء تنفيذ العملية للمستخدم {UserId}", userId);\n    }\n\n    Log.Warning("هذا تحذير. المستوى: {Leve