ترحيل وكيل Elastic APM إلى OpenTelemetry: الانتقال إلى EDOT Java

ترحيل وكيل Elastic APM إلى OpenTelemetry عبر EDOT Java: مطابقة الإعدادات، نقطة نهاية واحدة، javaagent، وما لا يوجد له مكافئ.
Migrer agent Elastic APM OpenTelemetry : passer à EDOT Java

تُرسل مجموعة تطبيقات Java لديك تتبعاتها إلى APM Server عبر وكيل Elastic APM، وتوصي Elastic الآن بالانتقال إلى OpenTelemetry. من أجل ترحيل وكيل Elastic APM إلى OpenTelemetry في Java، تقترح الوثائق EDOT Java، وهي توزيعة OpenTelemetry من Elastic. الخطر على فريق SRE: فقدان spans مخصصة أو مقاييس دون الانتباه، وتعطّل التنبيهات التي تعتمد عليها.

يتبع هذا الدرس صفحة الترحيل من Elastic: مطابقة الإعدادات، والإبقاء على نقطة نهاية (endpoint) واحدة، واستبدال الوسيط -javaagent، ثم التحقق. ويسرد أيضًا ما لا مكافئ له. الهدف: ترحيل خدمة واحدة في كل مرة دون فجوات في الرؤية، والحفاظ على شيفرة قياس متوافقة مع أي خلفية OTLP.

النطاق: Elastic Stack وServerless Observability، وفق وثائق Elastic التي روجعت في 30 أكتوبر 2026. لا تشير صفحة الترحيل إلى حالة «preview»؛ وهي تذكر Java 8 أو أحدث. ولا يرد فيها أي إصدار محدد من EDOT Java: تحقق من الإصدار المنشور في Maven Central قبل النشر. لا يتناول هذا الدليل Dynatrace Managed ولا SaaS، لكن الناتج هو OpenTelemetry قياسي (انظر نهاية المقال).

ترحيل وكيل Elastic APM إلى OpenTelemetry: ما الذي يتغير

وكيل Elastic APM وكيل مملوك. أما EDOT Java فهو توزيعة من وكيل Java الخاص بـ OpenTelemetry: قياس تلقائي دون تعديل الشيفرة، مع المكتبات التي يغطيها مشروع OpenTelemetry الأصلي. تُرسل البيانات عبر OTLP وتحتفظ بالاصطلاحات الدلالية لـ OpenTelemetry. وبخصوص جسر مقاييس OpenTelemetry، توضح Elastic أن أسماء السمات تحتفظ بنقاطها بدلًا من أن تتحول إلى حقول labels.*.

النتيجة العملية: تتغير أسماء مقاييس JVM، وتختفي بعض الإعدادات، ويجب استبدال واجهة وكيل Elastic البرمجية (spans اليدوية) إن كنت تستخدمها. لفهم وجهة إرسال هذه البيانات، اقرأ أولًا OTLP APM Server أو EDOT Collector.

المتطلبات

  • Java 8 أو أحدث (صفحة ترحيل EDOT Java).
  • نقطة دخول OTLP: EDOT Collector أو Elastic Managed OTLP endpoint (Serverless) أو نقطة نهاية في نشرك. بالنسبة إلى Collector محلي، تذكر صفحة الإعداد العنوان http://localhost:4318 دون مصادقة.
  • مفتاح API أو secret token من Elastic، إذا كانت نقطة الدخول تتطلب مصادقة. لا تكتبهما أبدًا في مستودع.
  • الوكيل co.elastic.otel:elastic-otel-javaagent، منزَّلًا من Maven Central.
  • قائمة إعدادات ELASTIC_APM_* في خدماتك الحالية: إنها نقطة انطلاقك.

الخطوة 1: ترحيل القياس اليدوي

خطوة اختيارية بحسب Elastic، لكنها حرجة: إذا كانت الشيفرة تستدعي واجهة وكيل Elastic APM لإنشاء معاملات أو spans، فيجب الانتقال إلى التعليقات التوضيحية (annotations) وواجهة OpenTelemetry. وإلا لم تعد هذه الـ spans المخصصة تُولَّد. أحصِها قبل التحويل: قد يؤدي غياب span إلى اختفاء تفاصيل SLI للزمن الاستجابي.

الخطوة 2: ترجمة الإعدادات

تقدم صفحة الترحيل جدول مطابقة. هذا أهم ما فيه:

مقتطف من مطابقة إعدادات وكيل Elastic APM لـ Java مع متغيرات OpenTelemetry في EDOT Java
وكيل Elastic APM EDOT Java / OpenTelemetry
server_url OTEL_EXPORTER_OTLP_ENDPOINT
secret_token OTEL_EXPORTER_OTLP_HEADERS مع Authorization=Bearer …
api_key OTEL_EXPORTER_OTLP_HEADERS مع Authorization=ApiKey …
service_name OTEL_SERVICE_NAME أو السمة service.name
service_version سمة المورد service.version
environment سمة المورد deployment.environment.name
global_labels أزواج مفتاح=قيمة في OTEL_RESOURCE_ATTRIBUTES
disable_instrumentations OTEL_INSTRUMENTATION_<name>_ENABLED=false
log_sending مفعّل افتراضيًا؛ اضبط otel.logs.exporter على none لإيقافه
verify_server_cert ELASTIC_OTEL_VERIFY_SERVER_CERT (الافتراضي true)

توجد إعدادات أخرى (trace_methods وcapture_headers وcapture_jmx_metrics وservice_node_name…) بصيغ مختلفة: راجع الصفحة الكاملة. ملاحظتان تستحقان التذكر: يصبح trace_methods هو OTEL_INSTRUMENTATION_METHODS_INCLUDE بصيغة مختلفة ومحارف بدل أقل، والتقاط الترويسات ثابت عند بدء التشغيل بينما كان ديناميكيًا.

الخطوة 3: نقطة نهاية واحدة

لا مكافئ للإعداد server_urls (عدة خوادم): يقبل EDOT Java نقطة نهاية واحدة فقط. لتعدد الوجهات، ضع Collector أمام خدماتك وأدر التصدير هناك. راجع OpenTelemetry Collector على Kubernetes وElastic Agent كمجمّع OpenTelemetry.

يمكن اختصار الإعداد الأدنى في الوثائق بثلاثة متغيرات:

متغيرات البيئة الدنيا في EDOT Java وتشغيل التطبيق بالوسيط javaagent، بحسب وثائق Elastic
export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.ingest.us-west1.gcp.cloud.es.io
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey P....l"
export OTEL_SERVICE_NAME="my-awesome-service"

بحسب صفحة الإعداد، المتغير OTEL_SERVICE_NAME مطلوب للتكامل مع الواجهة والربط، والمتغير OTEL_EXPORTER_OTLP_ENDPOINT إلزامي ما لم يكن Collector يستجيب على http://localhost:4317، وهو العنوان الافتراضي.

الخطوة 4: استبدال javaagent

استبدل الوسيط -javaagent الخاص بوكيل Elastic APM بوسيط EDOT، ثم أعد التشغيل:

java \
-javaagent:/path/to/agent.jar \
-jar myapp.jar

إذا لم تستطع تعديل سطر الأوامر، فإن JAVA_TOOL_OPTIONS يعمل، لكن Elastic تحذّر من أنه يُطبَّق على جميع عمليات JVM في البيئة نفسها، بما فيها أدوات البناء. فضّل سكربت بدء تشغيل الخادم: CATALINA_OPTS في bin/setenv.sh لـ Tomcat مثلًا. وعلى Kubernetes، تحيل الوثائق إلى مشغّل OpenTelemetry. احذف أيضًا متغيرات ELASTIC_APM_* التي لم تعد لازمة.

ما لا مكافئ له

تسرد صفحة الترحيل ما سيُفقد. اقرأها والوحات المعلومات (dashboards) مفتوحة أمامك.

قائمة ميزات وكيل Elastic APM لـ Java التي لا مكافئ لها في EDOT Java، بحسب صفحة الترحيل
  • server_urls: نقطة نهاية واحدة.
  • application_packages: لا تصفية للمكدسات حسب الحزمة.
  • الإرفاق عن بُعد: يحل محله الإرفاق التلقائي أثناء التشغيل، مع قيود.
  • ضغط الـ spans ومقاييس breakdown: غير متاحة.
  • قياس عميل LDAP: غير متاح.
  • صحة الوكيل وحمله الزائد، ومقاييس cgroup: غير مدعومة؛ استخدم hostmetricsreceiver أو kubeletstatsreceiver في Collector.

أما المقاييس، فأسماء JVM تتبع اصطلاحات OpenTelemetry: مثلًا يصبح jvm.gc.time هو jvm.gc.duration، وتمر الذاكرة عبر jvm.memory.used مع السمة jvm.memory.type. ولا مكافئ مباشر لـ jvm.gc.count. أعد كتابة الاستعلامات والتنبيهات التي تعتمد على الأسماء القديمة. قياس Micrometer: معطّل افتراضيًا، ويُفعَّل بـ otel.instrumentation.micrometer.enabled=true.

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

  1. اضبط مستوى سجل الوكيل على DEBUG عبر ELASTIC_OTEL_JAVAAGENT_LOG_LEVEL: توصي به الوثائق للتشخيص، ويعرض الـ spans بصيغة JSON.
  2. تحقق في واجهة Observability من Elastic أن الخدمة تظهر بالاسم الصحيح، مع الإصدار والبيئة المتوقعين.
  3. قارن الإنتاجية وزمن الاستجابة p95 قبل الترحيل وبعده في أول خدمة تُرحَّل.
  4. تأكد من وجود الـ spans اليدوية المرحَّلة ومن إعادة كتابة التنبيهات بأسماء المقاييس الجديدة.

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

  • رحِّل خدمة تجريبية أولًا، ثم على دفعات: يكون MTTR لحادثة ما أقصر عندما يتغير متغير واحد في كل مرة.
  • أبقِ الوكيل القديم يعمل بالتوازي في بيئة اختبار لمقارنة النتائج.
  • أبقِ الأسرار خارج المستودع، في مدير الأسرار لديك.
  • لا تعطّل ELASTIC_OTEL_VERIFY_SERVER_CERT إلا لتجربة: توصي Elastic بإضافة جهة التصديق إلى trust store الخاص بـ JVM.
  • وحِّد المعيار على OTLP: لمنطق المعيار المشترك، راجع OpenTelemetry وPrometheus.

وماذا عن Dynatrace؟

يظل EDOT Java وكيل OpenTelemetry: فهو يُصدر OTLP قياسيًا. تقبل Dynatrace بروتوكول OTLP، لكن هذا المقال لم يجرّب هذا المسار ولا تتحدث عنه وثائق Elastic: لا تفترضه. وللمقارنة بين مقاربات المزوّدين، اقرأ Dynatrace وDatadog.

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

هل يجب ترحيل شيفرة القياس اليدوي؟

تصنّف Elastic هذه الخطوة على أنها اختيارية، لكنها توضح أن المعاملات والـ spans المنشأة بواجهة وكيل Elastic لا تُولَّد ما لم تُرحَّل إلى واجهة OpenTelemetry.

هل يمكنني الإبقاء على عدة خوادم عبر server_urls؟

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

هل ستواصل لوحات المعلومات الخاصة بمقاييس JVM عملها؟

ليس كما هي. تتغير أسماء عدة مقاييس، وبعضها بلا مكافئ مباشر. أعد كتابتها استنادًا إلى القائمة الواردة في صفحة الترحيل.

الخلاصة

يتلخص ترحيل وكيل Elastic APM إلى OpenTelemetry عبر EDOT Java في أربع خطوات: جرد شيفرة القياس، وترجمة الإعدادات، والاكتفاء بنقطة نهاية واحدة، وتغيير -javaagent. الخسائر الحقيقية موجودة في قائمة «ما لا مكافئ له»: اقرأها قبل أول نشر. المصادر: ترحيل EDOT Java والتثبيت والإعداد.

span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC ولا لشركة Elastic N.V. Dynatrace علامة تجارية لشركة Dynatrace LLC. معلومات Elastic مأخوذة من وثائقها العامة التي روجعت في 30 أكتوبر 2026؛ تحقق منها لإصدارك.

Total
0
Shares
Leave a Reply

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

Previous Post
OTLP vers Datadog : Agent, DDOT ou intake direct, comment choisir

OTLP إلى Datadog: الوكيل أم DDOT أم الاستقبال المباشر، كيف تختار

Next Post
Logsdb Elasticsearch : réduire le stockage des logs sans réindexer

logsdb Elasticsearch: تقليل تخزين السجلات دون إعادة الفهرسة

Related Posts