الترقية من Application Insights Java 2.x SDK

عادةً لا توجد تغييرات في التعليمات البرمجية عند الترقية إلى الإصدار 3.x. تبعيات 3.x SDK هي إصدارات واجهة برمجة تطبيقات غير عملية لتبعيات 2.x SDK. ومع ذلك، عند استخدامه مع عامل Java 3.x، يوفر عامل Java 3.x التنفيذ لهم. ونتيجة لذلك، يرتبط تقرير حالة النظام المخصص الخاص بك بجميع البنى التلقائية الجديدة التي يوفرها عامل Java 3.x.

الخطوة 1: تحديث التبعيات

الإصدار 2.x من التبعيات	الإجراء	الملاحظات
applicationinsights-core	قم بتحديث الإصدار إلى 3.4.3 أو إصدار أحدث
applicationinsights-web	قم بتحديث الإصدار إلى 3.4.3 أو إصدار أحدث، وإزالة عامل تصفية ويب Application Insights لملف web.xml.
applicationinsights-web-auto	استبدله بالإصدار 3.4.3 أو الأحدث من applicationinsights-web
applicationinsights-logging-log4j1_2	قم بإزالة التبعية وإزالة تطبيق Application Insights من تكوين Log4j الخاص بك.	لم تعد هناك حاجة منذ Log4j 1.2 يتم اختراقه تلقائيا في عامل Java 3.x.
applicationinsights-logging-log4j2	قم بإزالة التبعية وإزالة تطبيق Application Insights من تكوين Log4j الخاص بك.	لم تعد هناك حاجة لأن Log4j 2 مصدق تلقائيا في عامل Java 3.x.
applicationinsights-logging-logback	قم بإزالة التبعية وإزالة تطبيق Application Insights من تكوين Logback الخاص بك.	لم تعد هناك حاجة لأن Logback مصدق تلقائيا في عامل Java 3.x.
applicationinsights-spring-boot-starter	استبدله بالإصدار 3.4.3 أو الأحدث من applicationinsights-web	لم يعد اسم دور السحابة افتراضيا على spring.application.name. لمعرفة كيفية تكوين اسم دور السحابة، راجع مستندات تكوين 3.x.

الخطوة 2: إضافة عامل Java 3.x

أضف عامل Java 3.x إلى سطر أوامر Java Virtual Machine (JVM)، على سبيل المثال:

-javaagent:path/to/applicationinsights-agent-3.6.2.jar

إذا كنت تستخدم وكيل Java Application Insights 2.x، فما عليك سوى استبدال الموجود -javaagent:... بالمثال السابق.

إشعار

إذا كنت تستخدم برنامج التشغيل spring-boot-starter وإذا كنت تفضل ذلك، فهناك بديل لاستخدام عامل Java. ارجع إلى 3.x Spring Boot.

الخطوة 3: تكوين سلسلة الاتصال Application Insights

ارجع إلى تكوين سياسة الاتصال.

الإشعارات الأخرى

يصف الجزء المتبقي من هذا المستند القيود والتغييرات التي قد تواجهها عند الترقية من 2.x إلى 3.x، وبعض الحلول البديلة التي قد تجدها مفيدة.

متتبعات بيانات تتبع الاستخدام

لا يتم تشغيل 2.x SDK TelemetryInitializers عند استخدام عامل 3.x. يمكن حل العديد من حالات الاستخدام التي كانت تتطلب سابقا كتابة TelemetryInitializer في Application Insights Java 3.x عن طريق تكوين أبعاد مخصصة. أو استخدام السمات الموروثة.

معالجات التتبع

لا يتم تشغيل 2.x SDK TelemetryProcessors عند استخدام عامل 3.x. يمكن حل العديد من حالات الاستخدام التي كانت تتطلب سابقا كتابة TelemetryProcessor في Application Insights Java 3.x عن طريق تكوين تجاوزات أخذ العينات.

تطبيقات متعددة في جهاز Java ظاهري واحد

يتم دعم حالة الاستخدام هذه في Application Insights Java 3.x باستخدام تجاوزات اسم دور السحابة (معاينة) و/أو تجاوز سلسلة الاتصال (معاينة).

أسماء العمليات

في Application Insights Java 2.x SDK، في بعض الحالات، تحتوي أسماء العمليات على المسار الكامل، على سبيل المثال:

تم تغيير أسماء العمليات في Application Insights Java 3.x لتوفير عرض مجمع أفضل بشكل عام في مدخل Application Insights U/X، على سبيل المثال:

ومع ذلك، بالنسبة لبعض التطبيقات، قد لا تزال تفضل طريقة العرض المجمعة في U/X التي تم توفيرها بواسطة أسماء العمليات السابقة. في هذه الحالة، يمكنك استخدام ميزة معالجات بيانات تتبع الاستخدام (معاينة) في 3.x لنسخ السلوك السابق.

تقوم القصاصة البرمجية التالية بتكوين ثلاثة معالجات بيانات تتبع الاستخدام التي تدمج لنسخ السلوك السابق. تقوم معالجات القياس عن بعد بتنفيذ الإجراءات التالية (بالترتيب):

1. أول معالج للقياس عن بُعد هو معالج سمات (له النوع attribute)، ما يعني أنه ينطبق على جميع عمليات القياس عن بُعد التي لها سمات (حاليًا requests وdependencies، ولكن قريبًا أيضًا traces).

   يطابق أي بيانات تتبع الاستخدام التي تحتوي على سمات مسماة http.request.method و url.path.

   ثم يستخرج السمة url.path في سمة جديدة تسمى tempName.

2. المعالج الثاني للقياس عن بعد هو معالج span (له النوع span)، مما يعني أنه ينطبق على requests وdependencies.

   يطابق أي نطاق له سمة تسمى tempPath.

   ثم يقوم بتحديث اسم النطاق من السمة tempPath.

3. آخر معالج للقياس عن بعد هو معالج سمات، وهو نفس نوع معالج القياس عن بُعد الأول.

   يطابق أي بيانات تتبع الاستخدام التي تحتوي على سمة تسمى tempPath.

   ثم يحذف السمة المسماة tempPath، وتظهر السمة كبعد مخصص.

{
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "attributes": [
            { "key": "http.request.method" },
            { "key": "url.path" }
          ]
        },
        "actions": [
          {
            "key": "url.path",
            "pattern": "https?://[^/]+(?<tempPath>/[^?]*)",
            "action": "extract"
          }
        ]
      },
      {
        "type": "span",
        "include": {
          "matchType": "strict",
          "attributes": [
            { "key": "tempPath" }
          ]
        },
        "name": {
          "fromAttributes": [ "http.request.method", "tempPath" ],
          "separator": " "
        }
      },
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "attributes": [
            { "key": "tempPath" }
          ]
        },
        "actions": [
          { "key": "tempPath", "action": "delete" }
        ]
      }
    ]
  }
}

مثال المشروع

يتم ترحيل مشروع Java 2.x SDK هذا إلى مشروع جديد باستخدام عامل Java 3.x.