سجل التطبيقات المنظم لـ Azure Spring Apps
إشعار
يعد Azure Spring Apps هو الاسم الجديد لخدمة Azure Spring Cloud. رغم أن الخدمة تحمل اسماً جديداً، سترى الاسم القديم في بعض الأماكن لفترة من الوقت بينما نعمل على تحديث الأصول مثل لقطات الشاشة، ومقاطع الفيديو، والرسوم التخطيطية.
تنطبق هذه المقالة على: ✔️ Basic/Standard ✔️ Enterprise
توضح هذه المقالة كيفية إنشاء بيانات سجل التطبيقات المنظمة وجمعها في Azure Spring Apps. مع التكوين المناسب، توفر Azure Spring Apps استعلاماً وتحليلاً مفيداً لسجل التطبيقات من خلال Log Analytics.
متطلبات مخطط السجل
لتحسين تجربة استعلام السجل، يجب أن يكون سجل التطبيق بتنسيق JSON وأن يتوافق مع مخطط. تستخدم Azure Spring Apps هذا المخطط لتحليل تطبيقك ودفقه إلى Log Analytics.
إشعار
تمكين تنسيق سجل JSON يجعل من الصعب قراءة إخراج دفق السجل من وحدة التحكم. للحصول على إخراج قابل للقراءة البشرية، قم بإلحاق الوسيطة --format-json
بأمر CLI az spring app logs
. راجع تنسيق سجلات JSON المنظمة.
متطلبات مخطط JSON:
مفتاح Json | نوع قيمة Json | المطلوب | عمود في Log Analytics | الوصف |
---|---|---|---|---|
الطابع الزمني | سلسلة | نعم | AppTimestamp | الطابع الزمني بتنسيق UTC |
المسجل | سلسلة | لا | المسجل | المسجل |
المستوى | سلسلة | لا | CustomLevel | مستوى السجل |
مؤشر الترابط | سلسلة | لا | مؤشر الترابط | مؤشر الترابط |
رسالة | سلسلة | لا | رسالة | رسالة السجل |
stackTrace | سلسلة | لا | StackTrace | تتبع مكدس الاستثناء |
exceptionClass | سلسلة | لا | ExceptionClass | اسم فئة الاستثناء |
mdc | JSON المتداخل | لا | سياق تشخيصي معين | |
mdc.traceId | سلسلة | لا | TraceId | معرف التتبع للتتبع الموزع |
mdc.spanId | سلسلة | لا | SpanId | معرف الامتداد للتتبع الموزع |
- حقل "الطابع الزمني" مطلوب، ويجب أن يكون بتنسيق UTC، وجميع الحقول الأخرى اختيارية.
- يتم استخدام "traceId" و"spanId" في حقل "mdc" لغرض التتبع.
- سجل كل سجل JSON في سطر واحد.
نموذج سجل السجل
{"timestamp":"2021-01-08T09:23:51.280Z","logger":"com.example.demo.HelloController","level":"ERROR","thread":"http-nio-1456-exec-4","mdc":{"traceId":"c84f8a897041f634","spanId":"c84f8a897041f634"},"stackTrace":"java.lang.RuntimeException: get an exception\r\n\tat com.example.demo.HelloController.throwEx(HelloController.java:54)\r\n\","message":"Got an exception","exceptionClass":"RuntimeException"}
القيود
يحتوي كل سطر من سجلات JSON على 16 كيلو بايت على الأكثر. إذا تجاوز إخراج JSON لسجل سجل واحد هذا الحد، يتم تقسيمه إلى أسطر متعددة، ويتم جمع كل سطر أولي في Log
العمود دون تحليله هيكليا.
بشكل عام، يحدث هذا الموقف على تسجيل الاستثناء باستخدام stacktrace العميق، خاصة عند تمكين AppInsights In-Process Agent . تطبيق إعدادات الحد على إخراج stacktrace (راجع نماذج التكوين أدناه) لضمان تحليل الإخراج النهائي بشكل صحيح.
إنشاء سجل JSON متوافق مع المخطط
بالنسبة لتطبيقات Spring، يمكنك إنشاء تنسيق سجل JSON متوقع باستخدام أطر عمل التسجيل الشائعة، مثل Logback وLog4j2.
تسجيل الدخول باستخدام logback
عند استخدام مبتدئين Spring Boot، يتم استخدام Logback بشكل افتراضي. بالنسبة لتطبيقات Logback، استخدم logstash-encoder لإنشاء سجل بتنسيق JSON. يتم اعتماد هذا الأسلوب في الإصدار 2.1 من Spring Boot أو أحدث.
الإجراء:
أضف تبعية logstash في ملفك
pom.xml
.<dependency> <groupId>net.logstash.logback</groupId> <artifactId>logstash-logback-encoder</artifactId> <version>6.5</version> </dependency>
قم بتحديث ملف التكوين
logback-spring.xml
لتعيين تنسيق JSON.<configuration> <appender name="stdout" class="ch.qos.logback.core.ConsoleAppender"> <encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder"> <providers> <timestamp> <fieldName>timestamp</fieldName> <timeZone>UTC</timeZone> </timestamp> <loggerName> <fieldName>logger</fieldName> </loggerName> <logLevel> <fieldName>level</fieldName> </logLevel> <threadName> <fieldName>thread</fieldName> </threadName> <nestedField> <fieldName>mdc</fieldName> <providers> <mdc /> </providers> </nestedField> <stackTrace> <fieldName>stackTrace</fieldName> <!-- maxLength - limit the length of the stack trace --> <throwableConverter class="net.logstash.logback.stacktrace.ShortenedThrowableConverter"> <maxDepthPerThrowable>200</maxDepthPerThrowable> <maxLength>14000</maxLength> <rootCauseFirst>true</rootCauseFirst> </throwableConverter> </stackTrace> <message /> <throwableClassName> <fieldName>exceptionClass</fieldName> </throwableClassName> </providers> </encoder> </appender> <root level="info"> <appender-ref ref="stdout" /> </root> </configuration>
عند استخدام ملف تكوين التسجيل مع لاحقة
-spring
، مثلlogback-spring.xml
، يمكنك تعيين تكوين التسجيل استناداً إلى ملف تعريف Spring النشط.<configuration> <springProfile name="dev"> <!-- JSON appender definitions for local development, in human readable format --> <include resource="org/springframework/boot/logging/logback/defaults.xml" /> <include resource="org/springframework/boot/logging/logback/console-appender.xml" /> <root level="info"> <appender-ref ref="CONSOLE" /> </root> </springProfile> <springProfile name="!dev"> <!-- JSON appender configuration from previous step, used for staging / production --> ... </springProfile> </configuration>
للتطوير المحلي، قم بتشغيل تطبيق Spring باستخدام وسيطة JVM
-Dspring.profiles.active=dev
، ثم يمكنك مشاهدة السجلات القابلة للقراءة البشرية بدلاً من سطور JSON المنسقة.
سجل باستخدام log4j2
بالنسبة لتطبيقات log4j2، استخدم json-template-layout لإنشاء سجل بتنسيق JSON. هذا الأسلوب مدعوم في الإصدار 2.1+ من Spring Boot.
الإجراء:
استبعد
spring-boot-starter-logging
منspring-boot-starter
، وأضف تبعياتspring-boot-starter-log4j2
،log4j-layout-template-json
في ملفpom.xml
لديك.<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <exclusions> <exclusion> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-logging</artifactId> </exclusion> </exclusions> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-log4j2</artifactId> </dependency> <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-layout-template-json</artifactId> <version>2.14.0</version> </dependency>
قم بإعداد ملف قالب تخطيط JSON
jsonTemplate.json
في مسار الفئة.{ "mdc": { "$resolver": "mdc" }, "exceptionClass": { "$resolver": "exception", "field": "className" }, "stackTrace": { "$resolver": "exception", "field": "stackTrace", "stringified": true }, "message": { "$resolver": "message", "stringified": true }, "thread": { "$resolver": "thread", "field": "name" }, "timestamp": { "$resolver": "timestamp", "pattern": { "format": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'", "timeZone": "UTC" } }, "level": { "$resolver": "level", "field": "name" }, "logger": { "$resolver": "logger", "field": "name" } }
استخدم قالب تخطيط JSON هذا في ملف التكوين
log4j2-spring.xml
.<configuration> <appenders> <console name="Console" target="SYSTEM_OUT"> <!-- maxStringLength - limit the length of the stack trace --> <JsonTemplateLayout eventTemplateUri="classpath:jsonTemplate.json" maxStringLength="14000" /> </console> </appenders> <loggers> <root level="info"> <appender-ref ref="Console" /> </root> </loggers> </configuration>
تحليل السجلات في Log Analytics
بعد إعداد التطبيق الخاص بك بشكل صحيح، يتم دفق سجل وحدة تحكم التطبيق الخاص بك إلى Log Analytics. تمكن البنية الاستعلام الفعال في Log Analytics.
التحقق من بنية السجل في Log Analytics
نفذ الإجراءات التالية:
انتقل إلى صفحة نظرة عامة على الخدمة لمثيل الخدمة.
حدد إدخال سجلات في قسم المراقبة.
قم بتشغيل هذا الاستعلام.
AppPlatformLogsforSpring | where TimeGenerated > ago(1h) | project AppTimestamp, Logger, CustomLevel, Thread, Message, ExceptionClass, StackTrace, TraceId, SpanId
ترجع سجلات التطبيق كما هو موضح في الصورة التالية:
إظهار إدخالات السجل التي تحتوي على أخطاء
لمراجعة إدخالات السجل التي بها خطأ، قم بتشغيل الاستعلام التالي:
AppPlatformLogsforSpring
| where TimeGenerated > ago(1h) and CustomLevel == "ERROR"
| project AppTimestamp, Logger, ExceptionClass, StackTrace, Message, AppName
| sort by AppTimestamp
استخدم هذا الاستعلام للبحث عن أخطاء، أو تعديل مصطلحات الاستعلام للعثور على فئة استثناء معينة أو رمز خطأ معين.
إظهار إدخالات السجل لـ traceId معين
لمراجعة إدخالات السجل لمعرف تتبع محدد "trace_id"، قم بتشغيل الاستعلام التالي:
AppPlatformLogsforSpring
| where TimeGenerated > ago(1h)
| where TraceId == "trace_id"
| project AppTimestamp, Logger, TraceId, SpanId, StackTrace, Message, AppName
| sort by AppTimestamp
الخطوات التالية
- لمعرفة المزيد حول استعلام السجل، راجع بدء استخدام استعلامات السجل في مراقبة Azure
الملاحظات
https://aka.ms/ContentUserFeedback.
قريبًا: خلال عام 2024، سنتخلص تدريجيًا من GitHub Issues بوصفها آلية إرسال ملاحظات للمحتوى ونستبدلها بنظام ملاحظات جديد. لمزيد من المعلومات، راجعإرسال الملاحظات وعرضها المتعلقة بـ