دليل تشغيل شهري لتقرير روابط خلفية

لماذا شهري وليس يومياً

يتم تحديث الرسم البياني لدينا تقريباً مرة واحدة شهرياً. المهمة اليومية تعيد إنتاج نفس الأرقام.

تشغيله بشكل متكرر لا يجعل التقرير أكثر حداثة، بل يجعله أكثر تكلفة في الشرح. القارئ الذي يرى 30 نقطة متطابقة سيفترض أن خط الأنابيب معطل.

اختر يوماً واحداً شهرياً عن قصد، ويفضل أن يكون بعد أسبوع من استقرار التحديث السابق. اكتب التاريخ في اسم الملف، بحيث يكون الجدول نفسه موثقاً.

حدد التقويم أولاً ودع التقرير يتبعه. التقرير الذي يعاد بناؤه كلما فتح شخص ما دفتر الملاحظات لا يحتوي على تاريخ واضح على الإطلاق، وهو أمر يصعب الدفاع عنه في المراجعة.

ما الذي يجب تخزينه بجانب الأرقام

نصف التقرير عبارة عن بيانات وصفية، لذا قم بتخزينه بجانب الأرقام.

اكتب تاريخ السحب، واسم الإجراء، والمعاملات (per، sort، order) وحقل الرصيد من الاستجابة في ملف مساعد صغير بجانب كل لقطة. بعد ستة أشهر، عندما يسأل زميل لماذا يبدو أكتوبر مختلفاً عن سبتمبر، يجيب هذا الملف في عشر ثوانٍ بدلاً من فترة بعد الظهر.

أضف التزام git للبرنامج النصي وإصدارات الحزم من renv. التقرير الذي لا يستطيع القول أي كود وحالة فهرس أنتجا الرسم البياني هو مجرد لقطة شاشة، وليس تحليلاً، بغض النظر عن مدى أناقة شكل tibble.

تخطيط targets الحد الأدنى

ثلاثة أهداف كافية عندما يظل الخطة صغيرة.

يهدف هدف واحد للسحب من واجهة برمجة التطبيقات وكتابة الملف المؤرخ، ويهدف آخر لقراءة الملف وبناء tibble، ويهدف ثالث لإنشاء مستند Quarto. لأن الهدف الأول فقط يتصل بالشبكة، يمكنك إعادة تشغيل الأهداف الأخرى دون اتصال كلما شئت ولن يتغير الرسم البياني بالخطأ.

ثبت إصدارات الحزم باستخدام renv، وسجل معلومات الجلسة في تذييل التقرير، واحتفظ بجدول العتبات من صفحة التقييم الجماعي في المستودع بجانب الكود. بالنسبة للجانب المالي، تخبرك صفحة الميزانية بما يجب أن يكلفه الشهر.

عند فشل شيء ما، اقرأ الكود أولاً. يعني HTTP 401 أن المفتاح خاطئ أو مفقود. يعني HTTP 402 نفاد الرصيد. أي خطأ آخر يستحق التسجيل بالكامل. يغطي التفكيك تلك المراحل، ومثال الدمج هو مهمة أولى جيدة للجدولة.

معرفة أن التشغيل فشل قبل أن يلاحظها زميلك

تقرير روابط خلفية قابل للتكرار يفشل بصمت يخدش أكثر من الذي لم يعمل أبداً. السؤال الحقيقي ليس عما إذا كانت المهمة يمكن أن تفشل، بل مدى سرعة سماع الشخص بذلك.

اجعل المهمة تفشل بصوت عالٍ

تخرج المهمة المجدولة بحالة غير صفرية عند إرجاع المكالكة لخطأ HTTP 401 أو 402، ويحدد الجدول التشغيل كفاشل. هذا هو أرخص تنبيه لديك، ولا يحتاج إلى خدمة إضافية.

السحوبات الجزئية هي الحالة الخطرة. إذا كتب البرنامج النصي ملفه بعد عشرين من ثلاثين قطعة، فإن الملف موجود ويبدو جيداً. اكتب في اسم مؤقت وقم بإعادة تسميته فقط عند النجاح.

أرسل رسالة واحدة لكل فشل

اختر قناة واحدة للفشل، مثل بريد إلكتروني لمالك التقرير أو رسالة في دردشة الفريق. قناتان تعنيان مكانين للنظر فيهما، واحتمال أعلى ألا ينظر أحد إلى أي منهما.

يجب أن تذكر الرسالة الهدف الذي فشل، ورمز الحالة والوقت. كل شيء آخر ينتمي إلى السجل.

تحقق من أن المخرج معقول

يمكن أن ينجح التشغيل ولا يزال خاطئاً. قارن عدد الأسطر مع الشهر الماضي، وحدد انخفاضاً يتجاوز عتبة اخترتها مسبقاً.

يمكن أن يكون الفحص بسيطاً كمدى متوقع. الهدف هو ملاحظة لقطة نصف فارغة قبل أن يصل الرسم البياني إلى العميل.

سمِّ مالكاً واحداً للتقرير

سمِّ مالكاً واحداً للتقرير. التنبيه بدون مالك يقرأه الجميع ولا يتصرف فيه أحد.

ليس على المالك إصلاح المهمة. على المالك أن يقرر ما إذا كان التقرير المتأخر مقبولاً، وأن يقول ذلك في التقرير نفسه.

اكتب اسم المالك في رأس دليل التشغيل، وحدثه عند تغيير المالك. دليل التشغيل الذي يحتوي على مالك سابق هو خطر صامت.

اختيار اليوم وتشغيل المهمة الأولى يدوياً

التوقيت والتشغيل الأول يقرران ما إذا كان الجدول سيستمر. كلاهما سهل الخطأ في الشهر الأول، وكلاهما رخيص الإصلاح.

قراران، مكتوبان مرة واحدة، ينقذان معظم الحجج لاحقاً. الأول هو اليوم. الثاني هو مكان تشغيل المؤقت. كلاهما ينتمي إلى دليل التشغيل، وليس في رأس أي شخص.

اختر يوماً واحداً واكتبه

يوم ثابت في الشهر، مثل أول يوم عمل بعد استقرار التحديث، أسهل في الشرح من تخمين بداية الشهر.

ضع اليوم في ملف الجدول نفسه، بحيث يكون التوقيت جزءاً من الكود وليس ذاكرة في تقويم شخص ما.

شغل المهمة الأولى يدوياً

يجب أن يكون التشغيل المجدول الأول يدوياً. شغل البرنامج النصي بنفسك، اقرأ السجل، قارن الملف بالسابق، ثم فقط سلم المؤقت.

يختبر التشغيل الأول أيضاً متجر الأسرار. المفتاح الذي يعمل على جهازك ولكنه مفقود في CI هو سبب شائع لفشل التشغيل المجدول الأول.

حافظ على صدق الملف المساعد

يسجل الملف المساعد ما فعله التشغيل. إذا كتبه شخص يدوياً، فإنه يبتعد عن التشغيل. اجعل البرنامج النصي يكتبه، ودع الناس يقرؤون فقط.

الملف المساعد الذي لم يلمسه البرنامج النصي هو ملاحظة، وليس سجلاً، ويجب أن يستشهد التقرير بالسجل.

قارن الملف المساعد مع الملف مرة واحدة شهرياً. إذا اختلفت الأرقام في الاثنين، فإن التشغيل فشل بطريقة لم يلاحظها البرنامج النصي.

أين يعيش المؤقت

يفشل المشغل المستضاف وإدخال cron المحلي بطرق مختلفة. يمكن إيقاف المشغل المستضاف بإعداداته الخاصة، ويتوقف إدخال cron المحلي عندما يكون الجهاز في وضع السكون. تحقق مما اخترته، واختبر المؤقت مرة واحدة بجدول زمني قصير قبل الجدول الحقيقي.

مهما اخترت، اكتب المؤقت في المستودع بجانب البرنامج النصي، حتى يعرف الشخص التالي أين تعيش المهمة.