Como solucionar problemas de rastreamentos, segmentos ou serviços do X-Ray ausentes do mapa de serviços?

Breve descrição

Rastreamentos ausentes causam a falta de serviços no mapa de serviços. A seguir estão as causas que levam à ausência de rastreamentos:

• Instrumentação incorreta
• O SDK do X-Ray não consegue acessar o daemon do X-Ray pelo número da porta ou endereço do daemon
• O daemon do X-Ray não consegue alcançar o endpoint de serviço do X-Ray
• O rastreamento não está configurado no nível de serviço individual
• Permissões ausentes do AWS Identity and Access Management (IAM)
• Configuração de regras de amostragem
• Configuração ausente no OpenTelemetry Collector

A ausência de segmentos principais abertos para os subsegmentos pode causar a ausência de segmentos. Para obter mais informações, consulte Troubleshooting AWS X-Ray.

Resolução

Instrumentação incorreta

Instrumentação incorreta ao usar o SDK do X-Ray

Se o código do seu aplicativo não estiver corretamente instrumentado para que o SDK do X-Ray corrija as bibliotecas e estruturas compatíveis, você poderá experimentar rastreamentos ausentes. IDs de rastreamento que não são passados para os serviços posteriores também podem causar rastreamentos ausentes.

Para solucionar este problema, ative o registro em log no nível de depuração no SDK para gerar logs mais detalhados para o arquivo log do aplicativo. Isso permite isolar ainda mais os problemas que estão relacionados à instrumentação e rastrear o fluxo do ID de rastreamento no aplicativo. Os logs também indicam se um rastreamento está ausente porque o rastreamento não foi amostrado ou devido à configuração incorreta da instrumentação. Para obter mais informações, consulte o registro em log de depuração no SDK do X-Ray para Java, Node.js, Python, .NET ou Ruby.

Observação: se o aplicativo usar um agente de instrumentação automática para Java, ele não capturará rastreamentos para solicitações assíncronas e perderá rastreamentos. Se você tiver rastreamentos ausentes, use a instrumentação manual. Se o SDK do X-Ray não tiver alguns recursos ou enfrentar problemas, verifique o SDK do OpenTelemetry do agente de instrumentação automática para Java.

Instrumentação incorreta ao usar o SDK do OpenTelemetry

Se você usa o SDK do OpenTelemetry e o código do aplicativo não está corretamente instrumentado para corrigir as bibliotecas e estruturas compatíveis, o código pode apresentar rastreamentos ausentes. IDs de rastreamento que não são passados para os serviços posteriores também podem causar segmentos ausentes.

Para solucionar esse problema, realize as seguintes ações:

• Ative o registro em log em nível de depuração no SDK para enviar logs mais detalhados para o arquivo log do seu aplicativo. Isso permite isolar ainda mais os problemas relacionados à instrumentação e rastrear o fluxo do ID de rastreamento no aplicativo. Os logs indicam se um rastreamento está ausente porque o rastreamento não foi amostrado ou devido à configuração incorreta da instrumentação. Para obter mais informações, consulte o registro em log de depuração no SDK do X-Ray para Java, Node.js, Python, .NET ou Ruby.
• Certifique-se de que a sua instrumentação não esteja desligada. Para obter mais informações, consulte Suppressing specific auto-instrumentation no site da OpenTelemetry.

Observação: para enriquecer os rastreamentos com informações de infraestrutura da AWS, certifique-se de que o detector de recursos da AWS seja compatível com o serviço da AWS no SDK do OpenTelemetry. Para obter mais informações, consulte Using the AWS resource detectors.

O SDK do X-Ray não consegue acessar o daemon do X-Ray pelo número da porta ou endereço do daemon

Se o SDK do X-Ray não conseguir acessar o daemon do X-Ray pelo endereço e número da porta padrão ou configurada do daemon, o SDK perderá rastreamentos. O endereço do daemon do X-Ray passa para o SDK com a variável ambiental AWS_XRAY_DAEMON_ADDRESS. Por padrão, o daemon do X-Ray escuta na porta 2000 UDP. Você pode alterar essa porta por meio da opção de linha de comando e do arquivo de configuração que é passado para o daemon do X-Ray. Para obter mais informações, consulte Usar um arquivo de configuração.

Se você executa o daemon do X-Ray com logs de depuração, execute o seguinte comando para identificar a porta UDP configurada para o daemon do X-Ray:

./xray -l debug

Observação: o exemplo a seguir identifica 3000 como o número da porta.

Exemplo de saída:

2023-03-28T15:15:43-07:00 \[Debug\] Listening on UDP 127.0.0.1:3000

Se você não executa o daemon do X-Ray com logs de depuração, ative a opção de depurar logs e execute novamente o daemon. Para obter mais informações, consulte Usar um arquivo de configuração.

Observação: se o daemon do X-Ray não for executado na mesma máquina que o seu aplicativo e o SDK do X-Ray, verifique as regras de entrada e ingresso. Verifique se a regra de entrada do grupo de segurança e a regra de ingresso da lista de controle de acesso à rede (ACL da rede) permitem tráfego. É preciso permitir tráfego para o SDK do X-Ray pela porta de escuta do daemon do X-Ray.

O daemon do X-Ray não consegue alcançar o endpoint de serviço do X-Ray

Se o daemon do X-Ray não conseguir alcançar o endpoint de serviço do X-Ray, execute as seguintes ações:

• Se você configurou um proxy na extremidade de origem, verifique se o proxy não permite que o tráfego alcance o endpoint de serviço do X-Ray.
• Se usar o endpoint da Amazon Virtual Private Cloud (Amazon VPC) do X-Ray com.amazonaws.region.xray para se conectar ao serviço do X-Ray, verifique o grupo de segurança anexado. Certifique-se de que o grupo de segurança tenha tráfego de saída que permita que o tráfego HTTPS envie dados para a API do serviço do X-Ray. Além disso, certifique-se de que o grupo de segurança permita o tráfego de entrada na porta 443 para permitir o daemon do X-Ray.
• Verifique se a ACL da rede associada e o endpoint da Amazon VPC do X-Ray têm uma regra de saída que permite tráfego na porta 443 para qualquer lugar 0.0.0.0/0. O daemon do X-Ray deve enviar dados para o endpoint de serviço do X-Ray. Além disso, verifique se a regra de entrada da ACL da rede permite o tráfego do daemon do X-Ray para o endpoint da Amazon VPC.

O rastreamento não está configurado no nível de serviço individual

Quando você não ativa a configuração do X-Ray para determinados serviços da AWS, você pode experimentar rastreamentos ausentes. A seguir está uma lista dos serviços da AWS que exigem a ativação da configuração do X-Ray no nível do serviço:

• AWS AppSync
• AWS App Runner
• Amazon API Gateway
• Amazon CloudWatch RUM
• AWS Lambda
• Amazon Simple Notification Service (Amazon SNS)
• AWS Step Functions

Permissões ausentes do IAM

Confirme se você tem as permissões necessárias do IAM:

• Se você receber erros de Acesso negado nos logs do daemon do X-Ray, verifique as permissões do IAM. Para enviar rastreamentos para o endpoint de serviço do X-Ray, o perfil do IAM do daemon do X-Ray requer permissões na política gerenciada AWSXRAYDaemonWriteAccess. Se você usa uma condição baseada em tags em sua política do IAM, certifique-se de que a política do IAM se refira à tag correta. Para obter mais informações, consulte Authorization based on X-Ray tags.
• Se o daemon do X-Ray for executado no Amazon Elastic Container Service (Amazon ECS) como um contêiner auxiliar na tarefa, verifique o perfil da tarefa do Amazon ECS. Certifique-se de que a política AWSXRayDaemonWriteAccess esteja anexada ao perfil da tarefa do Amazon ECS.
• Se você implantar o daemon do X-Ray no Amazon Elastic Kubernetes Services (Amazon EKS), verifique o contêiner auxiliar no pod. Certifique-se de que o contêiner use perfis do IAM para contas de serviço (IRSA) e que a política AWSXRayDaemonWriteAccess esteja anexada ao perfil do IAM.
• Se você configurou o daemon do X-Ray no Amazon Elastic Compute Cloud (Amazon EC2), verifique o perfil de instância associado. Certifique-se de que a política AWSXRayDaemonWriteAccess esteja anexada ao perfil de instância que está associado a essa instância do EC2.
• Se você configurou o daemon do X-Ray no AWS Lambda, verifique o perfil de execução do Lambda. Confirme se o perfil de execução do Lambda tem a política AWSXRayDaemonWriteAccess. Certifique-se de que a política esteja anexada.
• Se você ativou o rastreamento ativo no Amazon SNS e ainda não consegue ver seus rastreamentos, configure uma política de recursos no X-Ray.

Observação: para confirmar as permissões do X-Ray, use o simulador de políticas do IAM para testar seu perfil ou política do IAM anexada ao recurso. Além disso, verifique as políticas de controle de serviços (SCPs) da sua organização. As SCPs restringem o acesso no nível da conta para chamadas de API específicas.

Para obter uma lista das políticas gerenciadas do IAM para o X-Ray, consulte IAM managed policies for X-Ray.

Configuração de regras de amostragem

Se o SDK do X-Ray e os serviços da AWS compatíveis com o rastreamento ativo com configuração de amostragem não coletarem amostras de rastreamentos, você poderá perder rastreamentos. Use regras de amostragem para determinar as solicitações a serem registradas. Por padrão, o SDK do X-Ray registra a primeira solicitação a cada segundo e 5% de todas as solicitações adicionais. Você pode alterar a taxa de amostragem para diminuir ou aumentar o número de rastreamentos registrados.

Por exemplo, um reservatório é definido como 1. Um reservatório de 1 indica que a primeira solicitação de cada segundo é atendida. Ou a taxa de amostragem é definida como 0,1. Uma taxa de amostragem de 0,1 indica que 10% das solicitações adicionais de cada segundo são registradas.

Como o SDK do X-Ray limita o número de solicitações que o SDK registra, talvez nem todas as solicitações sejam rastreadas. Para registrar mais rastreamentos, aumente as configurações do reservatório e da taxa de amostragem. Para obter mais informações, consulte Sampling rule examples.

Observação: se você configurou várias regras de amostragem e o número de rastreamentos amostrados flutuar, verifique a regra de amostragem usada pelo SDK do X-Ray. Para obter mais informações, consulte Viewing sampling results.

Configuração ausente no OpenTelemetry Collector

Se você estiver usando o OpenTelemetry Collector em vez do daemon do X-Ray, talvez a configuração necessária de receptor e exportador esteja ausente. Se uma configuração estiver ausente, os rastreamentos não serão enviados para o endpoint de serviço do X-Ray. Com base no seu receptor, verifique a configuração do receptor no arquivo config.yaml para verificar se não há nenhuma configuração ausente.

Veja esses exemplos de configurações no site do GitHub:

• Exportador do X-Ray
• Receptor do X-Ray
• Receptor ZipKin

Observação: certifique-se de que as permissões necessárias do IAM estejam na política gerenciada AWSXRayDaemonWriteAccess.