تُصدر خدماتك بالفعل تتبعات (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 إن شغّلت عدة نسخ.
كيف تتحقق من أنه يعمل
- سجلات Collector:
docker logs -f otel-collector. عند البدء يجب أن ترى العبارة “Everything is ready”. وأي خطأ في التصدير يُظهر رمز HTTP الذي أعادته Dynatrace. - مصدّر debug: أضف
debugمؤقتًا إلىexportersفي أحد المسارات. يكتب Collector عندئذ ما يستقبله في سجلاته. فإن لم يظهر شيء فالمشكلة في جهة التطبيق وليست في Dynatrace. - 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. تحقق دائمًا من القيم (المنافذ والإصدارات والأحجام) في الوثائق الرسمية الخاصة بإصدارك.