Log do aplicativo estruturado para o Azure Spring Apps

Este artigo se aplica ao: ✔️ nível Básico/Standard ✔️ nível Enterprise

Este artigo explica como gerar e coletar dados do log do aplicativo estruturado no Azure Spring Apps. Com a configuração adequada, o Azure Spring Apps fornece consulta e análise úteis de log do aplicativo por meio do Log Analytics.

Requisitos do esquema do log

Para melhorar a experiência de consulta de log, um log de aplicativo precisa estar no formato JSON e em conformidade com um esquema. O Azure Spring Apps usa esse esquema para analisar o aplicativo e transmitir para o Log Analytics.

Requisitos do esquema do JSON:

• O campo "carimbo de data/hora" é obrigatório e deve estar no formato UTC, todos os outros campos são opcionais.
• "traceId" e "spanId" no campo "mdc" são usados para fins de rastreamento.
• Registre cada registro JSON em uma linha.

Exemplo de registro de log

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

Limitações

Cada linha dos logs JSON tem no máximo 16 K bytes. Se a saída JSON de um único registro de log exceder esse limite, ela será dividida em várias linhas e cada linha bruta será coletada na coluna Log sem ser analisada estruturalmente.

Em geral, essa situação acontece no log de exceções com rastreamento de pilha profundo, especialmente quando o AppInsights In-Process Agent está habilitado. Aplique as configurações de limite à saída do rastreamento de pilha (consulte os exemplos de configuração abaixo) para garantir que a saída final seja analisada corretamente.

Gerar log JSON compatível com esquema

Para aplicativos Spring, você pode gerar o formato de log JSON esperado usando as estruturas de log comuns, como Logback e Log4j2.

Log com logback

Ao usar iniciadores Spring Boot, o Logback é usado por padrão. Para aplicativos de Logback, use logstash-encoder para gerar log formatado em JSON. Esse método tem suporte no Spring Boot versão 2.1 ou posterior.

Procedimento:

1. Adicione a dependência logstash no arquivo pom.xml.

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

2. Atualize o arquivo de configuração logback-spring.xml para definir o formato JSON.

   <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. Ao usar o arquivo de configuração de log com um sufixo -spring, como logback-spring.xml, defina a configuração de log com base no perfil ativo do Spring.

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

   Para o desenvolvimento local, execute o aplicativo Spring com o argumento JVM -Dspring.profiles.active=dev e você verá logs legíveis em vez de linhas formatadas em JSON.

Registrar com log4j2

Para aplicativos log4j2, use json-template-layout para gerar o log formatado em JSON. Esse método é compatível com o Spring Boot versão 2.1+.

Procedimento:

1. Exclua spring-boot-starter-logging de spring-boot-starter e adicione as dependências spring-boot-starter-log4j2 e log4j-layout-template-json no arquivo pom.xml.

   <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. Prepare um arquivo de modelo de layout JSON jsonTemplate.json em seu caminho de classe.

   {
       "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. Use este modelo de layout JSON em seu arquivo de configuração 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>
   

Analisar os logs no Log Analytics

Depois que o aplicativo for configurado corretamente, o log do console do aplicativo será transmitido para o Log Analytics. A estrutura permite uma consulta eficiente no Log Analytics.

Verificar a estrutura do log no Log Analytics

Use este procedimento:

1. Vá para a página Visão geral do serviço da sua instância de serviço.

2. Selecione a entrada Logs na seção Monitoramento.

3. Execute esta consulta.

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

4. Os logs de aplicativo retornam conforme mostrado na imagem a seguir:

   

Mostrar as entradas de log contendo erros

Para analisar as entradas de log que têm erro, execute a seguinte consulta:

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

Use essa consulta para localizar erros ou modificar os termos da consulta para localizar uma classe de exceção ou um código de erro específicos.

Mostrar as entradas de log para uma traceId específica

Para analisar as entradas de log de uma "trace_id" (ID de rastreamento) específica, execute a seguinte consulta:

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

Próximas etapas

• Para saber mais sobre Consulta de Log, confira Introdução às consultas de log no Azure Monitor