تتبعات OpenTelemetry غير ظاهرة في Dynatrace: قائمة استكشاف أخطاء OTLP في 8 خطوات

تتبعات OpenTelemetry غير ظاهرة في Dynatrace؟ اتبع 8 فحوص لـ OTLP: العنوان والرمز والبروتوكول والشبكة وCollector والعيّنات، في SaaS وManaged.
Traces OpenTelemetry absentes de Dynatrace : checklist de dépannage OTLP en 8 étapes

لقد أضفت قياس OpenTelemetry إلى خدمة، وCollector يعمل، ومع ذلك تبقى تتبعات OpenTelemetry غير ظاهرة في Dynatrace وتترك شاشة Distributed Tracing فارغة. وفي الأثناء تظل الحادثة الجارية بلا سياق، ويرتفع MTTR، ويشك الفريق في سلسلة القياس بأكملها.

هدف هذا الدرس التطبيقي: اتباع قائمة استكشاف أخطاء OTLP في 8 خطوات، من التطبيق حتى Grail، وعزل الحلقة التي تفقد الـ spans في أقل من 30 دقيقة. ينطبق المحتوى على Dynatrace SaaS وDynatrace Managed؛ وتُذكر فروق العناوين (URL) في كل موضع.

إن لم يكن لديك Collector بعد، فابدأ بـ تثبيت Collector الخاص بـ OpenTelemetry وإعداده لـ Dynatrace ثم عد إلى هنا.

المبدأ: تتبّع السلسلة حلقة بحلقة

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

المتطلبات

  • صلاحية قراءة سجلات التطبيق وCollector.
  • رمز API مميّز (token) من Dynatrace بالنطاق openTelemetryTrace.ingest (Ingest OpenTelemetry traces).
  • الأداة curl على جهاز في الشبكة نفسها التي يوجد فيها التطبيق.
  • SaaS: الوصول إلى Notebooks أو تطبيق Distributed Tracing. Managed: الوصول إلى شاشة Distributed traces في البيئة.

تتبعات OpenTelemetry غير ظاهرة: القائمة في 8 خطوات

الخطوة 1 — تحقق من أن SDK ينتج spans

فعّل مصدّر وحدة التحكم (console) بجانب مصدّر OTLP. مع القياس التلقائي (Java وPython وNode.js) تكفي متغيرات البيئة القياسية:

export OTEL_SERVICE_NAME=checkout
export OTEL_TRACES_EXPORTER=otlp,console
export OTEL_TRACES_SAMPLER=always_on

إن لم يظهر أي span في الخرج القياسي فالمشكلة في التطبيق: وكيل لم يُحمَّل، أو مكتبة غير مقيسة، أو sampler مضبوط على always_off. ويتوقف دعم القيمة console على اللغة، فراجع وثائق SDK الخاص بك.

الخطوة 2 — تحقق من البروتوكول والمنفذ

تقبل نقطة OTLP في Dynatrace بروتوكول OTLP عبر HTTP (protobuf). ولن ينجح SDK مضبوط على gRPC (المنفذ 4317) نحو Dynatrace مباشرة. حدّد البروتوكول صراحة:

export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

وإن كان التطبيق يرسل إلى Collector محلي فكلٌّ من gRPC على 4317 وHTTP على 4318 يعمل، بشرط تفعيل المستقبِل (receiver) المقابل في Collector.

الخطوة 3 — تحقق من العنوان بدقة

هذا السبب الأول. يستقبل المتغير العام OTEL_EXPORTER_OTLP_ENDPOINT العنوان الأساسي، ويضيف SDK المسار /v1/traces. أما المتغير الخاص OTEL_EXPORTER_OTLP_TRACES_ENDPOINT فيستقبل العنوان الكامل.

# SaaS
export OTEL_EXPORTER_OTLP_ENDPOINT=https://<env-id>.live.dynatrace.com/api/v2/otlp
# Managed
export OTEL_EXPORTER_OTLP_ENDPOINT=https://<votre-domaine>/e/<env-id>/api/v2/otlp
# ActiveGate d'environnement
export OTEL_EXPORTER_OTLP_ENDPOINT=https://<activegate>:9999/e/<env-id>/api/v2/otlp

الخطأ الكلاسيكي: وضع /api/v2/otlp/v1/traces في المتغير العام، فينتج /v1/traces/v1/traces واستجابة 404. تحقق من الصيغة الدقيقة في وثائق OTLP API في Dynatrace.

الخطوة 4 — تحقق من الرمز المميّز وترويسته

export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Api-Token%20dt0c01.XXXX"

البادئة Api-Token متبوعة بمسافة إلزامية؛ وفي هذا المتغير تُكتب المسافة %20. يدل الرمز 401 على رمز غير صالح أو سيئ الصياغة، ويدل 403 على نطاق (scope) ناقص. اختبر النقطة يدويًا للحسم:

curl -s -o /dev/null -w "%{http_code}\n" -X POST \
  "https://<env-id>.live.dynatrace.com/api/v2/otlp/v1/traces" \
  -H "Authorization: Api-Token $DT_TOKEN" \
  -H "Content-Type: application/x-protobuf" \
  --data-binary @/dev/null

الجسم الفارغ ليس تتبعًا صالحًا؛ فالمهم هو التمييز بين 401/403 (المصادقة) و404 (المسار) واستجابة 2xx أو 400 (النقطة قابلة للوصول والرمز مقبول). وقد يختلف الرمز الدقيق للجسم الفارغ.

الخطوة 5 — تحقق من الشبكة وTLS

من الـ pod أو مضيف التطبيق (لا من جهازك):

curl -v https://<env-id>.live.dynatrace.com/api/v2/otlp/v1/traces 2>&1 | grep -E "Connected|SSL|HTTP/"

تشير مهلة الاتصال (timeout) إلى جدار حماية، أو وكيل صادر (proxy) غير مضبوط، أو NetworkPolicy في Kubernetes. وخطأ الشهادة في Managed يدل غالبًا على جهة إصدار داخلية لا تعرفها بيئة تشغيل التطبيق؛ أضفها إلى مخزن الثقة الخاص ببيئة التشغيل.

الخطوة 6 — اقرأ سجلات Collector ومقاييسه

إن كان Collector في السلسلة، فأضف مؤقتًا المصدّر debug إلى خط التتبعات:

exporters:
  debug:
    verbosity: detailed
  otlphttp:
    endpoint: https://<env-id>.live.dynatrace.com/api/v2/otlp
    headers:
      Authorization: "Api-Token ${env:DT_API_TOKEN}"
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp, debug]

إن ظهرت الـ spans في سجل debug ولم تظهر في Dynatrace فالمشكلة في جهة الإرسال (الخطوات 3 إلى 5). وإن لم تظهر فالمستقبِل لا يتلقى شيئًا (الخطوتان 1 و2). وتؤكد المقاييس الداخلية لـ Collector، المعروضة افتراضيًا على المنفذ 8888، التشخيص: قارن otelcol_receiver_accepted_spans وotelcol_exporter_sent_spans وotelcol_exporter_send_failed_spans (قد تُضاف اللاحقة _total بحسب الإصدار).

الخطوة 7 — تحقق من أخذ العيّنات والمرشحات

قد يُسقط المعالج filter أو tail_sampling المتشدد جدًا كل تتبعات خدمة قليلة الحمل. فالـ sampler من نوع parentbased_traceidratio بقيمة 0.01 على خدمة اختبار تتلقى 10 طلبات في الساعة لا ينتج تقريبًا شيئًا. ارجع مؤقتًا إلى always_on وأزل المرشحات للتأكد.

الخطوة 8 — ابحث عن الـ spans في المكان الصحيح داخل Dynatrace

تصل الـ spans أحيانًا لكن باسم خدمة آخر، أو في فترة أخرى، أو خارج منطقة الإدارة (management zone) الخاصة بك. في SaaS استعلم من Grail مباشرة:

fetch spans, from: now() - 30m
| filter contains(service.name, "checkout")
| summarize spans = count(), by: { service.name, k8s.namespace.name }

في Managed افتح Distributed traces، وصفِّ على الفترة الأخيرة وأزل منطقة الإدارة. كما أن الطابع الزمني الخاطئ (ساعة الحاوية المنحرفة) يضع الـ spans خارج النافذة المعروضة: قارن وقت الخادم بخادم NTP.

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

  1. لم تعد سجلات Collector تُظهر أخطاء تصدير، ويبقى otelcol_exporter_send_failed_spans ثابتًا.
  2. يعيد استعلام DQL في الخطوة 8 عددًا غير صفري من الـ spans لخدمتك.
  3. يُفتح تتبع كامل من البداية إلى النهاية ويُظهر الـ spans من كل خدمة، بأصل مشترك.

وللتوسع في انتشار السياق بين الخدمات اقرأ OpenTelemetry من البداية إلى النهاية مع Dynatrace.

أفضل الممارسات

  • احتفظ بخط اختبار أدنى (مستقبِل OTLP وbatch وتصدير) ووثّقه في دليل تشغيل (runbook) المناوبة.
  • راقب Collector نفسه: فتنبيه على إخفاقات التصدير يجنّبك اكتشاف العطل أثناء حادثة.
  • خزّن الرمز المميّز في سر (secret)، ولا تضعه أبدًا نصًا صريحًا في manifest أو مستودع.
  • تجنّب القياس المزدوج: إن كان OneAgent يقيس العملية أصلًا فتحقق من الوثائق عن كيفية تعايشه مع SDK الخاص بـ OpenTelemetry.
  • بعد عودة التتبعات حوّلها إلى مؤشرات: راجع إنشاء SLO على بيانات OpenTelemetry.

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

هل يقبل Dynatrace بروتوكول OTLP عبر gRPC؟

نقطة OTLP في واجهة Dynatrace API موثقة لبروتوكول OTLP عبر HTTP. لإرسال gRPC ضع Collector يستقبل gRPC ويصدّر عبر HTTP إلى Dynatrace.

المقاييس تصل لكن التتبعات لا تصل: لماذا؟

لكل إشارة مسارها (/v1/traces و/v1/metrics و/v1/logs) ونطاق رمزها. تأكد من أن الرمز يحمل أيضًا openTelemetryTrace.ingest وأن خط traces موجود في Collector.

كم أنتظر قبل أن أرى الـ spans؟

عادةً من بضع ثوانٍ إلى دقيقة، بحسب المعالج batch والاستيعاب. وبعد بضع دقائق أعد القائمة بدل الانتظار.

الخلاصة

ثمانية فحوص تكفي في الغالب: الإنتاج والبروتوكول والعنوان والرمز والشبكة وCollector وأخذ العيّنات والبحث. احتفظ بهذه القائمة في دليل التشغيل: فالحادثة القادمة في القياس ستُحل في دقائق لا في ساعات.

span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC. Dynatrace علامة تجارية لشركة Dynatrace LLC. ميزات SaaS تتطور بسرعة: تحقق من توفرها في بيئتك وفي الوثائق الرسمية.

Total
0
Shares
Leave a Reply

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

Previous Post
Alertes burn rate SLO dans Dynatrace : le tutoriel multi-fenêtres (SaaS et Managed)

تنبيهات معدل استهلاك SLO في Dynatrace: درس تطبيقي متعدد النوافذ (SaaS وManaged)

Next Post
SLO OpenTelemetry dans Dynatrace : disponibilité et latence en DQL

SLO OpenTelemetry في Dynatrace: التوافر وزمن الاستجابة بلغة DQL

Related Posts