اتفاقيات OpenTelemetry الدلالية (semantic conventions) تحدد أسماء السمات والامتدادات (spans) والمقاييس ووحداتها: http.request.method وserver.address وhttp.server.request.duration. لكل اسم مستوى استقرار، وهذا المستوى هو ما يقرر هل ستصمد لوحاتك وتنبيهاتك أمام التحديث القادم لأي SDK.
يشرح هذا المقال المستويات (development وstable وdeprecated)، وما تعد به المواصفة وما تمنعه، ثم كيفية الترحيل دون كسر استعلاماتك عبر المتغير OTEL_SEMCONV_STABILITY_OPT_IN. ينطبق على أي واجهة خلفية تدعم OpenTelemetry، ومنها Dynatrace SaaS وDynatrace Managed: يتم الترحيل في الأدوات المُدمجة (instrumentation) وفي Collector، قبل وصول البيانات.
باختصار
- تبدأ السمة أو المقياس في مستوى development: ما زال اسمها قابلاً للتغيير.
- بعد أن تصبح stable، يجب أن يمر أي تغيير في الاسم بمرحلة يتعايش فيها الاسم القديم والجديد.
- اتفاقيات HTTP مستقرة: استُبدلت الأسماء القديمة (
http.methodوhttp.status_code). - يُتحكم في الانتقال عبر
OTEL_SEMCONV_STABILITY_OPT_IN: القيمةhttp/dupتصدر المجموعتين، والقيمةhttpتصدر الجديدة فقط.
اتفاقيات OpenTelemetry الدلالية: ما الذي يغطيه الاستقرار
وفق صفحة Versioning and stability من المواصفة، يشمل استقرار الاتفاقيات الدلالية مفاتيح السمات، وأسماء الامتدادات وأنواعها، وأسماء المقاييس وأنواعها ووحداتها، ومفاتيح سمات السجلات. أما قيم السمات فلا تُغطى عمومًا، باستثناء قوائم القيم المعروفة التي يمكن إضافة قيم جديدة إليها.
النتيجة ملموسة لفريق SRE. فالتنبيه على http.server.duration أو الفلتر على http.status_code يعتمدان على هذه الأسماء بالضبط. وإذا غيّرت الأداة المُدمجة الاسم، تختفي السلسلة أو الحقل من استعلاماتك دون أي خطأ ظاهر: يصبح الرسم البياني فارغًا ببساطة.
مستويات الاستقرار واحدًا واحدًا
تسرد صفحة Semantic convention groups مستويات المجموعة: development وalpha وbeta وrelease_candidate وstable. تكون المجموعة في development افتراضيًا. ولا يمكن لمجموعة مستقرة أن تغيّر مستواها.
Development
بحسب المواصفة، قد تحدث تغييرات كاسرة، ولا ينبغي بناء اعتماد طويل الأمد. كان هذا المستوى يُسمى سابقًا «Experimental». إذا بنيت لوحة على سمة في مستوى development، فخطّط لإعادة كتابتها.
Stable
الإشارة المستقرة تسمح باعتماد طويل الأمد. تحدّ المواصفة من التغييرات المسموحة: إضافة سمات إلى اتفاقية قائمة مسموحة دائمًا، ولا تُقبل إعادة التسمية إلا إذا أمكن وصفها بملف مخطط (schema). وتضيف أن هناك تعليقًا مؤقتًا على استخدام تحويلات المخطط لأجل استقرار القياس عن بُعد. ضمان آخر: سمات المورد service.* يجب ألا تتغير أبدًا.
Deprecated
لا يمكن إهمال إشارة إلا إذا كان بديلها مستقرًا. ولا تُحذف المجموعات أبدًا: يبقى الاسم القديم موثقًا، ما يساعد على قراءة شيفرة الأدوات المُدمجة القديمة.
مستقر وغير مستقر في المجموعة نفسها
يمكن لمجموعة مستقرة أن تضيف سمات غير مستقرة بشرط أن تكون opt_in، لكن لا يمكنها سحب سمات مستقرة. وبالمثل، يجب ألا تصدر أداة مُدمجة مستقرة قياسًا عن بُعد غير مستقر افتراضيًا، وإن كان بإمكانها عرضه كخيار.
مثال HTTP: ما الذي تغيّر اسمه
يسرد دليل ترحيل HTTP في المواصفة عمليات إعادة التسمية. وتشير صفحة HTTP spans إلى أن اتفاقيات امتدادات HTTP للعميل وللخادم موسومة Stable، بينما تبقى التوصيات المتعلقة بحالة الامتداد في Development.

تتغير المقاييس أيضًا: وفق الدليل نفسه، يصبح http.server.duration هو http.server.request.duration، وتنتقل الوحدة من الميلي ثانية إلى الثانية. لذلك يصبح حد تنبيه مكتوب بالميلي ثانية خاطئًا بمعامل 1000 إذا لم تصححه. وتتطور أسماء الامتدادات أيضًا: ينتقل امتداد الخادم الذي له مسار من {http.route} إلى {summary} {http.route}.
الترحيل دون كسر: OTEL_SEMCONV_STABILITY_OPT_IN
تنص المواصفة على متغير بيئة للانتقال من اتفاقية تجريبية إلى أول نسخة مستقرة منها. تُوصف ثلاثة سلوكيات:
http: يصدر الاتفاقيات المستقرة ويتوقف عن إصدار القديمة؛http/dup: يصدر المجموعتين، لنشر تدريجي؛- غياب المتغير: تواصل الأداة المُدمجة إصدار الاتفاقيات القديمة.

توضيح مهم: تشير صفحة HTTP spans إلى أن http/dup تتقدم على http إذا وُجدت القيمتان معًا. كما يجب على مؤلفي الأدوات المُدمجة الاستمرار في صيانة الإصدار الرئيسي القديم، على الأقل بإصلاحات أمنية، لمدة ستة أشهر على الأقل بعد بدء إصدار المجموعتين. لا يخص هذا المتغير إلا الأدوات المُدمجة التي كانت تصدر أصلًا اتفاقيات HTTP تجريبية: الأداة الحديثة لا تحتاج إليه.
خطة ترحيل في خمس خطوات
- الجرد. أحصِ السمات والمقاييس المستخدمة في لوحاتك وتنبيهاتك وأهداف SLO وقواعد التوجيه. ابحث عن الأسماء القديمة:
http.methodوhttp.status_codeوhttp.urlوnet.peer.name. - الإصدار المزدوج. اضبط
OTEL_SEMCONV_STABILITY_OPT_IN=http/dupعلى خدمة تجريبية. تصل المجموعتان من السمات ولا ينكسر شيء. - إعادة كتابة الاستعلامات. انقل لوحاتك وتنبيهاتك إلى الأسماء الجديدة، مع تصحيح وحدة المدد (الثواني).
- التحويل. استبدل
http/dupبالقيمةhttpعندما لا يعود أي استعلام يستخدم الأسماء القديمة. - المراقبة. تحقق من أن حركة المرور لكل خدمة ومعدلات الأخطاء لم تنخفض بعد التحويل.
للخدمات التي لا يمكنك ترحيلها فورًا، يمكن لـ Collector إعادة التسمية أثناء المرور. يشغّل معالج transform في مستودع opentelemetry-collector-contrib تعليمات OTTL؛ يقوم المثال التالي بنسخ سمة ثم حذفها. صيغة المسارات (span.attributes) تطابق الوثائق الحالية للمعالج: كيّفها مع إصدار Collector لديك.

processors:
transform/semconv:
error_mode: ignore
trace_statements:
- context: span
statements:
- set(span.attributes["http.request.method"], span.attributes["http.method"]) where span.attributes["http.method"] != nil
- delete_key(span.attributes, "http.method")
تعالج هذه الرقعة الاسم لا الوحدة ولا أسماء المقاييس: تبقى جسرًا مؤقتًا. للإعداد العام لسمات المورد، راجع المقال عن سمات OpenTelemetry في Dynatrace.
ماذا يتغير بالنسبة لمنصتك
ضع الترحيل في المشروع نفسه الذي تختار فيه إصدارات SDK: قد تغيّر ترقية الإصدار الأسماء إذا لم يكن المتغير مضبوطًا. وفي سلسلة تتضمن Collector، تُعد إعدادات Collector على Kubernetes المكان الطبيعي لتركيز التحويلات وتجنب تكرارها في كل خدمة. وإذا كنت تستخدم أخذ العينات، فتحقق من أن قواعد tail sampling لا تفلتر على اسم سمة قديم. وللأساس المفاهيمي، راجع OpenTelemetry وPrometheus.
من جهة Dynatrace، لا يُؤكد هنا شيء تلقائي: تحقق في وثائق منصتك (Managed أو SaaS) من السمات التي تستخدمها عروضك وقواعدك، ثم اختبر بالإصدار المزدوج قبل أي تحويل.
ممارسات جيدة
- اضبط متغير الاستقرار صراحةً في ملفات النشر لديك بدل الاعتماد على الافتراضي في SDK.
- عامل كل سمة في مستوى development على أنها مؤقتة: اعزلها في طبقة استعلامات واحدة.
- احتفظ بقائمة مُدارة بالإصدارات لأسماء السمات التي تستخدمها تنبيهاتك.
- اختبر حدود المدد بعد كل تغيير في الوحدة.
الأسئلة الشائعة
ماذا تعني «stable» بالنسبة لاتفاقية دلالية؟
يصبح الاعتماد طويل الأمد ممكنًا. لا تسمح المواصفة بعد ذلك إلا بإضافة السمات وعمليات إعادة التسمية الموصوفة بمخطط، ولا تغيّر المجموعات المستقرة مستواها.
هل يجب تفعيل OTEL_SEMCONV_STABILITY_OPT_IN؟
فقط إذا كانت أداتك المُدمجة تصدر اتفاقيات HTTP تجريبية وتريد الانتقال إلى المستقرة. استخدم http/dup للترحيل دون انقطاع، ثم http.
هل يمكن أن تتغير السمات service.*؟
لا: تنص المواصفة على أن سمات المورد service.* يجب ألا تتغير أبدًا.
الخلاصة
تبيّن مستويات الاستقرار أي الأسماء آمنة. أحصِ، وضاعف الإصدار، وأعد كتابة الاستعلامات، ثم حوّل: يبقى الترحيل عملًا اعتياديًا للمنصة، لا حالة طوارئ.
span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC ولا للمشاريع المذكورة. Dynatrace علامة تجارية لشركة Dynatrace LLC. العلامات المذكورة تعود إلى مالكيها. المعلومات مأخوذة من الوثائق الرسمية لـ OpenTelemetry (الإصدار 1.44.0 من الاتفاقيات الدلالية، اطُّلع عليه في 31 أكتوبر 2026)؛ تحقق منها لإصدارك.