Delen via

Gestructureerd toepassingslogboek voor Azure Spring Apps

Notitie

De Basic, Standarden Enterprise--plannen zijn op 17 maart 2025 buiten gebruik gesteld. Zie de aankondiging over buitengebruikstelling van Azure Spring Apps voor meer informatie.

Het Standaardverbruik en het toegewezen-plan zijn op 30 september 2024 met een uitfasering begonnen, met een volledige beëindiging eind maart 2025. 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, wordt het moeilijker om de uitvoer van logboekstreaming vanuit 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
tijdstempel tekenreeks Ja AppTijdstempel tijdstempel in UTC-indeling
Registratiesysteem tekenreeks Nee Logger Logger
niveau tekenreeks Nee CustomLevel logboekniveau
draad tekenreeks Nee Thread discussielijn
bericht tekenreeks Nee Bericht logboekbericht
stackTrace tekenreeks Nee StackTrace uitzonderingsstacktracering
exceptionClass tekenreeks Nee Uitzonderingsklasse naam van uitzonderingsklasse
mdc geneste JSON Nee in kaart gebrachte diagnostische context
mdc.traceId tekenreeks Nee TraceId trace-ID voor gedistribueerd traceren
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-geformatteerd logbestand te genereren. Deze methode wordt ondersteund in Spring Boot versie 2.1 of hoger.

De procedure:

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

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

  3. Wanneer u het configuratiebestand voor logboekregistratie met -spring-achtervoegsel gebruikt, kunt u de configuratie voor logboekregistratie instellen op basis van het actieve Spring-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.

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

  1. Sluit spring-boot-starter-logging uit van spring-boot-starter, voeg de afhankelijkheden spring-boot-starter-log4j2 en log4j-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>

  2. 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"
    }
}

  3. Gebruik deze JSON-layoutsjabloon 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:

  1. Ga naar de overzichtspagina van uw service-instantie.

  2. Selecteer de vermelding Logboeken in de sectie Bewaking .

  3. Voer deze query uit.

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

  4. Toepassingslogboeken worden geretourneerd zoals weergegeven in de volgende afbeelding:

    Schermopname van Azure Portal met het deelvenster Resultaten van logboeken.

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