Strukturerad programlogg för Azure Spring Apps

Den här artikeln gäller för:✅ Basic/Standard ✅ Enterprise

Den här artikeln beskriver hur du genererar och samlar in strukturerade programloggdata i Azure Spring Apps. Med rätt konfiguration tillhandahåller Azure Spring Apps användbar programloggfråga och analys via Log Analytics.

Krav för loggschema

För att förbättra loggfrågeupplevelsen måste en programlogg vara i JSON-format och överensstämma med ett schema. Azure Spring Apps använder det här schemat för att parsa ditt program och strömma till Log Analytics.

JSON-schemakrav:

• Fältet "tidsstämpel" krävs och ska vara i UTC-format. Alla andra fält är valfria.
• "traceId" och "spanId" i fältet "mdc" används i spårningssyfte.
• Logga varje JSON-post på en rad.

Exempel på loggpost

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

Varje rad i JSON-loggarna har högst 16 K byte. Om JSON-utdata för en enskild loggpost överskrider den här gränsen delas den upp i flera rader och varje rårad samlas in i Log kolumnen utan att parsas strukturellt.

I allmänhet sker den här situationen vid undantagsloggning med djupgående stacktrace, särskilt när AppInsights In-Process Agent är aktiverad. Använd gränsinställningar för stacktrace-utdata (se konfigurationsexemplen nedan) för att säkerställa att de slutliga utdata parsas korrekt.

Generera schemakompatibel JSON-logg

För Spring-program kan du generera förväntat JSON-loggformat med hjälp av vanliga loggningsramverk, till exempel Logback och Log4j2.

Använd logback för att logga

När du använder Spring Boot-starter används Logback som standard. För Logback-appar använder du logstash-encoder för att generera JSON-formaterad logg. Den här metoden stöds i Spring Boot version 2.1 eller senare.

Proceduren:

1. Lägg till logstash-beroende i dinpom.xml-fil .

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

2. Uppdatera konfigurationsfilen logback-spring.xml för att ange JSON-formatet.

   <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. När du använder loggningskonfigurationsfilen med -spring suffix som logback-spring.xmlkan du ange loggningskonfigurationen baserat på den springaktiva profilen.

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

   För lokal utveckling kör du Spring-programmet med JVM-argumentet -Dspring.profiles.active=dev. Sedan kan du se loggar som kan läsas av människor i stället för JSON-formaterade rader.

Logga med log4j2

För log4j2-appar använder du json-template-layout för att generera JSON-formaterad logg. Den här metoden stöds i Spring Boot version 2.1+.

Proceduren:

1. Exkludera spring-boot-starter-logging från spring-boot-starter, lägg till beroenden spring-boot-starter-log4j2log4j-layout-template-json i dinpom.xml-fil.

   <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. Förbered en JSON-layoutmallfil jsonTemplate.json i din klasssökväg.

   {
       "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. Använd den här JSON-layoutmallen i konfigurationsfilen log4j2-spring.xml .

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

Analysera loggarna i Log Analytics

När programmet har konfigurerats korrekt strömmas programkonsolloggen till Log Analytics. Strukturen möjliggör effektiv fråga i Log Analytics.

Kontrollera loggstrukturen i Log Analytics

Använd följande procedur:

1. Gå till tjänstöversiktssidan för din tjänstinstans.

2. Välj posten Loggar i avsnittet Övervakning .

3. Kör den här sökfrågan.

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

4. Programloggar returneras enligt följande bild:

   

Visa loggposter som innehåller fel

Om du vill granska loggposter som har ett fel kör du följande fråga:

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

Använd den här frågan för att hitta fel eller ändra frågetermerna för att hitta en specifik undantagsklass eller felkod.

Visa loggposter för ett specifikt traceId

Om du vill granska loggposter för ett specifikt spårnings-ID "trace_id" kör du följande fråga:

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

Nästa steg

• Mer information om loggfrågan finns i Kom igång med loggfrågor i Azure Monitor