Megosztás a következőn keresztül:

Strukturált alkalmazásnapló az Azure Spring Appshez

  • Cikk

Feljegyzés

Az Alapszintű, a Standard és a Nagyvállalati csomag 2025. március közepétől megszűnik, 3 éves nyugdíjazási időszakkal. Javasoljuk, hogy váltson az Azure Container Appsre. További információkért lásd az Azure Spring Apps kivonási bejelentését.

A standard felhasználás és a dedikált csomag 2024. szeptember 30-tól megszűnik, hat hónap után pedig teljes leállítással. Javasoljuk, hogy váltson az Azure Container Appsre. További információ: Azure Spring Apps Standard-használat migrálása és dedikált csomag az Azure Container Appsbe.

Ez a cikk a következőre vonatkozik: ✔️ Basic/Standard ✔️ Enterprise

Ez a cikk bemutatja, hogyan hozhat létre és gyűjthet strukturált alkalmazásnapló-adatokat az Azure Spring Appsben. A megfelelő konfigurációval az Azure Spring Apps hasznos alkalmazásnapló-lekérdezést és elemzést biztosít a Log Analytics használatával.

Naplóséma követelményei

A napló lekérdezési élményének javítása érdekében az alkalmazásnaplónak JSON formátumban kell lennie, és meg kell felelnie egy sémának. Az Azure Spring Apps ezzel a sémával elemzi az alkalmazást, és streameli a Log Analyticsbe.

Feljegyzés

A JSON-naplóformátum engedélyezése megnehezíti a naplóstreamelési kimenet beolvasását a konzolról. Az olvasható kimenet lekéréséhez fűzze hozzá az --format-json argumentumot a az spring app logs CLI-parancshoz. Lásd: Strukturált JSON-naplók formázása.

JSON-sémakövetelmények:

JSON-kulcs Json-érték típusa Kötelező Oszlop a Log Analyticsben Leírás
időbélyeg sztring Igen AppTimestamp időbélyeg UTC formátumban
Tuskózó húr Nem Tuskózó Tuskózó
szint húr Nem Egyéni szint naplószint
szál húr Nem Fonál szál
üzenet húr Nem Üzenet naplóüzenet
stackTrace húr Nem StackTrace kivétel verem nyomkövetése
exceptionClass húr Nem ExceptionClass kivételosztály neve
Mdc beágyazott JSON Nem megfeleltetett diagnosztikai környezet
mdc.traceId húr Nem TraceId nyomkövetési azonosító az elosztott nyomkövetéshez
mdc.spanId húr Nem SpanId elosztott nyomkövetés span ID azonosítója
  • Az "időbélyeg" mező kötelező, és UTC formátumban kell lennie, az összes többi mező nem kötelező.
  • Az "mdc" mezőben a "traceId" és a "spanId" a nyomkövetési célra szolgál.
  • Minden JSON-rekordot egy sorban naplózhat.

Naplórekord minta

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

Korlátozások

A JSON-naplók minden sora legfeljebb 16 K bájtból áll. Ha egy naplórekord JSON-kimenete meghaladja ezt a korlátot, az több sorra van bontva, és a rendszer az egyes nyers sorokat szerkezeti elemzés nélkül gyűjti be az Log oszlopba.

Ez a helyzet általában a deep stacktrace-et tartalmazó kivételnaplózáskor fordul elő, különösen akkor, ha az AppInsights Folyamaton belüli ügynök engedélyezve van. Limitbeállítások alkalmazása a stacktrace-kimenetre (lásd az alábbi konfigurációs mintákat), hogy a végső kimenet megfelelően legyen elemezve.

Séma-kompatibilis JSON-napló létrehozása

Spring-alkalmazások esetén a várt JSON-naplóformátumot olyan gyakori naplózási keretrendszerek használatával hozhatja létre, mint a Logback és a Log4j2.

Log with log with logback

A Spring Boot-kezdők használata esetén a rendszer alapértelmezés szerint a logbacket használja. A logstash-encoder használatával JSON formátumú naplót hozhat létre a logstash-encoder használatával. Ez a módszer a Spring Boot 2.1-es vagy újabb verziójában támogatott.

Az eljárás:

  1. Adja hozzá a logstash-függőséget a pom.xml fájlhoz.

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

  2. Frissítse a logback-spring.xml konfigurációs fájlt a JSON formátum beállításához.

    <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. Ha a naplózási konfigurációs fájlt olyan utótaggal -spring használja, mint a logback-spring.xmlspring active profil, beállíthatja a naplózási konfigurációt.

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

    Helyi fejlesztéshez futtassa a Spring alkalmazást JVM argumentummal -Dspring.profiles.active=dev, majd JSON formátumú sorok helyett emberi olvasható naplókat láthat.

Log with log4j2

A log4j2-alkalmazások json-template-layout használatával hozhatnak létre JSON formátumú naplót. Ez a módszer a Spring Boot 2.1+-es verziójában támogatott.

Az eljárás:

  1. Kizárás spring-boot-starter-logging a fájlbólspring-boot-starter, függőségek log4j-layout-template-json spring-boot-starter-log4j2pom.xml hozzáadása.

    <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. JSON-elrendezéssablonfájl jsonTemplate.json előkészítése az osztály elérési útjá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. Használja ezt a JSON-elrendezéssablont a log4j2-spring.xml konfigurációs fájlban.

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

Naplók elemzése a Log Analyticsben

Az alkalmazás megfelelő beállítása után az alkalmazáskonzol naplója a Log Analyticsbe lesz streamelve. A struktúra hatékony lekérdezést tesz lehetővé a Log Analyticsben.

Naplóstruktúra ellenőrzése a Log Analyticsben

Kövesse az alábbi eljárást:

  1. Nyissa meg a szolgáltatáspéldány szolgáltatásáttekintő oldalát.

  2. Válassza ki a Naplók bejegyzést a Figyelés szakaszban.

  3. Futtassa ezt a lekérdezést.

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

  4. Az alkalmazásnaplók az alábbi képen látható módon térnek vissza:

    Képernyőkép az Azure Portalról a naplóeredmények panelen.

Hibákat tartalmazó naplóbejegyzések megjelenítése

A hibával rendelkező naplóbejegyzések áttekintéséhez futtassa a következő lekérdezést:

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

Ezzel a lekérdezésrel hibákat kereshet, vagy módosíthatja a lekérdezési kifejezéseket adott kivételosztály vagy hibakód megkereséséhez.

Adott traceId naplóbejegyzéseinek megjelenítése

Ha egy adott nyomkövetési azonosító "trace_id" naplóbejegyzéseit szeretné áttekinteni, futtassa a következő lekérdezést:

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

Következő lépések