إعداد OpenTelemetry Collector مع Dynatrace: التتبعات والمقاييس والسجلات عبر OTLP/HTTP

إعداد OpenTelemetry Collector مع Dynatrace: ملف YAML كامل، رمز API وصلاحياته، وOTLP/HTTP وزمنية delta وDocker والتحقق بـ DQL، لـ SaaS وManaged.
Configurer le collector OpenTelemetry Dynatrace : traces, métriques et logs en OTLP/HTTP

تُصدر خدماتك بالفعل تتبعات (traces) ومقاييس (metrics) وسجلات (logs) بصيغة OpenTelemetry، لكنّ كل خدمة ترسلها بطريقتها. يحلّ إعداد OpenTelemetry Collector مع Dynatrace هذه الفوضى: نقطة خروج واحدة، ورمز واحد، وإعداد واحد تقرؤه أثناء الحادثة.

الرهان هنا ملموس لمهندس SRE. التصدير المضبوط بشكل سيئ يعني spans مفقودة ومؤشرات SLI خاطئة ومدة أطول لاستعادة الخدمة (MTTR) في اليوم الذي تحتاج فيه إلى فهم عطل ما. وتوحيد التصدير في Collector يقلّل العمل اليدوي المتكرر (toil)، إذ تغيّر نقطة النهاية أو الرمز في مكان واحد.

ينطبق هذا الدرس التطبيقي على Dynatrace SaaS وDynatrace Managed معًا. نشير إلى الفروق (نقطة النهاية وActiveGate والاستعلامات) عند كل خطوة.

الهدف والمتطلبات المسبقة

في النهاية يعمل Collector داخل Docker، ويستقبل بيانات OTLP من تطبيقاتك، ويرسل التتبعات والمقاييس والسجلات إلى Dynatrace عبر OTLP/HTTP. وستعرف أيضًا كيف تتحقق من وصول البيانات.

  • بيئة Dynatrace SaaS، أو عنقود (cluster) Managed مع environment ActiveGate؛
  • Docker مثبّت على الجهاز الذي سيستضيف Collector؛
  • تطبيق مزوّد مسبقًا بـ OpenTelemetry SDK (راجع OpenTelemetry من البداية إلى النهاية مع Dynatrace)؛
  • رمز API مميّز (API token) بصلاحيات الاستيعاب الموضحة في الخطوة 2.

إعداد OpenTelemetry Collector مع Dynatrace خطوة بخطوة

الخطوة 1: اختر التوزيعة

هناك خياران معقولان:

  • Collector contrib (otel/opentelemetry-collector-contrib): توزيعة المجتمع، كاملة جدًا وتضم كل المكونات؛
  • توزيعة Dynatrace (ghcr.io/dynatrace/dynatrace-otel-collector/dynatrace-otel-collector): مجموعة مكونات اختبرتها Dynatrace وتدعمها، ومنها المكونات المستخدمة هنا.

إن أردت دعمًا من الشركة المصنِّعة فاختر توزيعة Dynatrace. وإن احتجت إلى مكوّن غير شائع فاختر contrib. وفي الحالتين ثبّت إصدارًا محددًا من الصورة، فالـ Collector الذي يغيّر إصداره من تلقاء نفسه مصدر حوادث.

الخطوة 2: أنشئ رمز API

في Dynatrace افتح Access tokens وأنشئ رمزًا مخصصًا لـ Collector بهذه الصلاحيات (scopes):

  • openTelemetryTrace.ingest للتتبعات؛
  • metrics.ingest للمقاييس؛
  • logs.ingest للسجلات.

رمز واحد لكل Collector، ولا صلاحية خارج هذه القائمة. فإن تسرّب ألغيتَ رمزًا واحدًا دون قطع التدفقات الأخرى.

الخطوة 3: اعثر على نقطة نهاية OTLP

تقبل واجهة OTLP الخاصة بـ Dynatrace صيغة OTLP/HTTP (protobuf) فقط. ويُلحق Collector بنفسه المسارات /v1/traces و/v1/metrics و/v1/logs بالعنوان الأساسي:

# Dynatrace SaaS
https://{env-id}.live.dynatrace.com/api/v2/otlp

# Dynatrace Managed (via environment ActiveGate)
https://{activegate-host}:9999/e/{env-id}/api/v2/otlp

في Managed يحدد المسار /e/{env-id}/ البيئة. تحقق من المنفذ والنطاق الدقيقين لـ ActiveGate لديك في وثائق واجهة OTLP لـ Dynatrace.

الخطوة 4: اكتب الملف otel-collector-config.yaml

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  memory_limiter:
    check_interval: 1s
    limit_percentage: 75
    spike_limit_percentage: 15
  resource:
    attributes:
      - key: deployment.environment
        value: production
        action: upsert
  cumulativetodelta: {}
  batch:
    send_batch_size: 1000
    timeout: 5s

exporters:
  otlphttp:
    endpoint: ${env:DT_ENDPOINT}
    headers:
      Authorization: "Api-Token ${env:DT_API_TOKEN}"
  debug:
    verbosity: basic

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, resource, batch]
      exporters: [otlphttp]
    metrics:
      receivers: [otlp]
      processors: [memory_limiter, resource, cumulativetodelta, batch]
      exporters: [otlphttp]
    logs:
      receivers: [otlp]
      processors: [memory_limiter, resource, batch]
      exporters: [otlphttp]

الأسطر الحاسمة:

  • المستقبِل otlp: يمكن لتطبيقاتك التحدث إلى Collector عبر gRPC (المنفذ 4317) أو HTTP (المنفذ 4318). أما التصدير إلى Dynatrace فيجب أن يتم عبر HTTP فقط؛
  • memory_limiter أولًا: يرفض البيانات قبل أن يُنهى Collector بسبب نقص الذاكرة؛
  • resource: يضيف سمة مشتركة تفيد في التصفية حسب البيئة داخل استعلاماتك؛
  • batch أخيرًا: يجمّع عمليات الإرسال ويقلّل عدد الطلبات؛
  • Authorization: تبدأ القيمة بـ Api-Token يليها فراغ ثم الرمز. ويأتي الرمز من متغير بيئة، وليس من الملف أبدًا.

الخطوة 5: تعامل مع زمنية المقاييس (temporality)

تتوقع Dynatrace مقاييس OTLP بزمنية delta. أما كثير من حزم SDK والمستقبِلات فتنتج افتراضيًا زمنية cumulative. أمامك خياران: ضبط SDK على delta، أو ترك المعالج cumulativetodelta يحوّل داخل Collector كما في مسار metrics أعلاه. يحتفظ هذا المعالج بحالة في الذاكرة، فإن وُجدت عدة نسخ فتأكد أن السلسلة الواحدة تصل دائمًا إلى Collector نفسه. وبالنسبة إلى المدرّجات التكرارية (histograms) راجع أيضًا المقاييس والمدرّجات التكرارية مع OpenPipeline.

الخطوة 6: انشر باستخدام Docker

export DT_ENDPOINT="https://{env-id}.live.dynatrace.com/api/v2/otlp"
export DT_API_TOKEN="dt0c01.XXXX"   # do not commit

docker run -d --name otel-collector \
  -p 4317:4317 -p 4318:4318 \
  -e DT_ENDPOINT -e DT_API_TOKEN \
  -v "$(pwd)/otel-collector-config.yaml:/etc/otelcol/config.yaml" \
  ghcr.io/dynatrace/dynatrace-otel-collector/dynatrace-otel-collector:<version> \
  --config=/etc/otelcol/config.yaml

بعد ذلك وجّه تطبيقاتك إلى Collector، مثلًا OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318.

Kubernetes: يصبح الملف نفسه ConfigMap، ويصبح الرمز Secret يُحقن كمتغير بيئة. يمكن لمخطط Helm الخاص بمشروع OpenTelemetry أو لـ Dynatrace Operator نشر Collector. اختر Deployment لبوابة مركزية وDaemonSet للجمع على مستوى كل عقدة. وتذكّر قيد cumulativetodelta إن شغّلت عدة نسخ.

كيف تتحقق من أنه يعمل

  1. سجلات Collector: docker logs -f otel-collector. عند البدء يجب أن ترى العبارة “Everything is ready”. وأي خطأ في التصدير يُظهر رمز HTTP الذي أعادته Dynatrace.
  2. مصدّر debug: أضف debug مؤقتًا إلى exporters في أحد المسارات. يكتب Collector عندئذ ما يستقبله في سجلاته. فإن لم يظهر شيء فالمشكلة في جهة التطبيق وليست في Dynatrace.
  3. DQL في Notebook (SaaS):
fetch spans, from: now() - 15m
| filter deployment.environment == "production"
| summarize spans = count(), by: {service.name}
| sort spans desc

المبدأ نفسه للسجلات باستخدام fetch logs. وفي Managed، حيث لا يوجد Grail، افتح عرض التتبعات الموزّعة (Distributed traces) وصفِّ حسب اسم الخدمة. وللتعمق في DQL وبيانات OTLP في SaaS راجع الوحدة 8 من المسار التدريبي لـ SaaS.

Managed وSaaS: ما الذي يتغير

العنصر Dynatrace SaaS Dynatrace Managed
نقطة النهاية {env-id}.live.dynatrace.com/api/v2/otlp نطاق ActiveGate أو العنقود + /e/{env-id}/api/v2/otlp
الشهادة عامة غالبًا داخلية: أضف مرجع الشهادات (CA) إلى Collector
التحليل Grail وDQL وNotebooks العروض الكلاسيكية (Distributed traces وData Explorer)

استكشاف الأخطاء وإصلاحها

العَرَض السبب المرجّح الحل
401 Unauthorized الرمز مفقود أو مشوّه أو ملغى تحقق من البادئة Api-Token ومن متغير البيئة
403 Forbidden صلاحية ناقصة أضف إلى الرمز الصلاحية الخاصة بذلك النوع من الإشارات
404 Not Found مسار خاطئ العنوان الأساسي /api/v2/otlp دون /v1/...؛ والمسار /e/{env-id} في Managed
فشل مع المصدّر otlp Dynatrace لا تدعم gRPC استخدم otlphttp
مقاييس مفقودة أو مرفوضة زمنية cumulative أضف cumulativetodelta أو حوّل SDK إلى delta

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

  • رمز واحد لكل Collector، بصلاحيات الاستيعاب فقط، ومخزّن في secret.
  • ضع memory_limiter أولًا وbatch أخيرًا في المسار دائمًا.
  • ثبّت إصدار الصورة وارفعه بقرار مقصود.
  • راقب Collector نفسه: تصدير يفشل بصمت يشوّه أهداف SLO لديك.
  • أزل المصدّر debug بعد انتهاء التحقق.

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

هل أحتاج إلى Collector إذا كان OneAgent مثبتًا بالفعل؟

ليس بالضرورة. يستطيع OneAgent التقاط بيانات OpenTelemetry على المضيفات التي يراقبها. ويصبح Collector مفيدًا عند غياب OneAgent، أو لتوحيد عدة مصادر، أو للتصفية والإثراء قبل الإرسال.

هل يمكنني الإرسال إلى Dynatrace عبر gRPC؟

لا، فواجهة OTLP الخاصة بـ Dynatrace تتوقع OTLP/HTTP. يمكن لتطبيقاتك التحدث إلى Collector عبر gRPC، ثم يصدّر Collector عبر HTTP.

contrib أم توزيعة Dynatrace؟

تغطي توزيعة Dynatrace الحالات الشائعة مع دعم من الشركة. أما contrib فتوفر مكونات أكثر دون هذا الدعم. والإعداد المعروض هنا يعمل مع الاثنتين.

الخلاصة

يمنحك Collector المضبوط جيدًا سلسلة تصدير مقروءة: نقطة نهاية واحدة، ورمزًا واحدًا، وثلاثة مسارات. وتكسب نقطة تحكم واحدة في القياس عن بُعد (telemetry)، وبالتالي تشخيصًا أسرع عندما يتراجع أحد أهداف SLO. ابدأ بالتتبعات، وتحقق في Notebook، ثم أضف المقاييس والسجلات.

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
Module 8 : OpenTelemetry/IA, des traces OTLP aux agents MCP

OpenTelemetry والذكاء الاصطناعي في Dynatrace SaaS: OTLP وLLM وMCP (الوحدة 8)

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

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

Related Posts