Strukturált alkalmazásnapló az Azure Spring Appshez

Megjegyzés

A Alapszintű, Standardés Enterprise tervek 2025. március 17-én nyugdíjazási időszakba léptek. További információkért lásd az Azure Spring Apps kivonási bejelentését.

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.

Megjegyzé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	Szükséges	Oszlop a Log Analyticsben	Leírás
timestamp	karakterlánc	Yes	AppTimestamp	időbélyeg UTC formátumban
naplózó	karakterlánc	Nem	Naplózó	naplózó
szint	karakterlánc	Nem	CustomLevel	naplószint
beszélgetés	karakterlánc	Nem	Szál	beszélgetés
üzenet	karakterlánc	Nem	Üzenet	naplóüzenet
stackTrace	karakterlánc	Nem	StackTrace	kivétel-visszaverem nyomkövetése
exceptionClass	karakterlánc	Nem	ExceptionClass	kivételosztály neve
mdc	beágyazott JSON	Nem		térképezett diagnosztikai környezet
mdc.traceId	karakterlánc	Nem	TraceId	nyomkövetési azonosító az elosztott nyomkövetéshez
mdc.spanId	karakterlánc	Nem	SpanId	span ID elosztott nyomkövetéshez

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óbejegyzés 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"}

Limitations

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 In-Process-ü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.

Naplózás logback-kel

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

Az eljárás:

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>

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>

Ha a naplózási konfigurációs fájlt olyan utótaggal használja, mint a -spring, beállíthatja a naplózási konfigurációt a Spring aktív profil alapján.

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

Zárja ki spring-boot-starter-logging a spring-boot-starter fájlból, és adja hozzá a spring-boot-starter-log4j2, log4j-layout-template-json függőségeket a pom.xml fájlba.

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

Készítsen elő egy JSON sablonfájlt jsonTemplate.json 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"
    }
}

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:

Nyissa meg a szolgáltatáspéldány szolgáltatásáttekintő oldalát.
Válassza ki a Naplók bejegyzést a Figyelés szakaszban.

Futtassa ezt a lekérdezést.

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

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

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

A napló lekérdezésével kapcsolatos további információkért tekintse meg a napló lekérdezéseinek első lépéseit az Azure Monitorban

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2026-03-26