Configuração do Application Signals

Esta seção contém informações sobre como configurar o CloudWatch Application Signals.

Taxa de amostragem de rastreamentos

Por padrão, quando você habilita a amostragem centralizada do X-Ray para o Application Signals, a habilitação ocorre usando as configurações de taxa de amostragem padrão de reservoir=1/s e fixed_rate=5%. As variáveis ​​de ambiente para o agente do SDK para AWS Distro para OpenTelemetry (ADOT) são definidas conforme apresentado a seguir.

Para obter informações sobre como alterar a configuração de amostragem, consulte o seguinte:

Caso deseje desabilitar a amostragem centralizada do X-Ray e usar a amostragem local, defina os valores a seguir para o agente em Java do SDK para ADOT, conforme apresentado abaixo. O exemplo apresentado a seguir define a taxa de amostragem em 5%.

Para obter informações sobre configurações de amostragem mais avançadas, consulte OTEL_TRACES_SAMPLER.

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.

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

Todas essas instrumentações são fornecidas pela comunidade do OpenTelemetry. 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.

Depois de habilitar a correlação de logs de rastreamento,

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

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="FILE" class="ch.qos.logback.core.FileAppender">
  <file>app.log</file>
  <append>true</append>
  <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>
  <File name="FILE" fileName="app.log">
    <PatternLayout pattern="trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p - %m%n"/>
  </File>
</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=%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.

<appender name="FILE" class="org.apache.log4j.FileAppender">;
  <param name="File" value="app.log"/>;
  <param name="Append" value="true"/>;
  <layout class="org.apache.log4j.PatternLayout">;
    <param name="ConversionPattern" value="trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{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.

Habilitar a correlação entre métrica e logs

Se você publicar logs de aplicação em grupos de logs no CloudWatch Logs, poderá habilitar a correlação entre métrica e log de aplicação no Application Signals. Com a correlação entre log e métrica, o console do Application Signals exibe automaticamente os grupos de logs relevantes associados a uma métrica.

Por exemplo, suponha que você observe um pico no grafo de latência. Você pode escolher um ponto no gráfico para carregar as informações de diagnóstico desse ponto no tempo. As informações de diagnóstico mostrarão os grupos relevantes de logs de aplicação associados ao serviço e à métrica atuais. Em seguida, você poderá escolher um botão para executar uma consulta do CloudWatch Logs Insights nesses grupos de logs. Dependendo das informações contidas nos logs da aplicação, isso pode ajudar você a investigar a causa do pico de latência.

Dependendo da arquitetura de execução da sua aplicação, talvez também seja necessário definir uma variável de ambiente para habilitar a correlação entre métrica e log de aplicação.

Gerenciamento de operações de alta cardinalidade

O Application Signals inclui configurações no agente do CloudWatch que podem ser usadas para gerenciar a cardinalidade das operações e administrar a exportação de métricas para otimizar custos. Por padrão, a função de limitação de métricas torna-se ativa quando o número de operações distintas para um serviço ao longo do tempo excede o limite padrão de 500. É possível ajustar o comportamento ao adaptar as definições de configuração.

Como determinar se a limitação de métricas está ativada

É possível usar os métodos apresentados a seguir para descobrir se a limitação de métricas padrão está ocorrendo. Se a limitação estiver ativada, considere otimizar o controle de cardinalidade ao seguir as etapas da próxima seção.

Como otimizar o controle de cardinalidade

Para otimizar o controle de cardinalidade, é possível fazer o seguinte:

Criar regras personalizadas para agregar operações

Às vezes, as operações de alta cardinalidade podem ser causadas por valores exclusivos inadequados que foram extraídos do contexto. Por exemplo, o envio de solicitações HTTP/S que incluem IDs de usuário ou IDs de sessão no caminho pode resultar em centenas de operações diferentes. Para resolver esses problemas, recomendamos configurar o agente do CloudWatch com regras de personalização para gravar novamente essas operações.

Nos casos em que há um aumento na geração de inúmeras métricas diferentes por meio de chamadas RemoteOperation individuais, como PUT /api/customer/owners/123, PUT /api/customer/owners/456 e solicitações semelhantes, recomendamos consolidar essas operações em uma única RemoteOperation. Uma abordagem possível é padronizar todas as chamadas RemoteOperation que começam com PUT /api/customer/owners/ para um formato uniforme, especificamente PUT /api/customer/owners/{ownerId}. Isso é ilustrado no exemplo a seguir. Para obter informações sobre outras regras de personalização, consulte Habilitar o CloudWatch Application Signals.

{
   "logs":{
      "metrics_collected":{
         "application_signals":{
            "rules":[
               {
                  "selectors":[
                     {
                        "dimension":"RemoteOperation",
                        "match":"PUT /api/customer/owners/*"
                     }
                  ],
                  "replacements":[
                     {
                        "target_dimension":"RemoteOperation",
                        "value":"PUT /api/customer/owners/{ownerId}"
                     }
                  ],
                  "action":"replace"
               }
            ]
         }
      }
   }
}

Em outros casos, as métricas de alta cardinalidade podem ter sido agregadas a AllOtherRemoteOperations e pode não estar claro quais métricas específicas estão incluídas. O agente do CloudWatch é capaz de registrar em log as operações descartadas. Para identificar as operações descartadas, use a configuração apresentada no exemplo a seguir para ativar o registro em log até que o problema ocorra novamente. Em seguida, inspecione os logs do agente do CloudWatch (acessíveis por stdout do contêiner ou por arquivos de log do EC2) e pesquise a palavra-chave drop metric data.

{
  "agent": {
    "config": {
      "agent": {
        "debug": true
      },
      "traces": {
        "traces_collected": {
          "application_signals": {
          }
        }
      },
      "logs": {
        "metrics_collected": {
          "application_signals": {
            "limiter": {
              "log_dropped_metrics": true
            }
          }
        }
      }
    }
  }
}

Criar a política de limitação de métricas

Se a configuração de limitação de métricas padrão não abordar a cardinalidade para o seu serviço, será possível personalizar a configuração do limitador de métricas. Para fazê-lo, adicione uma seção limiter na seção logs/metrics_collected/application_signals no arquivo de configuração do agente do CloudWatch.

O exemplo apresentado a seguir reduz o limite de limitação de métricas de 500 métricas distintas para 100.

{
  "logs": {
    "metrics_collected": {
      "application_signals": {
        "limiter": {
          "drop_threshold": 100
        }
      }
    }
  }
}