Azure Spring Apps için yapılandırılmış uygulama günlüğü

  • Makale

Not

Azure Spring Apps, Azure Spring Cloud hizmetinin yeni adıdır. Hizmetin yeni bir adı olsa da, ekran görüntüleri, videolar ve diyagramlar gibi varlıkları güncelleştirmek için çalışırken bazı yerlerde eski adı bir süre görürsünüz.

Bu makale şunlar için geçerlidir: ✔️ Temel/Standart ✔️ Kurumsal

Bu makalede, Azure Spring Apps'te yapılandırılmış uygulama günlüğü verilerinin nasıl oluşturulacağı ve topladığı açıklanır. Uygun yapılandırma ile Azure Spring Apps, Log Analytics aracılığıyla kullanışlı uygulama günlüğü sorgusu ve analizi sağlar.

Günlük şeması gereksinimleri

Günlük sorgusu deneyimini geliştirmek için bir uygulama günlüğünün JSON biçiminde olması ve şemaya uyması gerekir. Azure Spring Apps, uygulamanızı ayrıştırmak ve Log Analytics'e akış yapmak için bu şemayı kullanır.

Not

JSON günlük biçiminin etkinleştirilmesi, konsoldan günlük akışı çıktısının okunmasını zorlaştırır. okunabilir bir çıkış elde etmek için bağımsız değişkeni CLI komutuna az spring app logs ekleyin--format-json. Bkz . JSON yapılandırılmış günlüklerini biçimlendirme.

JSON şema gereksinimleri:

Json Anahtarı Json değer Türü Zorunlu Log Analytics'teki sütun Açıklama
timestamp string Yes AppTimestamp UTC biçiminde zaman damgası
Günlükçü Dize Hayır Günlükçü Günlükçü
düzey Dize Hayır CustomLevel günlük düzeyi
thread Dize Hayır İleti Dizisi thread
ileti Dize Hayır Mesaj günlük iletisi
Stacktrace Dize Hayır StackTrace özel durum yığını izleme
exceptionClass Dize Hayır ExceptionClass özel durum sınıfı adı
Mdc iç içe JSON Hayır eşlenmiş tanılama bağlamı
mdc.traceId Dize Hayır TraceId dağıtılmış izleme için izleme kimliği
mdc.spanId Dize Hayır SpanId Dağıtılmış izleme için span kimliği
  • "Zaman damgası" alanı gereklidir ve UTC biçiminde olmalıdır, diğer tüm alanlar isteğe bağlıdır.
  • İzleme amacıyla "mdc" alanındaki "traceId" ve "spanId" kullanılır.
  • Her JSON kaydını tek satırda günlüğe kaydedin.

Günlük kaydı örneği

{"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"}

Sınırlamalar

JSON günlüklerinin her satırında en fazla 16 K bayt vardır. Tek bir günlük kaydının JSON çıkışı bu sınırı aşarsa, birden çok satıra ayrılır ve her ham satır yapısal olarak ayrıştırılmadan sütuna Log toplanır.

Genellikle, bu durum özellikle Uygulama Analizler İşlem İçi Aracısı etkinleştirildiğinde derin yığın izleme ile özel durum günlüğünde gerçekleşir. Son çıkışın düzgün ayrıştırıldığından emin olmak için stacktrace çıkışına sınır ayarları uygulayın (aşağıdaki yapılandırma örneklerine bakın).

Şema uyumlu JSON günlüğü oluşturma

Spring uygulamaları için Logback ve Log4j2 gibi ortak günlük çerçevelerini kullanarak beklenen JSON günlük biçimini oluşturabilirsiniz.

Logback ile günlüğe kaydetme

Spring Boot başlatıcıları kullanılırken varsayılan olarak Logback kullanılır. Logback uygulamaları için logstash-encoder kullanarak JSON biçimli günlük oluşturun. Bu yöntem Spring Boot sürüm 2.1 veya sonraki sürümlerde desteklenir.

Yordam:

  1. Dosyanıza pom.xml logstash bağımlılığı ekleyin.

    <dependency>
    <groupId>net.logstash.logback</groupId>
    <artifactId>logstash-logback-encoder</artifactId>
    <version>6.5</version>
</dependency>

  2. JSON biçimini ayarlamak için yapılandırma dosyanızı logback-spring.xml güncelleştirin.

    <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>

  3. gibi logback-spring.xmlsonek içeren -spring günlük yapılandırma dosyasını kullanırken, Günlük yapılandırmasını Spring etkin profiline göre ayarlayabilirsiniz.

    <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>

    Yerel geliştirme için Spring uygulamasını JVM bağımsız değişkeniyle -Dspring.profiles.active=devçalıştırın, ardından JSON biçimli çizgiler yerine okunabilir günlükleri görebilirsiniz.

log4j2 ile günlük

log4j2 uygulamaları için json-template-layout kullanarak JSON biçimli günlük oluşturun. Bu yöntem Spring Boot sürüm 2.1+'da desteklenir.

Yordam:

  1. dosyasından spring-boot-starterhariç tutarak spring-boot-starter-logging bağımlılıkları log4j-layout-template-jsonspring-boot-starter-log4j2pom.xml ekleyin.

    <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>

  2. Sınıf yolunuzda bir JSON düzen şablonu dosyası jsonTemplate.json hazırlayın.

    {
    "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"
    }
}

  3. Bu JSON düzen şablonunu yapılandırma dosyanızda log4j2-spring.xml kullanın.

    <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'te günlükleri analiz etme

Uygulamanız düzgün bir şekilde ayarlandıktan sonra, uygulama konsol günlüğünüz Log Analytics'e akışla gönderilir. Yapısı Log Analytics'te verimli sorgu sağlar.

Log Analytics'te günlük yapısını denetleme

Aşağıdaki yordamı kullanın:

  1. Hizmet örneğinizin hizmete genel bakış sayfasına gidin.

  2. İzleme bölümünde Günlükler girdisini seçin.

  3. Bu sorguyu çalıştırın.

    AppPlatformLogsforSpring
| where TimeGenerated > ago(1h)
| project AppTimestamp, Logger, CustomLevel, Thread, Message, ExceptionClass, StackTrace, TraceId, SpanId

  4. Uygulama günlükleri aşağıdaki görüntüde gösterildiği gibi döner:

    Screenshot of the Azure portal showing the log Results pane.

Hata içeren günlük girdilerini göster

Hata içeren günlük girdilerini gözden geçirmek için aşağıdaki sorguyu çalıştırın:

AppPlatformLogsforSpring
| where TimeGenerated > ago(1h) and CustomLevel == "ERROR"
| project AppTimestamp, Logger, ExceptionClass, StackTrace, Message, AppName
| sort by AppTimestamp

Hataları bulmak için bu sorguyu kullanın veya belirli özel durum sınıfını veya hata kodunu bulmak için sorgu terimlerini değiştirin.

Belirli bir traceId için günlük girdilerini gösterme

Belirli bir izleme kimliği "trace_id" için günlük girdilerini gözden geçirmek için aşağıdaki sorguyu çalıştırın:

AppPlatformLogsforSpring
| where TimeGenerated > ago(1h)
| where TraceId == "trace_id"
| project AppTimestamp, Logger, TraceId, SpanId, StackTrace, Message, AppName
| sort by AppTimestamp

Sonraki adımlar