Solução de problemas relacionados à instalação do Application Signals - Amazon CloudWatch

Solução de problemas relacionados à instalação do Application Signals

Esta seção contém dicas de solução de problemas para o CloudWatch Application Signals.

Performance de inicialização a frio da camada Java do Application Signals

Adicionar a camada do Application Signals às funções Java do Lambda aumenta a latência de inicialização (tempo de inicialização a frio). As dicas a seguir podem ajudar a reduzir a latência para funções sensíveis ao tempo.

Inicialização rápida do agente Java: a camada Java para o Lambda do Application Signals inclui um recurso de inicialização rápida que é desativado por padrão, mas pode ser habilitado definindo a variável OTEL_JAVA_AGENT_FAST_STARTUP_ENABLED como true. Quando habilitado, esse recurso configura a JVM para usar o compilador C1 de compilação em camadas de nível 1 para gerar código nativo otimizado rapidamente para inicializações a frio mais rápidas. O compilador C1 prioriza a velocidade em detrimento da otimização de longo prazo, enquanto o compilador C2 fornece performance geral superior ao caracterizar dados ao longo do tempo.

Para obter mais informações, consulte Fast startup for Java agent.

Reduzir tempos de inicialização a frio com simultaneidade provisionada: a simultaneidade provisionada pelo AWS Lambda pré-aloca um número específico de instâncias de função, mantendo-as inicializadas e prontas para lidar com solicitações imediatamente. Isso reduz os tempos de inicialização a frio, eliminando a necessidade de inicializar o ambiente da função durante a execução, garantindo uma performance mais rápida e consistente, especialmente para workloads sensíveis à latência. Para obter mais informações, consulte Configurar a simultaneidade provisionada para uma função.

Otimizar a performance da inicialização usando o Lambda SnapStart: o AWS Lambda SnapStart é um recurso que otimiza a performance de inicialização das funções do Lambda criando um snapshot pré-inicializado do ambiente de execução após a fase de inicialização da função. Esse snapshot é então reutilizado para iniciar novas instâncias, reduzindo significativamente os tempos de inicialização a frio ao ignorar o processo de inicialização durante a invocação da função. Para obter informações, consulte Aprimoramento da performance de inicialização com o Lambda SnapStart.

A aplicação não inicia após a habilitação do Application Signals

Se a aplicação em um cluster do Amazon EKS não iniciar após a habilitação do Application Signals no cluster, verifique o seguinte:

  • Verifique se a aplicação foi instrumentada por outra solução de monitoramento. O Application Signals não é compatível com a coexistência com outras soluções de instrumentação.

  • Confirme se a aplicação atende aos requisitos de compatibilidade para o uso do Application Signals. Para obter mais informações, consulte Sistemas compatíveis.

  • Se não foi possível usar a aplicação para realizar a extração dos artefatos do Application Signals, como o agente em Java ou em Python do AWS Distro para OpenTelemetery e as imagens do agente do CloudWatch, pode ser um problema de rede.

Para mitigar o problema, remova a anotação instrumentation.opentelemetry.io/inject-java: "true" ou instrumentation.opentelemetry.io/inject-python: "true" do manifesto de implantação da aplicação e implante-a novamente. Em seguida, verifique se a aplicação está funcionando.

Problemas conhecidos

Sabemos que a coleção de métricas de runtime na versão v1.32.5 do Java SDK não funciona com aplicações que usam o JBoss Wildfly. Esse problema se estende ao complemento Amazon CloudWatch Observability EKS, afetando as versões 2.3.0-eksbuild.1 até 2.5.0-eksbuild.1.

Se você for afetado, faça o downgrade da versão ou desabilite a coleção de métricas de runtime adicionando a variável de ambiente OTEL_AWS_APPLICATION_SIGNALS_RUNTIME_ENABLED=false à sua aplicação.

A aplicação em Python não é iniciada após a habilitação do Application Signals

É um problema conhecido na instrumentação automática do OpenTelemetry que uma variável de ambiente PYTHONPATH ausente pode, às vezes, causar falha na inicialização da aplicação. Para resolver isso, certifique-se de definir a variável de ambiente PYTHONPATH para o local do diretório de trabalho da sua aplicação. Para obter mais informações sobre esse problema, consulte Python autoinstrumentation setting of PYTHONPATH is not compliant with Python's module resolution behavior, breaking Django applications.

Para aplicações em Django, existem configurações adicionais necessárias, descritas na documentação do OpenTelemetry em Python.

  • Use o sinalizador --noreload para evitar o recarregamento automático.

  • Defina a variável de ambiente DJANGO_SETTINGS_MODULE para o local do arquivo settings.py da sua aplicação em Django. Isso garante que o OpenTelemetry possa acessar e se integrar adequadamente às suas configurações do Django.

Não há dados do Application Signals para aplicações em Python que usam um servidor WSGI

Se você estiver usando um servidor WSGI, como Gunicorn ou uWSGI, é necessário realizar alterações adicionais para que a instrumentação automática em Python do ADOT funcione.

nota

Certifique-se de que está usando a versão mais recente do ADOT para Python e do complemento de observabilidade do EKS do Amazon CloudWatch antes de prosseguir.

Etapas adicionais para habilitar o Application Signals com um servidor WSGI
  1. Faça a importação da instrumentação automática nos processos de trabalho separados.

    Para Gunicorn, use o hook post_fork:

    # gunicorn.conf.py def post_fork(server, worker): from opentelemetry.instrumentation.auto_instrumentation import sitecustomize

    Para uWSGI, use a diretiva import:

    # uwsgi.ini [uwsgi] ; required for the instrumentation of worker processes enable-threads = true lazy-apps = true import = opentelemetry.instrumentation.auto_instrumentation.sitecustomize
  2. Habilite a configuração para a instrumentação automática em Python do ADOT com a finalidade de ignorar o processo principal e delegar para o processamento ao definir a variável de ambiente OTEL_AWS_PYTHON_DEFER_TO_WORKERS_ENABLED como true.

Minha aplicação em Node.js não está instrumentada ou não está gerando telemetria do Application Signals

Para habilitar o Application Signals para o Node.js, você deve garantir que a aplicação Node.js use o formato de módulo do CommonJS (CJS). No momento, o AWS Distro para OpenTelemetry no Node.js não é compatível com o formato de módulo do ESM, devido ao fato de que o suporte em JavaScript do OpenTelemetry ao ESM é experimental e ainda está em desenvolvimento.

Para determinar se a aplicação está usando CJS, em vez de ESM, verifique se ela não atende às condições necessárias para habilitar o ESM.

Nenhum dado da aplicação no painel do Application Signals

Se as métricas ou os rastreamentos estiverem ausentes nos painéis do Application Signals, as informações apresentadas a seguir podem ser as causas. Investigue essas causas somente se você tiver aguardado 15 minutos para que o Application Signals coletasse e exibisse dados desde a última atualização.

  • Certifique-se de que a biblioteca e a estrutura que você está usando sejam compatíveis com o agente em Java do ADOT. Para obter mais informações, consulte Libraries / Frameworks.

  • Certifique-se de que o agente do CloudWatch esteja em execução. Primeiro, verifique o status dos pods do agente do CloudWatch e certifique-se de que todos estejam com o status Running.

    kubectl -n amazon-cloudwatch get pods.

    Adicione o conteúdo apresentado a seguir ao arquivo de configuração do agente do CloudWatch para habilitar os logs de depuração e, em seguida, reinicie o agente.

    "agent": { "region": "${REGION}", "debug": true },

    Em seguida, verifique se ocorreram erros nos pods do agente do CloudWatch.

  • Verifique se há problemas de configuração com o agente do CloudWatch. Confirme se o conteúdo apresentado a seguir ainda está no arquivo de configuração do agente do CloudWatch e se o agente foi reiniciado desde que houve essa adição.

    "agent": { "region": "${REGION}", "debug": true },

    Em seguida, verifique os logs de depuração do OpenTelemetry em busca de mensagens de erro, como ERROR io.opentelemetry.exporter.internal.grpc.OkHttpGrpcExporter - Failed to export .... É possível que essas mensagens indiquem o problema.

    Se isso não resolver o problema, realize o despejo e verifique as variáveis de ambiente com nomes que começam com OTEL_ ao descrever o pod com o comando kubectl describe pod.

  • Para habilitar que o OpenTelemetry em Python depure o registro em log, defina a variável de ambiente OTEL_PYTHON_LOG_LEVEL para debug e implante a aplicação novamente.

  • Verifique se há permissões incorretas ou insuficientes para a exportação de dados do agente do CloudWatch. Se você visualizar mensagens de Access Denied nos logs do agente do CloudWatch, esse pode ser o problema. É possível que as permissões aplicadas quando você instalou o agente do CloudWatch tenham sido alteradas ou revogadas posteriormente.

  • Verifique se há um problema relacionado ao AWS Distro para OpenTelemetry (ADOT) ao gerar dados de telemetria.

    Certifique-se de que as anotações de instrumentação instrumentation.opentelemetry.io/inject-java e sidecar.opentelemetry.io/inject-java estejam aplicadas à implantação da aplicação e que o valor seja true. Sem essas anotações, os pods da aplicação não serão instrumentados, mesmo que o complemento do ADOT esteja instalado corretamente.

    Em seguida, verifique se o contêiner init está aplicado na aplicação e se o estado Ready é True. Se o contêiner init não estiver pronto, consulte o status para saber o motivo.

    Se o problema persistir, habilite o registro em log de depuração no SDK do OpenTelemetry para Java definindo a variável de ambiente OTEL_JAVAAGENT_DEBUG como true e reimplantando a aplicação. Em seguida, procure por mensagens que comecem com ERROR io.telemetry.

  • O exportador de métricas ou de extensões pode estar descartando dados. Para descobrir se isso está ocorrendo, verifique o log da aplicação em busca de mensagens que incluam Failed to export....

  • O agente do CloudWatch pode estar com controle de utilização ao enviar métricas ou extensões para o Application Signals. Verifique se há mensagens que indicam um controle de utilização nos logs do agente do CloudWatch.

  • Verifique se você habilitou a configuração de descoberta de serviços. Você precisa fazer isso somente uma vez na sua região.

    Para confirmar essa configuração, no console do CloudWatch, escolha Application Signals, Serviços. Se a Etapa 1 não estiver marcada como Concluída, escolha Começar a descobrir os serviços. Os dados devem começar a fluir em até cinco minutos.

Métricas de dependência ou de serviço têm valores desconhecidos

Se você vir UnknownService, UnknownOperation, UnknownRemoteService ou UnknownRemoteOperation para um nome de dependência ou operação nos painéis do Application Signals, verifique se a ocorrência de pontos de dados para o serviço remoto desconhecido e para a operação remota desconhecida estão coincidindo com as implantações.

  • UnknownService significa que o nome de uma aplicação instrumentada é desconhecido. Se a variável de ambiente OTEL_SERVICE_NAME for indefinida e o service.name não estiver especificado em OTEL_RESOURCE_ATTRIBUTES, o nome do serviço será definido como UnknownService. Para corrigir isso, especifique o nome do serviço em OTEL_SERVICE_NAME ou OTEL_RESOURCE_ATTRIBUTES.

  • UnknownOperation significa que o nome de uma operação invocada é desconhecido. Essa situação ocorre quando o Application Signals não consegue descobrir um nome de operação que invoque a chamada remota, ou quando o nome da operação extraída contém valores altos de cardinalidade.

  • UnknownRemoteService significa que o nome do serviço de destino é desconhecido. Essa situação ocorre quando o sistema não consegue extrair o nome do serviço de destino que a chamada remota acessa.

    Uma solução é criar um intervalo personalizado para a função que envia a solicitação e adicionar o atributo aws.remote.service com o valor designado. Outra opção é configurar o agente do CloudWatch para personalizar o valor da métrica do RemoteService. Para obter mais informações sobre personalizações no agente do CloudWatch, consulte Habilitar o CloudWatch Application Signals.

  • UnknownRemoteOperation significa que o nome da operação de destino é desconhecido. Essa situação ocorre quando o sistema não consegue extrair o nome da operação de destino que a chamada remota acessa.

    Uma solução é criar um intervalo personalizado para a função que envia a solicitação e adicionar o atributo aws.remote.operation com o valor designado. Outra opção é configurar o agente do CloudWatch para personalizar o valor da métrica do RemoteOperation. Para obter mais informações sobre personalizações no agente do CloudWatch, consulte Habilitar o CloudWatch Application Signals.

Tratamento de um ConfigurationConflict durante o gerenciamento do complemento Amazon CloudWatch Observability do EKS

Ao instalar ou atualizar o complemento Amazon CloudWatch Observability do EKS, se você perceber uma falha causada por um Health Issue do tipo ConfigurationConflict com uma descrição que começa com Conflicts found when trying to apply. Will not continue due to resolve conflicts mode, é provável que você já tenha o agente do CloudWatch e os componentes associados, como o ServiceAccount, o ClusterRole e o ClusterRoleBinding instalados no cluster. Quando o complemento tentar instalar o agente do CloudWatch e os componentes associados, se ele detectar quaisquer alterações no conteúdo, por padrão, apresentará falhas na instalação ou na atualização para evitar a substituição do estado dos recursos no cluster.

Se você estiver tentando realizar a integração do complemento Amazon CloudWatch Observability do EKS e obter essa falha, recomendamos excluir uma configuração existente do agente do CloudWatch instalada anteriormente no cluster e, em seguida, instalar o complemento do EKS. Certifique-se de fazer backup de quaisquer personalizações que você possa ter executado na configuração original do agente do CloudWatch, como uma configuração do agente personalizada, e fornecê-las ao complemento Amazon CloudWatch Observability do EKS na próxima instalação ou atualização. Se você realizou a instalação do agente do CloudWatch para a integração com o Container Insights, consulte Exclusão do agente do CloudWatch e do Fluent Bit para o Container Insights para obter mais informações.

Como alternativa, o complemento oferece suporte a uma opção de configuração de resolução de conflitos que tem a funcionalidade de especificar OVERWRITE. É possível usar essa opção para prosseguir com a instalação ou a atualização do complemento ao substituir os conflitos no cluster. Se você estiver usando o console do Amazon EKS, encontrará o Método de resolução de conflitos ao escolher as Definições de configuração opcionais na criação ou na atualização do complemento. Caso esteja usando a AWS CLI, você poderá fornecer o comando --resolve-conflicts OVERWRITE para criar ou atualizar o complemento.

Quero filtrar métricas e rastreamentos desnecessários

Se o Application Signals estiver coletando rastreamentos e métricas que você não deseja, consulte Gerenciamento de operações de alta cardinalidade para obter informações sobre como configurar o agente do CloudWatch com regras personalizadas para reduzir a cardinalidade.

Para obter informações sobre como personalizar regras de amostragem de rastreamentos, consulte Configure sampling rules na documentação do X-Ray.

O que significa InternalOperation?

Uma InternalOperation é uma operação que é acionada internamente pela aplicação e não por uma invocação externa. Ver InternalOperation é esperado, comportamento íntegro.

Alguns exemplos típicos em que você veria InternalOperation incluem o seguinte:

  • Pré-carregamento na inicialização: sua aplicação executa uma operação chamada loadDatafromDB que lê metadados de um banco de dados durante a fase de aquecimento. Em vez de observar loadDatafromDB como uma operação de serviço, você a verá categorizada como uma InternalOperation.

  • Execução assíncrona em segundo plano: sua aplicação assina uma fila de eventos e processa os dados de streaming adequadamente sempre que há uma atualização. Cada operação acionada será classificada em InternalOperation como uma operação de serviço.

  • Recuperação de informações do host de um registro de serviços: sua aplicação se comunica com um registro de serviços para a descoberta de serviços. Todas as interações com o sistema de descoberta são classificadas como uma InternalOperation.

Como habilito o registro em log para aplicações .NET?

Para habilitar o registro em log para aplicações .NET, configure as seguintes variáveis de ambiente. Para obter mais informações sobre como configurar essas variáveis de ambiente, consulte Troubleshooting .NET automatic instrumentation issues na documentação do OpenTelemetry.

  • OTEL_LOG_LEVEL

  • OTEL_DOTNET_AUTO_LOG_DIRECTORY

  • COREHOST_TRACE

  • COREHOST_TRACEFILE

Como resolvo conflitos de versão de montagem em aplicações .NET?

Se você receber o erro a seguir, consulte Assembly version conflicts na documentação do OpenTelemetry para ver as etapas de resolução.

Unhandled exception. System.IO.FileNotFoundException: Could not load file or assembly 'Microsoft.Extensions.DependencyInjection.Abstractions, Version=7.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'. The system cannot find the file specified. File name: 'Microsoft.Extensions.DependencyInjection.Abstractions, Version=7.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60' at Microsoft.AspNetCore.Builder.WebApplicationBuilder..ctor(WebApplicationOptions options, Action`1 configureDefaults) at Microsoft.AspNetCore.Builder.WebApplication.CreateBuilder(String[] args) at Program.<Main>$(String[] args) in /Blog.Core/Blog.Core.Api/Program.cs:line 26

Posso desabilitar o FluentBit?

Você pode desabilitar o FluentBit configurando o complemento de observabilidade do EKS do Amazon CloudWatch. Para obter mais informações, consulte (Opcional) Configuração adicional.

Posso filtrar logs de contêineres antes de exportar para o CloudWatch Logs?

Não, ainda não há compatibilidade para filtrar logs de contêineres.

Resolver TypeError ao usar a camada do Lambda JavaScript do AWS Distro para OpenTelemetry (ADOT)

Sua função do Lambda pode falhar com o erro TypeError - "Cannot redefine property: handler" quando você:

  • Usa a camada do Lambda JavaScript do ADOT

  • Usa esbuild para compilar o TypeScript

  • Exporta seu manipulador com a palavra-chave export

A camada do Lambda JavaScript do ADOT precisa modificar seu manipulador em tempo de execução. Quando você usa a palavra-chave export com esbuild (diretamente ou por meio do AWS CDK), esbuild torna seu manipulador imutável, evitando essas modificações.

Exporte sua função de manipulador usando module.exports em vez da palavra-chave export:

// Before export const handler = (event) => { // Handler Code }
// After const handler = async (event) => { // Handler Code } module.exports = { handler }

Atualizar para as versões necessárias dos agentes ou do complemento do Amazon EKS

Após 9 de agosto de 2024, o CloudWatch Application Signals não oferecerá mais suporte a versões anteriores do complemento de observabilidade do EKS do Amazon CloudWatch, do agente do CloudWatch e do agente de instrumentação automática do AWS Distro para OpenTelemetry.

  • Para o complemento de observabilidade do EKS do Amazon CloudWatch, as versões anteriores à v1.7.0-eksbuild.1 não serão mais compátíveis.

  • Para o agente do CloudWatch, as versões anteriores à 1.300040.0 não serão mais compatíveis.

  • Para o agente de instrumentação automática do AWS Distro para OpenTelemetry:

    • Para Java, versões mais antigas que a versão 1.32.2 não são compatíveis.

    • Para Python, versões mais antigas que a versão 0.2.0 não são compatíveis.

    • Para .NET, versões mais antigas que a versão 1.3.2 não são compatíveis.

    • Para o Node.js, as versões anteriores à 0.3.0 não são compatíveis.

Importante

As versões mais recentes dos agentes incluem atualizações no esquema métrico do Application Signals. Essas atualizações não são compatíveis com versões anteriores, o que poderá resultar em problemas de dados se versões incompatíveis forem usadas. Para ajudar a garantir uma transição ininterrupta para a nova funcionalidade, faça o seguinte:

  • Se a aplicação estiver em execução no Amazon EKS, certifique-se de reiniciar todas as aplicações instrumentadas após atualizar o complemento de observabilidade do Amazon CloudWatch.

  • Para aplicações executadas em outras plataformas, certifique-se de atualizar ambos os agentes do CloudWatch e da instrumentação automática do AWS OpenTelemetry para as versões mais recentes.

As instruções nas seções a seguir podem ajudar você a atualizar para uma versão compatível.

Atualizar o complemento de observabilidade do EKS do Amazon CloudWatch

Para o complemento de observabilidade do EKS do Amazon CloudWatch, você pode usar o AWS Management Console ou a AWS CLI.

Usar o console

Para atualizar o complemento usando o console
  1. Abra o console do Amazon EKS em https://console.aws.amazon.com/eks/home#/clusters.

  2. Escolha o nome do cluster do Amazon EKS a ser atualizado.

  3. Escolha a guia Complementos e, em seguida, escolha Observabilidade do Amazon CloudWatch.

  4. Escolha Editar, selecione a versão para a qual você deseja atualizar, e escolha Salvar alterações.

    Certifique-se de escolher v1.7.0-eksbuild.1 ou superior.

  5. Insira um dos comandos da AWS CLI a seguir para reiniciar os serviços.

    # Restart a deployment kubectl rollout restart deployment/name # Restart a daemonset kubectl rollout restart daemonset/name # Restart a statefulset kubectl rollout restart statefulset/name

Usar a AWS CLI

Para atualizar o complemento usando a AWS CLI
  1. Insira o comando a seguir para encontrar a versão mais recente.

    aws eks describe-addon-versions \ --addon-name amazon-cloudwatch-observability
  2. Insira comando a seguir para atualizar o complemento. Substitua $VERSION por uma versão que seja a v1.7.0-eksbuild.1 ou posterior. Substitua $AWS_REGION e $CLUSTER pelos nomes da região e do cluster.

    aws eks update-addon \ --region $AWS_REGION \ --cluster-name $CLUSTER \ --addon-name amazon-cloudwatch-observability \ --addon-version $VERSION \ # required only if the advanced configuration is used. --configuration-values $JSON_CONFIG
    nota

    Caso esteja usando uma configuração personalizada para o complemento, você poderá encontrar um exemplo da configuração a ser usada para $JSON_CONFIG em Habilitar o CloudWatch Application Signals.

  3. Insira um dos comandos da AWS CLI a seguir para reiniciar os serviços.

    # Restart a deployment kubectl rollout restart deployment/name # Restart a daemonset kubectl rollout restart daemonset/name # Restart a statefulset kubectl rollout restart statefulset/name

Atualizar o agente do CloudWatch e o do ADOT

Se seus serviços estiverem sendo executados em arquiteturas diferentes do Amazon EKS, você precisará atualizar o agente do CloudWatch e o da instrumentação automática do ADOT para usar os recursos mais recentes do Application Signals.

Atualizar no Amazon ECS

Para atualizar os agentes para serviços executados no Amazon ECS
  1. Crie uma nova revisão de definição de tarefa. Para obter mais informações, consulte Atualizar uma definição de tarefa usando o console.

  2. Substitua a $IMAGE do contêiner ecs-cwagent pela tag de imagem mais recente de cloudwatch-agent no Amazon ECR.

    Se você atualizar para uma versão fixa, certifique-se de usar uma versão igual ou posterior à 1.300040.0.

  3. Substitua a $IMAGE do contêiner init pela tag de imagem mais recente dos seguintes locais:

  4. Atualize as variáveis de ambiente do Application Signals no contêiner da sua aplicação seguindo as instruções em Etapa 4: instrumentalizar a aplicação com o agente do CloudWatch.

  5. Implemente seu serviço com a nova definição de tarefa.

Atualizar no Amazon EC2 ou em outras arquiteturas

Para atualizar os agentes para serviços executados no Amazon EC2 ou em outras arquiteturas
  1. Siga as instruções em Baixar o pacote do atendente do CloudWatch e atualize o agente do CloudWatch para a versão mais recente. Certifique-se de selecionar a versão 1.300040.0 ou posterior.

  2. Faça download da versão mais recente do agente de instrumentação automática do AWS Distro para OpenTelemetry para um dos seguintes locais:

  3. Aplique as variáveis de ambiente atualizadas do Application Signals em sua aplicação e a inicie. Para obter mais informações, consulte Etapa 3: instrumentalizar a aplicação e iniciá-la.