إعادة توجيه OneAgent إلى SaaS دون إعادة تثبيته ممكنة: تتيح وثائق Dynatrace أداة سطر الأوامر oneagentctl: فهي تغيّر نقطة الاتصال لوكيل مثبَّت أصلًا. وبالنسبة لفريق SRE ينتقل من Managed إلى SaaS، هذه أقل الطرق تدخّلًا لنقل مجموعة من المضيفين، بشرط معرفة ما الذي يتغيّر فعلًا وكيف يُتحقق من النتيجة.
المشكلة مألوفة. المضيفون تعمل، والتطبيقات مزوّدة بالأجهزة القياسية، ولا أحد يريد إعادة نشر كامل على مئات الأجهزة لمجرد تغيير الوجهة. يكمّل هذا الدليل الخطة الشاملة لـالترحيل من Managed إلى SaaS واستعادة الضبط الموصوفة في Monaco من Managed إلى SaaS: هنا يخصّ الأمر الوكلاء وحدهم.
يستند المحتوى إلى الوثائق الرسمية لـoneagentctl (نسختا SaaS وManaged من الصفحة) وإلى مرجع واجهة API للنشر. وهو صالح لـDynatrace Managed (المصدر) وDynatrace SaaS (الهدف).
إعادة توجيه OneAgent إلى SaaS: ما يجب معرفته أولًا
وفق الوثائق، يتيح oneagentctl ضبط OneAgent على مستوى مضيف منفرد. يحدّد المعامل --set-server نقطة الاتصال: يُذكر عنوان أو اسم، متبوعًا باللاحقة /communication. وقد تكون النقطة خادم Dynatrace أو عنقود Managed أو ActiveGate.
تعمل ثلاثة معاملات معًا عند إعادة التوجيه إلى بيئة أخرى:
--set-server: نقطة الاتصال الجديدة؛--set-tenant: معرّف البيئة. توضح الوثائق أنه صحيح افتراضيًا؛ ويجب تغييره هنا لأن البيئة الهدف مختلفة. ويُستخدم دائمًا مع--set-tenant-token؛--set-tenant-token: الرمز المميّز الذي يوثّق الاتصال بالنقطة المحددة (لا تخلطه برمز API المميّز).
تتطلب معاملات set إعادة تشغيل خدمة OneAgent. ووفق الصفحة نفسها، تتطلب هذه الإعدادات أيضًا في بعض الحالات إعادة تشغيل التطبيقات المراقَبة. يعيد المعامل --restart-service تشغيل الخدمة في الأمر نفسه. ويمكن الجمع بين عدة معاملات set في أمر واحد.
المتطلبات
- بيئة Dynatrace SaaS يمكن الوصول إليها من المضيفين عبر HTTPS صادر (مباشرة أو عبر ActiveGate).
- صلاحية root في Linux أو مسؤول في Windows: تشترط الوثائق ذلك لتشغيل
oneagentctl. - رمز API مميّز لـ SaaS بنطاق (scope)
InstallerDownloadلقراءة معلومات الاتصال (أو، مع عميل OAuth أو platform token، النطاقfleet-management:oneagent.connection-info:read). - جرد للمضيفين حسب الدفعة، كما في دليل الترحيل. ومضيف اختبار للدفعة الأولى.
الخطوة 1: الحصول على معلومات الاتصال بـ SaaS
يصف مرجع واجهة API للنشر الطلب GET https://{id-environnement}.live.dynatrace.com/api/v1/deployment/installer/agent/connectioninfo. والاستجابة JSON من أربعة حقول: communicationEndpoints (قائمة مرتبة بأولوية تنازلية)، وformattedCommunicationEndpoints، وtenantToken، وtenantUUID. وهذه هي القيم نفسها التي تُمرَّر إلى oneagentctl.

يعيد المعامل الاختياري networkZone نقاط اتصال network zone محددة؛ ويطلب version (بصيغة 1.221) صيغة القائمة المثلى لإصدار الوكيل المعني. تعامل مع tenantToken بوصفه سرًّا: خزّنه في مخزن الأسرار لديك، لا في مستودع Git.
الخطوة 2: إعادة توجيه مضيف Linux
في Linux توجد الأداة افتراضيًا في /opt/dynatrace/oneagent/agent/tools (أو <INSTALL_PATH>/agent/tools إذا خُصّص التثبيت). ويُكتب أمر إعادة التوجيه هكذا، بقيم تمثيلية:

cd /opt/dynatrace/oneagent/agent/tools
sudo ./oneagentctl --set-server="https://<id-env>.live.dynatrace.com/communication" \
--set-tenant=<id-env> \
--set-tenant-token=<tenant-token> \
--restart-service
إذا مرّ المضيفون عبر ActiveGate، فنقطة الاتصال هي نقطة ActiveGate مع منفذها: تعطي الوثائق المثال https://<activegate-endpoint>:9999/communication. ولتحديد عدة نقاط، تنص الوثائق على فصلها بفاصلة منقوطة ووضع المجموعة بين علامتي اقتباس. وتُعالج مشكلات المنفذ في OneAgent وActiveGate على المنفذ 9999.
في Windows الصيغة نفسها مع .\oneagentctl.exe، من وحدة تحكم بصلاحية المسؤول؛ وتوجد الأداة افتراضيًا في %PROGRAMFILES%\dynatrace\oneagent\agent\tools. وبلا صلاحيات، تشير الوثائق إلى أن Windows تعرض نافذة التحكم في حساب المستخدم وأن الأمر يفشل.
الخطوة 3: إعادة تشغيل التطبيقات عند الحاجة
إعادة تشغيل الخدمة لا تكفي دائمًا. تذكر الوثائق أن هذه المعاملات تتطلب، بحسب الحالات، إعادة تشغيل التطبيقات المراقَبة. وبالنسبة لعملية حُقن فيها الوكيل أصلًا، خطّط لإعادة التشغيل مع فريق التطبيق، بعيدًا عن أوقات الذروة. وهذه النقطة تؤثر في MTTR: قد يظل تطبيق لم تتم إعادة تشغيله غائبًا عن البيئة الهدف بينما المضيف نفسه ظاهر.
كيف تتحقق من أن الأمر يعمل
تُستخدم معاملات get لقراءة الحالة. وهي لا تعدّل شيئًا وتناسب فحصًا آليًا بعد كل دفعة.

- يعرض
--get-serverنقاط الاتصال التي يرسل OneAgent بياناته إليها. ومنذ OneAgent 1.207، يجمع الخرج بين أقواس معقوفة نقاط الاتصال ذات الأولوية نفسها، مرتبة حسب أولوية الاتصال، وتشير علامة نجمة إلى النقطة المستخدمة حاليًا. - يعرض
--get-tenantمعرّف البيئة: يجب أن يطابق بيئة SaaS. - يعرض
--get-tenant-tokenالرمز المميّز المحدد. لا تنسخ هذا الخرج في تذكرة أو سجل مشترك. - في بيئة SaaS يجب أن يظهر المضيف؛ قارن عدد المضيفين الظاهرين بجرد الدفعة (معيار نجاح قابل للقياس، مثل 100% خلال 30 دقيقة).
وبالنسبة إلى CI أو أداة النشر، تشكل هذه القراءات الثلاث اختبارًا بسيطًا: المضيف الذي لا يطابق خادمه أو tenant الهدف مضيف لم يُرحَّل.
أفضل الممارسات والأخطاء الشائعة
- اختبار أولًا: أعد توجيه مضيف غير حرج، وتحقق، ثم وسّع على دفعات مع خطة رجوع (الأمر نفسه بقيم Managed).
- بيئة واحدة لكل وكيل: يستبدل
--set-serverنقطة الاتصال؛ فلا تعوّل على إرسال مزدوج للمقارنة. احتفظ بمضيفين شاهدين على Managed. - الأسرار: يمر رمز tenant عبر سكربتاتك. احقنه من مخزن الأسرار.
- جدار الحماية: افتح المسارات نحو SaaS أو ActiveGate قبل الدفعة، لا أثناءها.
- معرّفات الكيانات: يجب التأكد منها على مضيف الاختبار، إذ يجب مراجعة كل ما يشير إلى معرّف مكتوب صراحةً (لوحات المعلومات، السكربتات). هذه النقطة غير مفصّلة في صفحة
oneagentctl. - OpenTelemetry: تشير مصدِّرات OTLP وCollectors إلى البيئة لا إلى OneAgent؛ وتُغيَّر عناوينها ورموزها بشكل منفصل (انظر OneAgent وOpenTelemetry: تجنّب التكرار).
وللأتمتة على نطاق واسع، تبقى إعادة التثبيت النظيفة عبر أداة النشر خيارًا، ويعود اختيار نمط التثبيت إلى سياقك؛ وأساسيات النشر موصوفة في OneAgent في Linux.
الأسئلة الشائعة
هل يجب إعادة تثبيت OneAgent للانتقال من Managed إلى SaaS؟
ليس بالضرورة: يغيّر oneagentctl نقطة الاتصال والبيئة والرمز المميّز لوكيل مثبَّت. تحقق من إصدار الوكيل واختبر على مضيف قبل التعميم.
أين أجد رمز tenant المميّز وعنوان الاتصال؟
في استجابة واجهة API للنشر connectioninfo: tenantToken وtenantUUID وقائمة communicationEndpoints. وهي تتطلب النطاق InstallerDownload.
هل يجب إعادة تشغيل التطبيقات؟
تشير الوثائق إلى أن معاملات set تتطلب إعادة تشغيل خدمة OneAgent، وفي بعض الحالات التطبيقات المراقَبة. ضمّن ذلك في جدول الدفعة.
الخلاصة
تتلخص إعادة توجيه OneAgent إلى SaaS في أمر واحد: --set-server و--set-tenant و--set-tenant-token، ثم إعادة التشغيل. والعمل الحقيقي حوله: الحصول على القيم الصحيحة، والتقدم على دفعات، والتحقق بمعاملات get، والاحتفاظ بخطة رجوع.
span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC. Dynatrace علامة تجارية لشركة Dynatrace LLC. المعاملات والإصدارات تتغيّر: تحقق دائمًا من القيم في الوثائق الرسمية لـoneagentctl ولـواجهة API للنشر.