OTTL OpenTelemetry: تحويل بيانات القياس عن بُعد داخل Collector

OTTL OpenTelemetry: أخفِ سرًّا من السجلات، وأعد تسمية مقياس، وصفِّ الضجيج داخل Collector عبر معالجَي transform وfilter خطوة بخطوة.
OTTL OpenTelemetry : transformer la télémétrie dans le Collector

يظهر رمز تفويض داخل خاصية في أحد السجلات، ويصل مقياس باسم لا يعرفه أحد، وتضخّم فحوصات الصحة (health checks) فاتورة التتبّعات. ثلاث مشكلات لها جواب واحد داخل Collector هو لغة OTTL OpenTelemetry، التي تصحّح بيانات القياس عن بُعد أثناء مرورها وقبل أن تصل إلى الواجهة الخلفية.

ينطلق هذا المقال من ثلاثة قرارات تشغيلية بدل أن ينطلق من قائمة الدوال: ما الذي يجب إخفاؤه، وما الذي يجب إعادة تسميته، وما الذي يجب التخلص منه؟ وكل جواب يتّسع له بضعة أسطر. وللاطلاع على مكوّنات Collector كاملة، راجع المقال المخصص لمكوّنات Collector contrib؛ أما هنا فنركّز على اللغة نفسها.

الوقائع مأخوذة من صفحة «Transforming telemetry» على opentelemetry.io ومن ملفات README في مستودع opentelemetry-collector-contrib (الحزم pkg/ottl وtransformprocessor وfilterprocessor)، وقد قُرئت في 12 نوفمبر 2026. تجري المعالجة داخل Collector قبل التصدير عبر OTLP، فالمنطق نفسه يصلح مع Dynatrace SaaS وDynatrace Managed وأي واجهة خلفية أخرى.

قراءة تعليمة OTTL في ثلاثين ثانية

تتكوّن تعليمة OTTL من دالة وشرط اختياري. تحوّل الدالة البيانات، أما الشرط الذي يبدأ بـ where فيقرّر هل تُنفَّذ الدالة. ومثال الـ README سطر واحد: set(span.attributes["test"], "pass") where span.attributes["test"] == nil.

الوسيط الأول مسار (path) يشير إلى حقل: span.attributes أو resource.attributes أو log.body أو metric.name. وتدل البادئة على السياق. يعدّد الـ README السياقات التالية: resource وscope وspan وspan event وspan link وmetric وdatapoint وexemplar وlog. ومن المهم أن تعرف أن OTTL لا تتعامل مع التداخل بين الإشارات، فنسخ متن سجل إلى خاصية في span مرفوض.

للدوال عائلتان. المحرّرات (editors) تعدّل البيانات: set وdelete_key وreplace_pattern وkeep_keys وtruncate_all. والمحوّلات (converters) تحسب قيمة وتُكتب بحرف أول كبير: SHA256 وIsMatch وConcat وSubstring وParseJSON. وتُستعمل اللغة في أكثر من موضع: معالج transform ومعالج filter وأخذ العينات المتأخر (tail sampling) وموصّل التوجيه (routing connector).

الإخفاء: أزل السر قبل التصدير

أول ما يُفعل عند حدوث تسرّب هو حذف المفتاح المسؤول ثم تنظيف ما بقي في النص. يستقبل معالج transform قوائم تعليمات لكل إشارة: log_statements وtrace_statements وmetric_statements. وفي إعداد السجلات التالي تُحذف ترويسة، وتُخفى كلمة مرور في المتن، ويُستبدل معرّف بمعرّف مشتق منه.

ملف YAML لمعالج transform يضم أربع تعليمات OTTL: delete_key وreplace_pattern وset مع SHA256 ثم delete_key
  1. تحذف delete_key الخاصية http.request.header.authorization، وهذا مثال الوثائق نفسه.
  2. تستبدل replace_pattern كل تسلسل password=… في المتن بـ password=***. وهي تفترض أن المتن نص؛ فإن كان بنيويًا فاختبرها قبل الاعتماد عليها.
  3. تكتب set مع SHA256 بصمة user.id في خاصية جديدة، بشرط وجود الخاصية.
  4. ثم تحذف تعليمة delete_key الأخيرة القيمة الأصلية.

انتبه إلى معنى كلمة «إخفاء». تتيح بصمة SHA-256 ربط أحداث المستخدم الواحد ببعضها دون رؤية معرّفه. لكن إن كان المعرّف قصيرًا أو متوقعًا، فبوسع أي شخص أن يحسب بصمة كل قيمة محتملة. هذا استدلال عام وليس وعدًا من الوثائق، وفي البيانات الخاضعة للتنظيم يُفضَّل الحذف.

في Dynatrace يوجد كذلك إخفاء عند الاستقبال بدوال خاصة بالمنصة، شُرح في المقال المخصص للإخفاء في OpenPipeline. ولا يُخلط بين النهجين: الأول يعمل داخل Collector، والثاني بعد وصول البيانات.

تغيير الأسماء: وحّد التسمية مع اتفاقياتك

الغاية من تغيير الأسماء أن تحمل البيانات نفسها الاسم نفسه في كل مكان، مثلًا لاحترام الاتفاقيات الدلالية. لا يوجد في المقتطفات المقروءة محرّر مخصص باسم rename، لذا تُجمع خطوتان: نسخ القيمة إلى الاسم الجديد ثم حذف القديم. أما اسم المقياس فتعمل عليه replace_pattern مباشرة عبر metric.name.

ملف YAML لمعالج transform يعيد تسمية المقاييس من kube_ إلى k8s. وينقل خاصية span باستخدام set ثم delete_key

التعليمة الأولى من الـ README، وتحوّل kube_pod_… إلى k8s.pod…. لاحظ $$1. ففي ملف إعداد Collector تُستخدم علامة الدولار لتوسيع المتغيرات، ولذلك تُضاعف للحصول على مجموعة التقاط. وبدون ذلك يُفسَّر المرجع قبل أن يبلغ OTTL.

أما الزوج الثاني فينقل الخاصية route إلى http.route. والترتيب مهم: يجب أن تسبق تعليمة النسخ تعليمة الحذف، وإلا اختفت القيمة قبل نسخها. تُنفَّذ التعليمات بترتيب كتابتها.

وتعرض صفحة opentelemetry.io أيضًا المعالج metricstransform الذي يعيد تسمية المقاييس والوسوم بمطابقة التعابير النمطية. هذا طريق آخر بصياغته الخاصة. اختر أداة واحدة لكل تحويل حتى يعرف القارئ التالي أين يبحث.

التصفية: تخلّص من الضجيج لكن بحذر

يستعمل معالج filter هو أيضًا OTTL، لكن بشروط (conditions) لا بتعليمات. وقاعدة القراءة هنا مخالفة للحدس: إذا تحقق الشرط حُذفت البيانات. وتُجمع الشروط في القائمة الواحدة بـ OR، أي يكفي أن يتحقق واحد منها. ويُسمح داخل الشرط بـ and وor والأقواس.

ملف YAML لمعالج filter فيه شرط على مسار /healthz في الـ spans وشرط على شدة السجلات، يليه خط معالجة السجلات

يستبعد الإعداد أعلاه الـ spans الخاصة بـ /healthz والسجلات التي دون مستوى INFO، ثم يضع المرشّح في خط المعالجة. وينبّه الـ README إلى عدة آثار جانبية:

  • إذا حُذف span أُهملت شروط أحداثه؛
  • إذا حُذفت جميع أحداث span بقي الـ span؛
  • إذا حُذفت جميع نقاط بيانات مقياس حُذف المقياس نفسه؛
  • قد يترك حذف الـ spans spans فرعية أو سجلات يتيمة.

وثمة فارق آخر: يصف الـ README الصيغة الحالية (trace_conditions وlog_conditions وmetric_conditions) ويذكر أن الخيارات القديمة traces.* وmetrics.* وlogs.* مهجورة، بينما لا تزال صفحة opentelemetry.io تعرض الصيغة القديمة. وإن أردت أن تقرّر أي التتبّعات تُحفظ بحسب محتواها الكلي فالمرشّح لا يصلح لذلك، وانظر قواعد tail sampling.

تشغيل OTTL OpenTelemetry في الإنتاج

ثلاثة ضبطات تجنّبك المفاجآت.

  1. اختر error_mode. القيم هي ignore (الافتراضية: يُسجَّل الخطأ وتُنفَّذ التعليمة التالية) وsilent (بلا تسجيل) وpropagate (يرتفع الخطأ وتُهمل الدفعة). وفي الإخفاء يمكن تبرير propagate: فقدان دفعة أهون من تصدير سر. ويمكن لمجموعة تعليمات أن تتجاوز القيمة العامة.
  2. رتّب المعالجات. تُطبَّق بترتيب خط المعالجة. صفِّ أولًا كي لا تحوّل ما سيُحذف، وأخفِ قبل أي تصدير.
  3. فعّل سجل debug لفهم النتيجة. فعند ضبط service.telemetry.logs.level على debug يعرض Collector كل تعليمة وهل تحقق شرطها وحالة السياق بعد التنفيذ.

وللحالات الأعقد، تجمع الصيغة المتقدمة لمعالج transform التعليمات مع context وconditions وerror_mode خاصة بكل مجموعة. أما التعليمات التي تخلط مسارات أو دوال غير متوافقة فتفشل عند التحميل، ويلزم فصلها في مجموعات. ويورد الـ README مثال convert_sum_to_gauge() مع مسار datapoint.

ممارسات جيدة

  • أضف شرط where إلى كل تعليمة كي لا تعالج إلا البيانات المعنية: يوصي الـ README بذلك للأداء، وتحذّر صفحة opentelemetry.io من أن التحويلات المتقدمة قد تُضعف الأداء بوضوح.
  • اختبر على خط معالجة تجريبي مع مُصدِّر debug قبل الإنتاج.
  • احتفظ بقواعد الإخفاء في ملف واحد خاضع للإصدارات ويُراجَع كما يُراجَع الكود.
  • قِس قبل التغيير وبعده: الحجم المُصدَّر وزمن الاستجابة في خط المعالجة وذاكرة Collector. لا يضمن هذا المقال أي رقم.
  • تجنّب الاعتماد على دوال موسومة بأنها تجريبية؛ فإشارات التتبّعات والمقاييس والسجلات مستقرة في الـ README، أما profiles فقيد التطوير.

الأسئلة الشائعة

هل تحلّ OTTL محلّ معالجَي attributes وresource؟

ليس بالضرورة. يغطي هذان المعالجان، المعروضان في opentelemetry.io، الحالات البسيطة (إدراج خاصية أو تحديثها أو حذفها) بإعداد تصريحي. وتصبح OTTL مفيدة متى احتجت إلى شرط أو حساب أو تعبير نمطي. أما الخلط بين الأسلوبين على الحقل نفسه فيعقّد المراجعة.

هل يمكن حذف span بمعالج transform؟

لا تصف المصادر المقروءة دالة حذف في transform؛ فهذا دور معالج filter. ولم أتحقق مما إذا كان إصدار حديث يتيح ذلك بطريقة أخرى، والمرجع هو وثائق إصدارك.

كيف أعرف سبب عدم تطبيق تعليمة ما؟

اضبط مستوى سجل Collector على debug. تظهر كل تعليمة مع نتيجة شرطها. ثم افحص بادئة السياق في المسار: مسار log في خط معالجة للتتبّعات لن يعمل.

الخلاصة

تُختصر OTTL OpenTelemetry في مخطط واحد: دالة ومسار وشرط. أخفِ ما لا يجوز أن يغادر شبكتك، وأعد التسمية لتوحيد اتفاقياتك، وصفِّ الضجيج، واضبط error_mode بحسب المخاطر. المراجع: README حزمة OTTL وصفحة Transforming telemetry.

span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC. Dynatrace علامة تجارية لشركة Dynatrace LLC. الأمثلة وهمية ولم تُنفَّذ داخل Collector، فتحقق دائمًا من القيم (المنافذ والإصدارات والأحجام) في الوثائق الرسمية الخاصة بإصدارك.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
Exemplars Prometheus : relier un pic de latence à sa trace

Prometheus exemplars: اربط ذروة التأخر بالتتبع الخاص بها

Related Posts