swift log
Swift Log 1.6.1
الأشياء الأولى أولاً: هذه هي بداية مشروع مفتوح المصدر يقوده المجتمع ويسعى بنشاط إلى الحصول على مساهمات، سواء كانت تعليمات برمجية أو وثائق أو أفكار. بصرف النظر عن المساهمة في SwiftLog نفسها، هناك فجوة كبيرة أخرى في الوقت الحالي: SwiftLog عبارة عن حزمة API تحاول إنشاء واجهة برمجة تطبيقات مشتركة يمكن للنظام البيئي استخدامها. لجعل التسجيل يعمل حقًا مع أعباء العمل في العالم الحقيقي، نحتاج إلى واجهات خلفية للتسجيل متوافقة مع SwiftLog والتي إما أن تستمر في الاحتفاظ برسائل السجل في الملفات، أو عرضها بألوان أجمل على الجهاز، أو إرسالها إلى Splunk أو ELK.
ما يقدمه SwiftLog اليوم يمكن العثور عليه في مستندات API.
إذا كان لديك تطبيق Swift من جانب الخادم، أو ربما تطبيق/مكتبة مشتركة بين الأنظمة الأساسية (على سبيل المثال Linux وmacOS)، وترغب في التسجيل، فإننا نعتقد أن استهداف حزمة واجهة برمجة التطبيقات للتسجيل هذه يعد فكرة رائعة. ستجد أدناه كل ما تحتاج إلى معرفته للبدء.
تم تصميم SwiftLog لـ Swift 5.8 والإصدارات الأحدث. للاعتماد على حزمة واجهة برمجة التطبيقات للتسجيل، يتعين عليك الإعلان عن تبعيتك في Package.swift الخاص بك:
. package ( url : " https://github.com/apple/swift-log.git " , from : " 1.0.0 " ) , وإلى هدف التطبيق/المكتبة، أضف "Logging" إلى dependencies ، على سبيل المثال مثل هذا:
. target ( name : " BestExampleApp " , dependencies : [
. product ( name : " Logging " , package : " swift-log " )
] , // 1) let's import the logging API package
import Logging
// 2) we need to create a logger, the label works similarly to a DispatchQueue label
let logger = Logger ( label : " com.example.BestExampleApp.main " )
// 3) we're now ready to use it
logger . info ( " Hello World! " ) 2019-03-13T15:46:38+0000 info: Hello World!
Logger الافتراضي يوفر SwiftLog تسجيلًا أساسيًا للغاية لوحدة التحكم خارج الصندوق عن طريق StreamLogHandler . من الممكن تبديل الإخراج الافتراضي إلى stderr كما يلي:
LoggingSystem . bootstrap ( StreamLogHandler . standardError ) يعد StreamLogHandler في المقام الأول وسيلة راحة فقط ولا يوفر أي تخصيص جوهري. يجب على مشرفي المكتبات الذين يهدفون إلى إنشاء واجهات خلفية للتسجيل الخاصة بهم من أجل التكامل والاستهلاك تنفيذ بروتوكول LogHandler مباشرةً كما هو منصوص عليه في قسم "حول تنفيذ الواجهة الخلفية للتسجيل".
لمزيد من المعلومات، يرجى مراجعة وثائق API.
يمكنك الاختيار من إحدى الواجهات الخلفية التالية لاستهلاك سجلاتك. إذا كنت مهتمًا بتنفيذ أحد هذه الإجراءات، فراجع قسم "اعتبارات التنفيذ" أدناه لشرح كيفية القيام بذلك. قائمة المكتبات المتوافقة مع SwiftLog API:
| مستودع | وصف المعالج |
|---|---|
| كيتورا/هيليوملوجر | خلفية تسجيل مستخدمة على نطاق واسع في نظام Kitura البيئي |
| ianpartridge/swift-log- syslog | الواجهة الخلفية لسجل النظام |
| Adorkable/swift-log- تنسيق وأنبوب | واجهة خلفية تسمح بتخصيص تنسيق الإخراج والوجهة الناتجة |
| كريسالجودي/swift-log- oslog | واجهة OSLog Unified Logging الخلفية للاستخدام على منصات Apple. ملاحظة هامة: نوصي باستخدام os_log مباشرة كما هو موضح هنا. سيكون استخدام os_log من خلال Swift-log باستخدام هذه الواجهة الخلفية أقل كفاءة وسيمنع أيضًا تحديد خصوصية الرسالة. تستخدم الواجهة الخلفية دائمًا %{public}@ كسلسلة تنسيق وتقوم بتحويل جميع استيفاءات السلسلة إلى سلاسل بفارغ الصبر. وهذا له عيبان: 1. سيتم نسخ المكونات الثابتة لاستكمال السلسلة بفارغ الصبر بواسطة نظام التسجيل الموحد، مما سيؤدي إلى فقدان الأداء. 2. يجعل جميع الرسائل عامة، مما يغير سياسة الخصوصية الافتراضية لـ os_log، ولا يسمح بتحديد الخصوصية الدقيقة لأقسام الرسالة. في عمل منفصل مستمر، يتم تحسين واجهات برمجة تطبيقات Swift لـ os_log وجعلها تتماشى بشكل وثيق مع واجهات برمجة تطبيقات Swift-log. المراجع: توحيد مستويات التسجيل، وجعل os_log يقبل استكمالات السلسلة باستخدام تفسير وقت الترجمة. |
| تمويل الدماغ / تسجيل Stackdriver | واجهة خلفية منظمة لتسجيل JSON للاستخدام على Google Cloud Platform مع وكيل تسجيل Stackdriver |
| DnV1eX/GoogleCloudLogging | مكتبة من جانب العميل لتسجيل أحداث التطبيق في Google Cloud عبر REST API v2. |
| مجموعة البخار/وحدة التحكم | مسجل إلى المحطة الحالية أو stdout مع إخراج منمق (ANSI). المسجل الافتراضي لجميع تطبيقات Vapor |
| اختبار Neallester/Swift-log | يوفر الوصول إلى رسائل السجل لاستخدامها في التأكيدات (ضمن أهداف الاختبار) |
| wlisac/swift-log-slack | واجهة خلفية للتسجيل ترسل رسائل سجل مهمة إلى Slack |
| NSHipster/swift-log-github-actions | واجهة خلفية للتسجيل تترجم رسائل التسجيل إلى أوامر سير عمل لإجراءات GitHub. |
| stevapple/swift-log-telegram | واجهة خلفية للتسجيل ترسل رسائل السجل إلى أي دردشة Telegram (مستوحاة من wlisac/swift-log-slack ومتشعبة منها) |
| jagreenwood/swift-log-datadog | واجهة خلفية للتسجيل ترسل رسائل السجل إلى خدمة إدارة سجل Datadog |
| جوجل/SwiftLogFireCloud | واجهة خلفية للتسجيل لتسجيل السلاسل الزمنية والتي تدفع السجلات كملفات ثابتة إلى Firebase Cloud Storage. |
| crspybits/swift-log-file | مسجل ملفات محلي بسيط (باستخدام Foundation FileManager ) |
| سوشيتشوب/جرو | واجهة خلفية للتسجيل تدعم عمليات نقل متعددة (وحدة التحكم، الملف، سجل النظام، وما إلى ذلك) وتتمتع بميزة التنسيق وتدوير سجل الملفات |
| ShivaHuang/swift-log-SwiftyBeaver | واجهة خلفية للتسجيل لطباعة التسجيل الملون إلى وحدة تحكم/ملف Xcode، أو إرسال التسجيل المشفر إلى منصة SwiftyBeaver. |
| أبوديني/سويفت-لوج-إلك | واجهة خلفية للتسجيل تقوم بتنسيق بيانات السجل وتخزينها مؤقتًا وإرسالها إلى Elastic/logstash |
| binaryscraping/swift-log-supabase | واجهة خلفية للتسجيل ترسل إدخالات السجل إلى Supabase. |
| كيليانكو/swift-log-matrix | واجهة خلفية للتسجيل لإرسال السجلات مباشرة إلى غرفة Matrix |
| DiscordBM/DiscordLogger | تنفيذ تسجيل Discord لإرسال سجلاتك إلى قناة Discord بطريقة جيدة المظهر ومع الكثير من خيارات التكوين بما في ذلك القدرة على إرسال عدد قليل فقط من مستويات السجل المهمة مثل warning / error / critical . |
| كاكاوحطاب | إطار عمل تسجيل سريع وبسيط ولكنه قوي ومرن لأنظمة macOS وiOS وtvOS وwatchOS، والذي يتضمن واجهة تسجيل خلفية لـ Swift-Log. |
| rwbutler/swift-log-ecs | خلفية تسجيل لتسجيل الدخول بتنسيق سجل ECS. متوافق مع Vapor ويسمح بتسلسل العديد من LogHandlers. |
| ShipBook/swift-log -shipbook | واجهة التسجيل الخلفية التي ترسل إدخالات السجل إلى Shipbook - يمنحك Shipbook القدرة على جمع سجلات المستخدم والاستثناءات الخاصة بك والبحث فيها وتحليلها عن بعد في السحابة، على أساس كل مستخدم وجلسة. |
| مكتبتك؟ | تواصل معنا! |
سعيد لأنك سألت. نحن نؤمن أنه بالنسبة للنظام البيئي Swift on Server، من الضروري أن يكون لديك واجهة برمجة تطبيقات للتسجيل يمكن لأي شخص اعتمادها حتى تتمكن العديد من المكتبات من أطراف مختلفة من تسجيل الدخول إلى وجهة مشتركة. وبشكل أكثر تحديدًا، يعني هذا أننا نعتقد أن جميع رسائل السجل من جميع المكتبات تنتهي في نفس الملف أو قاعدة البيانات أو مثيل Elastic Stack/Splunk أو أي شيء تختاره.
ومع ذلك، في العالم الحقيقي، هناك الكثير من الآراء حول كيفية تصرف نظام التسجيل بالضبط، وكيف ينبغي تنسيق رسالة السجل، وأين/كيف يجب أن تستمر. نعتقد أنه ليس من الممكن انتظار حزمة تسجيل واحدة لدعم كل ما يحتاجه نشر محدد مع الحفاظ على سهولة الاستخدام والحفاظ على الأداء الجيد. ولهذا السبب قررنا تقليص المشكلة إلى النصف:
توفر هذه الحزمة فقط واجهة برمجة تطبيقات التسجيل نفسها، وبالتالي فإن SwiftLog عبارة عن "حزمة واجهة برمجة تطبيقات التسجيل". يمكن تكوين SwiftLog (باستخدام LoggingSystem.bootstrap ) لاختيار أي تطبيق متوافق للواجهة الخلفية للتسجيل. بهذه الطريقة يمكن للحزم أن تتبنى واجهة برمجة التطبيقات (API) ويمكن للتطبيق اختيار أي تطبيق متوافق للواجهة الخلفية للتسجيل دون الحاجة إلى أي تغييرات من أي من المكتبات.
فقط من أجل الاكتمال: تتضمن حزمة واجهة برمجة التطبيقات هذه في الواقع تنفيذًا خلفيًا للتسجيل مفرط التبسيط وغير قابل للتكوين والذي يكتب ببساطة جميع رسائل السجل إلى stdout . السبب وراء تضمين هذا التطبيق الخلفي للتسجيل المفرط في التبسيط هو تحسين تجربة الاستخدام لأول مرة. لنفترض أنك بدأت مشروعًا وجربت SwiftLog للمرة الأولى، فمن الأفضل كثيرًا أن ترى شيئًا قمت بتسجيله يظهر على stdout بتنسيق مبسط بدلاً من عدم حدوث أي شيء على الإطلاق. بالنسبة لأي تطبيق في العالم الحقيقي، ننصح بتكوين تنفيذ آخر للواجهة الخلفية للتسجيل والذي يسجل النمط الذي تريده.
يتم استخدام Logger لإصدار رسائل السجل، وبالتالي فهو النوع الأكثر أهمية في SwiftLog ، لذا يجب أن يكون استخدامه بسيطًا قدر الإمكان. في أغلب الأحيان، يتم استخدامها لإصدار رسائل السجل في مستوى سجل معين. على سبيل المثال:
// logging an informational message
logger . info ( " Hello World! " )
// ouch, something went wrong
logger . error ( " Houston, we have a problem: ( problem ) " )يتم دعم مستويات السجل التالية:
tracedebuginfonoticewarningerrorcritical يمكن تغيير مستوى السجل لمسجل معين، لكن التغيير سيؤثر فقط على المسجل المحدد الذي قمت بتغييره عليه. يمكنك القول أن Logger هو نوع قيمة فيما يتعلق بمستوى السجل.
بيانات تعريف التسجيل هي بيانات تعريف يمكن إرفاقها بالمسجلين لإضافة معلومات مهمة عند تصحيح أخطاء المشكلة. في الخوادم، المثال المعتاد هو إرفاق طلب UUID بمسجل سيكون موجودًا بعد ذلك في جميع رسائل السجل المسجلة باستخدام هذا المسجل. مثال:
var logger = logger
logger [ metadataKey : " request-uuid " ] = " ( UUID ( ) ) "
logger . info ( " hello world " )سوف طباعة
2019-03-13T18:30:02+0000 info: request-uuid=F8633013-3DD8-481C-9256-B296E43443ED hello world
مع تطبيق الواجهة الخلفية للتسجيل الافتراضي الذي يأتي مع SwiftLog . وغني عن القول أن التنسيق يتم تعريفه بالكامل من خلال الواجهة الخلفية للتسجيل التي تختارها.
LogHandler )ملاحظة: إذا كنت لا ترغب في تنفيذ واجهة خلفية مخصصة للتسجيل، فمن المحتمل ألا يكون كل شيء في هذا القسم ذا صلة كبيرة، لذا لا تتردد في تخطيه.
لكي تصبح واجهة خلفية متوافقة للتسجيل يمكن لجميع مستهلكي SwiftLog استخدامها، يتعين عليك القيام بأمرين: 1) تنفيذ نوع (عادةً ما struct ) ينفذ LogHandler ، وهو بروتوكول مقدم من SwiftLog و2) توجيه SwiftLog لاستخدام تنفيذ الواجهة الخلفية للتسجيل الخاص بك .
إن تنفيذ LogHandler أو الواجهة الخلفية للتسجيل هو أي شيء يتوافق مع البروتوكول التالي
public protocol LogHandler {
func log ( level : Logger . Level , message : Logger . Message , metadata : Logger . Metadata ? , source : String , file : String , function : String , line : UInt )
subscript ( metadataKey _ : String ) -> Logger . Metadata . Value ? { get set }
var metadata : Logger . Metadata { get set }
var logLevel : Logger . Level { get set }
} إن توجيه SwiftLog لاستخدام الواجهة الخلفية للتسجيل الخاصة بك باعتبارها الواجهة التي يجب أن يستخدمها التطبيق بأكمله (بما في ذلك جميع المكتبات) أمر بسيط للغاية:
LoggingSystem . bootstrap ( MyLogHandler . init ) يتحكم LogHandler في معظم أجزاء نظام التسجيل:
LogHandler يتحكم LogHandler في الجزأين الأساسيين لتكوين Logger ، وهما:
logger.logLevel )logger[metadataKey:] و logger.metadata ) ومع ذلك، لكي يعمل النظام، من المهم أن يتعامل LogHandler مع التكوين كأنواع قيمة . هذا يعني أن LogHandler s يجب أن تكون struct ويجب أن يؤثر التغيير في مستوى السجل أو بيانات تعريف التسجيل فقط على LogHandler نفسه الذي تم تغييره عليه.
ومع ذلك، في حالات خاصة، من المقبول أن يوفر LogHandler بعض تجاوزات مستوى السجل العام التي قد تؤثر على جميع LogHandler التي تم إنشاؤها.
LogHandler s لا يتحكم LogHandler في ما إذا كان يجب تسجيل الرسالة أم لا. سوف يقوم Logger باستدعاء وظيفة log الخاصة بـ LogHandler فقط إذا قرر Logger أنه يجب إصدار رسالة سجل في ضوء مستوى السجل الذي تم تكوينه.
يحمل Logger label (غير قابلة للتغيير) وتحمل كل رسالة سجل معلمة source (منذ SwiftLog 1.3.0). تحدد تسمية Logger منشئ Logger . إذا كنت تستخدم التسجيل المنظم عن طريق الحفاظ على البيانات التعريفية عبر وحدات متعددة، فإن label Logger ليست طريقة جيدة لتحديد مصدر رسالة السجل لأنها تحدد منشئ Logger الذي غالبًا ما يتم تمريره بين المكتبات للحفاظ على بيانات التعريف و مثل.
إذا كنت تريد تصفية جميع رسائل السجل الصادرة من نظام فرعي معين، فقم بالتصفية حسب source الذي يكون افتراضيًا هو الوحدة النمطية التي ترسل رسالة السجل.
يرجى مراجعة SECURITY.md للتعرف على عملية أمان SwiftLog.
تم تصميم واجهة برمجة تطبيقات التسجيل هذه مع المساهمين في مجتمع Swift on Server وتمت الموافقة عليها من قبل SSWG (Swift Server Work Group) على "مستوى الحماية" لعملية حضانة SSWG.
