قابلية الرصد / المتقدم: الانحياز والثقة وهندسة الأدلة / الدرس 17
اختبارات عقود القياس وهجراتها
احم معنى الإشارات عبر تغييرات SDK والاتفاقيات والجامع والاستعلامات، باستخدام عينات حتمية وحدود دليل صريحة.
في هذه الصفحة
أهداف الدرس
- اختر تأكيدات تختبر سلوك القياس ذا المعنى.
- افصل توافق المخطط عن التكافؤ الدلالي.
- صمم هجرة مرحلية للمستهلكين.
اختبر المعنى الذي يعتمد عليه المستخدم
يشمل عقد القياس مجموعة الأحداث وحد المشاهدة والوحدات والهوية والسمات المسموحة ومعنى الوقت وسلوك الفشل. ينبغي أن تحمي الاختبارات هذه المعاني، لا أن تلتقط كل حقل عرضي في صورة ثابتة. يعد حدث اكتمال تحديث بعد فشل الثبات انحداراً مهماً، بينما قد لا يكون تغيير ترتيب السمات غير الضار كذلك. أنشئ حالات افتراضية للنجاح والفشل والمهلة والتكرار والغياب والحقول الممنوعة. حدد الطبقة التي تجيب كل ادعاء: يختبر مصنف خالص المعنى، ويحتاج تكامل SDK أو إعداد الجامع دليلاً تنفيذياً مستقلاً. اجعل المتوقع مستقلاً بما يكفي لكشف العيب المقصود.
قد يتجاوز تغير الحقل مجرد الإملاء
تتطور الاتفاقيات الدلالية وحزم الرصد وفق قواعد ثباتها الموثقة. قد يصاحب اسم حقل جديد تغير معنى أو مستوى إلزام أو وحدة. لا تستنتج التوافق من نجاح التحليل أو تسمية مخطط وحدهما. راجع النسخ وملاحظات الإصدار وآليات الهجرة المدعومة فعلياً. عند تعايش التدفقات القديمة والجديدة، يجب ألا يعدها المستهلكون مرتين. يمكن لتحويل صريح حفظ المعنى فقط عندما يتطابق تعريف المصدر والهدف حقاً. يظل التاريخ تابعاً لعقده الأصلي، إلا إذا غيّره تحويل متحقق عند حد قابل للتدقيق.
تحقق صراحة من هجرة وحدة ضيقة
تحول العينة المحلية حقل مللي ثانية افتراضياً إلى ثوانٍ مع الحفاظ على اسم العملية. تفحص قيمة معلومة وترفض مدخلاً يحوي حقلي المدة القديم والجديد معاً، تجنباً لاختيار ملتبس. إنها هجرة قاموس خالصة، وليست مترجم مخططات OpenTelemetry. تحتاج الهجرات الفعلية أيضاً فحوص الناقص والنوع والمدى والهوية والمستهلكين. بيّن هل يغير التحويل التمثيل فقط أم مجموعة القياس أيضاً. لا تثبت دالة تحويل مرتبة التكافؤ إذا كان الحدث القديم يُرصد قبل الثبات والجديد بعده.
def migrate(record):
if "duration_ms" in record and "duration_seconds" in record:
raise ValueError("ambiguous-duration-fields")
return {"operation": record["operation"], "duration_seconds": record["duration_ms"] / 1000}
converted = migrate({"operation": "parcel.store", "duration_ms": 250})
assert converted["duration_seconds"] == 0.25
print(converted["operation"], converted["duration_seconds"])
try:
migrate({"operation": "parcel.store", "duration_ms": 250, "duration_seconds": 0.25})
except ValueError as error:
print(error)
parcel.store 0.25
ambiguous-duration-fields
تدعم الدالة شكلاً قديماً محدداً واحداً فقط. تثبت تحويل العينة وحاجز غموض الحقول، ولا تثبت توافق مخططات SDK أو الجامع.
انقل المنتجين والمستهلكين بقصد
تراجع الخطة التحريرية التعريفين القديم والجديد، وتختبر المستهلكين، وتحد التداخل، وتحفظ افتراضات الرجوع. حدّث اللوحات والتنبيهات وقواعد التسجيل والصادرات والتوثيق معاً حيث تعتمد العقد المتغير. قد يكون نشر المنتج مختلط النسخ بين المثيلات، فاحسب فترة وجود النسختين. لا تزل مسار الاستعلام القديم قبل حصر بياناته ومستهلكيه. التوافق خاصية مختبرة للنسخ والتحويل المختارين، وليس وعداً بأن كل مكون OpenTelemetry أو مخزن يستطيع تحويل كل مخطط تلقائياً.
migration_review: parcel-duration-contract
compare: [population, boundary, unit, identity, stability-status]
fixtures: [known-value, missing-field, ambiguous-fields, forbidden-field]
consumer_updates: [queries, dashboards, alerts, exports]
overlap_policy: explicit-no-double-counting
rollback_limit: preserve-version-and-mapping-evidence
السجل خطة مراجعة، وليس أداة هجرة آلية. لا يغير الرصد أو الجامع أو البيانات المحفوظة أو الاستعلامات.
افصل الأدلة المحلية والتكاملية والتشغيلية
تعمل عينة وحدة معزولة بأمان دون خدمات خارجية، وتقدم دليلاً دقيقاً لقاعدة مدخلاتها ومخرجاتها. قد يتحقق اختبار تكامل من التسلسل أو تفعيل السياق أو صياغة المعالج لنسخ مدعومة. وتحتاج معدلات الإكمال وفرض الاحتفاظ والتعافي والوصول أدلة تشغيلية في بيئة فعلية. افصل الادعاءات واحفظ الفحوص الفاشلة والشروط غير المختبرة. ينفذ الدرس عينة الهجرة الخالصة فقط؛ ولا يثبت SDK أو حزمة اختبار أو يبدأ جامعاً أو يتحقق من استعلام حي. يحمي الاختبار الموثوق العقود المفيدة دون خلق شعور زائف بالاكتمال.
الأخطاء الشائعة وإصلاحها
يسمى نجاح المحلل توافقاً دلالياً.
- لماذا يحدث؟
- اختُبر شكل الحقول فقط.
- كيف تصلحه؟
- قارن المجموعة والحد والوحدات والهوية.
- كيف تتجنب تكراره؟
- أدرج عينات عقد لقيم معلومة ومسارات فشل.
يضاعف التدفقان القديم والجديد الإجمالي.
- لماذا يحدث؟
- لم تُعالج فترة التداخل أثناء النشر.
- كيف تصلحه؟
- حدد مسار عد متوافقاً واحداً وانقل المستهلكين.
- كيف تتجنب تكراره؟
- اختبر فواصل النسخ المختلطة.
تُعلن عينة محلية دليلاً من البداية إلى النهاية.
- لماذا يحدث؟
- أُغفلت حدود الدليل.
- كيف تصلحه؟
- حدد بدقة الشيفرة والمدخلات التي نُفذت.
- كيف تتجنب تكراره؟
- افصل نتائج النموذج والتكامل والتشغيل.
اختبر فهمك
1. يتغير مقياس من محاولات كتابة إلى كتابات مثبتة مع بقاء اسمه. هل هو مجرد تغيير تسمية غير ضار؟
اعرض الحل المشروح
لا. تغيرت المجموعة وحد الاكتمال رغم ثبات الإملاء. أنشئ نسخة للانتقال الدلالي، وحدّث المستهلكين، وتجنب مقارنة التاريخين كما لو كانا يقيسان مجموعة الأحداث نفسها. أضف عينات للثبات الفاشل والمجهول حتى يبقى المعنى الجديد صريحاً.
2. لماذا ترفض عينة الهجرة وجود حقلي المدة القديم والجديد معاً؟
اعرض الحل المشروح
تتجنب العينة عمداً اختيار قيمة بصمت عندما قد تختلف الحقول أو تمثل عقوداً مختلطة. قد تعرّف هجرة فعلية قاعدة أخرى مراجعة، لكن يجب أن يكون الغموض واضحاً. اختبر القاعدة بقيم متعارضة وحقول ناقصة ونسخ منتجين مختلطة، بدلاً من افتراض تكافؤ الحقلين.
أهم ما تعلمته
- يشمل توافق القياس معنى يتجاوز شكل المخطط.
- تحتاج فترات النسخ المختلطة قواعد عد صريحة.
- يجب أن يطابق الادعاء حد ما اختُبر فعلاً.