Share via

Gestructureerd toepassingslogboek voor Azure Spring Apps

  • Artikel

Notitie

Azure Spring Apps is de nieuwe naam voor de Azure Spring Cloud-service. Hoewel de service een nieuwe naam heeft, ziet u de oude naam op sommige plaatsen terwijl we werken aan het bijwerken van assets, zoals schermopnamen, video's en diagrammen.

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:

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

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

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

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

  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:

    Screenshot of the Azure portal showing the log Results pane.

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