ثلاث خدمات تحمل الاسم unknown_service:python، وتتبعات يستحيل ربطها بأي pod، وسمات للأعمال غير مرئية في الاستعلامات: معظم خيبات الأمل بعد أول استيعاب OTLP سببها السمات. إن ضبط سمات OpenTelemetry في Dynatrace على الوجه الصحيح، وهي التي يبني عليها كياناته، هو الفارق بين خريطة خدمات مقروءة وكومة من وحدات span اليتيمة.
الهدف: في نهاية هذا الدرس التطبيقي تحمل خدمات OTel لديك سمات المورد (resource attributes) القياسية، ويثريها الـ Collector بسياق Kubernetes والمضيف، وتعرف كيف تتحقق من السمات المخزَّنة فعلًا والقابلة للاستعلام. المحتوى صالح لـ Dynatrace SaaS (Grail وDQL) ولـ Dynatrace Managed. تختلف إدارة سمات span بين الاثنين، ونشير إلى ذلك في الخطوة المعنية.
لمعمارية الـ Collector انظر Collector من OpenTelemetry على Kubernetes.
المشكلة: بيانات بلا هوية
لا يرتبط span الذي يفتقر إلى service.name صحيح بأي خدمة مفيدة. وspan بلا سمات Kubernetes لا يقود إلى الـ pod الذي انهار. أثناء الحادثة يضيع على فريق المناوبة دقائق في تخمين «من» أنتج البيانات، فيتأثر MTTR. تجيب سمات المورد عن هذا السؤال مرة واحدة وإلى الأبد.
المتطلبات
- تطبيقات مقيسة بـ OpenTelemetry SDK (مثل وكيل OpenTelemetry لـ Java).
- Collector من نوع
otelcol-contribأو توزيعة تتضمنk8sattributesوresourcedetectionوresourceوtransform. في الإصدارات الحديثة من Collector contrib يُسمّىk8sattributesوresourcedetectionالآنk8s_attributesوresource_detection؛ وتظل الأسماء القديمة المستخدمة أدناه مقبولة كأسماء مستعارة مُهمَلة (deprecated aliases). - رمز Dynatrace بنطاقات استيعاب OTLP (التتبعات والمقاييس والسجلات).
المورد أم span: مستويان من السمات
- سمات المورد: تصف المُرسِل وتسري على كل بيانات القياس عن بُعد في العملية. أمثلة:
service.nameوservice.versionوdeployment.environmentوk8s.pod.nameوhost.name. - سمات span: تصف عملية بعينها. أمثلة:
http.request.methodوdb.systemوorder.id.
قاعدة بسيطة: ما لا يتغير طوال حياة العملية يوضع في المورد. فتشترك التتبعات والمقاييس والسجلات حينئذ في المفاتيح نفسها، وهذا ما يجعل الربط بينها ممكنًا.
ضبط سمات OpenTelemetry في Dynatrace كما يتوقعها
الخطوة 1: ضبط سمات المورد في التطبيق
# excerpt from a Kubernetes Deployment
env:
- name: OTEL_SERVICE_NAME
value: "checkout"
- name: POD_NAME
valueFrom:
fieldRef:
fieldPath: metadata.name
- name: OTEL_RESOURCE_ATTRIBUTES
value: "service.version=2.3.0,service.namespace=shop,deployment.environment=prod,k8s.pod.name=$(POD_NAME)"
أسطر حاسمة: يتقدم OTEL_SERVICE_NAME على أي service.name موضوع في OTEL_RESOURCE_ATTRIBUTES. وصيغة $(POD_NAME) يحلّها Kubernetes، بشرط أن يكون المتغير معرَّفًا قبلها. ملاحظة: تعيد اصطلاحات الدلالات الحديثة تسمية deployment.environment إلى deployment.environment.name؛ اختر مفتاحًا واحدًا والزمه في كل مكان.
الخطوة 2: الإثراء داخل Collector
يضيف الـ Collector ما يجهله التطبيق: مساحة الأسماء (namespace) والعقدة وحمل العمل (workload) والسحابة.
processors:
k8sattributes:
auth_type: serviceAccount
passthrough: false
extract:
metadata:
- k8s.namespace.name
- k8s.deployment.name
- k8s.pod.name
- k8s.pod.uid
- k8s.node.name
pod_association:
- sources:
- from: resource_attribute
name: k8s.pod.uid
- sources:
- from: connection
resourcedetection:
detectors: [env, system]
timeout: 2s
override: false
resource:
attributes:
- key: k8s.cluster.name
value: "prod-eu-1"
action: upsert
يتطلب k8sattributes حساب خدمة (ServiceAccount) بالصلاحيات get وlist وwatch على الـ pods ومساحات الأسماء وReplicaSets. ويمنع override: false الاكتشاف من الكتابة فوق قيم وضعها التطبيق.
الخطوة 3: إثراء Dynatrace على المضيفات التي يعمل عليها OneAgent
إذا كان OneAgent يعمل على المضيف، فيمكنه توفير ملفات إثراء تحتوي على سمات مثل dt.entity.host، تربط بيانات OTel بالكيانات التي اكتشفها OneAgent. يوصف مسار هذه الملفات وصيغتها في وثائق Dynatrace (القسم المتعلق بإثراء بيانات OpenTelemetry): تحقق منهما لإصدارك بدل ترميزهما في الشيفرة. ومن دون OneAgent يعتمد التعريف حصريًا على سمات الخطوتين 1 و2.
الخطوة 4: تنظيف السمات الحساسة وغير المفيدة
احذف البيانات الشخصية والسمات عالية الكاردينالية (high cardinality) قبل التصدير:
processors:
transform/clean:
error_mode: ignore
trace_statements:
- context: span
statements:
- delete_key(attributes, "user.email")
- replace_pattern(attributes["url.full"], "token=[^&]+", "token=***")
batch: {}
service:
pipelines:
traces:
receivers: [otlp]
processors: [k8sattributes, resourcedetection, resource, transform/clean, batch]
exporters: [otlphttp/dynatrace]
الخطوة 5: فهم قائمة السماح لسمات span
لا يعالج Dynatrace كل سمات span بالطريقة نفسها، بحسب نوع النشر:
- Dynatrace Managed (وSaaS دون تخزين وحدات span في Grail): يجب السماح صراحةً بسمات span المخصصة في إعدادات البيئة (قائمة سمات مسموح بها في قسم مراقبة الخدمات من جهة الخادم؛ والتسمية الدقيقة تتبع الإصدار). السمة غير الموجودة في القائمة لا تُحفظ. وتتوفر أيضًا خيارات إخفاء (masking).
- Dynatrace SaaS مع Grail: تُخزَّن السمات عمومًا مع وحدات span وتكون قابلة للاستعلام بـ DQL، مع مراعاة قواعد المعالجة والإخفاء المضبوطة (OpenPipeline وإعدادات الخصوصية).
يتطور السلوك الدقيق: راجع صفحة وثائق Dynatrace المخصصة لسمات span في بيئتك. أما سمات المورد القياسية فتُستخدم في الحالتين لتعريف الخدمة.
كيف تتحقق من أن كل شيء يعمل
- من جهة Collector: أضف مؤقتًا المُصدِّر
debugبالإعدادverbosity: detailedواقرأ سمات المورد في سجلات الـ Collector. - Dynatrace SaaS: تحقق من وجود السمات في دفتر ملاحظات (notebook):
fetch spans, from: now() - 30m | filter service.name == "checkout" | fields start_time, span.name, service.version, k8s.namespace.name, k8s.pod.name | limit 20يدل العمود الفارغ على سمة غير موضوعة أو غير محفوظة.
- Dynatrace Managed: افتح تتبعًا موزّعًا للخدمة واطلع على سمات span؛ والسمة المخصصة الغائبة يجب إضافتها أولًا إلى القائمة المسموح بها.
- اسم الخدمة: إذا ظهر
unknown_serviceفالعملية لا تقرأOTEL_SERVICE_NAME.
أفضل الممارسات
- اسم خدمة ثابت وفريد لكل مكوّن؛ والإصدار في
service.version، لا في الاسم أبدًا. - سمات المورد نفسها على التتبعات والمقاييس والسجلات، للانتقال من إشارة إلى أخرى (انظر سجلات OpenTelemetry مع trace_id).
- لا معرّف مستخدم ولا قيم عالية الكاردينالية في سمات المورد.
- صفِّ أهداف SLO حسب
deployment.environmentكي لا تخلط الاختبار بالإنتاج (انظر SLO من OpenTelemetry باستخدام DQL). - وثّق اصطلاح السمات لدى الفريق: عمل يدوي متكرر (toil) أقل مع كل خدمة جديدة.
الأسئلة الشائعة
لماذا تظهر خدمتي مرتين؟
غالبًا لأن قيمتين من service.name تتعايشان، أو لأن OneAgent وOTel SDK يقيسان العملية نفسها. وحّد الاسم وتحقق من التكرارات.
هل أضع بادئة لسماتي الخاصة بالأعمال؟
نعم، فمساحة اسم خاصة بك (shop.order.id) تتجنب التعارض مع اصطلاحات الدلالات الحالية والمستقبلية.
هل يعمل المعالج k8sattributes خارج Kubernetes؟
لا. خارج Kubernetes استخدم resourcedetection مع كواشف مناسبة (النظام والسحابة) والمعالج resource.
الخلاصة
سمات المورد هي هوية بيانات القياس عن بُعد لديك. ضعها في التطبيق، وأثرِها في الـ Collector، ونظّفها قبل التصدير، وتحقق مما يحتفظ به Dynatrace، في SaaS كما في Managed. المراجع: اصطلاحات دلالات المورد ووثائق Dynatrace حول OpenTelemetry.
span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC. Dynatrace علامة تجارية لشركة Dynatrace LLC. تحقق دائمًا من القيم (المنافذ والإصدارات والأحجام) في الوثائق الرسمية الخاصة بإصدارك.