Gestructureerd toepassingslogboek voor Azure Spring Apps

Artikel
10/01/2024

Notitie

De Basic-, Standard- en Enterprise-abonnementen worden afgeschaft vanaf medio maart 2025, met een pensioenperiode van 3 jaar. We raden u aan om over te stappen naar Azure Container Apps. Zie de aankondiging over buitengebruikstelling van Azure Spring Apps voor meer informatie.

Het standaardverbruik en het speciale abonnement worden vanaf 30 september 2024 afgeschaft, met een volledige afsluiting na zes maanden. We raden u aan om over te stappen naar Azure Container Apps. Zie Azure Spring Apps Standard-verbruik en toegewezen abonnement migreren naar Azure Container Apps voor meer informatie.

Dit artikel is van toepassing op: ✔️ Basic/Standard ✔️ Enterprise

In dit artikel wordt uitgelegd hoe u gestructureerde toepassingslogboekgegevens genereert en verzamelt in Azure Spring Apps. Met de juiste configuratie biedt Azure Spring Apps nuttige query's en analyses van toepassingslogboeken via Log Analytics.

Vereisten voor logboekschema's

Om de ervaring van logboekquery's te verbeteren, moet een toepassingslogboek een JSON-indeling hebben en voldoen aan een schema. Azure Spring Apps gebruikt dit schema om uw toepassing te parseren en naar Log Analytics te streamen.

Notitie

Als u de JSON-logboekindeling inschakelt, is het lastig om de uitvoer van logboekstreaming van de console te lezen. Als u menselijke leesbare uitvoer wilt ophalen, voegt u het --format-json argument toe aan de az spring app logs CLI-opdracht. Zie Gestructureerde JSON-logboeken opmaken.

Vereisten voor JSON-schema:

Json-sleutel	Json-waardetype	Vereist	Kolom in Log Analytics	Beschrijving
timestamp	tekenreeks	Ja	AppTimestamp	tijdstempel in UTC-indeling
Logger	tekenreeks	Nee	Logger	Logger
niveau	tekenreeks	Nee	CustomLevel	logboekniveau
thread	tekenreeks	Nee	Thread	thread
bericht	tekenreeks	Nee	Bericht	logboekbericht
stackTrace	tekenreeks	Nee	StackTrace	uitzonderingsstacktracering
exceptionClass	tekenreeks	Nee	ExceptionClass	naam van uitzonderingsklasse
Mdc	geneste JSON	Nee		toegewezen diagnostische context
mdc.traceId	tekenreeks	Nee	TraceId	tracerings-id voor gedistribueerde tracering
mdc.spanId	tekenreeks	Nee	SpanId	span ID voor gedistribueerde tracering

Het veld Tijdstempel is vereist en moet de UTC-indeling hebben, alle andere velden zijn optioneel.
'traceId' en 'spanId' in het veld 'mdc' worden gebruikt voor traceringsdoeleinden.
Registreer elke JSON-record op één regel.

Voorbeeld van logboekrecord

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

Beperkingen

Elke regel van de JSON-logboeken heeft maximaal 16 K bytes. Als de JSON-uitvoer van één logboekrecord deze limiet overschrijdt, wordt deze onderverdeeld in meerdere regels en wordt elke onbewerkte regel in de Log kolom verzameld zonder structureel te worden geparseerd.

Over het algemeen treedt deze situatie op bij uitzonderingslogboeken met deep stacktrace, met name wanneer de AppInsights In-Process Agent is ingeschakeld. Pas limietinstellingen toe op de stacktrace-uitvoer (zie de onderstaande configuratievoorbeelden) om ervoor te zorgen dat de uiteindelijke uitvoer correct wordt geparseerd.

JSON-logboek genereren dat compatibel is met schema

Voor Spring-toepassingen kunt u een verwachte JSON-logboekindeling genereren met behulp van algemene frameworks voor logboekregistratie, zoals Logback en Log4j2.

Aanmelden met logback

Wanneer u Spring Boot-starters gebruikt, wordt Logback standaard gebruikt. Voor Logback-apps gebruikt u logstash-encoder om een JSON-opgemaakt logboek te genereren. Deze methode wordt ondersteund in Spring Boot versie 2.1 of hoger.

De procedure:

Voeg logstash-afhankelijkheid toe aan uw pom.xml bestand.

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

Werk uw logback-spring.xml configuratiebestand bij om de JSON-indeling in te stellen.

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

Wanneer u het configuratiebestand voor logboekregistratie met -spring achtervoegsel gebruikt, kunt logback-spring.xmlu de configuratie voor logboekregistratie instellen op basis van het Spring-actieve profiel.

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

Voor lokale ontwikkeling voert u de Spring-toepassing uit met het JVM-argument -Dspring.profiles.active=dev. Vervolgens kunt u leesbare logboeken zien in plaats van in JSON-opgemaakte regels.

Logboek met log4j2

Gebruik voor log4j2-apps json-template-layout om een JSON-opgemaakt logboek te genereren. Deze methode wordt ondersteund in Spring Boot versie 2.1+.

De procedure:

spring-boot-starterSluit spring-boot-starter-logging uit, voeg afhankelijkheden spring-boot-starter-log4j2log4j-layout-template-json toe aan uw pom.xml bestand.

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

Bereid een JSON-indelingssjabloonbestand jsonTemplate.json voor in uw klaspad.

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

Gebruik deze JSON-indelingssjabloon in uw log4j2-spring.xml configuratiebestand.

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

De logboeken analyseren in Log Analytics

Nadat uw toepassing correct is ingesteld, wordt het logboek van de toepassingsconsole gestreamd naar Log Analytics. De structuur maakt efficiënte query's mogelijk in Log Analytics.

Logboekstructuur controleren in Log Analytics

Gebruik de volgende procedure:

Ga naar de overzichtspagina van uw service-exemplaar.
Selecteer de vermelding Logboeken in de sectie Bewaking .

Voer deze query uit.

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

Toepassingslogboeken worden geretourneerd zoals weergegeven in de volgende afbeelding:

Logboekvermeldingen met fouten weergeven

Als u logboekvermeldingen met een fout wilt bekijken, voert u de volgende query uit:

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

Gebruik deze query om fouten te vinden of wijzig de querytermen om specifieke uitzonderingsklasse of foutcode te vinden.

Logboekvermeldingen voor een specifieke traceId weergeven

Als u logboekvermeldingen voor een specifieke tracerings-id 'trace_id' wilt bekijken, voert u de volgende query uit:

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

Volgende stappen

Zie Aan de slag met logboekquery's in Azure Monitor voor meer informatie over de logboekquery

Delen via