سجل التطبيقات المنظم لـ Azure Spring Apps

مقالة
02/01/2024

إشعار

يعد 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

Share via