سمات OpenTelemetry في Dynatrace: service.name والإثراء وقائمة السماح

سمات OpenTelemetry في Dynatrace: اضبط service.name وأثرِ البيانات بـ k8sattributes وأدر قائمة السماح لسمات span وتحقق في SaaS وManaged.
Attributs OpenTelemetry Dynatrace : service.name, enrichissement et allow-list

ثلاث خدمات تحمل الاسم 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 في بيئتك. أما سمات المورد القياسية فتُستخدم في الحالتين لتعريف الخدمة.

كيف تتحقق من أن كل شيء يعمل

  1. من جهة Collector: أضف مؤقتًا المُصدِّر debug بالإعداد verbosity: detailed واقرأ سمات المورد في سجلات الـ Collector.
  2. 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
    

    يدل العمود الفارغ على سمة غير موضوعة أو غير محفوظة.

  3. Dynatrace Managed: افتح تتبعًا موزّعًا للخدمة واطلع على سمات span؛ والسمة المخصصة الغائبة يجب إضافتها أولًا إلى القائمة المسموح بها.
  4. اسم الخدمة: إذا ظهر 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. تحقق دائمًا من القيم (المنافذ والإصدارات والأحجام) في الوثائق الرسمية الخاصة بإصدارك.

Total
0
Shares
Leave a Reply

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

Previous Post
Tail sampling OpenTelemetry avant Dynatrace : maîtriser coûts et volume de traces

Tail sampling OpenTelemetry قبل Dynatrace: التحكم في التكاليف وحجم التتبعات

Next Post
Superviser collector OpenTelemetry : sa télémétrie interne dans Dynatrace (SaaS et Managed)

مراقبة OpenTelemetry Collector: قياسه الداخلي في Dynatrace (SaaS وManaged)

Related Posts