يريد فريقك قياسًا برمجيًا قياسيًا وقابلًا للنقل دون تعديل شيفرة تطبيق Spring Boot. وليس لديه OneAgent على هذه الحاويات، أو اختار OpenTelemetry معيارًا للمنصة. يلبّي وكيل OpenTelemetry لـ Java هذه الحاجة: ملف JAR يُضاف عند بدء تشغيل JVM، فتنطلق التتبعات والمقاييس والسجلات عبر OTLP إلى Dynatrace.
هدف هذا الدرس التطبيقي: تنزيل الوكيل (agent) وضبطه بمتغيرات البيئة لإرسال الإشارات الثلاث إلى Dynatrace، ونشره على VM ثم على Kubernetes، والتحقق من وصول البيانات. ينطبق المحتوى على Dynatrace SaaS وDynatrace Managed؛ وعنوان النقطة (URL) وحده يتغير.
إن كانت العملية نفسها يراقبها OneAgent أصلًا فاقرأ أولًا OneAgent وOpenTelemetry: تجنّب التكرار. فقياسان تلقائيان في JVM واحدة ينتجان spans مزدوجة.
المتطلبات
- Java 8 أو أحدث (تحقق من مصفوفة التوافق لإصدار الوكيل المختار).
- رمز API مميّز من Dynatrace بالنطاقات
openTelemetryTrace.ingestوmetrics.ingestوlogs.ingest. - عنوان نقطة OTLP:
- SaaS:
https://<env-id>.live.dynatrace.com/api/v2/otlp؛ - Managed:
https://<votre-domaine>/e/<env-id>/api/v2/otlp؛ - عبر ActiveGate:
https://<activegate>:9999/e/<env-id>/api/v2/otlp.
- SaaS:
- وصول صادر عبر HTTPS من التطبيق، أو Collector وسيط.
خطوات ضبط وكيل OpenTelemetry لـ Java
الخطوة 1 — تنزيل الوكيل
mkdir -p /opt/otel
curl -fsSL -o /opt/otel/opentelemetry-javaagent.jar \
https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
في الإنتاج استبدل latest بإصدار مثبّت (مثل download/v2.x.y/) لتكون كل عملية بناء قابلة للتكرار، واختبر رفع الإصدارات كما تختبر أي تبعية.
الخطوة 2 — ضبط التصدير إلى Dynatrace
أنشئ ملف بيئة /etc/checkout/otel.env:
OTEL_SERVICE_NAME=checkout
OTEL_RESOURCE_ATTRIBUTES=service.version=1.4.2,deployment.environment.name=production
OTEL_EXPORTER_OTLP_ENDPOINT=https://abc12345.live.dynatrace.com/api/v2/otlp
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Api-Token%20dt0c01.XXXX.YYYY
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp
OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta
OTEL_PROPAGATORS=tracecontext,baggage
الأسطر الحرجة:
OTEL_EXPORTER_OTLP_ENDPOINT: العنوان الأساسي، دون/v1/traces. يضيف الوكيل بنفسه/v1/tracesو/v1/metricsو/v1/logs.OTEL_EXPORTER_OTLP_HEADERS: المسافة بينApi-Tokenوالرمز تُرمَّز%20، كما تنص مواصفات متغيرات OpenTelemetry.http/protobuf: تتوقع واجهة OTLP في Dynatrace بروتوكول HTTP مع protobuf. وإن أردت gRPC فمرّر عبر Collector.delta: يتوقع Dynatrace مقاييس بزمنية delta. وبدون هذا السطر قد تُرفض العدّادات: الشرح كامل في زمنية مقاييس OTLP.
لا تضع هذا الملف مع الرمز في نظام التحكم بالإصدارات أبدًا: احقنه من مدير الأسرار لديك.
الخطوة 3 — تشغيل JVM مع الوكيل (VM أو bare metal)
وحدة systemd دنيا:
[Unit]
Description=Checkout service
After=network-online.target
[Service]
EnvironmentFile=/etc/checkout/otel.env
ExecStart=/usr/bin/java -javaagent:/opt/otel/opentelemetry-javaagent.jar -jar /opt/checkout/checkout.jar
Restart=on-failure
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl restart checkout
يجب أن يسبق الخيار -javaagent الخيار -jar، وإلا مُرّر وسيطًا إلى التطبيق وتُجوهل.
الخطوة 4 — صيغة Kubernetes
انسخ الوكيل إلى وحدة تخزين مشتركة بواسطة init container، ثم حمّله عبر JAVA_TOOL_OPTIONS:
apiVersion: apps/v1
kind: Deployment
metadata:
name: checkout
spec:
replicas: 2
selector:
matchLabels: { app: checkout }
template:
metadata:
labels: { app: checkout }
spec:
volumes:
- name: otel
emptyDir: {}
initContainers:
- name: otel-agent
image: curlimages/curl:8.10.1
command: ["curl", "-fsSL", "-o", "/otel/opentelemetry-javaagent.jar",
"https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v2.10.0/opentelemetry-javaagent.jar"]
volumeMounts: [{ name: otel, mountPath: /otel }]
containers:
- name: app
image: registry.example.com/checkout:1.4.2
envFrom:
- secretRef: { name: checkout-otel }
env:
- name: JAVA_TOOL_OPTIONS
value: "-javaagent:/otel/opentelemetry-javaagent.jar"
volumeMounts: [{ name: otel, mountPath: /otel }]
يحوي السر checkout-otel متغيرات الخطوة 2. إصدار الوكيل وصورة curl مجرد أمثلة: خذ إصدارًا منشورًا ومعتمدًا لديك. ومع مشغّل (operator) OpenTelemetry يؤتمت المورد Instrumentation هذا الحقن. وللتصدير المركزي وجّه النقطة بدلًا من ذلك إلى Collector الخاص بـ OpenTelemetry الذي يحتفظ بالرمز.
كيف تتحقق من أن كل شيء يعمل
- سجلات بدء التشغيل: تعرض JVM سطرًا من نوع
opentelemetry-javaagent - version: 2.x.y. وإن غاب فالوكيل غير محمَّل. - أخطاء التصدير: ابحث عن
Failed to exportفي السجلات. يدل الرمز 401 أو 403 على رمز أو نطاق غير صحيح؛ ويدل 404 على عنوان نقطة خاطئ. - وضع debug مؤقت:
OTEL_JAVAAGENT_DEBUG=trueيعرض الـ spans في وحدة التحكم. أزله بعد ذلك، فهو كثير الإسهاب. - في Dynatrace SaaS نفّذ في Notebook:
fetch spans, from: now() - 15m
| filter service.name == "checkout"
| summarize requetes = count(), by: { span.name }
| sort requetes desc
| limit 20
يجب أن ترى مسارات HTTP الخاصة بالتطبيق. وبالنسبة إلى السجلات: fetch logs | filter service.name == "checkout" | limit 20. وفي Managed تظهر الخدمة في قائمة الخدمات والتتبعات في عرض التتبعات الموزّعة؛ وتُرى المقاييس في مستكشف البيانات. تعتمد الشاشات الدقيقة على إصدارك: راجع وثائق OpenTelemetry في Dynatrace.
استكشاف الأخطاء وإصلاحها
- لا بيانات ولا أخطاء: لا تقرأ الصورة المتغير
JAVA_TOOL_OPTIONS(بعض الصور الأساسية تعيد تعريفه في سكربت بدء التشغيل). تحقق بـkubectl execمن أن JVM تعرض «Picked up JAVA_TOOL_OPTIONS». - التتبعات موجودة والمقاييس غائبة: بقيت الزمنية تراكمية (cumulative)، أو أن الرمز لا يملك النطاق
metrics.ingest. - سجلات مكررة: التطبيق يكتب أصلًا على الخرج القياسي الذي يجمعه وكيل آخر. اختر مسارًا واحدًا للسجلات.
- بدء تشغيل أبطأ: يضيف الوكيل كلفة عند بدء JVM. عدّل مجسّات الجاهزية (readiness) إن فشلت بعد إضافة الوكيل.
- أخطاء TLS: خلف وكيل (proxy) مؤسسي يجب أن تثق JVM بشهادة الوكيل (truststore الخاص بـ Java)، وإلا فشل التصدير بصمت من جهة التطبيق.
أفضل الممارسات
- اعتمد
service.nameثابتًا لكل خدمة: فهو يحمل SLO والتنبيهات، راجع تنبيهات burn rate لـ SLO. - حدّد
service.versionعند كل نشر: فتصبح المقارنة بين إصدارين فورية. - عطّل أدوات القياس غير الضرورية بدل التصفية لاحقًا (
OTEL_INSTRUMENTATION_<NOM>_ENABLED=false). - خذ العيّنات بحذر: فأخذ العيّنات العدواني جدًا من جهة العميل يشوّه SLI المحسوبة على الـ spans.
- لا تضع وكيل OpenTelemetry أبدًا في JVM يقيسها OneAgent أصلًا.
الأسئلة الشائعة
هل يجب تعديل شيفرة التطبيق؟
لا بالنسبة إلى القياس الأساسي: يقيس الوكيل تلقائيًا الأطر الشائعة (HTTP وJDBC والمراسلة). أضف واجهة OpenTelemetry API فقط من أجل spans أو سمات خاصة بالأعمال.
إرسال مباشر أم عبر Collector؟
يناسب الإرسال المباشر اختبارًا أو بضع خدمات. وما فوق ذلك يركّز Collector الرمز والتصفية وإعادة المحاولة.
هل تُلتقط سجلات التطبيق؟
يلتقط الوكيل appenders مكتبات السجلات الشائعة (Logback وLog4j) حين يكون تصدير السجلات مفعّلًا، مع معرّف التتبع المرتبط. تحقق من مكتبتك في قائمة أدوات القياس المدعومة.
الخلاصة
بملف JAR وعشرة متغيرات تقريبًا، يرسل وكيل OpenTelemetry لـ Java التتبعات والمقاييس والسجلات إلى Dynatrace دون لمس الشيفرة. ثبّت الإصدار، وافرض زمنية delta، وأبقِ مالك قياس واحدًا لكل عملية، وتحقق في Grail. فتقوم SLO لديك على بيانات قياسية وقابلة للنقل.
span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC. Dynatrace علامة تجارية لشركة Dynatrace LLC. الميزات تتطور بسرعة: تحقق من توفرها في بيئتك وفي الوثائق الرسمية.