وكيل OpenTelemetry لـ Java: قِس تطبيقك وأرسل بياناته إلى Dynatrace

وكيل OpenTelemetry لـ Java: نزّله، واضبط تصدير OTLP إلى Dynatrace، وانشره على VM أو Kubernetes، وتحقق من التتبعات والمقاييس والسجلات.
Agent OpenTelemetry Java : instrumenter une application et l'envoyer à Dynatrace

يريد فريقك قياسًا برمجيًا قياسيًا وقابلًا للنقل دون تعديل شيفرة تطبيق 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.
  • وصول صادر عبر 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 الذي يحتفظ بالرمز.

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

  1. سجلات بدء التشغيل: تعرض JVM سطرًا من نوع opentelemetry-javaagent - version: 2.x.y. وإن غاب فالوكيل غير محمَّل.
  2. أخطاء التصدير: ابحث عن Failed to export في السجلات. يدل الرمز 401 أو 403 على رمز أو نطاق غير صحيح؛ ويدل 404 على عنوان نقطة خاطئ.
  3. وضع debug مؤقت: OTEL_JAVAAGENT_DEBUG=true يعرض الـ spans في وحدة التحكم. أزله بعد ذلك، فهو كثير الإسهاب.
  4. في 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. الميزات تتطور بسرعة: تحقق من توفرها في بيئتك وفي الوثائق الرسمية.

Total
0
Shares
Leave a Reply

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

Previous Post
OneAgent OpenTelemetry doublons : éviter les spans en double et le contexte cassé

تكرار spans بين OneAgent وOpenTelemetry: تجنّب الـ spans المزدوجة والسياق المقطوع

Next Post
Temporalité métriques OTLP vers Dynatrace : delta ou cumulative, l'erreur qui fait disparaître vos compteurs

زمنية مقاييس OTLP إلى Dynatrace: delta أم cumulative، الخطأ الذي يُخفي عدّاداتك

Related Posts