Azure لمراقبة القياس عن بُعد المفتوح المستند إلى الأجهزة التلقائية لتطبيقات Java

هل هذه الصفحة مفيدة؟

هل لديك ملاحظات إضافية؟

سيتم إرسال الملاحظات إلى Microsoft: بالضغط على الزر «إرسال»، سيتم استخدام ملاحظاتك لتحسين منتجات Microsoft وخدماتها. نهج الخصوصية.

توضح هذه المقالة كيفية تمكين وتكوين عرض "Java لمراقبة Azure" المستند إلى القياس عن بُعد المفتوح. بعد الانتهاء من الإرشادات الواردة في هذه المقالة، ستتمكن من استخدام تطبيق Azure Monitor Insights لمراقبة التطبيق الخاص بك.

ملاحظة

في 31 مارس 2025 ، سينتهي دعم ابتلاع مفاتيح الأجهزة. سيستمر ابتلاع مفاتيح الأجهزة في العمل، ولكننا لن نقدم تحديثات أو دعما للميزة بعد الآن. الانتقال إلى سلاسل الاتصال للاستفادة من الإمكانات الجديدة.

الشروع في العمل

يمكن تمكين Java التلقائي في الأجهزة دون أي تغييرات في الرموز.

المتطلبات الأساسية

• تطبيق جافا باستخدام جافا 8+
• اشتراك Azure: إنشاء اشتراك Azure مجانا
• مورد Insights التطبيق: إنشاء مورد Insights تطبيق

مكّن Azure Monitor Application Insights

يوضح لك هذا القسم كيفية تنزيل ملف جرة الأجهزة التلقائية.

قم بتنزيل ملف الجرة

قم بتنزيل ملف .jar التطبيق-agent-3.2.11.

تحذير

إذا كنت تقوم بالترقية من معاينة 3.0:

• مراجعة كل خيارات التكوين بعناية. لقد تغير هيكل JSON تماما. اسم الملف الآن كله أحرف صغيرة.

إذا كنت تقوم بالترقية من الإصدار 3.0.x:

• أسماء العمليات وأسماء طلبات القياس عن بعد مسبوقة الآن بطريقة HTTP ، مثل GET و POST. يمكن أن يؤثر هذا التغيير على لوحات المعلومات المخصصة أو التنبيهات إذا كانت تعتمد على القيم السابقة. للحصول على التفاصيل، راجع ملاحظات الإصدار 3.1.0.

إذا كنت تقوم بالترقية من الإصدار 3.1.x:

• بدءا من 3.2.0 ، لا يتم التقاط تبعيات وحدة التحكم "InProc" بشكل افتراضي. للحصول على تفاصيل حول كيفية تمكين ذلك، يرجى الاطلاع على خيارات التكوين.
• أسماء تبعية قاعدة البيانات الآن أكثر إيجازًا مع الاستعلام الكامل (مطهرة) لا تزال موجودة في data الحقل. أسماء تبعية HTTP الآن أكثر وصفية. يمكن أن يؤثر هذا التغيير على لوحات المعلومات المخصصة أو التنبيهات إذا كانت تعتمد على القيم السابقة. للحصول على التفاصيل، راجع ملاحظات الإصدار 3.2.0.

أشر JVM إلى ملف الجرة

أضف -javaagent:path/to/applicationinsights-agent-3.2.11.jar إلى JVM args لتطبيقك.

تلميح

للحصول على مُساعدة حول تكوين JVM args لتطبيقك، راجع تلميحات لتحديث JVM argsالخاص بك.

تعيين سلسلة اتصال Insights التطبيق

1. هناك طريقتان يمكنك من خلالهما توجيه ملف jar إلى مورد Insights التطبيق الخاص بك:

   • يمكنك تعيين متغير بيئة:

     APPLICATIONINSIGHTS_CONNECTION_STRING = <Copy connection string from Application Insights Resource Overview>
     

   • أو يمكنك إنشاء ملف تكوين باسم applicationinsights.json. ضعه في نفس الدليل كما هو الحال applicationinsights-agent-3.2.11.jar مع المحتوى التالي:

     {
       "connectionString": "Copy connection string from Application Insights Resource Overview"
     }
     

2. ابحث عن سلسلة الاتصال على مورد Insights التطبيق.

   

تأكيد أن البيانات تتدفق

قم بتشغيل التطبيق الخاص بك وافتح علامة التبويب "مورد Insights التطبيق" في مدخل Azure. قد يستغرق الأمر بضع دقائق حتى تظهر البيانات في المدخل.

ملاحظة

إذا لم تتمكن من تشغيل التطبيق أو كنت لا تحصل على البيانات كما هو متوقع، فراجع قسم استكشاف الأخطاء وإصلاحها .

هام

إذا كان لديك خدمتان أو أكثر تنبعثان من القياس عن بعد إلى نفس التطبيق Insights المورد، فستتم مطالبتك بتعيين أسماء أدوار السحابة لتمثيلها بشكل صحيح على خريطة التطبيق.

كجزء من استخدام أجهزة تطبيق رؤى، نقوم بجمع وإرسال بيانات التشخيص إلى Microsoft. تساعدنا هذه البيانات على تشغيل وتحسين تطبيق رؤى. يمكنك تعطيل جمع البيانات غير الأساسية. لمعرفة المزيد، راجع Statsbeat في تطبيق Azure Insights.

خيارات التكوين

في applicationinsights.json الملف، يمكنك أيضًا تكوين هذه الإعدادات:

• اسم دور السحابة
• مثيل دور السحابة
• أخذ نماذج
• قياسات JMX
• الأبعاد المخصصة
• معالجات القياس عن بُعد (معاينة)
• التسجيل الذي تم جمعه تلقائيا
• مقاييس الميكرومتر التي تم جمعها تلقائيا، والتي تتضمن مقاييس مشغل التمهيد الربيعي
• رسالة كشف أخطاء الاتصال
• وكيل HTTP
• التشخيص الذاتي

لمزيد من المعلومات، راجع خيارات التكوين.

مكتبات الأجهزة

يتضمن Java 3.x مكتبات الأجهزة التالية.

الطلبات التي تم جمعها تلقائيا

• مستهلكو JMS
• مستهلكو كافكا
• نيتي/ ويبفلوكس
• Servlets
• جدولة الربيع

التبعيات التي تم جمعها تلقائيا

التبعيات التي تم جمعها تلقائيا بالإضافة إلى انتشار التتبع الموزع في المراحل النهائية:

• أباتشي HttpClient
• أباتشي HttpAsyncClient
• AsyncHttpClient
• جوجل HttpClient
• gRPC
• java.net.HttpURLConnection
• Java 11 HttpClient
• عميل JAX-RS
• Jetty HttpClient
• JMS
• Kafka
• عميل Netty
• OkHttp

التبعيات التي تم جمعها تلقائيا دون انتشار التتبع الموزع في المراحل النهائية:

• Cassandra
• JDBC
• MongoDB (غير متزامنة ومتزامنة)
• Redis (الخس وJedis)

السجلات التي تم جمعها تلقائيا

• Java.util.logging
• Log4j، الذي يتضمن خصائص MDC
• SLF4J/Logback، والذي يتضمن خصائص MDC

المقاييس التي تم جمعها تلقائيا

• ميكرومتر ، والذي يتضمن مقاييس مشغل التمهيد الربيعي
• قياسات JMX

Azure SDKs

يتم جمع القياس عن بعد المنبعث من مجموعات Azure SDK هذه تلقائيا بشكل افتراضي:

• Azure App Configuration 1.1.10+
• Azure Cognitive Search 11.3.0+
• Azure Communication Chat 1.0.0+
• Azure Communication Common 1.0.0+
• Azure Communication Identity 1.0.0+
• Azure Communication الهاتف Numbers 1.0.0+
• Azure Communication SMS 1.0.0+
• Azure Cosmos DB 4.13.0+
• أزور ديجيتال توينز - كور 1.1.0+
• Azure Event Grid 4.0.0+
• Azure Event Hubs 5.6.0+
• Azure Event Hubs - Azure Blob Storage Checkpoint Store 1.5.1+
• Azure Form Recognizer 3.0.6+
• Azure Identity 1.2.4+
• Azure Key Vault - الشهادات 4.1.6+
• Azure Key Vault - Keys 4.2.6+
• Azure Key Vault - Secrets 4.2.6+
• ناقل خدمة Azure 7.1.0+
• Azure Storage - Blobs 12.11.0+
• Azure Storage - Blobs Batch 12.9.0+
• Azure Storage - Blobs Cryptography 12.11.0+
• Azure Storage - Common 12.11.0+
• Azure Storage - Files Data Lake 12.5.0+
• Azure Storage - Files Shares 12.9.0+
• Azure Storage - قوائم الانتظار 12.9.0+
• Azure Text Analytics 5.0.4+

تعديل القياس عن بُعد

يشرح هذا القسم كيفية تعديل القياس عن بعد.

إضافة امتدادات

يمكنك استخدامها opentelemetry-api لإنشاء مقتفيات وامتدادات . تملأ Spans جدول التبعيات في Insights التطبيق. يتم حفظ السلسلة التي تم تمريرها لاسم النطاق إلى الحقل الهدف داخل التبعية.

ملاحظة

هذه الميزة فقط في 3.2.0 وأحدث.

1. أضف opentelemetry-api-1.6.0.jar إلى تطبيقك:

   <dependency>
     <groupId>io.opentelemetry</groupId>
     <artifactId>opentelemetry-api</artifactId>
     <version>1.6.0</version>
   </dependency>
   

2. إضافة نطاقات في التعليمات البرمجية:

    import io.opentelemetry.api.trace.Span;
   
    Span span = tracer.spanBuilder("mySpan").startSpan();
   

إضافة أحداث النطاق الممتد

يمكنك استخدامها opentelemetry-api لإنشاء أحداث امتداد، والتي تملأ جدول التتبع في Insights التطبيق. يتم حفظ السلسلة التي تم تمريرها إلى addEvent() حقل الرسالة داخل التتبع.

ملاحظة

هذه الميزة فقط في 3.2.0 وأحدث.

1. أضف opentelemetry-api-1.6.0.jar إلى تطبيقك:

   <dependency>
     <groupId>io.opentelemetry</groupId>
     <artifactId>opentelemetry-api</artifactId>
     <version>1.6.0</version>
   </dependency>
   

2. إضافة أحداث الامتداد في التعليمات البرمجية:

    import io.opentelemetry.api.trace.Span;
   
    span.addEvent("eventName");
   

إضافة سمات النطاق

يمكنك استخدام opentelemetry-api لإضافة سمات إلى النطاقات. يمكن أن تتضمن هذه السمات إضافة بعد عمل مخصص إلى قياسك عن بُعد. يمكنك أيضا استخدام السمات لتعيين حقول اختيارية في مخطط Insights التطبيق، مثل معرف المستخدم أو عنوان IP الخاص بالعميل.

إضافة بعد مخصص

تؤدي إضافة بعد مخصص واحد أو أكثر إلى ملء الحقل customDimensions في جدول الطلبات أو التبعيات أو التتبع أو الاستثناءات.

ملاحظة

هذه الميزة فقط في 3.2.0 وأحدث.

1. أضف opentelemetry-api-1.6.0.jar إلى تطبيقك:

   <dependency>
     <groupId>io.opentelemetry</groupId>
     <artifactId>opentelemetry-api</artifactId>
     <version>1.6.0</version>
   </dependency>
   

2. إضافة أبعاد مخصصة في رمزك:

    import io.opentelemetry.api.trace.Span;
    import io.opentelemetry.api.common.AttributeKey;
    import io.opentelemetry.api.common.Attributes;
   
    Attributes attributes = Attributes.of(AttributeKey.stringKey("mycustomdimension"), "myvalue1");
    span.setAllAttributes(attributes);
    span.addEvent("eventName", attributes);
   

تحديث حالة الامتداد واستثناءات السجل

يمكنك استخدامها opentelemetry-api لتحديث حالة الامتداد وتسجيل الاستثناءات.

ملاحظة

هذه الميزة فقط في 3.2.0 وأحدث.

1. أضف opentelemetry-api-1.6.0.jar إلى تطبيقك:

   <dependency>
     <groupId>io.opentelemetry</groupId>
     <artifactId>opentelemetry-api</artifactId>
     <version>1.6.0</version>
   </dependency>
   

2. قم بتعيين الحالة إلى خطأ وتسجيل استثناء في التعليمات البرمجية:

    import io.opentelemetry.api.trace.Span;
    import io.opentelemetry.api.trace.StatusCode;
   
    span.setStatus(StatusCode.ERROR, "errorMessage");
    span.recordException(e);
   

تعيين معرف المستخدم

املأ حقل معرف المستخدم في جدول الطلبات أو التبعيات أو الاستثناءات.

هام

راجع قوانين الخصوصية المعمول بها قبل تعيين معرف المستخدم المصادق عليه.

ملاحظة

هذه الميزة فقط في 3.2.0 وأحدث.

1. أضف opentelemetry-api-1.6.0.jar إلى تطبيقك:

   <dependency>
     <groupId>io.opentelemetry</groupId>
     <artifactId>opentelemetry-api</artifactId>
     <version>1.6.0</version>
   </dependency>
   

2. تعيين user_Id في التعليمات البرمجية الخاصة بك:

   import io.opentelemetry.api.trace.Span;
   
   Span.current().setAttribute("enduser.id", "myuser");
   

الحصول على معرف التتبع أو معرف الامتداد

يمكنك استخدامه opentelemetry-api للحصول على معرف التتبع أو معرف الامتداد. يمكن تنفيذ هذا الإجراء لإضافة هذه المعرفات إلى القياس عن بعد للتسجيل الحالي لتحسين الارتباط عند تصحيح المشكلات وتشخيصها.

ملاحظة

هذه الميزة فقط في 3.2.0 وأحدث.

1. أضف opentelemetry-api-1.6.0.jar إلى تطبيقك:

   <dependency>
     <groupId>io.opentelemetry</groupId>
     <artifactId>opentelemetry-api</artifactId>
     <version>1.6.0</version>
   </dependency>
   

2. الحصول على معرف تتبع الطلب ومعرف النطاق في رمزك:

   import io.opentelemetry.api.trace.Span;
   
   String traceId = Span.current().getSpanContext().getTraceId();
   String spanId = Span.current().getSpanContext().getSpanId();
   

القياس عن بُعد المخصص

هدفنا في تطبيق Insights Java 3.x هو السماح لك بإرسال القياس عن بعد المخصص باستخدام واجهات برمجة التطبيقات القياسية.

نحن ندعم حاليًا ميكرومتر، وأطر العمل للتسجيل الشائعة، وتطبيق رؤى Java 2.x SDK. التطبيق Insights Java 3.x يلتقط تلقائيا القياس عن بعد المرسل من خلال واجهات برمجة التطبيقات هذه ويربطه بالقياس عن بعد الذي تم جمعه تلقائيا.

القياس عن بُعد المخصص المعتمد

يمثل الجدول التالي أنواع القياس عن بعد المخصصة المعتمدة حاليا والتي يمكنك تمكينها لتكملة عامل Java 3.x. للتلخيص:

• يتم دعم المقاييس المخصصة من خلال الميكرومتر.
• يتم دعم الاستثناءات والآثار المخصصة من خلال أطر التسجيل.
• يتم دعم الطلبات المخصصة والتبعيات والاستثناءات من خلال opentelemetry-api.
• يتم دعم أي نوع من القياس عن بعد المخصص من خلال التطبيق Insights Java 2.x SDK.

نوع القياس عن بعد المخصص	ميكرومتر	Log4j، تسجيل الدخول، JUL	2.x SDK	opentelemetry-api
أحداث مخصصة			نعم
مقاييس مخصصة	نعم		نعم
التبعيات			نعم	نعم
استثناءات		نعم	نعم	نعم
طرق عرض الصفحة			نعم
الطلبات			نعم	نعم
التتبع		نعم	نعم	نعم

حاليا، نحن لا نخطط لإصدار SDK مع التطبيق Insights 3.x.

التطبيق رؤى Java 3.x هو الاستماع بالفعل لقياس عن بُعد الذي يتم إرساله إلى التطبيق رؤى Java 2.x SDK. تعد هذه الوظيفة جزءا مهما من قصة الترقية لمستخدمي 2.x الحاليين. وهو يملأ فجوة مهمة في دعم القياس عن بعد المخصص لدينا حتى تتوفر واجهة برمجة تطبيقات OpenTelemetry بشكل عام.

إرسال مقاييس مخصصة باستخدام ميكرومتر

1. أضف ميكرومتر إلى تطبيقك:

   <dependency>
     <groupId>io.micrometer</groupId>
     <artifactId>micrometer-core</artifactId>
     <version>1.6.1</version>
   </dependency>
   

2. استخدم التسجيل العالمي ميكرومتر لإنشاء عداد:

   static final Counter counter = Metrics.counter("test.counter");
   

3. استخدم العداد لتسجيل المقاييس:

   counter.increment();
   

4. سيتم استيعاب المقاييس في جدول المقاييس المخصصة ، مع التقاط العلامات في العمود customDimensions . يمكنك أيضا عرض المقاييس في مستكشف المقاييس ضمن مساحة اسم المقياس " المقاييس المستندة إلى السجل".

   ملاحظة

   التطبيق Insights Java يستبدل جميع الأحرف غير الأبجدية الرقمية (باستثناء الشرطات) في اسم مقياس ميكرومتر بشرطة سفلية ، لذلك سيظهر المقياس أعلاه ك test.countertest_counter.

إرسال آثار واستثناءات مخصصة باستخدام إطار التسجيل المفضل لديك

Log4j و Logback و java.util.logging يتم تشغيلها تلقائيا. يتم جمع التسجيل الذي يتم إجراؤه عبر أطر التسجيل هذه تلقائيا كتتبع وقياس عن بعد للاستثناء.

بشكل افتراضي، يتم تجميع التسجيل فقط عند إجراء ذلك التسجيل على مستوى INFO أو أعلى. لتغيير هذا المستوى، راجع خيارات التكوين.

إذا كنت تريد إرفاق أبعاد مخصصة بسجلاتك، فاستخدم Log4j 1.2 MDC أو Log4j 2 MDC أو Logback MDC. يلتقط التطبيق رؤى Java 3.x تلقائيًا تلك الخصائص MDC كأبعاد مخصصة على تتبعك واستثناء القياس عن بُعد.

إرسال القياس عن بعد المخصص باستخدام 2.x SDK

1. أضف applicationinsights-core-2.6.4.jar إلى طلبك. يتم دعم جميع إصدارات 2.x بواسطة تطبيق Insights Java 3.x. إذا كان لديك خيار ، فمن الجدير استخدام أحدث إصدار:

   <dependency>
     <groupId>com.microsoft.azure</groupId>
     <artifactId>applicationinsights-core</artifactId>
     <version>2.6.4</version>
   </dependency>
   

2. إنشاء القياس عن بُعد للعميل:

   static final TelemetryClient telemetryClient = new TelemetryClient();
   

3. استخدم العميل لإرسال القياس عن بُعد المخصص:

   الأحداث

   telemetryClient.trackEvent("WinGame");
   

   المقاييس

   telemetryClient.trackMetric("queueLength", 42.0);
   

   التبعيات

   boolean success = false;
   long startTime = System.currentTimeMillis();
   try {
       success = dependency.call();
   } finally {
       long endTime = System.currentTimeMillis();
       RemoteDependencyTelemetry telemetry = new RemoteDependencyTelemetry();
       telemetry.setSuccess(success);
       telemetry.setTimestamp(new Date(startTime));
       telemetry.setDuration(new Duration(endTime - startTime));
       telemetryClient.trackDependency(telemetry);
   }
   

   السجلات

   telemetryClient.trackTrace(message, SeverityLevel.Warning, properties);
   

   استثناءات

   try {
       ...
   } catch (Exception e) {
       telemetryClient.trackException(e);
   }
   

استكشاف الأخطاء وإصلاحها

للحصول على تعليمات حول استكشاف الأخطاء وإصلاحها، راجع استكشاف الأخطاء وإصلاحها.

ملاحظات الإصدار

راجع ملاحظات الإصدار على GitHub.

الدعم

للحصول على الدعم:

• للحصول على تعليمات حول استكشاف الأخطاء وإصلاحها، راجع خطوات استكشاف الأخطاء وإصلاحها.
• بالنسبة إلى مشكلات دعم Azure، افتح تذكرة دعم Azure.
• بالنسبة إلى مشكلات القياس عن بُعد المفتوح، اتصل بمجتمع القياس عن بُعد المفتوح مباشرة.

ردود فعل القياس عن بُعد المفتوح

لتقديم ملاحظات:

• املأ استطلاع آراء العملاءفي مجتمع القياس عن بُعد المفتوح.
• أخبر Microsoft عن نفسك من خلال الانضمام إلى مجتمع المتبنين المبكرين للقياس عن بعد OpenTelemetry.
• تفاعل مع مستخدمي Azure Monitor الآخرين في مجتمع Microsoft التقني.
• قم بتقديم طلب ميزة في منتدى ملاحظات Azure.

الخطوات التالية

• لمراجعة التعليمات البرمجية المصدر، راجع مستودع GitHub الأجهزة التلقائية ل Azure Monitor Java.
• لمعرفة المزيد حول OpenTelemetry ومجتمعه، راجع مستودع OpenTelemetry Java GitHub.
• لتمكين تجارب الاستخدام، راجع تمكين مراقبة مستخدم الويب أو المستعرض.