View a markdown version of this page

Habilitar a correlação entre rastreamento e logs - Amazon CloudWatch
Exemplos de configuração de correlação de logs de rastreamento

Habilitar a correlação entre rastreamento e logs

Você pode habilitar a correlação entre rastreamento e logs no Application Signals. Isso injeta automaticamente IDs de rastreamento e IDs de spam nos logs relevantes da aplicação. Depois, ao abrir uma página de detalhes do rastreamento no console do Application Signals, as entradas de log relevantes (se houver) que se correlacionam com o rastreamento atual aparecem automaticamente na parte inferior da página.

Por exemplo, suponha que você observe um pico no grafo de latência. Você pode escolher o ponto no grafo para carregar as informações de diagnóstico desse ponto no tempo. Você então escolhe o rastreamento relevante para obter mais informações. Ao visualizar as informações do rastreamento, você pode rolar para baixo para ver os logs associados a ele. Esses logs podem revelar padrões ou códigos de erro associados aos problemas que causam o pico de latência.

Instrumentar sua aplicação antes de configurar a correlação de rastreamentos de logs

Sua aplicação já deve estar instrumentada para o Application Signals antes de você configurar a correlação de rastreamentos de logs. A instrumentação do Application Signals é o que preenche os valores de trace_id, span_id e trace_flags do MDC no runtime. Sem instrumentação, esses valores permanecem vazios (por exemplo, trace_id=) e a correlação não funciona.

Para obter a correlação de log de rastreamento, o Application Signals depende do seguinte:

A comunidade do OpenTelemetry fornece todas essas instrumentações. O Application Signals usa essas instrumentações para injetar contextos de rastreamento, como o ID do rastreamento e o ID da extensão, nos logs da aplicação. Para habilitá-las, você deve alterar manualmente sua configuração de registro em log para habilitar a instrumentação automática.

Dependendo da arquitetura em que sua aplicação é executada, talvez também seja necessário definir uma variável de ambiente para ativar a correlação de logs de rastreamento, além de seguir as etapas desta seção.

  • No Amazon EKS, nenhuma variável de ambiente adicional é necessária. Você ainda precisa configurar sua saída de logs conforme descrito nos exemplos a seguir, e seu agente de log deve gravar em stdout para que o Container Insights possa coletar os logs.

  • No Amazon ECS, nenhuma variável de ambiente adicional é necessária. Você ainda precisa configurar sua saída de logs conforme descrito nos exemplos a seguir, e seu agente de log deve gravar em stdout para que o Container Insights possa coletar os logs.

  • No Amazon EC2, consulte a etapa 4 no procedimento na Etapa 3: instrumentalizar a aplicação e iniciá-la.

O OpenTelemetry Container Insights não habilita automaticamente a correlação de rastreamentos de logs

A habilitação do caminho de coleta de logs do Container Insights baseado no OpenTelemetry (por exemplo, por meio do complemento CloudWatch Observability para EKS) coleta e envia seus logs de contêineres para o CloudWatch Logs, mas não instrumenta sua aplicação para o Application Signals nem injeta contexto de rastreamento nesses logs. Para correlacionar rastreamentos com logs, você deve habilitar separadamente a instrumentação do Application Signals e configurar seu padrão de logs conforme descrito nesta página.

Depois de habilitar a correlação de rastreamento de logs, ao abrir uma página de detalhes dos rastreamentos, as entradas de logs que contêm o mesmo ID de rastreamento aparecem automaticamente na parte inferior da página. Com a correlação de rastreamento de logs, você pode passar rapidamente de um rastreamento para os logs relevantes da aplicação sem pesquisar manualmente.

Exemplos de configuração de correlação de logs de rastreamento

Esta seção contém exemplos de como configurar a correlação de logs de rastreamento em vários ambientes.

Spring Boot para Java

Suponha que você tenha uma aplicação Spring Boot em uma pasta chamada custom-app. Geralmente, a configuração da aplicação é um arquivo YAML chamado custom-app/src/main/resources/application.yml que pode ser apresentado como abaixo: 

spring:
  application:
    name: custom-app
  config:
    import: optional:configserver:${CONFIG_SERVER_URL:http://localhost:8888/}
    
...

Para habilitar a correlação de logs de rastreamento, adicione a configuração de registro em log a seguir.

spring:
  application:
    name: custom-app
  config:
    import: optional:configserver:${CONFIG_SERVER_URL:http://localhost:8888/}
    
...    

logging:
  pattern:
    level: trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p
O Spring Boot e a configuração baseada em XML são alternativas

A abordagem application.yml (logging.pattern.level) do Spring Boot e as abordagens de configuração XML Logback/Log4j2/Log4j mostradas nas seções a seguir são alternativas. Use um ou outro, não ambos. Se você definir o padrão em application.yml, a configuração padrão Logback do Spring Boot o selecionará automaticamente e nenhum logback.xml separado será necessário.

EKS e ECS: gravar logs em stdout

O Container Insights coleta logs do stdout/stderr do contêiner, não de arquivos gravados dentro do contêiner. Configure seu agente de log para gravar no console (stdout). Um FileAppender que grava em um arquivo como app.log produz linhas com as marcas de rastreamento corretas, mas elas não são coletadas e não aparecem correlacionadas na página de detalhes dos rastreamentos. Se precisar registrar em um arquivo, você também precisará enviar esse arquivo (por exemplo, um coletor auxiliar que lê um volume compartilhado), que está fora do escopo desta página.

Logback para Java

Na configuração de registro em log (como logback.xml), insira o contexto de rastreamento trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p em pattern do codificador. Por exemplo, a configuração a seguir adiciona o contexto de rastreamento antes da mensagem de log.

<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
  <encoder> 
    <pattern>trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p - %m%n</pattern> 
  </encoder>
</appender>

Para obter mais informações sobre codificadores no Logback, consulte Encoders na documentação do Logback.

Log4j2 para Java

Na configuração de registro em log (como log4j2.xml), insira o contexto de rastreamento trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p em PatternLayout. Por exemplo, a configuração a seguir adiciona o contexto de rastreamento antes da mensagem de log.

<Appenders>
  <Console name="CONSOLE" target="SYSTEM_OUT">
    <PatternLayout pattern="trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p - %m%n"/>
  </Console>
</Appenders>

Para obter mais informações sobre layouts de padrões no Log4j2, consulte Pattern Layout na documentação do Log4j2.

Log4j para Java

Na configuração de registro em log (como log4j.xml), insira o contexto de rastreamento trace_id=%X{trace_id} span_id=%X{span_id} trace_flags=%X{trace_flags} %5p em PatternLayout. Por exemplo, a configuração a seguir adiciona o contexto de rastreamento antes da mensagem de log.

<appender name="CONSOLE" class="org.apache.log4j.ConsoleAppender">
  <layout class="org.apache.log4j.PatternLayout">
    <param name="ConversionPattern" value="trace_id=%X{trace_id} span_id=%X{span_id} trace_flags=%X{trace_flags} %5p - %m%n"/>
  </layout>
</appender>

Para obter mais informações sobre layouts de padrões no Log4j, consulte Class Pattern Layout na documentação do Log4j.

Python

Defina a variável de ambiente OTEL_PYTHON_LOG_CORRELATION como true enquanto executa sua aplicação. Para obter mais informações, consulte Enable trace context injection na documentação do OpenTelemetry para Python.

Node.js

Para obter mais informações sobre como habilitar a injeção de contextos de rastreamento em Node.js para as bibliotecas de registro em log com suporte, consulte a documentação de uso do NPM para as instrumentações automáticas do Pino, Winston ou Bunyan para Node.js.

Verificar a configuração.

Depois de reimplantar sua aplicação, confirme se uma linha de log agora mostra um trace_id preenchido (por exemplo, executando kubectl logs pod-name). Em seguida, abra uma página de detalhes de rastreamentos no console do Application Signals e confirme se as entradas de logs correlacionadas aparecem na parte inferior da página.

No Amazon EKS, os logs são gravados no grupo de logs da aplicação do Container Insights (/aws/containerinsights/cluster-name/application, ou /aws/otel/containerinsights/cluster-name/application quando o caminho de logs do Container Insights com OpenTelemetry está habilitado).