As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Escolher uma interface
AWS X-Ray pode fornecer informações sobre como seu aplicativo funciona e como ele interage com outros serviços e recursos. Depois de instrumentar ou configurar o aplicativo, o X-Ray coleta dados de rastreamento à medida que ela atende às solicitações. Você pode analisar esses dados de rastreamento para identificar problemas de desempenho, solucionar erros e otimizar recursos. Este guia mostra como interagir com o X-Ray com as seguintes diretrizes:
+ Use um Console de gerenciamento da AWS se quiser começar rapidamente ou se puder usar visualizações pré-criadas para realizar tarefas básicas.
+ Escolha o CloudWatch console da Amazon para obter a experiência de usuário mais atualizada que contém todas as funcionalidades do console X-Ray.
+ Use o console do X-Ray se quiser uma interface mais simples ou não quiser alterar a forma como você interage com o X-Ray.
+ Use um SDK se precisar de mais recursos personalizados de rastreamento, monitoramento ou registro do que um Console de gerenciamento da AWS pode fornecer.
+ Escolha o SDK do ADOT se quiser um SDK independente de fornecedor baseado no SDK do OpenTelemetry de código aberto com camadas adicionais de segurança e otimização da AWS .
+ Escolha o X-Ray SDK se quiser um SDK mais simples ou não quiser atualizar o código do aplicativo.
+ Use as operações da API do X-Ray se um SDK não for compatível com a linguagem de programação do aplicativo.
O diagrama a seguir ajuda você a escolher como interagir com o X-Ray:
![\[O X-Ray exibe informações detalhadas sobre as solicitações do aplicativo.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/xray-choose-interface.png)
**Topics**
+ [Usar um SDK](aws-xray-interface-sdk.md)
+ [Usar um console](aws-xray-interface-console.md)
+ [Usar a API do X-Ray](xray-api.md)
# Usar um SDK
**nota**
Aviso de SDK/Daemon manutenção do X-Ray — Em 25 de fevereiro de 2026, o AWS X-Ray SDKs/Daemon entrará no modo de manutenção, onde AWS limitará as versões do X-Ray SDK e do Daemon para tratar apenas de problemas de segurança. Para obter mais informações sobre a linha do tempo do suporte, consulte [Cronograma de suporte do X-Ray SDK e do Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar para o. OpenTelemetry Para obter mais informações sobre a migração para OpenTelemetry, consulte [Migrando da instrumentação X-Ray para a instrumentação](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry
Use um SDK se quiser usar uma interface de linha de comando ou precisar de mais recursos personalizados de rastreamento, monitoramento ou log do que os disponíveis em um Console de gerenciamento da AWS. Você também pode usar um AWS SDK para desenvolver programas que usem o X-Ray APIs. Você pode usar o AWS Distro for OpenTelemetry (ADOT) SDK ou o X-Ray SDK.
Ao usar um SDK, você pode adicionar personalizações ao fluxo de trabalho ao instrumentar seu aplicativo e ao configurar o coletor ou o agente. Você pode usar um SDK para realizar as seguintes tarefas, o que não é possível usando um Console de gerenciamento da AWS:
+ Publicar métricas personalizadas: avalie métricas em altas resoluções de até 1 segundo, use várias dimensões para adicionar informações sobre uma métrica e agregue pontos de dados em um conjunto de estatísticas.
+ Personalizar seu coletor: personalize a configuração de qualquer parte de um coletor, incluindo o receptor, o processador, o exportador e o conector.
+ Personalizar sua instrumentação: personalize segmentos e subsegmentos, adicione pares de valor-chave personalizados como atributos e crie métricas personalizadas.
+ Crie e atualize regras de amostragem programaticamente.
Use o ADOT SDK se quiser a flexibilidade de usar um OpenTelemetry SDK padronizado com camadas adicionais de AWS segurança e otimização. O AWS Distro for OpenTelemetry (ADOT) SDK é um pacote independente de fornecedor que permite a integração com back-ends de outros fornecedores e não prestadores de AWS serviços sem precisar reinstrumentar seu código.
Use o X-Ray SDK se você já estiver usando o X-Ray SDK, se integrar apenas com backends da AWS e não quiser alterar a maneira como interage com o X-Ray ou com o código do aplicativo.
Para obter mais informações sobre cada recurso, consulte [Escolhendo entre o AWS Distro for OpenTelemetry e o X-Ray SDKs](xray-instrumenting-your-app.md#xray-instrumenting-choosing).
## Usar o SDK do ADOT
O ADOT SDK é um conjunto de bibliotecas e agentes de código APIs aberto que enviam dados para serviços de back-end. ADOTé suportado por AWS, se integra a vários back-ends e agentes e fornece um grande número de bibliotecas de código aberto mantidas pela OpenTelemetry comunidade. Use o SDK do ADOT para instrumentar seu aplicativo e coletar logs, metadados, métricas e rastreamentos. Você também pode usar ADOT para monitorar serviços e definir um alarme com base em suas métricas em CloudWatch.
Ao usar o SDK do ADOT, você tem as seguintes opções, em combinação com um agente:
+ Use o ADOT SDK com o [CloudWatch agente](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html) — recomendado.
+ Use o ADOT SDK com o [ADOTCollector](https://aws-otel.github.io/docs/getting-started/collector) — recomendado se você quiser usar um software independente de fornecedor com AWS camadas de segurança e otimização.
Para usar o SDK do ADOT, faça o seguinte:
+ Instrumente seu aplicativo usando o SDK do ADOT. Para obter mais informações, consulte a documentação de sua linguagem de programação na [documentação técnica do ADOT](https://aws-otel.github.io/docs/introduction).
+ Configure um coletor do ADOT para informá-lo para onde enviar os dados que ele coleta.
Depois que o ADOT coletor recebe seus dados, ele os envia para o back-end especificado na ADOT configuração. ADOTpode enviar dados para vários back-ends, inclusive para fornecedores externos AWS, conforme mostrado no diagrama a seguir:
![\[Você pode personalizar o coletor do ADOT ao instrumentar seu aplicativo e configurar o coletor.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/adot-sdk.png)
AWS ADOTatualiza regularmente para adicionar funcionalidades e se alinhar à [OpenTelemetry](https://opentelemetry.io/docs/)estrutura. Atualizações e futuros planos de desenvolvimento do ADOT fazem parte de um [roteiro](https://github.com/orgs/aws-observability/projects/4) que está disponível para o público. O ADOT é compatível com várias linguagens de programação que incluem o seguinte:
+ Go
+ Java
+ JavaScript
+ Python
+ .NET
+ Ruby
+ PHP
Se você estiver usando Python, o ADOT pode instrumentar automaticamente seu aplicativo. Para começar a usarADOT, consulte [Introdução e Introdução à AWS](https://aws-otel.github.io/docs/introduction) [distribuição do OpenTelemetry Collector](https://aws-otel.github.io/docs/getting-started/collector).
## Usar o SDK do X-Ray
O X-Ray SDK é um conjunto AWS APIs e bibliotecas que enviam dados para serviços de AWS back-end. Use o X-Ray SDK para instrumentar o aplicativo e coletar dados de rastreamento. Não é possível usar o X-Ray SDK para coletar dados métricos ou de log.
Ao usar o X-Ray SDK, você tem as seguintes opções, em combinação com um agente:
+ Usar o X-Ray SDK com o [AWS X-Ray daemon](xray-daemon.md): use isso se não quiser atualizar o código do aplicativo.
+ Use o X-Ray SDK com o CloudWatch agente — (recomendado) O CloudWatch agente é compatível com o X-Ray SDK.
Para usar o X-Ray SDK, faça o seguinte:
+ Instrumente seu aplicativo usando o X-Ray SDK.
+ Configure um coletor para informá-lo para onde enviar os dados que ele coleta. Você pode usar o CloudWatch agente ou o daemon X-Ray para coletar suas informações de rastreamento.
Depois que o coletor ou agente recebe seus dados, ele os envia para um AWS back-end que você especifica na configuração do agente. O X-Ray SDK só pode enviar dados para um backend da AWS , conforme mostrado no diagrama a seguir:
![\[Use o X-Ray SDK com o CloudWatch agente ou com o daemon X-Ray.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/xray-sdk.png)
Se estiver usando o Java, você pode usar o X-Ray SDK para instrumentar automaticamente seu aplicativo. Para começar a usar o X-Ray SDK, consulte as bibliotecas associadas às seguintes linguagens de programação:
+ [Go](xray-go.md)
+ [Java](xray-java.md)
+ [Node.js](xray-nodejs.md)
+ [Python](xray-python.md)
+ [.NET](xray-dotnet.md)
+ [Ruby](xray-ruby.md)
# Usar um console
Use um console se quiser uma interface gráfica do usuário (GUI) que exija o mínimo de codificação. Os usuários iniciantes no X-Ray podem começar rapidamente a usar visualizações pré-criadas e a executar tarefas básicas. Você pode fazer o seguinte diretamente no console:
+ Habilite o X-Ray.
+ Ver resumos gerais do desempenho da aplicação.
+ Verificar a integridade de suas aplicações.
+ Identificar erros gerais.
+ Ver resumos básicos de rastreamento.
Você pode usar o console do Amazon CloudWatch em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) ou o console do X-Ray em [https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home) para interagir com o X-Ray.
## Usar o console do Amazon CloudWatch
O console do CloudWatch inclui a nova funcionalidade X-Ray que foi reprojetada a partir do console do X-Ray para facilitar o uso. Se você usar o console do CloudWatch, poderá visualizar os logs e métricas do CloudWatch juntamente com os dados de rastreamento do X-Ray. Use o console do CloudWatch para visualizar e analisar dados, incluindo os seguintes:
+ Rastreamentos do X-Ray: visualize, analise e filtre os rastreamentos associados à sua aplicação à medida que ela atende a uma solicitação. Use esses rastreamentos para encontrar altas latências, depurar erros e otimizar o fluxo de trabalho da sua aplicação. Visualize um mapa de rastreamento e um mapa de serviços para ver representações visuais do fluxo de trabalho da sua aplicação.
+ Logs: visualize, analise e filtre os logs que sua aplicação produz. Use logs para solucionar erros e configurar o monitoramento com base em valores de log específicos.
+ Métricas: meça e monitore o desempenho da sua aplicação usando métricas que seus recursos emitem ou crie suas próprias métricas. Visualize essas métricas em gráficos e tabelas.
+ Monitoramento de redes e infraestrutura: monitore as principais redes em busca de interrupções e a integridade e o desempenho de sua infraestrutura, incluindo aplicações em contêineres, outros serviços da AWS e clientes.
+ Todas as funcionalidades do console do X-Ray listadas na seção **Usar o console do X-Ray** a seguir.
Para obter mais informações sobre o console do CloudWatch, consulte [Conceitos básicos do Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/GettingStarted.html).
Faça login no console do Amazon CloudWatch em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
## Usar o console do X-Ray
O console do X-Ray oferece rastreamento distribuído para solicitações de aplicações. Use o console do X-Ray se quiser uma experiência de console mais simples ou não quiser atualizar o código do aplicativo. A AWSnão está mais desenvolvendo o console do X-Ray. O console do X-Ray contém os seguintes recursos para aplicações instrumentadas:
+ [Insights](xray-console-insights.md): detecte automaticamente anomalias no desempenho da sua aplicação e encontre as causas subjacentes. Os Insights estão incluídos no console do CloudWatch em **Insights**. Para obter mais informações, consulte **Usar insights do X-Ray** no [Usar o console do X-Ray](#xray-console).
+ Mapa de serviços: visualize uma estrutura gráfica da sua aplicação e conexões com clientes, recursos, serviços e dependências.
+ Traços: veja uma visão geral dos rastreamentos que são gerados pela sua aplicação quando ela atende a uma solicitação. Use dados de rastreamento para entender o desempenho da sua aplicação em relação às métricas básicas, incluindo resposta HTTP e tempo de resposta.
+ Análise: interprete, explore e analise dados de rastreamento usando gráficos para distribuição do tempo de resposta.
+ Configuração: crie rastreamentos personalizados para alterar as configurações padrão para o seguinte:
+ Amostragem: crie uma regra que defina a frequência da amostragem da aplicação para obter informações de rastreamento. Para obter mais informações, consulte **Configurar regras de amostragem** no [Usar o console do X-Ray](#xray-console).
+ [Criptografia](xray-console-encryption.md): criptografe dados em repouso usando uma chave que você pode auditar ou desativar usando o AWS Key Management Service.
+ Grupos: use uma expressão de filtro para definir um grupo de rastreamentos com um recurso comum, como o nome de um URL ou um tempo de resposta. Para obter mais informações, consulte [Configurar grupos](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-groups).
Faça login no console do X-Ray em [https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home).
## Explorar o console do X-Ray
Use o console do X-Ray para visualizar um mapa dos serviços e rastreamentos associados às solicitações atendidas pelas aplicações e para configurar grupos e regras de amostragem que afetam a forma como os rastreamentos são enviados ao X-Ray.
**nota**
O mapa de serviços do X-Ray e o mapa do CloudWatch ServiceLens foram combinados no mapa de rastreamento do X-Ray no console do Amazon CloudWatch. Abra o [console do CloudWatch](https://console.aws.amazon.com/cloudwatch/) e escolha **Mapa de rastreamento** em **Rastreamentos do X-Ray** no painel de navegação esquerdo.
O CloudWatch agora inclui o [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html), que pode descobrir e monitorar serviços das suas aplicações, clientes, canários do Synthetics e dependências de serviços. Use o Application Signals para ver uma lista ou um mapa visual dos seus serviços, visualizar métricas de integridade com base nos seus objetivos de nível de serviço (SLOs) e fazer uma busca profunda para ver rastreamentos do X-Ray correlacionados para uma solução de problemas mais detalhada.
A página principal do console do X-Ray é o Mapa de rastreamento, que é uma representação visual do gráfico de serviço JSON que o X-Ray gera com base nos dados de rastreamento gerados pelas aplicações. O mapa consiste em nós de serviço para cada aplicativo na sua conta que atende solicitações, nós de cliente upstream que representam as origens das solicitações e nós de serviço downstream que representam serviços da Web e recursos usados por um aplicativo ao processar uma solicitação. Há páginas adicionais para visualizar rastreamentos e detalhes de rastreamento e configurar grupos e regras de amostragem.
Veja a experiência de console do X-Ray e compare com o console do CloudWatch nas seções a seguir.
**Topics**
+ [Usar o console do Amazon CloudWatch](#aws-xray-interface-console-cw)
+ [Usar o console do X-Ray](#xray-console)
+ [Explorar o console do X-Ray](#xray-console-explore)
+ [Usar o mapa de rastreamento do X-Ray](xray-console-servicemap.md)
+ [Visualizar rastreamentos e detalhes do rastreamento](xray-console-traces.md)
+ [Usar expressões de filtro](xray-console-filters.md)
+ [Rastreamento entre contas](xray-console-crossaccount.md)
+ [Rastrear aplicações orientadas a eventos](xray-tracelinking.md)
+ [Usar histogramas de latência](xray-console-histograms.md)
+ [Usar os insights do X-Ray](xray-console-insights.md)
+ [Interagir com o console do Analytics](xray-console-analytics.md)
+ [Configurar grupos](xray-console-groups.md)
+ [Configurar regras de amostragem](xray-console-sampling.md)
+ [Configurar amostragem adaptável](xray-adaptive-sampling.md)
+ [Vinculação direta do console](xray-console-deeplinks.md)
# Usar o mapa de rastreamento do X-Ray
Visualize o mapa de rastreamento do X-Ray para identificar os serviços nos quais estão ocorrendo erros, conexões com alta latência ou rastreamentos de solicitações com erros.
**nota**
O CloudWatch agora inclui o [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html), que pode descobrir e monitorar serviços das suas aplicações, clientes, canários do Synthetics e dependências de serviços. Use o Application Signals para ver uma lista ou um mapa visual dos seus serviços, visualizar métricas de integridade com base nos seus objetivos de nível de serviço (SLOs) e fazer uma busca profunda para ver rastreamentos do X-Ray correlacionados para uma solução de problemas mais detalhada.
O mapa de serviços do X-Ray e o mapa do CloudWatch ServiceLens foram combinados no mapa de rastreamento do X-Ray no console do Amazon CloudWatch. Abra o [console do CloudWatch](https://console.aws.amazon.com/cloudwatch/) e escolha **Mapa de rastreamento** em **Rastreamentos do X-Ray** no painel de navegação esquerdo.
## Exibir o mapa de rastreamento
O mapa de rastreamento é uma representação visual dos dados de rastreamento gerados pelas aplicações. Ele mostra nós de serviço que atendem a solicitações, nós de cliente precedentes que representam as origens das solicitações e nós de serviço subsequentes que representam serviços da web e recursos usados por uma aplicação ao processar uma solicitação.
O mapa de rastreamento exibe uma visão conectada dos rastreamentos em aplicações orientadas a eventos que usam o Amazon SQS e o Lambda. Para obter mais informações, consulte [Rastrear aplicações orientadas a eventos](xray-tracelinking.md). O mapa de rastreamento também é compatível com [rastreamento entre contas](xray-console-crossaccount.md), exibindo nós de várias contas em um único mapa.
------
#### [ CloudWatch console ]
**Como visualizar o mapa de rastreamento no console do CloudWatch**
1. [Abra o console do CloudWatch](https://console.aws.amazon.com/cloudwatch/). Escolha **Mapa de rastreamento** na seção **Rastreamentos do X-Ray** no painel de navegação esquerdo.
![\[Página do mapa de rastreamento do console do CloudWatch\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/console-servicemap-cw.png)
1. Escolha um nó de serviço para visualizar solicitações desse nó ou uma borda entre dois nós para visualizar solicitações que percorreram essa conexão.
1. Informações adicionais são exibidas abaixo do mapa de rastreamento, incluindo guias para métricas, alertas e distribuição do tempo de resposta. Na guia **Métricas**, selecione um intervalo em cada gráfico para ver mais detalhes ou escolha as opções **Falhas** ou **Erros** para filtrar os rastreamentos. Na guia **Distribuição do tempo de resposta**, selecione um intervalo no gráfico para filtrar os rastreamentos por tempo de resposta.
![\[Dashboard showing latency, requests, and faults metrics for an ElasticBeanstalk environment.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/console-cw-servicemap-node-detail.png)
1. Para visualize os rastreamentos, escolha **Visualizar rastreamentos** ou, se tiver sido aplicado um filtro, selecione **Exibir rastreamentos filtrados**.
1. Escolha **Visualizar logs** para ver os logs do CloudWatch associados ao nó selecionado. Nem todos os nós do mapa de rastreamento oferecem suporte à visualização de logs. Consulte [Solução de problemas de logs do CloudWatch](xray-troubleshooting.md#xray-troubleshooting-Nologs) para obter mais informações.
O mapa de rastreamento indica problemas em cada nó por meio de cores:
+ **Vermelho** para falhas do servidor (erros da série 500)
+ **Amarelo** para erros de clientes (erros da série 400)
+ **Roxo** para erros de controle de utilização (429, muitas solicitações)
Se o mapa de rastreamento for grande, use os controles na tela ou o mouse para aumentar e diminuir o zoom e mover o mapa.
------
#### [ X-Ray console ]
**Para visualizar o mapa de serviço**
1. Abra o [console do X-Ray](https://console.aws.amazon.com/xray/home#). O mapa de serviço é exibido por padrão. Você também pode escolher **Mapa de serviço** no painel de navegação esquerdo.
![\[Página do mapa de serviço do console do X-Ray\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/console-servicemap-xray.png)
1. Escolha um nó de serviço para visualizar solicitações desse nó ou uma borda entre dois nós para visualizar solicitações que percorreram essa conexão.
1. Use o [histograma](xray-console-histograms.md) de distribuição de resposta para filtrar rastreamentos por duração e selecione códigos de status cujos rastreamentos você deseja visualizar. Em seguida, escolha **Visualizar rastreamentos** para abrir a lista de rastreamentos com a expressão de filtro aplicada.
![\[Response distribution graph showing latency peaks and service details for Scorekeep AWS ECS container.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/console-servicemap-nodedetail-xray.png)
O mapa de serviço indica a integridade de cada nó atribuindo cores a ele com base no índice de chamadas bem-sucedidas em relação a erros e falhas:
+ **Verde** para chamadas bem-sucedidas
+ **Vermelho** para falhas do servidor (erros da série 500)
+ **Amarelo** para erros de clientes (erros da série 400)
+ **Roxo** para erros de controle de utilização (429, muitas solicitações)
Se o mapa de serviço for grande, use os controles na tela ou o mouse para ampliar e reduzir e mover o mapa.
------
**nota**
O mapa de rastreamento do X-Ray pode exibir até dez mil nós. Em situações raras em que o número total de nós de serviço excede esse limite, você pode receber um erro e não conseguir exibir um mapa de rastreamento completo no console.
## Filtrar o mapa de rastreamento por grupo
Ao usar uma [expressão de filtro](xray-console-filters.md), é possível definir critérios para incluir rastreamentos em um grupo. Use as etapas a seguir para exibir esse grupo específico no mapa de rastreamento.
------
#### [ CloudWatch console ]
Escolha um nome de grupo no filtro de grupos no canto superior esquerdo do mapa de rastreamento.
![\[Search bar for filtering by X-Ray group, with "TestGroup" displayed as an option.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/console-servicemap-groups-cw.png)
------
#### [ X-Ray console ]
Escolha um nome de grupo no menu suspenso à esquerda da barra de pesquisa.
![\[Drop-down menu showing Default, TestGroup, Create group, and Learn more options.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/group-select-console.png)
------
O mapa de serviço agora será filtrado para exibir rastreamentos que correspondam à expressão de filtro do grupo selecionado.
## Legenda e opções do mapa de rastreamento
O mapa de rastreamento inclui uma legenda e várias opções para personalizar a exibição do mapa.
------
#### [ CloudWatch console ]
Escolha o menu suspenso **Legenda e opções** no canto superior direito do mapa. Escolha o que é exibido nos nós, como:
+ **Métricas**: exibem o tempo médio de resposta e o número de rastreamentos enviados por minuto durante o intervalo de tempo escolhido.
+ **Nós**: exibem o ícone do serviço em cada nó.
Escolha configurações adicionais do mapa no painel **Preferências**, que pode ser acessado por meio do ícone de engrenagem no canto superior direito do mapa. Essas configurações exigem a seleção da métrica a ser usada para determinar o tamanho de cada nó e dos canários que devem ser exibidos no mapa.
------
#### [ X-Ray console ]
Exiba a legenda do mapa de serviço escolhendo o link **Legenda do mapa** no canto superior direito do mapa. As opções do mapa de serviço podem ser escolhidas no canto inferior direito do mapa de rastreamento, como:
+ **Ícones de serviço**: alternam o que é exibido em cada nó, exibindo o ícone do serviço ou o tempo médio de resposta e o número de rastreamentos enviados por minuto durante o intervalo de tempo escolhido.
+ **Dimensionamento de nó: Nenhum** define todos os nós com o mesmo tamanho.
+ **Dimensionamento de nó: Integridade** dimensiona os nós pelo número de solicitações afetadas, incluindo erros, falhas ou solicitações com controle de utilização.
+ **Dimensionamento de nó: Tráfego** dimensiona os nós pelo número total de solicitações.
------
# Visualizar rastreamentos e detalhes do rastreamento
Use a lista **Rastreamentos** no console do X-Ray para encontrar rastreamentos por URL, código de resposta ou outros dados do resumo de rastreamentos. Depois de selecionar um rastreamento na lista de rastreamentos, a página **Detalhes de rastreamento** exibe um mapa dos nós de serviço associados ao rastreamento selecionado e uma linha do tempo dos segmentos de rastreamento.
## Visualizar os rastreamentos
------
#### [ CloudWatch console ]
**Como exibir métricas no console do CloudWatch**
1. Faça login no Console de gerenciamento da AWS e abra o console do CloudWatch em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. No painel de navegação esquerdo, escolha **Rastreamentos do X-Ray** e, em seguida, selecione **Rastreamentos**. Você pode filtrar por grupo ou inserir uma [expressão de filtro](xray-console-filters.md). Isso filtra os rastreamentos que são exibidos na seção **Rastreamentos** na parte inferior da página.
Como alternativa, os rastreamentos podem ser procurados no mapa de serviço para navegar até um nó de serviço específico e visualizar os rastreamentos. Isso abre a página **Rastreamentos** com uma consulta já aplicada.
1. Refine sua consulta na seção **Refinadores de consulta**. Para filtrar rastreamentos por um atributo comum, escolha uma opção na seta para baixo ao lado de **Refinar consulta por**. As opções incluem o seguinte:
+ Nó: filtre rastreamentos por nó de serviço.
+ ARN do recurso: filtra os rastreamentos por um recurso associado a um rastreamento. Exemplos desses recursos incluem uma instância do Amazon Elastic Compute Cloud (Amazon EC2), uma função do AWS Lambda ou uma tabela do Amazon DynamoDB.
+ Usuário: filtre rastreamentos com um ID de usuário.
+ Mensagem de causa raiz do erro: filtra os rastreamentos pela causa raiz do erro.
+ URL: filtre os rastreamentos por um caminho de URL usado pela aplicação.
+ Código de status HTTP: filtre os rastreamentos pelo código de status HTTP retornado pela aplicação. Você pode especificar um código de resposta personalizado ou selecionar uma das seguintes opções:
+ `200`: a solicitação foi concluída com êxito.
+ `401`: a solicitação não tinha credenciais de autenticação válidas.
+ `403`: a solicitação não tinha permissões válidas.
+ `404`: o servidor não conseguiu encontrar o recurso solicitado.
+ `500`: o servidor encontrou uma condição inesperada e gerou um erro interno.
Escolha uma ou mais entradas e selecione **Adicionar à consulta** para adicionar à expressão de filtro na parte superior da página.
1. Para localizar um único rastreamento, insira um [ID de rastreamento](xray-api-sendingdata.md#xray-api-traceids) diretamente no campo de consulta. Você pode usar o formato X-Ray ou o formato World Wide Web Consortium (W3C). Por exemplo, um rastreamento criado usando o [AWS Distro for OpenTelemetry](xray-instrumenting-your-app.md#xray-instrumenting-opentel) está no formato W3C.
**nota**
Ao consultar os rastreamentos criados com um ID de rastreamento no formato W3C, o console exibe o rastreamento correspondente no formato X-Ray. Por exemplo, se você consultar `4efaaf4d1e8720b39541901950019ee5` no formato W3C, o console exibirá o equivalente ao X-Ray: `1-4efaaf4d-1e8720b39541901950019ee5`.
1. Escolha **Executar consulta** a qualquer momento para exibir uma lista de rastreamentos correspondentes na seção **Rastreamentos** na parte inferior da página.
1. Para exibir a página **Detalhes do rastreamento** para um único rastreamento, selecione o respectivo ID na lista.
A imagem a seguir mostra um **Mapa de rastreamento** contendo nós de serviço associados ao rastreamento e bordas entre os nós que representam o caminho percorrido pelos segmentos que compõem o rastreamento. Um **Resumo do rastreamento** acompanha o **Mapa do rastreamento**. O resumo contém informações sobre uma operação `GET` de amostra, seu **Código de resposta**, a **Duração** que o rastreamento levou para ser executado e a **Idade** da solicitação. A **Linha do tempo dos segmentos** segue o **Resumo do rastreamento**, que mostra a duração dos segmentos e subsegmentos de rastreamento.
![\[Um mapa de rastreamento, um resumo e uma linha do tempo de segmentos detalham as informações sobre os nós de serviço e os segmentos no rastreamento.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/xray-trace-details-cw.png)
Se você tiver uma aplicação orientada a eventos que usa o Amazon SQS e o Lambda, será possível ver uma visualização conectada dos rastreamentos de cada solicitação no **Mapa de rastreamento**. No mapa, os rastreamentos dos produtores de mensagens são vinculados aos rastros dos consumidores do AWS Lambda e são exibidos como uma borda tracejada. Para obter mais informações sobre aplicações orientadas por eventos, consulte [Rastrear aplicações orientadas a eventos](xray-tracelinking.md).
As páginas **Rastreamentos** e **Detalhes de rastreamento** também permitem [rastreamento entre contas](xray-console-crossaccount.md), que pode listar rastreamentos de várias contas na lista de rastreamento e em um único mapa de rastreamento.
------
#### [ X-Ray console ]
**Como visualizar rastreamentos no console do X-Ray**
1. Abra a página [Rastreamentos](https://console.aws.amazon.com/xray/home#/traces) no console do X-Ray. O painel **Visão geral do rastreamento** mostra uma lista de rastreamentos que são agrupados por recursos comuns, incluindo **Causas raiz do erro**, **ResourceARN** e **InstanceId**.
1. Para selecionar um atributo comum para visualizar um conjunto agrupado de rastreamentos, expanda a seta para baixo ao lado de **Agrupar por**. A ilustração a seguir mostra uma visão geral dos rastreamentos agrupados por URL para o [AWS X-Ray aplicação de amostra](xray-scorekeep.md) e uma lista dos rastreamentos associados.
![\[Exemplo de visão geral do rastreamento agrupado por URL, seguido por uma lista de rastreamento com detalhes, incluindo ID, Método e Resposta.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-traces.png)
1. Escolha o **ID** de um rastreamento para visualizá-lo na **Lista de rastreamento**. Você também pode escolher **Mapa de serviços** no painel de navegação para visualizar os rastreamentos de um nó de serviço específico. Em seguida, você pode visualizar os rastreamentos associados a esse nó.
A guia **Linha do tempo** mostra o fluxo de solicitações para o rastreamento e inclui o seguinte:
+ Um mapa do caminho para cada segmento no rastreamento.
+ Quanto tempo levou para o segmento alcançar um nó no mapa de rastreamento.
+ Quantas solicitações foram feitas ao nó no mapa de rastreamento.
A ilustração a seguir mostra um exemplo de **Mapa de rastreamento** associado a uma solicitação `GET` feita a uma aplicação de amostra. As setas mostram o caminho que cada segmento percorreu para concluir a solicitação. Os nós de serviço mostram o número de solicitações feitas durante a solicitação `GET`.
![\[Mapa de rastreamento seguido por uma linha do tempo com segmentos, sua duração, origem e fim em relação um ao outro.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/xray-trace-details.png)
Para obter mais informações sobre a guia **Linha do tempo**, consulte a seção **Explorar a linha do tempo do rastreamento** a seguir.
A guia **Dados brutos** mostra informações sobre o rastreamento e os segmentos e subsegmentos que compõem o rastreamento, no formato `JSON`. Essas informações podem incluir o seguinte:
+ Carimbos de data/hora
+ IDs exclusivos
+ Recursos associados ao segmento ou subsegmento
+ A fonte ou origem do segmento ou subsegmento
+ Informações adicionais sobre a solicitação à sua aplicação, como a resposta de uma solicitação HTTP
------
## Explorar a linha do tempo do rastreamento
A seção **Linha do tempo** mostra uma hierarquia de segmentos e subsegmentos ao lado de uma barra horizontal que corresponde ao tempo que eles usaram para concluir suas tarefas. A primeira entrada na lista é o segmento, que representa todos os dados registrados pelo serviço para uma única solicitação. Os subsegmentos são indentados e listados após o segmento. As colunas contêm informações sobre cada segmento.
------
#### [ CloudWatch console ]
No console do CloudWatch, a **Linha do tempo dos segmentos** fornece as seguintes informações:
+ A primeira coluna: lista os segmentos e subsegmentos no rastreamento selecionado.
+ A coluna **Status do segmento**: lista o resultado do status de cada segmento e subsegmento.
+ A coluna **Código de resposta**: lista um código de status de resposta HTTP para uma solicitação do navegador feita pelo segmento ou subsegmento, quando disponível.
+ A coluna **Duração**: lista por quanto tempo o segmento ou subsegmento foi executado.
+ A coluna **Hospedado em**: lista o namespace ou o ambiente em que o segmento ou subsegmento é executado, se aplicável. Para obter mais informações, consulte [Dimensões coletadas e combinações de dimensões](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AppSignals-StandardMetrics.html#AppSignals-StandardMetrics-Dimensions).
+ A última coluna: exibe barras horizontais que correspondem à duração da execução do segmento ou subsegmento, em relação aos outros segmentos ou subsegmentos na linha do tempo.
Para agrupar a lista de segmentos e subsegmentos por nó de serviço, ative **Agrupar por nós**.
------
#### [ X-Ray console ]
Na página de detalhes do rastreamento, escolha a guia **Linha do tempo** para ver a linha do tempo de cada segmento e subsegmento que compõe um rastreamento.
No console do X-Ray, a **Linha do tempo** fornece as seguintes informações:
+ A coluna **Nome**: lista os nomes dos segmentos e subsegmentos no rastreamento.
+ A coluna **Res.**: lista um código de status de resposta HTTP para uma solicitação do navegador feita pelo segmento ou subsegmento, quando disponível.
+ A coluna **Duração**: lista por quanto tempo o segmento ou subsegmento foi executado.
+ A coluna **Status**: lista o resultado do status do segmento ou subsegmento.
+ A última coluna: exibe barras horizontais que correspondem à duração da execução do segmento ou subsegmento, em relação aos outros segmentos ou subsegmentos na linha do tempo.
Para ver os dados de rastreamento brutos que o console usa para gerar a linha do tempo, escolha a guia **Dados brutos**. Os dados brutos mostram informações sobre o rastreamento e os segmentos e subsegmentos que compõem o rastreamento no formato `JSON`. Essas informações podem incluir o seguinte:
+ Carimbos de data/hora
+ IDs exclusivos
+ Recursos associados ao segmento ou subsegmento
+ A fonte ou origem do segmento ou subsegmento
+ Informações adicionais sobre a solicitação à sua aplicação, como a resposta de uma solicitação HTTP.
------
Quando você usa um SDK instrumentado da AWS, HTTP ou cliente SQL para fazer chamadas para recursos externos, o SDK do X-Ray registra os subsegmentos automaticamente. Você também pode usar o SDK do X-Ray para registrar subsegmentos personalizados para qualquer função ou bloco de código. Subsegmentos adicionais registrados enquanto um subsegmento personalizado estiver aberto tornam-se filhos do subsegmento personalizado.
## Visualizar os detalhes do segmento
Na **Linha do tempo** do rastreamento, escolha o nome de um segmento para visualizar seus detalhes.
O painel de **Detalhes do segmento** mostra as guias **Visão geral**, **Recursos**, **Anotações**, **Metadados**, **Exceções** e **SQL**. O seguinte se aplica:
+ A guia **Overview (Visão geral)** mostra informações sobre a solicitação e a resposta. As informações incluem o nome, a hora de início, a hora de término, a duração, o URL da solicitação, a operação da solicitação, o código de resposta da solicitação e quaisquer erros e falhas.
+ A guia **Recursos** de um segmento mostra informações sobre o SDK do X-Ray e os recursos da AWS em execução na aplicação. Use os plug-ins Amazon EC2, AWS Elastic Beanstalk ou Amazon ECS para o SDK do X-Ray para registrar informações de recursos específicas do serviço. Para obter mais informações sobre plug-ins, consulte a seção **Plug-ins de serviço** em [Configurar o X-Ray SDK para Java](xray-sdk-java-configuration.md).
+ As guias restantes mostram **Anotações**, **Metadados** e **Exceções** registrados no segmento. As exceções são capturadas automaticamente quando geradas de uma solicitação instrumentada. As anotações e os metadados contêm informações adicionais que são registradas usando as operações fornecidos pelo SDK do X-Ray. Para adicionar anotações ou metadados a seus segmentos, use o SDK do X-Ray. Para obter mais informações, consulte o link específico do idioma listado em Instrumentar sua aplicação com SDKs do AWS X-Ray em [Instrumentando seu aplicativo para AWS X-Ray](xray-instrumenting-your-app.md).
## Visualizar os detalhes do subsegmento
Na linha do tempo do rastreamento, escolha o nome de um subsegmento para visualizar os respectivos detalhes.
+ A guia **Visão geral** contém informações sobre a solicitação e a resposta. Isso inclui o nome, a hora de início, a hora de término, a duração, o URL da solicitação, a operação da solicitação, o código de resposta da solicitação e quaisquer erros e falhas. Para subsegmentos gerados com clientes instrumentados, a guia **Overview (Visão geral)** contém informações sobre a solicitação e a resposta do ponto de vista do seu aplicativo.
+ A guia **Recursos** de um subsegmento mostra detalhes sobre os recursos da AWS que foram usados para executar o subsegmento. Por exemplo, a guia de recursos pode incluir um ARN de função do AWS Lambda, informações sobre uma tabela do DynamoDB, qualquer operação chamada e o ID da solicitação.
+ As guias restantes mostram **Anotações**, **Metadados** e **Exceções** registrados no subsegmento. As exceções são capturadas automaticamente quando geradas de uma solicitação instrumentada. As anotações e os metadados contêm informações adicionais que são registradas usando as operações fornecidos pelo SDK do X-Ray. Use o SDK do X-Ray para adicionar anotações ou metadados a seus segmentos. Para obter mais informações, consulte o link específico do idioma listado em **Instrumentar sua aplicação com SDKs do AWS X-Ray** em [Instrumentando seu aplicativo para AWS X-Ray](xray-instrumenting-your-app.md).
Para subsegmentos personalizados, a guia **Overview (Visão geral)** mostra o nome do subsegmento, que é possível definir para especificar a área do código ou a função que ele registra. Para obter mais informações, consulte o link específico do idioma listado em **Instrumentar sua aplicação com SDKs do AWS X-Ray** em [Gerar subsegmentos personalizados com o X-Ray SDK para Java](xray-sdk-java-subsegments.md).
A imagem a seguir mostra a guia **Visão geral** de um subsegmento personalizado. A visão geral contém o ID do subsegmento, o ID principal, o nome, os horários de início e término, a duração, o status e os erros ou falhas.
![\[Informações gerais sobre um subsegmento, incluindo ID, ID principal, nome, horários, erros e falhas.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-PUTrules-customsubsegment-overview.png)
A guia **Metadados** de um subsegmento personalizado contém informações no formato JSON sobre os recursos usados por esse subsegmento.
# Usar expressões de filtro
Use *expressões de filtro* para visualizar rastreamentos ou um mapa de rastreamento para uma solicitação específica, um serviço, uma conexão entre dois serviços (uma borda) ou solicitações que satisfazem uma condição. O X-Ray fornece uma linguagem de expressão de filtro para filtrar solicitações, serviços e bordas com base em dados em cabeçalhos de solicitação, status de resposta e campos indexados nos segmentos originais.
Ao escolher um período de rastreamento para visualizar no console do X-Ray, você pode obter mais resultados do que o console é capaz de exibir. No canto superior direito, o console mostra o número de rastreamentos que verificou e se há mais rastreamentos disponíveis. É possível usar uma expressão de filtro para estreitar os resultados a apenas rastreamentos que você deseja localizar.
**Topics**
+ [Detalhes de expressão de filtro](#xray-console-filters-details)
+ [Usar expressões de filtro com grupos](#groups)
+ [Sintaxe de expressão de filtro](#console-filters-syntax)
+ [Palavras-chave boolianas](#console-filters-boolean)
+ [Palavras-chave de número](#console-filters-number)
+ [Palavras-chave de string](#console-filters-string)
+ [Palavras-chave complexas](#console-filters-complex)
+ [Função id](#console-filters-functions)
## Detalhes de expressão de filtro
Quando você [escolhe um nó no mapa de rastreamento](xray-console-servicemap.md), o console cria uma expressão de filtro com base no nome do serviço do nó e nos tipos de erro presentes com base em sua seleção. Para encontrar rastreamentos que mostram problemas de desempenho ou relacionados a solicitações específicas, é possível ajustar a expressão fornecida pelo console ou criar a sua própria. Se você adicionar anotações com o X-Ray SDK, poderá também filtrar com base na presença de uma chave de anotação ou no valor de uma chave.
**nota**
Se você escolher um intervalo de tempo relativo no mapa de rastreamento e escolher um nó, o console converterá o intervalo de tempo em uma hora de início e de término absoluta. Para garantir que os rastreamentos do nó apareçam nos resultados da pesquisa e evitar tempos de verificação quando o nó não estava ativo, o intervalo de tempo inclui apenas as horas em que o nó enviou rastreamentos. Para pesquisar com relação à hora atual, é possível voltar a um intervalo de tempo relativo na página de rastreamentos e verificar novamente.
Se ainda houver mais resultados disponíveis além do que o console pode mostrar, o console mostrará o número de rastreamentos correspondidos e o número de rastreamentos verificados. A porcentagem mostrada é a porcentagem do intervalo de tempo selecionado que foi verificado. Para garantir que você veja todos os rastreamentos correspondentes representados nos resultados, restrinja mais sua expressão de filtro ou escolha um limite de tempo mais curto.
Para obter os resultados mais recentes primeiro, o console inicia a verificação no final do intervalo de tempo e trabalha retroativamente. Se houver um grande número de rastreamentos, mas poucos resultados, o console dividirá o intervalo de tempo em partes e os verificará em paralelo. A barra de progresso mostra as partes do intervalo de tempo que foram verificadas.
![\[Progress bar showing 52% of time range scanned, with 49 matching traces found.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/console-tracescan-parallel.png)
## Usar expressões de filtro com grupos
Os grupos são uma coleção de rastreamentos definidos por uma expressão de filtro. Você pode usar grupos para gerar gráficos de serviços adicionais e fornecer CloudWatch métricas da Amazon.
Os grupos são identificados pelo nome ou pelo nome do recurso da Amazon (ARN) e contêm uma expressão de filtro. O serviço compara os rastreamentos de entrada com a expressão e os armazena adequadamente.
É possível criar e modificar grupos usando o menu suspenso à esquerda da barra de pesquisa da expressão de filtro.
**nota**
Se o serviço encontrar um erro na qualificação de um grupo, esse grupo não estará mais incluído no processamento de rastreamentos de entrada e uma métrica de erro será registrada.
Para obter mais informações sobre grupos, consulte [Configurar grupos](xray-console-groups.md).
## Sintaxe de expressão de filtro
As expressões de filtro podem conter uma *palavra-chave*, um *operador* unário ou binário e um *valor* para comparação.
```
keyword operator value
```
Operadores diferentes estão disponíveis para tipos diferentes de palavras-chave. Por exemplo, `responsetime` é uma palavra-chave de número e pode ser comparada com os operadores relacionados a números.
**Example Exemplo: solicitações em que o tempo de resposta foi superior a 5 segundos**
```
responsetime > 5
```
É possível combinar várias expressões em uma expressão composta usando os operadores `AND` ou `OR`.
**Example Exemplo: solicitações em que a duração total foi de 5 a 8 segundos**
```
duration >= 5 AND duration <= 8
```
Palavras-chave e operadores simples encontram problemas apenas no nível de rastreamento. Se ocorrer um erro de downstream, mas é controlado pelo seu aplicativo e não retornado ao usuário, uma pesquisa por `error` não o encontrará.
Para encontrar rastreamentos com problemas de downstream, use as [palavras-chave complexas](#console-filters-complex) `service()` e `edge()`. Essas palavras-chave permitem que você aplique uma expressão de filtro a todos os nós de downstream, um único nó de downstream ou uma borda entre dois nós. Para obter mais granularidade, filtre os serviços e bordas por tipo com [a função id()](#console-filters-functions).
## Palavras-chave boolianas
Os valores de palavras-chave boolianas são verdadeiros ou falsos. Use essas palavras-chave para encontrar rastreamentos que resultaram em erros.
**Palavras-chave boolianas**
+ `ok`: o código de status da resposta foi 2XX Êxito.
+ `error`: o código de status da resposta foi 4XX Erro do cliente.
+ `throttle`: o código de status da resposta foi 429 Solicitações em excesso.
+ `fault`: o código de status da resposta foi 5XX Erro do servidor.
+ `partial`: a solicitação tem segmentos incompletos.
+ `inferred`: a solicitação inferiu segmentos.
+ `first`: o elemento é o primeiro de uma lista enumerada.
+ `last`: o elemento é o último de uma lista enumerada.
+ `remote`: a entidade de causa raiz é remota.
+ `root`: o serviço é o ponto de entrada ou o segmento raiz de um rastreamento.
Os operadores boolianos encontram segmentos onde a chave especificada é `true` ou `false`.
**Operadores boolianos**
+ none: a expressão é verdadeira se a palavra-chave for verdadeira.
+ `!`: a expressão é verdadeira se a palavra-chave for falsa.
+ `=`,`!=`: compara o valor da palavra-chave com a string `true` ou `false`. Estes operadores agem da mesma forma que os outros operadores, mas são mais explícitos.
**Example Exemplo: o status de resposta é 2XX OK**
```
ok
```
**Example Exemplo: o status de resposta não é 2XX OK**
```
!ok
```
**Example Exemplo: o status de resposta não é 2XX OK**
```
ok = false
```
**Example Exemplo: o último rastreamento de falha enumerado tem o nome de erro "deserialize"**
```
rootcause.fault.entity { last and name = "deserialize" }
```
**Example Exemplo: solicitações com segmentos remotos em que a cobertura é maior que 0,7 e o nome do serviço é "traces"**
```
rootcause.responsetime.entity { remote and coverage > 0.7 and name = "traces" }
```
**Example Exemplo: solicitações com segmentos inferidos em que o tipo de serviço é "AWS:DynamoDB"**
```
rootcause.fault.service { inferred and name = traces and type = "AWS::DynamoDB" }
```
**Example Exemplo: solicitações que têm um segmento com o nome "data-plane" como raiz**
```
service("data-plane") {root = true and fault = true}
```
## Palavras-chave de número
Use palavras-chave de número para pesquisar solicitações com um tempo de resposta, duração ou status de resposta específico.
**Palavras-chave de número**
+ `responsetime`: o tempo que o servidor levou para enviar uma resposta.
+ `duration`: duração total da solicitação, incluindo todas as chamadas subsequentes.
+ `http.status`: código de status da resposta.
+ `index`: posição de um elemento em uma lista enumerada.
+ `coverage`: porcentagem decimal do tempo de resposta da entidade sobre o tempo de resposta do segmento raiz. Aplicável apenas para entidades de causa raiz de tempo de resposta.
**Operadores de número**
Palavras-chave de número usam operadores padrão de igualdade e comparação.
+ `=`,`!=`: a palavra-chave é igual ou não a um valor numérico.
+ `<`,`<=`, `>`,`>=`: a palavra-chave é menor ou maior do que um valor numérico.
**Example Exemplo: o status de resposta não é 200 OK**
```
http.status != 200
```
**Example Exemplo: solicitação em que a duração total foi de 5 a 8 segundos**
```
duration >= 5 AND duration <= 8
```
**Example Exemplo: solicitações que foram concluídas com êxito em menos de 3 segundos, incluindo todas as chamadas subsequentes**
```
ok !partial duration <3
```
**Example Exemplo: entidade de lista enumerada que tem um índice maior que 5**
```
rootcause.fault.service { index > 5 }
```
**Example Exemplo: solicitações em que a última entidade tem cobertura superior a 0,8**
```
rootcause.responsetime.entity { last and coverage > 0.8 }
```
## Palavras-chave de string
Use palavras-chave de string para encontrar traços com texto específico nos cabeçalhos da solicitação ou em um usuário IDs específico.
**Palavras-chave de string**
+ `http.url`: URL da solicitação.
+ `http.method`: método da solicitação.
+ `http.useragent`: string do agente de usuário da solicitação.
+ `http.clientip`: endereço IP do solicitante.
+ `user`: valor do campo de usuário em qualquer segmento no rastreamento.
+ `name`: o nome de um serviço ou exceção.
+ `type`: tipo de serviço.
+ `message`: mensagem de exceção.
+ `availabilityzone`: valor do campo da zona de disponibilidade em qualquer segmento no rastreamento.
+ `instance.id`: valor do campo de ID da instância em qualquer segmento no rastreamento.
+ `resource.arn`: valor do campo de ARN do recurso em qualquer segmento no rastreamento.
Os operadores de string encontram valores que são iguais a ou contêm um texto específico. Os valores devem sempre ser especificados entre aspas.
**Operadores de string**
+ `=`,`!=`: a palavra-chave é igual ou não a um valor numérico.
+ `CONTAINS`: a palavra-chave contém uma string específica.
+ `BEGINSWITH`,`ENDSWITH`: a palavra-chave começa ou termina com uma string específica.
**Example Exemplo: filtro http.url**
```
http.url CONTAINS "/api/game/"
```
Para testar se um campo existe em um rastreamento, independentemente do seu valor, verifique se ele contém a string vazia.
**Example Exemplo: filtro do usuário**
Encontre todos os rastros com o usuário IDs.
```
user CONTAINS ""
```
**Example Exemplo: selecionar rastreamentos com uma causa raiz de falha que inclua um serviço chamado "Auth"**
```
rootcause.fault.service { name = "Auth" }
```
**Example Exemplo: selecionar rastreamentos com uma causa raiz de tempo de resposta cujo último serviço tenha um tipo do DynamoDB**
```
rootcause.responsetime.service { last and type = "AWS::DynamoDB" }
```
**Example Exemplo: selecionar rastreamentos com uma causa raiz de falha cuja última exceção tenha a mensagem "Access Denied for account\$1id: 1234567890"**
```
rootcause.fault.exception { last and message = "Access Denied for account_id: 1234567890"
```
## Palavras-chave complexas
Use palavras-chave complexas para encontrar solicitações com base no nome do serviço, no nome de borda ou no valor de anotação. Para serviços e bordas, você pode especificar uma expressão de filtro adicional que se aplica ao serviço ou borda. Para anotações, é possível filtrar pelo valor de uma anotação com uma chave específica usando operadores boolianos, de número ou de string.
**Palavras-chave complexas**
+ `annotation[key]`— Valor de uma anotação com campo. *key* O valor de uma anotação pode ser um booliano, um número ou uma string; portanto, é possível usar qualquer um desses tipos de operador de comparação. É possível usar essa palavra-chave em combinação com as palavras-chave `service` ou `edge`. Uma chave de anotação que contenha pontos (pontos finais) deve ser colocada entre colchetes (**[ ]**).
+ `edge(source, destination) {filter}`— Conexão entre serviços *source* *destination* e. As chaves opcionais podem conter uma expressão de filtro que se aplica a segmentos nessa conexão.
+ `group.name / group.arn`: o valor da expressão de filtro de um grupo, referido pelo nome do grupo ou ARN do grupo.
+ `json`: objeto de causa raiz do JSON. Consulte [Obter dados do AWS X-Ray](xray-api-gettingdata.md) para ver as etapas para criar entidades JSON programaticamente.
+ `service(name) {filter}`— Serviço com nome*name*. Chaves opcionais podem conter uma expressão de filtro que se aplica a segmentos criados pelo serviço.
Use o serviço de palavras-chave para encontrar rastreamentos para solicitações que chegam a um determinado nó em seu mapa de rastreamento.
Os operadores complexos de palavras-chave encontram segmentos nos quais a chave especificada foi definida ou não.
**Operadores de palavras-chave complexos**
+ none: a expressão é verdadeira se a palavra-chave for definida. Se a palavra-chave for do tipo booliano, ela será avaliada como o valor booliano.
+ `!`: a expressão é verdadeira se a palavra-chave não for definida. Se a palavra-chave for do tipo booliano, ela será avaliada como o valor booliano.
+ `=`,`!=`: compara o valor da palavra-chave.
+ `edge(source, destination) {filter}`— Conexão entre serviços *source* *destination* e. As chaves opcionais podem conter uma expressão de filtro que se aplica a segmentos nessa conexão.
+ `annotation[key]`— Valor de uma anotação com campo. *key* O valor de uma anotação pode ser um booliano, um número ou uma string; portanto, é possível usar qualquer um desses tipos de operador de comparação. É possível usar essa palavra-chave em combinação com as palavras-chave `service` ou `edge`.
+ `json`: objeto de causa raiz do JSON. Consulte [Obter dados do AWS X-Ray](xray-api-gettingdata.md) para ver as etapas para criar entidades JSON programaticamente.
Use o serviço de palavras-chave para encontrar rastreamentos para solicitações que chegam a um determinado nó em seu mapa de rastreamento.
**Example Exemplo: filtro de serviço**
Solicitações que incluem uma chamada para `api.example.com` com uma falha (erro da série 500).
```
service("api.example.com") { fault }
```
É possível excluir o nome do serviço para aplicar uma expressão de filtro para todos os nós no seu mapeamento de serviço.
**Example Exemplo: filtro de serviço**
As solicitações que causam uma falha em qualquer lugar no mapa de rastreamento.
```
service() { fault }
```
A palavra-chave de borda aplica uma expressão de filtro a uma conexão entre dois nós.
**Example Exemplo: filtro de borda**
Solicitação em que o serviço `api.example.com` fez uma chamada para o `backend.example.com` que gerou um erro.
```
edge("api.example.com", "backend.example.com") { error }
```
Use também o operador `!` com palavras-chave de serviço e borda para excluir um serviço ou borda dos resultados de outra expressão de filtro.
**Example Exemplo: filtro de serviço e solicitação**
Solicitação em que o URL começa com `http://api.example.com/` e contém `/v2/`, mas não abrange um serviço chamado `api.example.com`.
```
http.url BEGINSWITH "http://api.example.com/" AND http.url CONTAINS "/v2/" AND !service("api.example.com")
```
**Example Exemplo: filtro de serviço e tempo de resposta**
Encontre rastreamento em que `http url` está definido e o tempo de resposta é maior que 2 segundos.
```
http.url AND responseTime > 2
```
Para anotações, você pode chamar todos os rastreamentos em que `annotation[key]` está definido ou usar os operadores de comparação que correspondem ao tipo de valor.
**Example Exemplo: anotação com valor de string**
Solicitações com uma anotação chamada `gameid` com o valor de string `"817DL6VO"`.
```
annotation[gameid] = "817DL6VO"
```
**Example Exemplo: a anotação está definida**
Solicitações com uma anotação definida como `age`.
```
annotation[age]
```
**Example Exemplo: a anotação não está definida**
Solicitações sem uma anotação definida como `age`.
```
!annotation[age]
```
**Example Exemplo: anotação com valor numérico**
Solicitações cuja idade de anotação tem um valor numérico maior do que 29.
```
annotation[age] > 29
```
**Example Exemplo: anotação em combinação com serviço ou borda**
```
service { annotation[request.id] = "917DL6VO" }
```
```
edge { source.annotation[request.id] = "916DL6VO" }
```
```
edge { destination.annotation[request.id] = "918DL6VO" }
```
**Example Exemplo: grupo com usuário**
Solicitações em que os rastreamentos atendem ao filtro de grupo `high_response_time` (por exemplo, `responseTime > 3`) e o usuário se chama Alice.
```
group.name = "high_response_time" AND user = "alice"
```
**Example Exemplo: JSON com entidade de causa raiz**
Solicitações com entidades de causa raiz correspondentes.
```
rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]
```
## Função id
Ao fornecer um nome de serviço para as palavras-chave `service` ou `edge`, você obtém resultados para todos os nós que têm esse nome. Para filtragem mais precisa, use a função `id` para especificar um tipo de serviço, além de um nome para distinguir os nós com o mesmo nome.
Use a função `account.id` para especificar uma conta específica para o serviço ao visualizar rastreamentos de várias contas em uma conta de monitoramento.
```
id(name: "service-name", type:"service::type", account.id:"account-ID")
```
Use a função `id` no lugar de um nome de serviço nos filtros de serviço e de borda.
```
service(id(name: "service-name", type:"service::type")) { filter }
```
```
edge(id(name: "service-one", type:"service::type"), id(name: "service-two", type:"service::type")) { filter }
```
Por exemplo, AWS Lambda as funções resultam em dois nós no mapa de rastreamento; um para a invocação da função e outro para o serviço Lambda. Os dois nós têm o mesmo nome, mas tipos diferentes. Um filtro de serviço padrão encontrará rastreamentos para ambos.
**Example Exemplo: filtro de serviço**
As solicitações que incluem um erro em qualquer serviço chamado `random-name`.
```
service("random-name") { error }
```
Use a função `id` para restringir a pesquisa para erros na função em si, excluindo os erros do serviço.
**Example Exemplo: filtro de serviço com a função id**
Solicitações que incluem um erro em um serviço chamado `random-name` com tipo `AWS::Lambda::Function`.
```
service(id(name: "random-name", type: "AWS::Lambda::Function")) { error }
```
Para procurar nós por tipo, também é possível excluir o nome inteiramente.
**Example Exemplo: filtro de serviço com função id e tipo de serviço**
Solicitações que incluem um erro em um serviço com o tipo `AWS::Lambda::Function`.
```
service(id(type: "AWS::Lambda::Function")) { error }
```
Para pesquisar nós para um determinado Conta da AWS, especifique um ID de conta.
**Example Exemplo: filtro de serviço com a função id e o ID da conta**
Solicitações que incluem um serviço dentro de um ID de conta `AWS::Lambda::Function` específico.
```
service(id(account.id: "account-id"))
```
# Rastreamento entre contas
O AWS X-Ray permite a *observabilidade entre contas*, possibilitando que você monitore e solucione problemas de aplicações que abrangem várias contas em uma Região da AWS. Você pode pesquisar, visualizar e analisar facilmente métricas, logs e rastreamentos em qualquer conta vinculada, como se estivesse operando em uma única conta. Isso fornece uma visão completa das solicitações que se estendem por várias contas. Você pode visualizar rastreamentos entre contas no mapa de rastreamento do X-Ray e nas páginas de rastreamentos no [console do CloudWatch](https://console.aws.amazon.com/cloudwatch/).
Os dados de observabilidade compartilhados podem incluir qualquer um dos seguintes tipos de telemetria:
+ Métricas no Amazon CloudWatch
+ Grupos de logs no Amazon CloudWatch Logs
+ Rastreamentos no AWS X-Ray
+ Aplicações no Amazon CloudWatch Application Insights
## Configurar a observabilidade entre contas
Para ativar a observabilidade entre contas, configure uma ou mais contas de *monitoramento* da AWS e vincule-as a diversas contas de *origem*. Uma conta de monitoramento é uma Conta da AWS central que pode visualizar e interagir com dados de observabilidade gerados das contas de origem. Uma conta de origem é uma Conta da AWS individual que gera dados de observabilidade para os recursos contidos nela.
As contas de origem compartilham os dados de observabilidade com as contas de monitoramento. Os rastreamentos são copiados de cada conta de origem para até cinco contas de monitoramento. As cópias dos rastreamentos das contas de origem para a primeira conta de monitoramento são gratuitas. As cópias dos rastreamentos enviados a contas de monitoramento adicionais são cobradas em cada conta de origem, com base no preço padrão. Para obter mais informações, consulte [Preços do AWS X-Ray](https://aws.amazon.com/xray/pricing/) e [Definição de preço do Amazon CloudWatch](https://aws.amazon.com/cloudwatch/pricing/).
Para criar vínculos entre as contas de monitoramento e as contas de origem, use o console do CloudWatch ou os novos comandos do Observability Access Manager na AWS CLI e na API. Para obter mais informações, consulte [Observabilidade entre contas do CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Unified-Cross-Account.html).
**nota**
Os rastreamentos do X-Ray são cobrados na Conta da AWS em que são recebidos. Se uma solicitação [amostrada](xray-concepts.md#xray-concepts-sampling) abranger serviços em mais de uma Conta da AWS, cada conta registrará um rastreamento separado e todos os demais compartilharão o mesmo ID de rastreamento. Para saber mais sobre os preços de observabilidade entre contas, consulte [Preços do AWS X-Ray](https://aws.amazon.com/xray/pricing/) e [Definição de preço do Amazon CloudWatch](https://aws.amazon.com/cloudwatch/pricing/).
## Visualizar rastreamentos entre contas
Os rastreamentos entre contas são exibidos na conta de monitoramento. Cada conta de origem exibe somente rastreamentos locais para essa conta específica. As seções a seguir pressupõem que você fez login na conta de monitoramento e abriu o console do Amazon CloudWatch. Tanto no mapa de rastreamento quanto nas páginas de rastreamentos, um selo da conta de monitoramento é exibido no canto superior direito.
![\[Selo da conta de monitoramento\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/crossaccount-monitoring-account.png)
### Mapa de rastreamento
No console do CloudWatch, escolha **Mapa de rastreamento** em **Rastreamentos do X-Ray** no painel de navegação esquerdo. Por padrão, o mapa de rastreamento exibe nós para todas as contas de origem que enviam rastreamentos à conta de monitoramento e nós para a própria conta de monitoramento. No mapa de rastreamento, escolha **Filtros** no canto superior esquerdo para filtrá-lo usando o menu suspenso **Contas**. Depois que um filtro de conta é aplicado, os nós de serviço de contas que não correspondem ao filtro atual ficam desabilitados.
![\[Mapa de rastreamento filtrado\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/crossaccount-servicemap-account-filter.png)
Quando você escolhe um nó de serviço, o painel de detalhes do nó inclui o ID da conta e o rótulo do serviço.
![\[Painel de detalhes do nó\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/crossaccount-servicemap-node-detail.png)
No canto superior direito do mapa de rastreamento, escolha **Visualização em lista** para ver uma lista de nós de serviço. A lista de nós de serviço inclui serviços da conta de monitoramento e de todas as contas de origem configuradas. Filtre a lista de nós por **Rótulo da conta** ou **ID da conta** escolhendo-os no filtro **Nós**.
![\[Lista de serviços filtrada\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/crossaccount-servicelist-account-filter.png)
### Rastreamentos
Visualize os detalhes do rastreamento que abrangem várias contas abrindo o console do CloudWatch na conta de monitoramento e escolhendo **Rastreamentos** em **Rastreamentos do X-Ray** no painel de navegação esquerdo. Você também pode abrir essa página escolhendo um nó no **Mapa de rastreamento** do X-Ray e selecionando **Visualizar rastreamentos** no painel de detalhes do nó.
A página **Rastreamentos** permite consultas por ID de conta. Para começar, [insira uma consulta](xray-console-filters.md) que inclua um ou mais IDs de conta. O exemplo a seguir consulta rastreamentos que passaram pelo ID da conta X* *ou *Y*:
```
service(id(account.id:"X")) OR service(id(account.id:"Y"))
```
![\[Rastreamentos de consulta por conta\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/crossaccount-traces-query-by-account.png)
Refine sua consulta por **Conta**. Selecione uma ou mais contas na lista e escolha **Adicionar à consulta**.
![\[Refinar a consulta de rastreamento por conta\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/crossaccount-traces-refine-by-account.png)
### Detalhes de rastreamento
Veja os detalhes de um rastreamento escolhendo-o na lista **Rastreamentos** na parte inferior da página **Rastreamentos**. Os **Detalhes de rastreamento** são exibidos, incluindo um mapa de detalhes do rastreamento com nós de serviço de todas as contas pelas quais o rastreamento passou. Escolha um nó de serviço específico para ver a conta correspondente.
A seção **Linha do tempo dos segmentos** exibe os detalhes da conta para cada segmento na linha do tempo.
![\[Linha do tempo dos segmentos\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/crossaccount-traces-segment-timeline.png)
# Rastrear aplicações orientadas a eventos
O AWS X-Ray é compatível com o rastreamento de aplicações orientados a eventos usando o Amazon SQS e o AWS Lambda. Use o console do CloudWatch para ver uma visualização conectada de cada solicitação à medida que ela é enfileirada com o Amazon SQS por uma ou mais funções do Lambda. Os rastreamentos dos produtores de mensagens precedentes são automaticamente vinculados aos rastreamentos dos nós consumidores subsequentes do Lambda, criando uma visão completa da aplicação.
**nota**
Cada segmento de rastreamento pode ser vinculado a até vinte traços, enquanto um rastreamento pode incluir no máximo cem links. Em determinadas situações, ao vincular rastreamentos adicionais, o [tamanho máximo do documento de rastreamentos](https://docs.aws.amazon.com/general/latest/gr/xray.html#limits_xray) pode ser excedido e resultar em um rastreamento possivelmente incompleto. Isso pode acontecer, por exemplo, quando uma função do Lambda com rastreamento habilitado envia muitas mensagens SQS para uma fila em uma única invocação. Se você se deparar com esse problema, há um método de mitigação que usa os X-Ray SDKs. Consulte o X-Ray SDK para [Java](https://github.com/aws/aws-xray-sdk-java#oversampling-mitigation), [Node.js](https://github.com/aws/aws-xray-sdk-node/tree/master/packages/core#oversampling-mitigation), [Python](https://github.com/aws/aws-xray-sdk-python#oversampling-mitigation), [Go](https://github.com/aws/aws-xray-sdk-go#oversampling-mitigation) ou [.NET](https://github.com/aws/aws-xray-sdk-dotnet#oversampling-mitigation) para obter mais informações.
## Visualizar rastreamentos vinculados no mapa de rastreamento
Use a página **Mapa de rastreamento** no [console do CloudWatch](https://console.aws.amazon.com/cloudwatch/) para visualizar um mapa de rastreamento com rastreamentos de produtores de mensagens vinculados a rastreamentos de consumidores do Lambda. Esses links são exibidos com uma borda tracejada que conecta o nó do Amazon SQS e os nós consumidores subsequentes do Lambda.
![\[Borda entre os nós do Amazon SQS e do Lambda.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/console-batch-servicemap-linkededge.png)
Selecione uma borda tracejada para exibir um histograma da *idade do evento recebido*, que mapeia a distribuição da idade do evento quando ele é recebido pelos consumidores. A idade é calculada sempre que um evento é recebido.
![\[Borda com histograma de idade do evento recebido.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/console-servicemap-linkededgedetails-cw.png)
## Visualizar detalhes de rastreamentos vinculados
**Veja os detalhes dos rastreamentos enviados por um produtor de mensagens, uma fila do Amazon SQS ou um consumidor do Lambda:**
1. Use o **mapa de rastreamento** para selecionar um produtor de mensagens, o Amazon SQS ou nó consumidor do Lambda.
1. Escolha **Visualizar rastreamentos** no painel de detalhes do nó para exibir uma lista de rastreamentos. Você também pode navegar diretamente para a página **Rastreamentos** no console do CloudWatch.
1. Escolha um rastreamento específico na lista para abrir a página de detalhes do rastreamento. A página de detalhes do rastreamento exibe uma mensagem quando o rastreamento selecionado faz parte de um conjunto vinculado de rastreamentos.
![\[Detalhes de rastreamentos vinculados\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/console-batch-tracedetails-header.png)
O mapa de detalhes do rastreamento exibe o rastreamento atual, bem como os rastreamentos vinculados precedentes e subsequentes, cada um deles contido em uma caixa que indica os limites de cada rastreamento. Se o rastreamento selecionado no momento estiver vinculado a vários rastreamentos precedentes e subsequentes, os nós dentro dos rastreamentos vinculados precedentes e subsequentes serão empilhados e um botão **Selecionar rastreamento** será exibido.
![\[Vários rastreamentos precedentes vinculados\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/console-batch-tracedetails-tracemap.png)
Abaixo do mapa de detalhes do rastreamento, é exibida uma linha do tempo dos segmentos de rastreamento, incluindo rastreamentos vinculados precedentes e subsequentes. Se houver vários rastreamentos vinculados precedentes e subsequentes, os detalhes do segmento não poderão ser exibidos. Para visualizar os detalhes do segmento de um único rastreamento em um conjunto de rastreamentos vinculados, [selecione um único rastreamento](#xray-tracelinking-filterbatch) conforme descrito abaixo.
![\[Linha do tempo dos segmentos mostrando rastreamentos vinculados\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/console-batch-tracedetails-timeline.png)
## Selecionar um único rastreamento dentro de um conjunto de rastreamentos vinculados
**Filtre um conjunto vinculado de rastreamentos em um único rastreamento para ver os detalhes do segmento na linha do tempo.**
1. Escolha **Selecionar rastreamento** abaixo dos rastreamentos vinculados no mapa de detalhes do rastreamento. Uma lista de rastreamentos é exibida.
![\[Lista de rastreamentos vinculados\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/console-batch-tracedetails-tracelist.png)
1. Selecione o botão de opção ao lado de um rastreamento para visualizá-lo no mapa de detalhes do rastreamento.
1. Escolha **Cancelar seleção de rastreamentos** para visualizar todo o conjunto de rastreamentos vinculados.
![\[Rastreamento vinculado único\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/console-batch-tracedetails-filteredbatch.png)
# Usar histogramas de latência
Quando você seleciona um nó ou uma borda em um [mapa de rastreamento](xray-console-servicemap.md) do AWS X-Ray, o console do X-Ray mostra um histograma de distribuição da latência.
## Latência
A latência é o tempo entre o início de uma solicitação e sua conclusão. Um histograma mostra uma distribuição de latências. Ela mostra a duração no eixo x e a porcentagem de solicitações correspondentes a cada período no eixo y.
Este histograma mostra um serviço que conclui a maioria das solicitações em menos de 300 ms. Uma pequena porcentagem de solicitações demora até 2 segundos, e algumas exceções levam mais tempo.
![\[Histograma de latência com a duração no eixo x e a porcentagem de solicitações para cada duração no eixo y\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-servicemap-histogram.png)
## Interpretar detalhes do serviço
Os histogramas de serviço e margem apresentam uma representação visual da latência a partir do ponto de vista de um serviço ou solicitante.
+ Clique no círculo para escolher um *nó de serviço*. O X-Ray mostra um histograma de solicitações atendidas pelo serviço. As latências são as registradas pelo serviço e não incluem nenhuma latência de rede entre o serviço e o solicitante.
+ Escolha uma *borda* clicando na linha ou na ponta da seta da borda entre dois serviços. O X-Ray mostra um histograma para pedidos do solicitante que foram atendidos pelo serviço subsequente. As latências são as registradas pelo solicitante e incluem a latência na conexão de rede entre os dois serviços.
Para interpretar o histograma de painel **Service details**, é possível examinar os valores que mais diferem da maioria dos valores no histograma. Essas *exceções* podem ser vistas como picos ou picos no histograma, e é possível visualizar os rastreamentos de uma área específica para investigar o que está acontecendo.
Para visualizar rastreamentos filtrados por latência, selecione um intervalo no histograma. Clique onde você deseja iniciar a seleção e arraste da esquerda para a direita a fim de destacar um intervalo de latências a serem incluídas no filtro de rastreamento.
![\[Selecione um intervalo para visualizar rastreamentos clicando em por onde começar e arrastando da esquerda para a direita a fim de criar o intervalo para o filtro de rastreamento\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-servicemap-servicedetails-selection.png)
Depois de selecionar um intervalo, você poderá escolher **Zoom** para visualizar apenas essa parte do histograma e refinar a seleção.
![\[Escolha Zoom para visualizar o intervalo selecionado no histograma\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-servicemap-servicedetails-zoom.png)
Assim que você tiver o foco definido na área pela qual tem interesse, escolha **View traces**.
# Usar os insights do X-Ray
O AWS X-Ray analisa continuamente os dados de rastreamento em sua conta para identificar problemas emergentes nas aplicações. Quando as taxas de falha excedem o intervalo esperado, ele cria um *insight* que registra o problema e rastreia o respectivo impacto até que ele seja resolvido. Com os insights, você pode:
+ Identificar onde os problemas estão ocorrendo na aplicação, a causa raiz do problema e o impacto correspondente. A análise de impacto fornecida pelos insights permite que você determine a gravidade e a prioridade de um problema.
+ Receber notificações à medida que o problema muda ao longo do tempo. As notificações de insights podem ser integradas à sua solução de monitoramento e alerta usando o Amazon EventBridge. Essa integração permite que você envie e-mails ou alertas automatizados com base na gravidade do problema.
O console do X-Ray identifica nós com incidentes contínuos no mapa de rastreamento. Para ver um resumo de insights, escolha o nó afetado. Você também pode visualizar e filtrar insights escolhendo **Insights** no painel de navegação à esquerda.
![\[Nó do mapa de rastreamento com resumo de insights.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/console-insights-servicemap.png)
O X-Ray cria um insight quando detecta uma *anomalia* em um ou mais nós do mapa de serviço. O serviço usa modelagem estatística para prever as taxas de falha esperadas dos serviços na aplicação. No exemplo anterior, a anomalia é um aumento nas falhas do AWS Elastic Beanstalk. O servidor do Elastic Beanstalk teve vários tempos limite de chamadas de API, causando uma anomalia nos nós subsequentes.
## Habilitar insights no console X-Ray
É necessário habilitar os insights para cada grupo com o qual você deseja usar os recursos de insight. Você pode habilitá-los na página **Grupos**.
1. Abra o [console do X-Ray](https://console.aws.amazon.com/xray/home#).
1. Selecione um grupo ou crie um escolhendo **Criar grupo** e escolha **Habilitar Insights**. Para obter mais informações sobre como configurar grupos no console do X-Ray, consulte [Configurar grupos](xray-console-groups.md).
1. No painel de navegação à esquerda, escolha **Insights** e selecione um insight para visualizar.
![\[Liste os insights no console do X-Ray.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/console-insights.png)
**nota**
O X-Ray usa as operações de API GetInsightSummaries, GetInsight, GetInsightEvents e GetInsightImpactGraph para recuperar dados de insights.
Para obter mais informações, consulte [Como AWS X-Ray funciona com o IAM](security_iam_service-with-iam.md).
## Habilitar notificações de insights
Com as notificações de insights, uma notificação é criada para cada evento de insight, como quando um insight é criado, muda significativamente ou é fechado. Os clientes podem receber essas notificações por meio de eventos do Amazon EventBridge e usar regras condicionais para realizar ações como notificação do SNS, invocação do Lambda e publicação de mensagens em uma fila do SQS ou qualquer um dos destinos compatíveis com o EventBridge. As notificações de insight são emitidas com base no melhor esforço, mas não são garantidas. Para obter mais informações sobre destinos, consulte [Amazon EventBridge Targets](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-targets.html).
Você pode habilitar as notificações de insight para qualquer grupo habilitado para insights na página **Grupos**.
**Como habilitar notificações para um grupo do X-Ray**
1. Abra o [console do X-Ray](https://console.aws.amazon.com/xray/home#).
1. Selecione um grupo ou crie um escolhendo **Criar grupo**. Certifique-se de que **Habilitar Insights** esteja selecionado e escolha **Habilitar notificações**. Para obter mais informações sobre como configurar grupos no console do X-Ray, consulte [Configurar grupos](xray-console-groups.md).
**Como configurar regras condicionais do Amazon EventBridge**
1. Abra o [console do Amazon EventBridge](https://console.aws.amazon.com/events/home).
1. Navegue até **Regras** na barra de navegação esquerda e escolha **Criar regra**.
1. Forneça um nome e uma descrição para a regra.
1. Escolha **Padrão de evento** e selecione **Padrão personalizado**. Forneça um padrão contendo `"source": [ "aws.xray" ]` e `"detail-type": [ "AWS X-Ray Insight Update" ]`. Veja a seguir alguns exemplos de padrões possíveis.
+ Padrão de evento para corresponder a todos os eventos de entrada de insights do X-Ray:
```
{
"source": [ "aws.xray" ],
"detail-type": [ "AWS X-Ray Insight Update" ]
}
```
+ Padrão de evento para corresponder a um **state** e **category** específicos:
```
{
"source": [ "aws.xray" ],
"detail-type": [ "AWS X-Ray Insight Update" ],
"detail": {
"State": [ "ACTIVE" ],
"Category": [ "FAULT" ]
}
}
```
1. Selecione e configure os destinos que você gostaria de invocar quando um evento corresponder a essa regra.
1. (Opcional) Forneça tags para identificar e selecionar essa regra com maior facilidade.
1. Escolha **Criar**.
**nota**
As notificações de insights do X-Ray enviam eventos para o Amazon EventBridge, que no momento não permite chaves gerenciadas pelo cliente. Para obter mais informações, consulte [Proteção de dados no AWS X-Ray](xray-console-encryption.md).
## Visão geral do insight
A página de visão geral de um insight tenta responder a três perguntas principais:
+ Qual é o problema subjacente?
+ Qual é a causa raiz?
+ Qual é o impacto?
A seção **Serviços anômalos** mostra um cronograma para cada serviço que ilustra a mudança nas taxas de falha durante o incidente. A linha do tempo mostra o número de rastreamentos com falhas sobrepostas em uma faixa sólida que indica o número esperado de falhas com base na quantidade de tráfego registrada. A duração do insight é visualizada por meio da *Janela de incidentes*. A janela de incidentes começa quando o X-Ray observa a métrica se tornando anômala e persiste enquanto o insight está ativo.
O exemplo a seguir mostra um aumento nas falhas que causaram um incidente:
![\[Página de visão geral de um insight do X-Ray.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/console-insights-overview.png)
A seção **Causa raiz** mostra um mapa de rastreamento focado no serviço de causa raiz e no caminho afetado. É possível ocultar os nós não afetados selecionando o ícone de olho na parte superior direita do mapa da causa raiz. O serviço de causa raiz é o nó posterior mais distante em que o X-Ray identificou uma anomalia. Ele pode representar um serviço que você instrumentou ou um serviço externo que seu serviço chamou com um cliente instrumentado. Por exemplo, se você chamar o Amazon DynamoDB com um cliente de SDK da AWS instrumentado, um aumento nas falhas do DynamoDB resultará em um insight com o DynamoDB como causa raiz.
Para investigar melhor a causa raiz, selecione **Visualizar detalhes da causa raiz** no gráfico da causa raiz. Você pode usar a página **Análises** para investigar a causa raiz e as mensagens relacionadas. Para obter mais informações, consulte [Interagir com o console do Analytics](xray-console-analytics.md).
![\[Página de visão geral de um insight do X-Ray.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/console-insights-root-cause.png)
As falhas que continuam na parte precedente no mapa podem afetar vários nós e causar várias anomalias. Se uma falha for passada de volta para o usuário que fez a solicitação, o resultado será uma *falha do cliente*. Essa é uma falha no nó raiz do mapa de rastreamento. O gráfico **Impacto** fornece uma linha do tempo da experiência do cliente para todo o grupo. Essa experiência é calculada com base em porcentagens dos seguintes estados: **Falha**, **Erro**, **Controle** e **OK**.
![\[Gráfico Impacto de um incidente do X-Ray.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/console-insights-impact.png)
Este exemplo mostra um aumento nos rastreamentos com uma falha no nó raiz durante o período de um incidente. Incidentes em serviços subsequentes nem sempre correspondem a um aumento nos erros de cliente.
Escolher **Analisar insight** abre o console do X-Ray Analytics em uma janela na qual você pode se aprofundar no conjunto de rastreamentos que causam o insight. Para obter mais informações, consulte [Interagir com o console do Analytics](xray-console-analytics.md).
**Noções básicas sobre impacto**
O AWS X-Ray mede o impacto causado por um problema contínuo como parte da geração de insights e notificações. O impacto é medido de duas maneiras:
+ Impacto no [grupo](xray-console-groups.md) do X-Ray
+ Impacto no serviço de causa raiz
Esse impacto é determinado pela porcentagem de solicitações que estão falhando ou causando um erro em um determinado intervalo de tempo. Essa análise de impacto permite que você determine a gravidade e a prioridade do problema com base em seu cenário específico. Esse impacto está disponível como parte da experiência do console, além das notificações de insight.
**Desduplicação**
Os insights do AWS X-Ray eliminam a duplicação de problemas em vários microsserviços. O serviço usa a detecção de anomalias para determinar o serviço que é a causa raiz de um problema, determina se outros serviços relacionados estão exibindo um comportamento anômalo devido à mesma causa raiz e registra o resultado como um único insight.
## Analisar o andamento de um insight
O X-Ray reavalia os insights periodicamente até que sejam resolvidos e registra cada alteração intermediária notável como uma [notificação](#xray-console-insight-notifications), que pode ser enviada como um evento do Amazon EventBridge. Isso permite que você crie processos e fluxos de trabalho para determinar como o problema mudou ao longo do tempo e tome as medidas apropriadas, como enviar um e-mail ou integrar-se a um sistema de alerta usando o EventBridge.
Você pode analisar os eventos do incidente no **Cronograma de impacto** na página **Inspecionar.** Por padrão, o cronograma exibe o serviço mais afetado até que você escolha um serviço diferente.
![\[Inspecione a página com o cronograma de impacto.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/console-insights-inspect.png)
Para ver um mapa de rastreamento e gráficos de um evento, escolha-o na linha no cronograma de impacto. O mapa de rastreamento mostra os serviços na aplicação que são afetados pelo incidente. Em **Análise de impacto**, os gráficos mostram cronogramas de falhas para o nó selecionado e os clientes do grupo.
![\[Gráfico de análise de impacto referente a um insight do X-Ray.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/console-insights-inspect-analysis.png)
Para analisar mais detalhadamente os rastreamentos envolvidos em um incidente, escolha **Analisar evento** na página **Inspecionar.** Você pode usar a página **Análises** para refinar a lista de rastreamentos e identificar os usuários afetados. Para obter mais informações, consulte [Interagir com o console do Analytics](xray-console-analytics.md).
# Interagir com o console do Analytics
O console do AWS X-Ray Analytics é uma ferramenta interativa de interpretação de dados de rastreamento para entender rapidamente o desempenho do aplicativo e dos serviços subjacentes. O console permite explorar, analisar e visualizar rastreamentos por meio de gráficos interativos de tempo de resposta e de séries temporais.
Ao fazer seleções no console do Analytics, o console cria filtros para refletir o subconjunto selecionado de todos os rastreamentos. É possível refinar o conjunto de dados ativo com filtros cada vez mais granulares clicando nos gráficos e nos painéis de métricas e campos que estão associados ao conjunto de rastreamentos atual.
**Topics**
+ [Recursos do console](#xray-console-analytics-features)
+ [Distribuição do tempo de resposta](#xray-console-analytics-response)
+ [Atividade de séries temporais](#xray-console-analytics-time)
+ [Exemplos de fluxo de trabalho](#xray-console-analytics-workflows)
+ [Observar as falhas no gráfico de serviço](#xray-console-analytics-observe-faults)
+ [Identificar picos de tempo de resposta](#xray-console-analytics-response-peaks)
+ [Visualizar todos os rastreamentos marcados com um código de status](#xray-console-analytics-response-peaks)
+ [Visualizar todos os itens de um subgrupo de rastreamentos associados a um usuário](#xray-console-analytics-subgroups)
+ [Compare dois conjuntos de rastreamentos com critérios diferentes](#xray-console-analytics-compare)
+ [Identificar um rastreamento de interesse e visualizar os detalhes](#xray-console-analytics-identify)
## Recursos do console
O console do X-Ray Analytics usa os principais recursos a seguir para agrupamento, filtragem, comparação e quantificação de dados de rastreamento.
### Atributos
| Recurso | Descrição |
| --- | --- |
| **Grupos** | O grupo selecionado inicial é `Default`. Para alterar o grupo recuperado, selecione um grupo diferente no menu à direita da barra de pesquisa da expressão de filtro principal. Para saber mais sobre grupos, consulte [Usar expressões de filtro com grupos](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-filters.html#groups). |
| **Rastreamentos recuperados** | Por padrão, o console do Analytics gera gráficos com base em todos os rastreamentos no grupo selecionado. Rastreamentos recuperados representam todos os rastreamentos em seu conjunto de trabalho. Você pode encontrar a contagem de rastreamentos neste bloco. As expressões de filtro aplicadas à barra de pesquisa principal refinam e atualizam os rastreamentos recuperados. |
| **Show in charts/Hide from charts (Mostrar nos gráficos/Ocultar dos gráficos** | Um botão para comparar o grupo ativo com os rastreamentos recuperados. Para comparar os dados relacionados ao grupo com qualquer filtro ativo, escolha **Show in charts (Mostrar nos gráficos)**. Para remover essa visão dos gráficos, escolha **Hide from charts (Ocultar dos gráficos)**. |
| **Conjunto de rastreamentos filtrados A** | Por meio de interações com os gráficos e tabelas, aplique filtros para criar os critérios para o **conjunto de rastreamentos filtrados A**. À medida que os filtros são aplicados, o número de rastreamentos aplicáveis e a porcentagem de rastreamentos do total que são recuperados são calculados neste bloco. Os filtros são preenchidos como tags no bloco **Filtered trace set A (Conjunto de rastreamentos filtrados A)** e também podem ser removidos do bloco. |
| **Refinar** | Esta função atualiza o conjunto de rastreamentos recuperados com base nos filtros aplicados ao conjunto de rastreamentos A. O refinamento do conjunto de rastreamentos recuperados atualiza o conjunto de trabalho de todos os rastreamentos recuperados com base nos filtros para o conjunto de rastreamentos A. O conjunto de trabalho de rastreamentos recuperados é um subconjunto de amostragem de todos os rastreamentos no grupo. |
| **Conjunto de rastreamentos filtrados B** | Quando criado, o **conjunto de rastreamentos filtrados B** é uma cópia do **conjunto de rastreamentos filtrados A**. Para comparar os dois conjuntos de rastreamentos, faça novas seleções de filtro que serão aplicadas ao conjunto de rastreamentos B, enquanto o conjunto de rastreamentos A permanece fixo. À medida que os filtros são aplicados, o número de rastreamentos aplicáveis e a porcentagem de rastreamentos do total recuperado são calculados dentro desse bloco. Os filtros são preenchidos como tags no bloco **Filtered trace set B (Conjunto de rastreamentos filtrados B)** e também podem ser removidos do bloco. |
| **Response time root cause entity paths (Caminhos da entidade de causa raiz do tempo de resposta** | Uma tabela de caminhos de entidades registrados. O X-Ray determina qual caminho no rastreamento é a causa mais provável do tempo de resposta. O formato indica uma hierarquia de entidades encontradas, terminando em uma causa raiz do tempo de resposta. Use essas linhas para filtrar falhas de tempo de resposta recorrentes. Para obter mais informações sobre como personalizar um filtro de causa raiz e obter dados por meio da API, consulte [Recuperar e refinar a análise da causa raiz](https://docs.aws.amazon.com/xray/latest/devguide/xray-api-gettingdata.html#xray-api-analytics). |
| **Delta (**�**)** | Uma coluna que é incluída nas tabelas de métricas quando ambos os conjuntos de rastreamentos A e B estão ativos. A coluna Delta calcula a diferença na porcentagem de rastreamentos entre o conjunto de rastreamentos A e o conjunto de rastreamentos B. |
## Distribuição do tempo de resposta
O console do X-Ray Analytics gera dois gráficos primários para ajudar você a visualizar rastreamentos: **Distribuição do tempo de resposta** e **Atividade de séries temporais**. Esta seção e a seguinte fornecem exemplos de cada uma delas e explicam os conceitos básicos de como ler os gráficos.
Veja a seguir as cores associadas ao gráfico de linha de tempo de resposta (o gráfico de série temporal usa o mesmo esquema de cores):
+ **Todos os rastreamentos no grupo**: cinza
+ **Rastreamentos recuperados**: laranja
+ **Conjunto de rastreamentos filtrados A**: verde
+ **Conjunto de rastreamentos filtrados B**: azul
**Example Exemplo: distribuição do tempo de resposta**
A distribuição do tempo de resposta é um gráfico que mostra o número de rastreamentos com um determinado tempo de resposta. Clique e arraste para fazer seleções dentro da distribuição do tempo de resposta. Isso seleciona e cria um filtro no conjunto de rastreamentos de trabalho nomeado `responseTime` para todos os rastreamentos dentro de um tempo de resposta específico.
![\[Um gráfico que mostra a distribuição do tempo de resposta dos rastreamentos.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/analytics-responseTime.png)
## Atividade de séries temporais
O gráfico de atividade das séries temporais mostra o número de rastreamentos em um determinado período. Os indicadores de cor refletem as cores do gráfico de linhas da distribuição do tempo de resposta. Quanto mais escuro e mais cheio for o bloco de cores dentro da série de atividades, mais traços serão representados no momento determinado.
**Example Exemplo: atividade de séries temporais**
Clique e arraste para fazer seleções no gráfico de atividades da séries temporais. Isso seleciona e cria um filtro chamado `timerange` no conjunto de rastreamentos de trabalho para todos os rastreamentos dentro de um intervalo de tempo específico.
![\[Fazer uma seleção e criar um filtro\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/analytics-timeSeries.png)
## Exemplos de fluxo de trabalho
Os exemplos a seguir mostram casos de uso comuns do console do X-Ray Analytics. Cada exemplo demonstra uma função-chave da experiência do console. Como um grupo, os exemplos seguem um fluxo de trabalho básico de solução de problemas. As etapas explicam como identificar primeiro os nós não íntegros e, depois, como interagir com o console do Analytics para gerar automaticamente consultas comparativas. Depois de restringir o escopo por meio de consultas, você finalmente analisará os detalhes dos traços de interesse para determinar o que está prejudicando a integridade do seu serviço.
## Observar as falhas no gráfico de serviço
O mapa de rastreamento indica a integridade de cada nó destacando por cores com base no índice de chamadas bem-sucedidas para erros e falhas. Quando você vê uma porcentagem de vermelho no seu nó, ele sinaliza uma falha. Use o console do X-Ray Analytics para investigar.
Para obter mais informações sobre como ler o mapa de rastreamento, consulte [Exibir o mapa de rastreamento](https://docs.aws.amazon.com/xray/latest/devguide/xray-console.html#xray-console-servicemap).
![\[Observar uma falha\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-gettingstarted-servicemap-before-2021.png)
## Identificar picos de tempo de resposta
Usando a distribuição do tempo de resposta, você pode observar picos no tempo de resposta. Ao selecionar o pico no tempo de resposta, as tabelas abaixo dos gráficos serão atualizadas para expor todas as métricas associadas, como códigos de status.
Quando você clica e arrasta, o X-Ray selecione e cria um filtro. Ele será exibido em uma sombra cinza na parte superior das linhas em gráficos. Agora você pode arrastar esse destaque para a esquerda e para a direita ao longo da distribuição para atualizar sua seleção.
![\[Fazer uma seleção e criar um filtro\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/analytics-showFilterf.png)
## Visualizar todos os rastreamentos marcados com um código de status
Você pode analisar rastreamentos no pico selecionado usando as métricas tabelas abaixo dos gráficos. Clicando em uma linha na tabela **HTTP STATUS CODE (CÓDIGO DE STATUS HTTP)**, você cria automaticamente um filtro no conjunto de dados de trabalho. Por exemplo, você pode ver todos os rastreamentos do código de status 500. Isso cria uma tag de filtro no bloco do conjunto de rastreamentos chamado `http.status`.
## Visualizar todos os itens de um subgrupo de rastreamentos associados a um usuário
Analise o conjunto de erros com base no usuário, URL, causa raiz do tempo de resposta ou outros atributos predefinidos. Por exemplo, para filtrar o conjunto de rastreamentos adicionalmente com um código de status 500, selecione uma linha na tabela **USERS (USUÁRIOS)**. Isso resulta em duas tags de filtro no bloco do conjunto de rastreamentos: `http.status`, conforme designado anteriormente, e `user`.
## Compare dois conjuntos de rastreamentos com critérios diferentes
Compare vários usuários e suas solicitações POST para encontrar outras discrepâncias e correlações. Aplique o primeiro conjunto de filtros. Eles são definidos por uma linha azul na distribuição do tempo de resposta. Depois selecione **Compare (Comparar)**. Inicialmente, isso cria uma cópia dos filtros no conjunto de rastreamentos A.
Para continuar, defina um novo conjunto de filtros para aplicar ao conjunto de rastreamentos B. Esse segundo conjunto é representado por uma linha verde. O exemplo a seguir mostra diferentes linhas de acordo com o esquema de cor verde e azul.
![\[Comparação de gráfico de linha\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/analytics-compareLines.png)
## Identificar um rastreamento de interesse e visualizar os detalhes
À medida que você restringe seu escopo usando os filtros de console, a lista de rastreamentos abaixo das tabelas de métricas se torna mais significativa. A tabela da lista de rastreamentos combina informações sobre **URL**, **USER (USUÁRIO)** e **STATUS CODE (CÓDIGO DE STATUS)** em uma exibição. Para obter mais informações, selecione uma linha na tabela para abrir a página de detalhes de rastreamento e visualizar a linha do tempo e dados brutos.
# Configurar grupos
Os grupos são uma coleção de rastreamentos definidos por uma expressão de filtro. Você pode usar grupos para gerar gráficos de serviço adicionais e fornecer métricas do Amazon CloudWatch. Você pode usar o console do AWS X-Ray ou a API do X-Ray para criar e gerenciar grupos para seus serviços. Este tópico descreve como criar e gerenciar grupos usando o console do X-Ray. Para obter informações sobre como gerenciar grupos usando a API do X-Ray, consulte [Groups (Grupos)](xray-api-configuration.md#xray-api-configuration-groups).
Você pode criar grupos de rastreamentos para mapas de rastreamento, rastreamentos ou análises. Ao criar um grupo, ele fica disponível como um filtro no menu suspenso do grupo em todas as três páginas: **Mapa de rastreamento**, **Rastreamentos** e **Análises**.
![\[Menu de grupos\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/group-menu.png)
Os grupos são identificados pelo nome ou pelo nome do recurso da Amazon (ARN) e contêm uma expressão de filtro. O serviço compara os rastreamentos de entrada com a expressão e os armazena adequadamente. Para obter mais informações sobre como criar uma expressão de filtro, consulte [Usar expressões de filtro](xray-console-filters.md).
Atualizar a expressão de filtro de um grupo não altera os dados que já estão registrados. A atualização se aplica somente aos rastreamentos subsequentes. Isso pode resultar em um gráfico mesclado das expressões novas e antigas. Para evitar isso, exclua o grupo atual e crie outro.
**nota**
Os grupos são faturados pelo número de rastreamentos recuperados que correspondem à expressão de filtro. Para obter mais informações, consulte [Preços do AWS X-Ray](https://aws.amazon.com/xray/pricing/).
**Topics**
+ [Criar um grupo](#xray-console-group-create-console)
+ [Aplicar um grupo](#xray-console-group-apply)
+ [Editar um grupo](#xray-console-group-edit)
+ [Clonar um grupo](#xray-console-group-clone)
+ [Excluir um grupo](#xray-console-group-delete)
+ [Visualizar métricas de grupo no Amazon CloudWatch](#xray-console-group-cloudwatch)
## Criar um grupo
**nota**
Agora você pode configurar as regras de amostragem do X-Ray no console do Amazon CloudWatch. Você também pode continuar usando o console do X-Ray.
------
#### [ CloudWatch console ]
1. Faça login no Console de gerenciamento da AWS e abra o console do CloudWatch em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Escolha **Configurações** no painel de navegação à esquerda.
1. Escolha **Visualizar configurações** em **Grupos** na seção **Rastreamentos do X-Ray**.
1. Escolha **Criar grupo** acima da lista de grupos.
1. Na página **Criar grupo**, digite um nome para o grupo. O nome de grupo pode ter no máximo 32 caracteres, mas somente caracteres alfanuméricos e hifens. Os nomes de grupo diferenciam letras maiúsculas de minúsculas.
1. Insira uma expressão de filtro. Para obter mais informações sobre como criar uma expressão de filtro, consulte [Usar expressões de filtro](xray-console-filters.md). No exemplo a seguir, o grupo filtra os rastreamentos de falhas do serviço `api.example.com` e as solicitações ao serviço em que o tempo de resposta foi maior ou igual a cinco segundos.
```
fault = true AND http.url CONTAINS "example/game" AND responsetime >= 5
```
1. Em **Insights**, habilite ou desabilite o acesso a insights para o grupo. Para obter mais informações sobre insights, consulte [Usar os insights do X-Ray](xray-console-insights.md).
![\[Caixas de seleção Insights na página do grupo\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/group-insights-cw.png)
1. Em **Tags**, escolha **Adicionar nova tag** para inserir uma chave de tag e, opcionalmente, um valor de tag. Continue adicionando outras tags conforme desejado. As chaves de tag devem ser exclusivas. Para excluir uma tag, escolha **Remover** abaixo de cada tag. Para obter mais informações sobre tags, consulte [Marcar grupos e regras de amostragem do X-Ray](xray-tagging.md).
![\[Campos de tag na página Grupo\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/group-tags-cw.png)
1. Escolha **Criar grupo**.
------
#### [ X-Ray console ]
1. Faça login no Console de gerenciamento da AWS e abra o console do X-Ray em [https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home).
1. Abra a página **Criar grupo** na página **Grupos** no painel de navegação esquerdo ou no menu de grupos em uma das seguintes páginas: **Mapa de rastreamento**, **Rastreamentos** e **Análises**.
1. Na página **Criar grupo**, digite um nome para o grupo. O nome de grupo pode ter no máximo 32 caracteres, mas somente caracteres alfanuméricos e hifens. Os nomes de grupo diferenciam letras maiúsculas de minúsculas.
1. Insira uma expressão de filtro. Para obter mais informações sobre como criar uma expressão de filtro, consulte [Usar expressões de filtro](xray-console-filters.md). No exemplo a seguir, o grupo filtra os rastreamentos de falhas do serviço `api.example.com` e as solicitações ao serviço em que o tempo de resposta foi maior ou igual a cinco segundos.
```
fault = true AND http.url CONTAINS "example/game" AND responsetime >= 5
```
1. Em **Insights**, habilite ou desabilite o acesso a insights para o grupo. Para obter mais informações sobre insights, consulte [Usar os insights do X-Ray](xray-console-insights.md).
![\[Caixas de seleção Insights na página do grupo\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/group-insights.png)
1. Em **Tags**, insira uma chave de tag e, opcionalmente, um valor de tag. Ao adicionar uma tag, uma nova linha aparece para você adicionar outra tag. As chaves de tag devem ser exclusivas. Para excluir uma tag, escolha **X** no final da linha da tag. Para obter mais informações sobre tags, consulte [Marcar grupos e regras de amostragem do X-Ray](xray-tagging.md).
![\[Campos de tag na página Grupo\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/group-tags.png)
1. Escolha **Criar grupo**.
------
## Aplicar um grupo
------
#### [ CloudWatch console ]
1. Faça login no Console de gerenciamento da AWS e abra o console do CloudWatch em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Abra uma das páginas a seguir no painel de navegação em **Rastreamentos do X-Ray**:
+ **Mapa de rastreamento**
+ **Rastreamentos**
1. Insira um nome de grupo no filtro **Filtrar por grupo do X-Ray**. Os dados mostrados na página são alterados para corresponder à expressão de filtro definida no grupo.
------
#### [ X-Ray console ]
1. Faça login no Console de gerenciamento da AWS e abra o console do X-Ray em [https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home).
1. Abra uma das seguintes páginas no painel de navegação:
+ **Mapa de rastreamento**
+ **Rastreamentos**
+ **Analytics**
1. No menu de grupos, escolha o grupo em que você criou em [Criar um grupo](#xray-console-group-create-console). Os dados mostrados na página são alterados para corresponder à expressão de filtro definida no grupo.
------
## Editar um grupo
------
#### [ CloudWatch console ]
1. Faça login no Console de gerenciamento da AWS e abra o console do CloudWatch em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Escolha **Configurações** no painel de navegação à esquerda.
1. Escolha **Visualizar configurações** em **Grupos** na seção **Rastreamentos do X-Ray**.
1. Escolha um grupo na seção **Grupos** e selecione **Editar**.
1. Embora não seja possível renomear um grupo, você pode atualizar a expressão de filtro. Para obter mais informações sobre como criar uma expressão de filtro, consulte [Usar expressões de filtro](xray-console-filters.md). No exemplo a seguir, o grupo filtra rastreamentos de falha do serviço `api.example.com` em que o endereço do URL da solicitação contém `example/game` e o tempo de resposta para solicitações foi maior ou igual a cinco segundos.
```
fault = true AND http.url CONTAINS "example/game" AND responsetime >= 5
```
1. Em **Insights**, habilite ou desabilite o acesso a insights para o grupo. Para obter mais informações sobre insights, consulte [Usar os insights do X-Ray](xray-console-insights.md).
![\[Caixas de seleção Insights na página do grupo\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/group-insights-cw.png)
1. Em **Tags**, escolha **Adicionar nova tag** para inserir uma chave de tag e, opcionalmente, um valor de tag. Continue adicionando outras tags conforme desejado. As chaves de tag devem ser exclusivas. Para excluir uma tag, escolha **Remover** abaixo de cada tag. Para obter mais informações sobre tags, consulte [Marcar grupos e regras de amostragem do X-Ray](xray-tagging.md).
![\[Campos de tag na página Grupo\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/group-tags-cw.png)
1. Quando terminar de atualizar o grupo, escolha **Atualizar grupo**.
------
#### [ X-Ray console ]
1. Faça login no Console de gerenciamento da AWS e abra o console do X-Ray em [https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home).
1. Realize uma das seguintes ações para abrir a página **Editar grupo**:
1. Na página **Grupos**, escolha o nome de um grupo para editá-lo.
1. No menu de grupos em uma das páginas a seguir, aponte para um grupo e escolha **Editar**.
+ **Mapa de rastreamento**
+ **Rastreamentos**
+ **Analytics**
1. Embora não seja possível renomear um grupo, você pode atualizar a expressão de filtro. Para obter mais informações sobre como criar uma expressão de filtro, consulte [Usar expressões de filtro](xray-console-filters.md). No exemplo a seguir, o grupo filtra rastreamentos de falha do serviço `api.example.com` em que o endereço do URL da solicitação contém `example/game` e o tempo de resposta para solicitações foi maior ou igual a cinco segundos.
```
fault = true AND http.url CONTAINS "example/game" AND responsetime >= 5
```
1. Em **Insights**, habilite ou desabilite os insights e as notificações de insights para o grupo. Para obter mais informações sobre insights, consulte [Usar os insights do X-Ray](xray-console-insights.md).
![\[Caixas de seleção Insights na página do grupo\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/group-insights.png)
1. Em **Tags**, edite chaves e valores da tag. As chaves de tag devem ser exclusivas. Os valores das tags são opcionais; você pode excluir valores se quiser. Para excluir uma tag, escolha **X** no final da linha da tag. Para obter mais informações sobre tags, consulte [Marcar grupos e regras de amostragem do X-Ray](xray-tagging.md).
![\[Campos de tag na página Grupo\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/group-tags.png)
1. Quando terminar de atualizar o grupo, escolha **Atualizar grupo**.
------
## Clonar um grupo
A clonagem de um grupo cria um grupo com a expressão de filtro e as tags de um grupo existente. Quando você clona um grupo, o novo tem o mesmo nome do grupo do qual ele foi clonado, com `-clone` anexado ao nome.
------
#### [ CloudWatch console ]
1. Faça login no Console de gerenciamento da AWS e abra o console do CloudWatch em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Escolha **Configurações** no painel de navegação à esquerda.
1. Escolha **Visualizar configurações** em **Grupos** na seção **Rastreamentos do X-Ray**.
1. Escolha um grupo na seção **Grupos** e selecione **Clonar**.
1. Na página **Criar grupo**, o nome do grupo é *group-name*`-clone`. Opcionalmente, insira um novo nome para o grupo. O nome de grupo pode ter no máximo 32 caracteres, mas somente caracteres alfanuméricos e hifens. Os nomes de grupo diferenciam letras maiúsculas de minúsculas.
1. Você pode manter a expressão de filtro do grupo ou, opcionalmente, inserir uma nova expressão de filtro. Para obter mais informações sobre como criar uma expressão de filtro, consulte [Usar expressões de filtro](xray-console-filters.md). No exemplo a seguir, o grupo filtra os rastreamentos de falhas do serviço `api.example.com` e as solicitações ao serviço em que o tempo de resposta foi maior ou igual a cinco segundos.
```
service("api.example.com") { fault = true OR responsetime >= 5 }
```
1. Em **Tags**, edite chaves e valores da tag, se necessário. As chaves de tag devem ser exclusivas. Os valores das tags são opcionais; você pode excluir valores se quiser. Para excluir uma tag, escolha **X** no final da linha da tag. Para obter mais informações sobre tags, consulte [Marcar grupos e regras de amostragem do X-Ray](xray-tagging.md).
1. Escolha **Criar grupo**.
------
#### [ X-Ray console ]
1. Faça login no Console de gerenciamento da AWS e abra o console do X-Ray em [https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home).
1. Abra a página **Grupos** no painel de navegação esquerdo e escolha o nome de um grupo que você deseja clonar.
1. No menu **Ações**, escolha **Clonar grupo**.
1. Na página **Criar grupo**, o nome do grupo é *group-name*`-clone`. Opcionalmente, insira um novo nome para o grupo. O nome de grupo pode ter no máximo 32 caracteres, mas somente caracteres alfanuméricos e hifens. Os nomes de grupo diferenciam letras maiúsculas de minúsculas.
1. Você pode manter a expressão de filtro do grupo ou, opcionalmente, inserir uma nova expressão de filtro. Para obter mais informações sobre como criar uma expressão de filtro, consulte [Usar expressões de filtro](xray-console-filters.md). No exemplo a seguir, o grupo filtra os rastreamentos de falhas do serviço `api.example.com` e as solicitações ao serviço em que o tempo de resposta foi maior ou igual a cinco segundos.
```
service("api.example.com") { fault = true OR responsetime >= 5 }
```
1. Em **Tags**, edite chaves e valores da tag, se necessário. As chaves de tag devem ser exclusivas. Os valores das tags são opcionais; você pode excluir valores se quiser. Para excluir uma tag, escolha **X** no final da linha da tag. Para obter mais informações sobre tags, consulte [Marcar grupos e regras de amostragem do X-Ray](xray-tagging.md).
1. Escolha **Criar grupo**.
------
## Excluir um grupo
Siga as etapas nesta seção para excluir um grupo. Não é possível excluir o grupo **padrão**.
------
#### [ CloudWatch console ]
1. Faça login no Console de gerenciamento da AWS e abra o console do CloudWatch em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Escolha **Configurações** no painel de navegação à esquerda.
1. Escolha **Visualizar configurações** em **Grupos** na seção **Rastreamentos do X-Ray**.
1. Escolha um grupo na seção **Grupos** e selecione **Excluir**.
1. Quando for solicitada sua confirmação, escolha **Excluir**.
------
#### [ X-Ray console ]
1. Faça login no Console de gerenciamento da AWS e abra o console do X-Ray em [https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home).
1. Abra a página **Grupos** no painel de navegação esquerdo e escolha o nome de um grupo que você deseja excluir.
1. No menu **Ações**, escolha **Excluir grupo**.
1. Quando for solicitada sua confirmação, escolha **Excluir**.
------
## Visualizar métricas de grupo no Amazon CloudWatch
Assim que um grupo é criado, os rastreamentos de entrada são verificados em relação à expressão de filtro do grupo, pois são armazenados no serviço X-Ray. As métricas referentes à quantidade de rastreamentos correspondentes a cada critério são publicadas no Amazon CloudWatch a cada minuto. Escolher **Exibir métricas** na página **Editar grupo** abre o console do CloudWatch na página **Métrica**. Para obter mais informações sobre como usar métricas do CloudWatch, consulte [Usar métricas do Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html) no *Guia do usuário do Amazon CloudWatch*.
------
#### [ CloudWatch console ]
1. Faça login no Console de gerenciamento da AWS e abra o console do CloudWatch em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Escolha **Configurações** no painel de navegação à esquerda.
1. Escolha **Visualizar configurações** em **Grupos** na seção **Rastreamentos do X-Ray**.
1. Escolha um grupo na seção **Grupos** e selecione **Editar**.
1. Na página **Editar grupo** escolha **Exibir métrica**.
A página **Métricas** do console do CloudWatch é aberta em uma nova guia.
------
#### [ X-Ray console ]
1. Faça login no Console de gerenciamento da AWS e abra o console do X-Ray em [https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home).
1. Abra a página **Grupos** no painel de navegação esquerdo e escolha o nome de um grupo do qual você deseja visualizar as métricas.
1. Na página **Editar grupo** escolha **Exibir métrica**.
A página **Métricas** do console do CloudWatch é aberta em uma nova guia.
------
# Configurar regras de amostragem
Você pode usar o AWS X-Ray console para configurar regras de amostragem para seus serviços. O AWS Distro for OpenTelemetry, X-Ray SDK e Serviços da AWS que oferecem suporte ao [rastreamento ativo com configurações de amostragem](xray-services.md) usam regras de amostragem para determinar quais solicitações devem ser registradas.
**Topics**
+ [Configurar regras de amostragem](#xray-console-config)
+ [Personalizar regras de amostragem](#xray-console-custom)
+ [Opções de regras de amostragem](#xray-console-sampling-options)
+ [Exemplos de regras de amostragem](#xray-console-sampling-examples)
+ [Configurar o serviço para usar regras de amostragem](#xray-console-sampling-service)
+ [Visualização dos resultados de amostragem](#xray-console-sampling-results)
+ [Próximas etapas](#xray-console-sampling-nextsteps)
## Configurar regras de amostragem
Você pode configurar a amostragem para os seguintes casos de uso:
+ **Ponto de entrada do API Gateway**: o API Gateway é compatível com amostragem e rastreamento ativo. Para habilitar o rastreamento ativo em um estágio de API, consulte [Compatibilidade com o rastreamento ativo do Amazon API Gateway para o AWS X-Ray](xray-services-apigateway.md).
+ **AWS AppSync**— AWS AppSync suporta amostragem e rastreamento ativo. Para ativar o rastreamento ativo nas AWS AppSync solicitações, consulte [Rastreamento com X-Ray AWS](https://docs.aws.amazon.com/appsync/latest/devguide/x-ray-tracing.html).
+ **AWS Step Functions**— AWS Step Functions suporta amostragem e rastreamento ativo. Para ativar o rastreamento ativo em máquinas de AWS Step Functions estado, consulte [Rastreamento de X-Ray em Step Functions](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-xray-tracing.html).
+ **Instrument AWS Distro para OpenTelemetry plataformas computacionais — Ao usar plataformas** computacionais como Amazon, EC2 Amazon ECS ou AWS Elastic Beanstalk, a amostragem é suportada quando o aplicativo foi instrumentado com o mais recente AWS Distro for ou X-Ray SDK. OpenTelemetry
## Personalizar regras de amostragem
Ao personalizar regras de amostragem, você pode controlar a quantidade de dados registrados. Você também pode modificar o comportamento da amostragem sem modificar ou reimplantar seu código. As regras de amostragem informam ao AWS Distro for OpenTelemetry (ADOT) ou ao X-Ray SDK quantas solicitações devem ser registradas de acordo com um conjunto de critérios. Por padrão, o SDK registra a primeira solicitação a cada segundo e cinco por cento de todas as solicitações adicionais. Uma solicitação por segundo é o *reservatório*. Isso garante que pelo menos um rastreamento seja registrado a cada segundo à medida que o serviço atende às solicitações. Cinco por cento é a *taxa* segundo a qual as solicitações adicionais, além do tamanho de reservatório, são amostradas.
Você pode configurar o X-Ray SDK para ler as regras de amostragem de um documento JSON incluído com seu código. No entanto, ao executar várias instâncias do seu serviço, cada instância realiza a amostragem de forma independente. Isso faz com que a porcentagem total de solicitações amostradas aumente, pois os reservatórios de todas as instâncias são efetivamente somados. Além disso, para atualizar as regras de amostragem locais, você deve reimplantar seu código.
Ao definir regras de amostragem no console do X-Ray e [configurar o SDK](#xray-console-sampling-service) para ler as regras do serviço do X-Ray, você pode evitar esses problemas. O serviço gerencia o reservatório para cada regra e atribui cotas para cada instância de seu serviço a fim de distribuir o reservatório uniformemente com base no número de instâncias que estão em execução. O limite do reservatório é calculado de acordo com as regras definidas. Como as regras são configuradas no serviço, você pode gerenciá-las sem fazer implantações adicionais.
**nota**
Ao configurar as regras de amostragem, é fundamental entender que a amostragem por X-Ray é “baseada nos pais”. Isso significa que a decisão de amostragem é tomada apenas uma vez, normalmente pelo primeiro X-Ray-enabled serviço que processa a solicitação (o serviço “Root”).
Se um serviço downstream receber uma solicitação que já tenha uma decisão de amostragem de um pai upstream, ele honrará essa decisão independentemente de qualquer uma de suas próprias regras de amostragem correspondentes.
Quando as regras se aplicam: Suas regras de amostragem personalizadas só entram em vigor em serviços em que a decisão de amostragem ainda não foi tomada. Isso geralmente se aplica a:
O ponto de entrada do seu aplicativo (por exemplo, um API Gateway, um Load Balancer ou o primeiro microsserviço instrumentado).
Processos ou trabalhadores assíncronos que iniciam um novo rastreamento.
Armadilha comum: se você criar uma regra de amostragem estrita para o “Serviço B”, mas o “Serviço B” sempre for chamado pelo “Serviço A”, sua regra para o Serviço B provavelmente nunca será aplicada porque está simplesmente seguindo a decisão passada pelo Serviço A. Para alterar a amostragem de traços desse fluxo de trabalho, você deve configurar a regra de amostragem para o serviço raiz (Serviço A).
**nota**
Como o X-Ray usa a abordagem de melhor esforço na aplicação de regras de amostragem, em alguns casos a taxa de amostragem efetiva pode não corresponder exatamente às regras de amostragem configuradas. No entanto, com o tempo, o número de solicitações amostradas deve estar próximo à porcentagem configurada.
Agora você pode configurar as regras de amostragem do X-Ray no CloudWatch console da Amazon.
**Para configurar as regras de amostragem no console CloudWatch**
1. Faça login no Console de gerenciamento da AWS e abra o CloudWatch console em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. **Escolha **Configurações** no painel de navegação esquerdo, abaixo de Configuração.**
1. Escolha **Ver configurações** em **Regras de amostragem** na seção **Rastreamento do X-Ray**.
1. Para criar uma regra, escolha **Criar regra de amostragem**.
Para editar uma regra, escolha uma regra e selecione **Editar** para editá-la.
Para excluir uma regra, escolha uma regra e selecione **Excluir**, para excluí-la.
## Opções de regras de amostragem
As opções a seguir estão disponíveis para cada regra. Valores de string podem usar curingas para corresponder a um caractere único (`?`) ou zero ou mais caracteres (`*`).
**Opções de regras de amostragem**
+ **Nome da regra** (string): um nome exclusivo para a regra.
+ **Prioridade** (inteiro entre 1 e 9.999): a prioridade da regra de amostragem. Os serviços avaliam as regras em ordem decrescente de prioridade e tomam uma decisão de amostragem com a primeira regra correspondente.
+ **Reservatório** (inteiro não negativo): um número fixo de solicitações correspondentes para instrumentar por segundo, antes de aplicar a taxa fixa. O reservatório não é usado diretamente pelos serviços, mas se aplica a todos os serviços usando a regra coletivamente.
+ **Taxa** (número inteiro entre 0 e 100): a porcentagem de solicitações correspondentes para instrumentar, depois que o reservatório está esgotado. Ao configurar uma regra de amostragem no console, escolha uma porcentagem entre 0 e 100. Ao configurar uma regra de amostragem em um SDK de cliente usando um documento JSON, forneça um valor percentual entre 0 e 1.
+ **Nome do serviço** (string): o nome do serviço instrumentado, como ele aparece no mapa de rastreamento.
+ X-Ray SDK: o nome do serviço que você configura no gravador.
+ Amazon API Gateway: `api-name/stage`.
+ **Tipo do serviço** (string): o tipo de serviço, como ele aparece no mapa de rastreamento. Para o X-Ray SDK, defina o tipo de serviço aplicando o plug-in apropriado:
+ `AWS::ElasticBeanstalk::Environment`— Um AWS Elastic Beanstalk ambiente (plugin).
+ `AWS::EC2::Instance`— Uma EC2 instância da Amazon (plugin).
+ `AWS::ECS::Container`: um contêiner do Amazon ECS (plug-in).
+ `AWS::EKS::Container`— Um contêiner Amazon EKS (plugin).
+ `AWS::APIGateway::Stage`: um estágio do Amazon API Gateway.
+ `AWS::AppSync::GraphQLAPI `— Uma solicitação de AWS AppSync API.
+ `AWS::StepFunctions::StateMachine`— Uma máquina AWS Step Functions estatal.
+ **Host** (string): o nome de host do cabeçalho de host HTTP.
+ **Método HTTP** (string): o método da solicitação HTTP.
+ **Caminho do URL (string)**: o caminho URL da solicitação.
+ X-Ray SDK: a porção do caminho URL da solicitação HTTP.
+ **ARN do recurso** (string) — O ARN do AWS recurso que está executando o serviço.
+ X-Ray SDK: sem suporte. O SDK só pode usar regras com o **Resource ARN (ARN do recurso)** definido como `*`.
+ Amazon API Gateway: o ARN do estágio.
+ (Opcional) **Atributos** (chave e valor): atributos de segmento que são conhecidos quando a decisão de amostragem é feita.
+ X-Ray SDK: sem suporte. O SDK ignora as regras que especificam atributos.
+ Amazon API Gateway: cabeçalhos da solicitação HTTP original.
+ (Opcional) **SamplingRateBoost**(objeto) — Controla o comportamento de aumento de amostragem baseado em anomalias.
+ MaxRate (número inteiro entre 0 e 100) — Taxa máxima de amostragem (0,0—1,0) O raio-X pode aumentar para durante anomalias
+ CooldownWindowMinutes (número inteiro maior que 0) — Janela de tempo (minutos) na qual somente um impulso pode ser acionado, evitando aumentos contínuos
## Exemplos de regras de amostragem
**Example Exemplo: regra padrão sem reservatório e com taxa baixa**
Você pode modificar o reservatório e a taxa da regra padrão. A regra padrão se aplica às solicitações que não correspondem a nenhuma outra regra.
+ **Reservatório**: **0**
+ **Taxa**: **5** (**0.05** se configurada usando um documento JSON)
**Example Exemplo: regra de depuração para rastrear todas as solicitações para uma rota problemática**
Uma regra de alta prioridade aplicada temporariamente para depuração.
+ **Nome da regra**: **DEBUG – history updates**
+ **Prioridade**: **1**
+ **Reservatório**: **1**
+ **Taxa**: **100** (**1** se configurada usando um documento JSON)
+ **Nome de serviço**: **Scorekeep**
+ **Tipo de serviço:** **\$1**
+ **Host**: **\$1**
+ **Método HTTP**: **PUT**
+ **Caminho URL**: **/history/\$1**
+ **ARN do recurso**: **\$1**
**Example — Taxa mínima mais alta para POSTs**
+ **Nome da regra**: **POST minimum**
+ **Prioridade**: **100**
+ **Reservatório**: **10**
+ **Taxa**: **10** (**.1** se configurada usando um documento JSON)
+ **Nome de serviço**: **\$1**
+ **Tipo de serviço:** **\$1**
+ **Host**: **\$1**
+ **Método HTTP**: **POST**
+ **Caminho URL**: **\$1**
+ **ARN do recurso**: **\$1**
**Example Ativar o aumento impulsionado por anomalias**
Configure uma regra que acione um aumento de amostragem para até 50% durante anomalias, com um tempo de desaquecimento de 10 minutos.
+ **Nome da regra**: **MyAdaptiveRule**
+ **Prioridade**: **100**
+ **Reservatório**: **1**
+ **FixedRate**: **0.0510**
+ **Nome de serviço**: **\$1**
+ **Tipo de serviço:** **\$1**
+ **Host**: **\$1**
+ **Método HTTP**: **POST**
+ **Caminho URL**: **\$1**
+ **maxRate**: **0.5**
+ **cooldownWindowMinutes**: **10**
## Configurar o serviço para usar regras de amostragem
O AWS Distro for OpenTelemetry (ADOT) e o X-Ray SDK exigem configuração adicional para usar as regras de amostragem que você configura no console. Consulte o tópico de configuração referente à sua linguagem para obter detalhes sobre como configurar uma estratégia de amostragem:
+ Java: [Usando a amostragem remota X-Ray](https://aws-otel.github.io/docs/getting-started/java-sdk/auto-instr#using-x-ray-remote-sampling) com ADOT Java
+ Go: [Configurando a amostragem](https://aws-otel.github.io/docs/getting-started/go-sdk/manual-instr#configuring-sampling) com o ADOT Go
+ Node.js: [Usando a amostragem remota X-Ray com ADOT](https://aws-otel.github.io/docs/getting-started/js-sdk/trace-metric-auto-instr#using-x-ray-remote-sampling) JavaScript
+ Python: Usando o [X-Ray Remote Sampling](https://aws-otel.github.io/docs/getting-started/python-sdk/auto-instr#using-x-ray-remote-sampling) com ADOT Python
+ Ruby: [Regras de amostragem](xray-sdk-ruby-configuration.md#xray-sdk-ruby-configuration-sampling)
+ .NET: [Usando o X-Ray Remote Sampling](https://aws-otel.github.io/docs/getting-started/dotnet-sdk/auto-instr#using-x-ray-remote-sampling) com ADOT.NET
Para API Gateway, consulte [Compatibilidade com o rastreamento ativo do Amazon API Gateway para o AWS X-Ray](xray-services-apigateway.md).
## Visualização dos resultados de amostragem
A página **Amostragem** do console do X-Ray mostra informações detalhadas sobre como seus serviços usam cada regra de amostragem.
A coluna **Trend (Tendência)** mostra como a regra foi usada nos últimos minutos. Cada coluna mostra estatísticas para uma janela de 10 segundos.
**Estatísticas da amostragem**
+ **Total de regras correspondidas**: o número de solicitações que correspondem a essa regra. Esse número não inclui solicitações que poderiam ter correspondido essa regra, mas que primeiro encontraram uma regra correspondente de prioridade mais alta.
+ **Total de amostra** o número de solicitações registradas.
+ **Amostradas com taxa fixa**: o número de solicitações amostradas aplicando a taxa fixa da regra.
+ **Amostra com reservatório limite**: o número de solicitações amostradas usando uma cota atribuída pelo X-Ray.
+ **Emprestado do reservatório**: o número de solicitações amostradas por empréstimo do reservatório. Na primeira vez em que um serviço corresponde a uma solicitação de uma regra, ele não recebe uma cota do X-Ray. No entanto, se o reservatório for pelo menos 1, o serviço tomará emprestado um rastreamento por segundo até que o X-Ray atribua uma cota.
Para obter mais informações sobre as estatísticas de amostragem e como usar os serviços de regras de amostragem, consulte [Usar regras de amostragem com a API do X-Ray](xray-api-sampling.md).
## Próximas etapas
Você pode usar a API do X-Ray para gerenciar as regras de amostragem. Com a API, você pode criar e atualizar regras de forma programática, em uma programação ou em resposta a alarmes ou notificações. Consulte [Definindo configurações de amostragem, grupos e criptografia com a API AWS X-Ray](xray-api-configuration.md) para obter instruções e ver mais exemplos de regras.
O AWS Distro for OpenTelemetry, o X-Ray SDK Serviços da AWS também usa a API X-Ray para ler regras de amostragem, relatar resultados de amostragem e obter alvos de amostragem. Os serviços devem controlar a frequência com que eles aplicam cada regra, avaliam as regras com base na prioridade e tomam emprestado do reservatório quando uma solicitação corresponde a uma regra para a qual o X-Ray ainda não tiver atribuído uma cota de serviço. Para obter mais detalhes sobre como um serviço usa a API de amostragem, consulte [Usar regras de amostragem com a API do X-Ray](xray-api-sampling.md).
Quando o AWS Distro for OpenTelemetry ou o X-Ray SDK chamam a amostragem APIs, eles usam o CloudWatch agente como proxy. Se você já usa a porta TCP 2000, pode configurar o agente para executar o proxy em uma porta diferente. Consulte o [guia de instalação do CloudWatch agente](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html) para obter detalhes.
# Configurar amostragem adaptável
A falta de rastreamentos críticos durante picos de anomalias pode dificultar a análise da causa raiz. No entanto, a manutenção de altas taxas de amostragem é cara. A amostragem adaptativa do X-Ray proporciona visibilidade completa das anomalias e controla os custos durante as operações normais. Com a amostragem adaptativa, você define uma taxa máxima de amostragem, e o X-Ray se ajusta automaticamente dentro desse limite. O X-Ray calcula o aumento mínimo necessário para capturar rastreamentos de erros. Se sua taxa de base capturar dados suficientes, nenhum aumento ocorrerá. Você só paga pela amostragem extra quando necessário.
Benefícios do uso da amostragem adaptável:
+ Visibilidade completa do incidente: obtenha rastreamentos completos durante os incidentes sem intervenção manual. O X-Ray ajusta automaticamente as taxas de amostragem para capturar rastreamentos de erros e, depois, retorna às taxas normais.
+ Visibilidade da causa raiz: confira sempre a origem dos problemas. O X-Ray captura dados de erros críticos mesmo quando a amostragem completa do traço não é acionada.
+ Otimize os custos: breves aumentos de amostragem (até 1 minuto) e períodos de espera automático evitam a sobreamostragem. Você só paga pelos dados necessários para diagnosticar problemas.
**Topics**
+ [SDKs e plataformas compatíveis](#adaptive-sampling-supported-sdks)
+ [Escolha sua abordagem de amostragem adaptável](#adaptive-sampling-features)
+ [Configuração do SDK local](#local-sdk-configuration)
## SDKs e plataformas compatíveis
**SDK compatível**: a amostragem adaptável requer a versão mais recente do SDK do ADOT.
**Linguagem compatível**: Java (versão [v2.11.5](https://github.com/aws-observability/aws-otel-java-instrumentation/releases/tag/v2.11.5) ou superior)
Sua aplicação deve ser instrumentada com o SDK do ADOT compatível e executada com o agente do Amazon CloudWatch ou o coletor do OpenTelemetry.
Por exemplo, o Amazon EC2, o Amazon ECS e o Amazon EKS são plataformas comuns nas quais o AWS Application Signals fornece orientações para ativar o SDK do ADOT e o agente do Amazon CloudWatch.
## Escolha sua abordagem de amostragem adaptável
A amostragem adaptável é compatível com duas abordagens: Aumento de amostragem e Captura de extensões de anomalias. Elas podem ser aplicadas de maneira independente ou podem ser combinadas.
### Aumento de amostragem
O aumento adaptável de amostragem se baseia em regras de amostragem e funciona com o modelo existente de amostragem com base no principal do X-Ray. Amostragem baseada em principais significa que as decisões de amostragem são tomadas no serviço raiz, e o indicador de amostragem é passado downstream para todos os serviços na cadeia de chamadas.
+ **Aumento baseado em regras**: o aumento está sempre vinculado a uma regra específica de amostragem do X-Ray. Cada regra pode definir sua própria taxa máxima de aumento e comportamento de espera.
+ **Amostragem baseada em principal**: as decisões de amostragem são tomadas no serviço raiz, e o indicador de amostragem é passado downstream para todos os serviços na cadeia de chamadas.
+ **Orientado por anomalias**: o X-Ray depende do SDK para relatar estatísticas de anomalias. Quando o X-Ray detecta anomalias, como erros ou alta latência, ele usa essas estatísticas para calcular uma taxa de aumento apropriada (até o máximo configurado).
**Relatórios de anomalias**
Cada serviço de aplicativo na cadeia de chamadas pode emitir estatísticas de anomalias por meio do SDK necessário:
+ **Serviço raiz**: deve ser executado em um SDK e uma plataforma compatíveis para permitir o aumento da amostragem. Se o serviço raiz não for compatível, nenhum aumento ocorrerá.
+ **Serviços downstream**: os serviços downstream relatam apenas anomalias; eles não podem tomar decisões de amostragem. Quando um serviço downstream está executando um SDK compatível, as anomalias detectadas podem acionar um aumento na amostragem. Quando um serviço downstream não é compatível (por exemplo, executando um SDK antigo), anomalias nesse serviço não acionarão um aumento. Esses serviços ainda podem propagar o contexto downstream quando seguem a propagação padrão do contexto (como contexto de rastreamento e bagagem do W3C). Isso garante que os SDKs compatíveis em outros serviços downstream possam relatar anomalias que desencadeiam um aumento.
**Aumentar o tempo e o escopo**
+ **Atraso do gatilho**: um aumento de amostragem pode começar em apenas 10 segundos após o X-Ray detectar uma anomalia.
+ **Período de aumento**: depois que o X-Ray aciona um aumento, ele dura até 1 minuto antes de retornar à taxa de base de amostragem.
+ **Aumento de espera**: após a ocorrência de um aumento, o X-Ray só acionará outro impulso para a mesma regra depois que a janela de espera tiver passado.
Por exemplo, quando você define `cooldown` para 10 minutos, quando um aumento termina, nenhum novo aumento poderá ser acionado até a próxima janela de 10 minutos.
Caso especial: quando você define `cooldown` para 1 minuto, e como o aumento em si pode durar até 1 minuto, os impulsos podem ser acionados de maneira eficaz e contínua se a anomalia persistir.
**nota**
Use SDKs e plataformas compatíveis para seu serviço raiz. O aumento de amostragem funciona somente com SDKs e plataformas compatíveis. Embora o aumento de amostragem tenha uma alta probabilidade de capturar rastreamentos de anomalias, ele pode não capturar todos os rastreamentos de anomalia.
**Aumentar a visibilidade**
Quando uma regra de amostragem é configurada com aumento de amostragem adaptável, o X-Ray emite automaticamente métricas fornecidas que permitem monitorar a atividade do aumento.
+ **Nome da métrica** – `SamplingRate`
+ **Dimensão** — `RuleName` (definida como o nome real da regra)
Cada regra com `SamplingRateBoost` habilitado publicará sua taxa de amostragem efetiva, incluindo a taxa de base e quaisquer aumentos temporários. Isso permite a você:
+ Monitorar quando os aumentos são acionados
+ Monitorar a taxa de amostragem efetiva para cada regra
+ Correlacionar os aumentos com anomalias do aplicativo (como picos de erros ou eventos de latência)
Você pode visualizar essas métricas no **Amazon CloudWatch Metrics, em AWS/X-Ray namespace. O valor métrico é um número de ponto flutuante entre 0 e 1, representando a taxa de amostragem efetiva**.
**Configurar o aumento de amostragem usando regras de amostragem do X-Ray**
Você pode habilitar a amostragem adaptável diretamente nas regras existentes de amostragem do X-Ray adicionando um novo campo `SamplingRateBoost`. Para obter mais informações, consulte [Personalizar regras de amostragem](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html#xray-console-custom). Essa é uma maneira centralizada de permitir a amostragem adaptável sem modificar o código do aplicativo ou aplicar a implantação dele. Quando você habilita a amostragem adaptativa, o X-Ray aumenta automaticamente a amostragem durante anomalias, como picos de erro ou valores discrepantes de latência, mantendo as taxas de amostragem dentro do limite máximo configurado. `SamplingRateBoost` pode ser aplicado a qualquer regra de amostragem personalizada, exceto à regra de amostragem `Default`.
O campo `SamplingRateBoost` define o limite superior e o comportamento da amostragem baseada em anomalias.
```
"SamplingRateBoost": {
"MaxRate": 0.25,
"CooldownWindowMinutes": 10
}
```
`MaxRate` define a taxa máxima de amostragem que o X-Ray aplicará ao detectar anomalias. O intervalo de valores é de `0.0` a `1.0`. Por exemplo, `"MaxRate": 0.25` permite que a amostragem aumente em até 25% das solicitações durante uma janela de anomalia. O X-Ray determina a taxa apropriada entre a sua linha de base e a máxima, dependendo da atividade da anomalia.
`CooldownWindowMinutes` define a janela de tempo (em minutos) na qual apenas um aumento na taxa de amostragem pode ser acionado. Depois que um aumento ocorre, nenhum aumento adicional é permitido até a próxima janela. O tipo de valor é *inteiro (minutos)*.
**Exemplo de regra com amostragem adaptável**
```
{
"RuleName": "MyAdaptiveRule",
"Priority": 1,
"ReservoirSize": 1,
"FixedRate": 0.05,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"SamplingRateBoost": {
"MaxRate": 0.25,
"CooldownWindowMinutes": 10
}
}
```
Neste exemplo, a amostragem de linha de base é 5% (`FixedRate: 0.05`). Durante anomalias, o X-Ray pode aumentar a amostragem em até 25% (`MaxRate: 0.25`). Aumente apenas uma vez a cada 10 minutos.
**Configuração da condição de anomalia**
Quando nenhuma configuração de condição de anomalia é fornecida, o SDK do ADOT usa **códigos de erro HTTP 5xx** como condição de anomalia padrão para acionar o aumento da amostragem.
Você também pode ajustar as condições de anomalia localmente no SDK do ADOT compatível usando variáveis de ambiente. Para obter mais informações, consulte [Configuração do SDK local](#local-sdk-configuration).
### Captura de extensões de anomalias
A captura da extensão de anomalias garante que as extensões críticas que representam anomalias sejam sempre registradas, mesmo que o rastreamento completo não seja amostrado. Esse recurso complementa o aumento da amostragem, concentrando-se na captura da anomalia em si, em vez de aumentar a amostragem para futuros rastreamentos.
Quando o SDK do ADOT detecta uma anomalia, ele emite essa extensão imediatamente, independentemente da decisão de amostragem. Como o SDK só emite extensões relacionadas à anomalia, esses rastreamentos são parciais, não transações completas de ponta a ponta.
Depois que o SDK do ADOT detecta uma extensão de anomalia, ele tenta emitir o maior número possível de extensões do mesmo rastreamento. Todas as extensões emitidas nesse recurso são marcadas com o atributo, `aws.trace.flag.sampled = 0`. Isso permite distinguir facilmente traços parciais (captura de anomalias) de traços completos (amostragem normal) na pesquisa e análise de transações.
É recomendável integrar a [Pesquisa de transações](https://docs.aws.amazon.com/xray/latest/devguide/xray-transactionsearch.html) para visualizar e consultar rastreamentos parciais. O exemplo a seguir mostra uma página de serviço no console do [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html). O ServiceC é configurado com captura de extensões de anomalias e faz parte de uma cadeia de chamadas em que o aumento da amostragem se aplica. Essas configurações geram rastreamentos completos e parciais. Você pode usar o atributo `aws.trace.flag.sampled` para distinguir entre os tipos de rastreamento.
![\[Captura de extensões de anomalias\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/adaptive-sampling.png)
A captura de extensões de anomalias só pode ser habilitada ou personalizada por meio do [Configuração do SDK local](#local-sdk-configuration).
## Configuração do SDK local
Você pode configurar recursos de amostragem adaptável no SDK do ADOT fornecendo uma configuração YAML por meio de uma variável de ambiente. A configuração local fornece controle refinado sobre condições e limites de anomalias.
Isso é necessário para a *captura de extensões de anomalias* e opcional para personalizar as condições de *aumento de amostragem*. Veja a seguir um exemplo de configuração:
```
version: 1.0
anomalyConditions:
- errorCodeRegex: "^5\\d\\d$"
usage: both
- operations:
- "/api"
errorCodeRegex: "^429|5\\d\\d$"
highLatencyMs: 300
usage: sampling-boost
- highLatencyMs: 1000
usage: anomaly-span-capture
anomalyCaptureLimit:
anomalyTracesPerSecond: 1
```
Confira as definições de campo abaixo:
+ `version`: versão do esquema do arquivo de configuração
+ `anomalyConditions`: define as condições sob as quais as anomalias são detectadas e como elas são usadas
+ `errorCodeRegex`: expressão regular que define quais códigos de status HTTP são considerados anomalias
+ `operations`: lista de operações ou endpoints aos quais a condição se aplica
+ `highLatencyMs`: limite de latência (em milissegundos) acima do qual as extensões são tratadas como anomalias
+ `usage`: define a qual recurso a condição se aplica:
+ `both`: aplica-se ao **aumento de amostragem** e à **captura de extensões de anomalias** (padrão se o uso não for especificado)
+ `sampling-boost`: usado somente para acionar aumentos de amostragem
+ `anomaly-span-capture`: usado somente para captura de extensões de anomalias
+ `anomalyCaptureLimit`: define os limites para a emissão de rastreamentos com extensões de anomalias.
`anomalyTracesPerSecond`: número máximo de rastreamentos com extensões de anomalias capturadas por segundo para evitar um volume excessivo de extensões (o valor padrão será 1 se anomalyCaptureLimit não estiver presente).
**nota**
`AnomalyConditions` **substitui** a condição de anomalia padrão para o aumento de amostragem (HTTP 5xx). Se você quiser reter a condição padrão ao usar a configuração local, deverá incluí-la explicitamente em qualquer item de `AnomalyConditions`.
Para cada item `anomalyConditions`:
Quando o campo `operations` é **omitido**, a condição se aplica a **todas as operações** (nível de serviço)
Quando o campo `operations` está presente, mas definido como uma **lista vazia**, a condição se aplica a **nenhuma operação**, tornando esse item sem operação
Quando `errorCodeRegex` e `highLatencyMs` são omitidos, a condição não tem critérios de anomalia a serem avaliados, tornando esse item sem operação
Relações lógicas:
Entre os itens em `anomalyConditions`, o relacionamento é **OR**.
Em um único item, vários campos (por exemplo, `errorCodeRegex` e`highLatencyMs`) são combinados com **AND**.
Por exemplo:
```
errorCodeRegex: "^429|5\\d\\d$"
highLatencyMs: 300
```
Essa condição significa que **o código de status corresponde a 429 ou 5xx E a latência é ≥ 300 ms**.
### Aplique a configuração local ao SDK do ADOT
Você pode aplicar a configuração local ao SDK do ADOT definindo a variável de ambiente `AWS_XRAY_ADAPTIVE_SAMPLING_CONFIG`. O valor deve ser um documento YAML válido (em linha ou aninhado).
Por exemplo, o Amazon EC2 e o Amazon ECS definem a variável de ambiente de maneira direta:
```
AWS_XRAY_ADAPTIVE_SAMPLING_CONFIG="{version: 1.0, anomalyConditions: [{errorCodeRegex: \"^500$\", usage: \"sampling-boost\"}, {errorCodeRegex: \"^501$\", usage: \"anomaly-trace-capture\"}], anomalyCaptureLimit: {anomalyTracesPerSecond: 10}}"
```
Para o Amazon EKS, defina a variável de ambiente dentro da especificação do pod como YAML aninhado:
```
apiVersion: v1
kind: Pod
metadata:
name: adot-sample
spec:
containers:
- name: adot-app
image: my-app:latest
env:
- name: AWS_XRAY_ADAPTIVE_SAMPLING_CONFIG
value: |
version: 1.0
anomalyConditions:
- errorCodeRegex: "^500$"
usage: sampling-boost
- errorCodeRegex: "^501$"
usage: anomaly-trace-capture
anomalyCaptureLimit:
anomalyTracesPerSecond: 10
```
# Vinculação direta do console
Você pode usar rotas e consultas para vinculação direta em rastreamentos específicos ou exibições filtradas de rastreamentos e mapas de rastreamento.
**Páginas do console**
+ Página de boas-vindas: [xray/home\$1/welcome](https://console.aws.amazon.com/xray/home#/welcome)
+ Conceitos básicos: [xray/home\$1/getting-started](https://console.aws.amazon.com/xray/home#/getting-started)
+ Mapa de rastreamento: [xray/home\$1/service-map](https://console.aws.amazon.com/xray/home#/service-map)
+ Rastreamentos: [xray/home\$1/traces](https://console.aws.amazon.com/xray/home#/traces)
## Rastreamentos
Você pode gerar links para as visualizações de cronograma, bruta e de mapa de rastreamentos individuais.
**Linha do tempo do rastreamento**: `xray/home#/traces/trace-id`
**Dados de rastreamento brutos**: `xray/home#/traces/trace-id/raw`
**Example Exemplo: dados de rastreamento brutos**
```
https://console.aws.amazon.com/xray/home#/traces/1-57f5498f-d91047849216d0f2ea3b6442/raw
```
## Expressões de filtro
Link para uma lista filtrada de rastreamentos.
**Visualização de rastreamentos filtrados**: `xray/home#/traces?filter=filter-expression`
**Example Exemplo: expressão de filtro**
```
https://console.aws.amazon.com/xray/home#/traces?filter=service("api.amazon.com") { fault = true OR responsetime > 2.5 } AND annotation.foo = "bar"
```
**Example Exemplo: expressão de filtro (URL codificado)**
```
https://console.aws.amazon.com/xray/home#/traces?filter=service(%22api.amazon.com%22)%20%7B%20fault%20%3D%20true%20OR%20responsetime%20%3E%202.5%20%7D%20AND%20annotation.foo%20%3D%20%22bar%22
```
Para obter mais informações sobre expressões de filtro, consulte [Usar expressões de filtro](xray-console-filters.md).
## Intervalo de tempo
Especifique um período ou hora inicial e final no formato ISO8601. Os intervalos de tempo estão em UTC e podem ser de até seis horas.
**Duração**: `xray/home#/page?timeRange=range-in-minutes`
**Example : mapa de rastreamento para a última hora**
```
https://console.aws.amazon.com/xray/home#/service-map?timeRange=PT1H
```
**Horas de início e término**: `xray/home#/page?timeRange=start~end`
**Example Exemplo: intervalo de tempo preciso em segundos**
```
https://console.aws.amazon.com/xray/home#/traces?timeRange=2023-7-01T16:00:00~2023-7-01T22:00:00
```
**Example Exemplo: intervalo de tempo preciso em minutos**
```
https://console.aws.amazon.com/xray/home#/traces?timeRange=2023-7-01T16:00~2023-7-01T22:00
```
## Região
Especifique uma Região da AWS a ser vinculada a páginas nessa região. Caso não especifique uma região, o console redirecionará você para a região visitada mais recentemente.
**Região**: `xray/home?region=region#/page`
**Example : mapa de rastreamento no Oeste dos EUA (Oregon) (us-west-2)**
```
https://console.aws.amazon.com/xray/home?region=us-west-2#/service-map
```
Quando você inclui uma região com outros parâmetros de consulta, a consulta da região fica antes do hash e as consultas específicas do X-Ray ficam depois do nome da página.
**Example : mapa de rastreamento na última hora no Oeste dos EUA (Oregon) (us-west-2)**
```
https://console.aws.amazon.com/xray/home?region=us-west-2#/service-map?timeRange=PT1H
```
## Combinado
**Example Exemplo: rastreamentos recentes com um filtro de duração**
```
https://console.aws.amazon.com/xray/home#/traces?timeRange=PT15M&filter=duration%20%3E%3D%205%20AND%20duration%20%3C%3D%208
```
**Resultado**
+ Página: Rastreamentos
+ Período: últimos 15 minutos
+ Filtro: duração >= 5 E duração <= 8
# Usar a API do X-Ray
Se o SDK do X-Ray não for compatível com sua linguagem de programação, você poderá usar as APIs do X-Ray diretamente ou o AWS Command Line Interface (AWS CLI) para chamar os comandos da API do X-Ray. Use as orientações a seguir para escolher como interagir com a API:
+ Use a AWS CLI para obter uma sintaxe mais simples usando comandos pré-formatados ou com opções dentro de sua solicitação.
+ Use a API do X-Ray diretamente para obter o máximo de flexibilidade e personalização das solicitações que você fizer ao X-Ray.
Se você usar a [API do X-Ray](https://docs.aws.amazon.com/xray/latest/api/Welcome.html) diretamente em vez da AWS CLI, será necessário parametrizar sua solicitação no formato de dados correto e talvez configurar a autenticação e o tratamento de erros.
O diagrama a seguir mostra orientações para escolher como interagir com a API do X-Ray:
![\[O X-Ray exibe informações detalhadas sobre as solicitações da aplicação.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/api-vs-cli.png)
Use a API do X-Ray para enviar dados de rastreamento diretamente para o X-Ray. A API do X-Ray é compatível com todas as funções disponíveis no SDK do X-Ray, incluindo as seguintes ações comuns:
+ [PutTraceSegments](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html): faz upload de documentos do segmento para o X-Ray.
+ [BatchGetTraces](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html): recupera uma lista de rastreamentos em uma lista de IDs de rastreamento. Cada rastreamento recuperado é uma coleção de documentos de segmento de uma única solicitação.
+ [GetTraceSummaries](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html): recupera IDs e anotações de rastreamentos. Você pode especificar uma `FilterExpression` para recuperar um subconjunto de resumos de rastreamento.
+ [GetTraceGraph](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceGraph.html): recupera um gráfico de serviço para um ID de rastreamento específico.
+ [GetServiceGraph](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html): recupera um documento formatado em JSON que descreve serviços que processam solicitações de entrada e chamam solicitações subsequentes.
Você também pode usar o AWS Command Line Interface (AWS CLI) dentro do código da aplicação para interagir programaticamente com o X-Ray. A AWS CLI é compatível com todas as funções disponíveis no SDK do X-Ray, incluindo aquelas para outros Serviços da AWS. As funções a seguir são versões das operações de API listadas anteriormente com um formato mais simples:
+ [put-trace-segments](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/put-trace-segments.html): faz upload de documentos do segmento para o X-Ray.
+ [batch-get-traces](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/batch-get-traces.html): recupera uma lista de rastreamentos em uma lista de IDs de rastreamento. Cada rastreamento recuperado é uma coleção de documentos de segmento de uma única solicitação.
+ [get-trace-summaries](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-trace-summaries.html): recupera IDs e anotações de rastreamentos. Você pode especificar uma `FilterExpression` para recuperar um subconjunto de resumos de rastreamento.
+ [get-trace-graph](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-trace-graph.html): recupera um gráfico de serviço para um ID de rastreamento específico.
+ [get-service-graph](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-service-graph.html): recupera um documento formatado em `JSON` que descreve serviços que processam solicitações de entrada e chamam solicitações subsequentes.
Para começar, você deve instalar a [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) para o seu sistema operacional. A AWS oferece suporte aos sistemas operacionais Linux, macOS e Windows. Para obter mais informações sobre a lista de comandos do X-Ray, consulte o [Guia de referência de comandos de AWS CLI para o X-Ray](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/index.html).
**Topics**
+ [Utilizar a API do AWS X-Ray com a AWS CLI](xray-api-tutorial.md)
+ [Enviando dados de rastreamento para AWS X-Ray](xray-api-sendingdata.md)
+ [Obter dados do AWS X-Ray](xray-api-gettingdata.md)
+ [Definindo configurações de amostragem, grupos e criptografia com a API AWS X-Ray](xray-api-configuration.md)
+ [Usar regras de amostragem com a API do X-Ray](xray-api-sampling.md)
+ [AWS X-RayDocumentos de segmento do](xray-api-segmentdocuments.md)
# Utilizar a API do AWS X-Ray com a AWS CLI
A AWS CLI permite que você acesse o serviço X-Ray diretamente e utilize as mesmas APIs que o console do X-Ray usa para recuperar o gráfico de serviço e os dados de rastreamento não processados. O aplicação de exemplo inclui scripts que mostram como usar essas APIs com a AWS CLI.
## Pré-requisitos
Este tutorial usa o aplicativo de amostra Scorekeep e scripts incluídos para gerar dados de rastreamento e um mapeamento de serviço. Siga as instruções no [tutorial de conceitos básicos](xray-gettingstarted.md) para iniciar o aplicativo.
Este tutorial utiliza a AWS CLI para mostrar o uso básico da API do X-Ray. A AWS CLI, [disponível para Windows, Linux e OS-X](https://docs.aws.amazon.com/cli/latest/userguide/installing.html), fornece acesso à linha de comando para as APIs públicas para todos os Serviços da AWS.
**nota**
Você deve verificar se a AWS CLI está configurada na mesma região em que o aplicativo de exemplo Scorekeep foi criado.
Os scripts incluídos para testar o aplicativo de exemplo usam `cURL` para enviar tráfego para a API e `jq` para analisar a saída. Você pode baixar do executável `jq` a partir de [stedolan.github.io](https://stedolan.github.io/jq/) e do executável `curl` a partir de [https://curl.haxx.se/download.html](https://curl.haxx.se/download.html). A maioria das instalações Linux e OS X incluem cURL.
## Gerar dados de rastreamento
O aplicativo Web continua a gerar tráfego para a API a cada poucos segundos enquanto o jogo está em andamento, mas apenas gera um tipo de solicitação. Use o script `test-api.sh` para executar cenários de ponta a ponta e gerar mais dados diversificados de rastreamento enquanto testa a API.
**Para usar o script `test-api.sh`**
1. Abra o [console do Elastic Beanstalk](https://console.aws.amazon.com/elasticbeanstalk).
1. Navegue até o [console de gerenciamento](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-console.html) do seu ambiente.
1. Copie o **URL** de ambiente do cabeçalho da página.
1. Abra `bin/test-api.sh` e substitua o valor para API com o URL do seu ambiente.
```
#!/bin/bash
API=scorekeep.9hbtbm23t2.us-west-2.elasticbeanstalk.com/api
```
1. Execute o script para gerar tráfego para a API.
```
~/debugger-tutorial$ ./bin/test-api.sh
Creating users,
session,
game,
configuring game,
playing game,
ending game,
game complete.
{"id":"MTBP8BAS","session":"HUF6IT64","name":"tic-tac-toe-test","users":["QFF3HBGM","KL6JR98D"],"rules":"102","startTime":1476314241,"endTime":1476314245,"states":["JQVLEOM2","D67QLPIC","VF9BM9NC","OEAA6GK9","2A705O73","1U2LFTLJ","HUKIDD70","BAN1C8FI","G3UDJTUF","AB70HVEV"],"moves":["BS8F8LQ","4MTTSPKP","463OETES","SVEBCL3N","N7CQ1GHP","O84ONEPD","EG4BPROQ","V4BLIDJ3","9RL3NPMV"]}
```
## Usar a API do X-Ray
A AWS CLI fornece comandos para todas as ações de API que o X-Ray fornece, incluindo [https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html) e [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html). Consulte a [AWS X-Ray Referência da API](https://docs.aws.amazon.com/xray/latest/api/Welcome.html) para mais informações sobre todas as ações suportadas e os tipos de dados que usam.
**Example bin/service-graph.sh**
```
EPOCH=$(date +%s)
aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH
```
O script recupera um gráfico de serviço para os últimos 10 minutos.
```
~/eb-java-scorekeep$ ./bin/service-graph.sh | less
{
"StartTime": 1479068648.0,
"Services": [
{
"StartTime": 1479068648.0,
"ReferenceId": 0,
"State": "unknown",
"EndTime": 1479068651.0,
"Type": "client",
"Edges": [
{
"StartTime": 1479068648.0,
"ReferenceId": 1,
"SummaryStatistics": {
"ErrorStatistics": {
"ThrottleCount": 0,
"TotalCount": 0,
"OtherCount": 0
},
"FaultStatistics": {
"TotalCount": 0,
"OtherCount": 0
},
"TotalCount": 2,
"OkCount": 2,
"TotalResponseTime": 0.054000139236450195
},
"EndTime": 1479068651.0,
"Aliases": []
}
]
},
{
"StartTime": 1479068648.0,
"Names": [
"scorekeep.elasticbeanstalk.com"
],
"ReferenceId": 1,
"State": "active",
"EndTime": 1479068651.0,
"Root": true,
"Name": "scorekeep.elasticbeanstalk.com",
...
```
**Example bin/trace-urls.sh**
```
EPOCH=$(date +%s)
aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Http.HttpURL'
```
O script recupera os URLs de rastreamentos gerados entre um e dois minutos atrás.
```
~/eb-java-scorekeep$ ./bin/trace-urls.sh
[
"http://scorekeep.elasticbeanstalk.com/api/game/6Q0UE1DG/5FGLM9U3/endtime/1479069438",
"http://scorekeep.elasticbeanstalk.com/api/session/KH4341QH",
"http://scorekeep.elasticbeanstalk.com/api/game/GLQBJ3K5/153AHDIA",
"http://scorekeep.elasticbeanstalk.com/api/game/VPDL672J/G2V41HM6/endtime/1479069466"
]
```
**Example bin/full-traces.sh**
```
EPOCH=$(date +%s)
TRACEIDS=$(aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Id' --output text)
aws xray batch-get-traces --trace-ids $TRACEIDS --query 'Traces[*]'
```
O script recupera rastreamentos completos gerados entre um e dois minutos atrás.
```
~/eb-java-scorekeep$ ./bin/full-traces.sh | less
[
{
"Segments": [
{
"Id": "3f212bc237bafd5d",
"Document": "{\"id\":\"3f212bc237bafd5d\",\"name\":\"DynamoDB\",\"trace_id\":\"1-5828d9f2-a90669393f4343211bc1cf75\",\"start_time\":1.479072242459E9,\"end_time\":1.479072242477E9,\"parent_id\":\"72a08dcf87991ca9\",\"http\":{\"response\":{\"content_length\":60,\"status\":200}},\"inferred\":true,\"aws\":{\"consistent_read\":false,\"table_name\":\"scorekeep-session-xray\",\"operation\":\"GetItem\",\"request_id\":\"QAKE0S8DD0LJM245KAOPMA746BVV4KQNSO5AEMVJF66Q9ASUAAJG\",\"resource_names\":[\"scorekeep-session-xray\"]},\"origin\":\"AWS::DynamoDB::Table\"}"
},
{
"Id": "309e355f1148347f",
"Document": "{\"id\":\"309e355f1148347f\",\"name\":\"DynamoDB\",\"trace_id\":\"1-5828d9f2-a90669393f4343211bc1cf75\",\"start_time\":1.479072242477E9,\"end_time\":1.479072242494E9,\"parent_id\":\"37f14ef837f00022\",\"http\":{\"response\":{\"content_length\":606,\"status\":200}},\"inferred\":true,\"aws\":{\"table_name\":\"scorekeep-game-xray\",\"operation\":\"UpdateItem\",\"request_id\":\"388GEROC4PCA6D59ED3CTI5EEJVV4KQNSO5AEMVJF66Q9ASUAAJG\",\"resource_names\":[\"scorekeep-game-xray\"]},\"origin\":\"AWS::DynamoDB::Table\"}"
}
],
"Id": "1-5828d9f2-a90669393f4343211bc1cf75",
"Duration": 0.05099987983703613
}
...
```
## Limpeza
Encerre seu ambiente do Elastic Beanstalk para desativar as instâncias do Amazon EC2, as tabelas do DynamoDB e outros recursos.
**Como encerrar o ambiente do Elastic Beanstalk**
1. Abra o [console do Elastic Beanstalk](https://console.aws.amazon.com/elasticbeanstalk).
1. Navegue até o [console de gerenciamento](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-console.html) do seu ambiente.
1. Escolha **Ações**.
1. Escolha **Terminate Environment**.
1. Escolha **Encerrar**.
Os dados de rastreamento são excluídos automaticamente do X-Ray após 30 dias.
# Enviando dados de rastreamento para AWS X-Ray
É possível enviar dados de rastreamento para o X-Ray em forma de documentos segmentados. Um documento segmentado é uma string formatada por JSON que contém informações sobre o trabalho que o aplicativo faz diante de uma solicitação. O aplicativo pode registrar dados sobre o trabalho que ele mesmo faz em segmentos ou o trabalho que usa serviços e recursos de downstream em subsegmentos.
Os segmentos registram informações sobre o trabalho que o aplicativo faz. Um segmento, no mínimo, registra o tempo gasto em uma tarefa, um nome e dois IDs. A ID de rastreamento rastreia a solicitação à medida que ela percorre os serviços. A ID de segmento rastreia o trabalho feito para a solicitação por um único serviço.
**Example Segmento completo mínimo**
```
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0a",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"end_time" : 1.478293361449E9
}
```
Quando uma solicitação é recebida, é possível enviar um segmento em andamento como um espaço reservado até a solicitação estar concluída.
**Example Segmento em andamento**
```
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
“in_progress”: true
}
```
É possível enviar segmentos ao X-Ray diretamente, com [`PutTraceSegments`](#xray-api-segments) ou [, por meio do daemon do X-Ray](#xray-api-daemon).
A maioria dos aplicativos chama outros serviços ou acessa recursos com o AWS SDK. Registre informações sobre chamadas subsequentes nos *subsegmentos*. O X-Ray usa subsegmentos para identificar serviços subsequentes que não enviam segmentos e criam entradas para eles no gráfico de serviço.
Um subsegmento pode ser incorporado em um documento de segmento completo ou enviado separadamente. Envie subsegmentos separadamente para rastrear chamadas subsequentes de forma assíncrona para solicitações de longa duração ou para evitar exceder o tamanho máximo do documento de segmentos (64 kB).
**Example Subsegmento**
Um subsegmento tem um `type` de `subsegment` e uma `parent_id` que identifica o segmento pai.
```
{
"name" : "www2.example.com",
"id" : "70de5b6f19ff9a0c",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979"
“end_time” : 1.478293361449E9,
“type” : “subsegment”,
“parent_id” : “70de5b6f19ff9a0b”
}
```
Para obter mais informações sobre os campos e valores que você pode incluir em segmentos e subsegmentos, consulte [AWS X-RayDocumentos de segmento do](xray-api-segmentdocuments.md).
**Topics**
+ [Gerando rastreamento IDs](#xray-api-traceids)
+ [Usando PutTraceSegments](#xray-api-segments)
+ [Enviar documentos de segmentos para o daemon do X-Ray](#xray-api-daemon)
## Gerando rastreamento IDs
Para enviar dados ao X-Ray, é necessário gerar um ID de rastreamento exclusivo para cada solicitação.
**Formato do ID de rastreamento do X-Ray**
Um `trace_id` do X-Ray consiste em três números separados por hifens. Por exemplo, .`1-58406520-a006649127e371903a2de979` Isso inclui:
+ O número da versão, que é `1`.
+ A hora da solicitação original, em horário epoch Unix, com **8 dígitos hexadecimais**.
Por exemplo, 10h no dia 1º de dezembro de 2016 PST equivale a `1480615200` segundos em horário epoch ou a `58406520` em dígitos hexadecimais.
+ Um identificador globalmente exclusivo de 96 bits para o rastreamento com **24 dígitos hexadecimais**.
**nota**
O X-Ray agora suporta IDs rastreamentos criados usando OpenTelemetry qualquer outra estrutura que esteja em conformidade com a especificação [W3C Trace](https://www.w3.org/TR/trace-context/) Context. Um ID de rastreamento do W3C deve ser formatado conforme o ID de rastreamento do X-Ray ao ser enviado ao X-Ray. Por exemplo, o ID de rastreamento `4efaaf4d1e8720b39541901950019ee5` do W3C deve ser formatado como `1-4efaaf4d-1e8720b39541901950019ee5` quando enviado ao X-Ray. O X-Ray Trace IDs inclui a data e hora da solicitação original no Unix epoch time, mas isso não é necessário ao enviar o rastreamento IDs W3C no formato X-Ray.
Você pode escrever um script para gerar o rastreamento de X-Ray IDs para teste. Veja dois exemplos a seguir.
**Python**
```
import time
import os
import binascii
START_TIME = time.time()
HEX=hex(int(START_TIME))[2:]
TRACE_ID="1-{}-{}".format(HEX, binascii.hexlify(os.urandom(12)).decode('utf-8'))
```
**Bash**
```
START_TIME=$(date +%s)
HEX_TIME=$(printf '%x\n' $START_TIME)
GUID=$(dd if=/dev/random bs=12 count=1 2>/dev/null | od -An -tx1 | tr -d ' \t\n')
TRACE_ID="1-$HEX_TIME-$GUID"
```
Consulte o aplicativo de amostra Scorekeep para ver scripts que criam, rastreiam IDs e enviam segmentos para o daemon X-Ray.
+ Python: [https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.py](https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.py)
+ Bash: [https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.sh](https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.sh)
## Usando PutTraceSegments
É possível fazer upload de documentos segmentados com a API [https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html). A API tem um único parâmetro, `TraceSegmentDocuments`, que utiliza uma lista de documentos segmentados JSON.
Com a AWS CLI, use o comando `aws xray put-trace-segments` para enviar documentos de segmentos diretamente para o X-Ray.
```
$ DOC='{"trace_id": "1-5960082b-ab52431b496add878434aa25", "id": "6226467e3f845502", "start_time": 1498082657.37518, "end_time": 1498082695.4042, "name": "test.elasticbeanstalk.com"}'
$ aws xray put-trace-segments --trace-segment-documents "$DOC"
{
"UnprocessedTraceSegments": []
}
```
**nota**
O Processador de Comandos do Windows e o Windows PowerShell têm requisitos diferentes para citar e escapar de aspas em cadeias de caracteres JSON. Consulte [Colocação de strings](https://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html#quoting-strings) no AWS CLI Guia do usuário para detalhes.
A saída lista todos os segmentos que falharam no processamento. Por exemplo, caso a data na ID de rastreamento seja muito antiga, você vê um erro como o erro a seguir.
```
{
"UnprocessedTraceSegments": [
{
"ErrorCode": "InvalidTraceId",
"Message": "Invalid segment. ErrorCode: InvalidTraceId",
"Id": "6226467e3f845502"
}
]
}
```
É possível passar vários documentos segmentados simultaneamente, separados por espaços.
```
$ aws xray put-trace-segments --trace-segment-documents "$DOC1" "$DOC2"
```
## Enviar documentos de segmentos para o daemon do X-Ray
Em vez de enviar documentos de segmentos para a API do X-Ray, você pode enviar segmentos e subsegmentos para o daemon do X-Ray, que os armazena em buffer e os carrega em lote na API do X-Ray. O X-Ray SDK envia documentos segmentos ao daemon para evitar fazer chamadas para a AWS diretamente.
**nota**
Consulte [Executar o daemon do X-Ray localmente](xray-daemon-local.md) para obter instruções sobre como executar o daemon.
Envie o segmento em JSON pela porta UDP 2000, acrescido do cabeçalho do daemon, `{"format": "json", "version": 1}\n`
```
{"format": "json", "version": 1}\n{"trace_id": "1-5759e988-bd862e3fe1be46a994272793", "id": "defdfd9912dc5a56", "start_time": 1461096053.37518, "end_time": 1461096053.4042, "name": "test.elasticbeanstalk.com"}
```
No Linux, é possível enviar documentos segmentados para o daemon de um terminal Bash. Salve o cabeçalho e o documento segmentado em um arquivo de texto e o encapsule em `/dev/udp` com `cat`.
```
$ cat segment.txt > /dev/udp/127.0.0.1/2000
```
**Example segment.txt**
```
{"format": "json", "version": 1}
{"trace_id": "1-594aed87-ad72e26896b3f9d3a27054bb", "id": "6226467e3f845502", "start_time": 1498082657.37518, "end_time": 1498082695.4042, "name": "test.elasticbeanstalk.com"}
```
Verifique o [log do daemon](xray-daemon.md#xray-daemon-logging) para confirmar se ele enviou o segmento ao X-Ray.
```
2017-07-07T01:57:24Z [Debug] processor: sending partial batch
2017-07-07T01:57:24Z [Debug] processor: segment batch size: 1. capacity: 50
2017-07-07T01:57:24Z [Info] Successfully sent batch of 1 segments (0.020 seconds)
```
# Obter dados do AWS X-Ray
AWS X-RayO processa dados de rastreamento que você envia a ele para gerar rastreamentos completos, resumos de rastreamentos e gráficos de serviço em JSON. Você pode recuperar os dados gerados diretamente da API com a AWS CLI.
**Topics**
+ [Recuperar o gráfico de serviço](#xray-api-servicegraph)
+ [Recuperar o gráfico de serviços por grupo](#xray-api-servicegraphgroup)
+ [Recuperar rastreamentos](#xray-api-traces)
+ [Recuperar e refinar a análise da causa raiz](#xray-api-analytics)
## Recuperar o gráfico de serviço
Você pode usar a API do [https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html) para recuperar o gráfico de serviço do JSON. A API requer um horário de início e término, que você pode calcular a partir de um terminal Linux com o comando `date`.
```
$ date +%s
1499394617
```
`date +%s` imprime uma data em segundos. Use esse número como um horário de término e subtraia o tempo dele para obter um horário de início.
**Example Script para recuperar um gráfico de serviço dos últimos 10 minutos**
```
EPOCH=$(date +%s)
aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH
```
O exemplo a seguir mostra um gráfico de serviço com quatro nós, incluindo um nó do cliente, uma instância do EC2, uma tabela do DynamoDB e um tópico do Amazon SNS.
**Example Saída do GetServiceGraph**
```
{
"Services": [
{
"ReferenceId": 0,
"Name": "xray-sample.elasticbeanstalk.com",
"Names": [
"xray-sample.elasticbeanstalk.com"
],
"Type": "client",
"State": "unknown",
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"Edges": [
{
"ReferenceId": 2,
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"SummaryStatistics": {
"OkCount": 3,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 1,
"TotalCount": 1
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 4,
"TotalResponseTime": 0.273
},
"ResponseTimeHistogram": [
{
"Value": 0.005,
"Count": 1
},
{
"Value": 0.015,
"Count": 1
},
{
"Value": 0.157,
"Count": 1
},
{
"Value": 0.096,
"Count": 1
}
],
"Aliases": []
}
]
},
{
"ReferenceId": 1,
"Name": "awseb-e-dixzws4s9p-stack-StartupSignupsTable-4IMSMHAYX2BA",
"Names": [
"awseb-e-dixzws4s9p-stack-StartupSignupsTable-4IMSMHAYX2BA"
],
"Type": "AWS::DynamoDB::Table",
"State": "unknown",
"StartTime": 1528317583.0,
"EndTime": 1528317589.0,
"Edges": [],
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.12
},
"DurationHistogram": [
{
"Value": 0.076,
"Count": 1
},
{
"Value": 0.044,
"Count": 1
}
],
"ResponseTimeHistogram": [
{
"Value": 0.076,
"Count": 1
},
{
"Value": 0.044,
"Count": 1
}
]
},
{
"ReferenceId": 2,
"Name": "xray-sample.elasticbeanstalk.com",
"Names": [
"xray-sample.elasticbeanstalk.com"
],
"Root": true,
"Type": "AWS::EC2::Instance",
"State": "active",
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"Edges": [
{
"ReferenceId": 1,
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.12
},
"ResponseTimeHistogram": [
{
"Value": 0.076,
"Count": 1
},
{
"Value": 0.044,
"Count": 1
}
],
"Aliases": []
},
{
"ReferenceId": 3,
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.125
},
"ResponseTimeHistogram": [
{
"Value": 0.049,
"Count": 1
},
{
"Value": 0.076,
"Count": 1
}
],
"Aliases": []
}
],
"SummaryStatistics": {
"OkCount": 3,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 1,
"TotalCount": 1
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 4,
"TotalResponseTime": 0.273
},
"DurationHistogram": [
{
"Value": 0.005,
"Count": 1
},
{
"Value": 0.015,
"Count": 1
},
{
"Value": 0.157,
"Count": 1
},
{
"Value": 0.096,
"Count": 1
}
],
"ResponseTimeHistogram": [
{
"Value": 0.005,
"Count": 1
},
{
"Value": 0.015,
"Count": 1
},
{
"Value": 0.157,
"Count": 1
},
{
"Value": 0.096,
"Count": 1
}
]
},
{
"ReferenceId": 3,
"Name": "SNS",
"Names": [
"SNS"
],
"Type": "AWS::SNS",
"State": "unknown",
"StartTime": 1528317583.0,
"EndTime": 1528317589.0,
"Edges": [],
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.125
},
"DurationHistogram": [
{
"Value": 0.049,
"Count": 1
},
{
"Value": 0.076,
"Count": 1
}
],
"ResponseTimeHistogram": [
{
"Value": 0.049,
"Count": 1
},
{
"Value": 0.076,
"Count": 1
}
]
}
]
}
```
## Recuperar o gráfico de serviços por grupo
Para chamar um gráfico de serviço baseado no conteúdo de um grupo, inclua um `groupName` ou `groupARN`. O exemplo a seguir mostra uma chamada de gráfico de serviço para um grupo chamado Example1.
**Example Script para recuperar um gráfico de serviço por nome para o grupo Example1**
```
aws xray get-service-graph --group-name "Example1"
```
## Recuperar rastreamentos
Você pode usar a API do [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) para obter uma lista dos resumos de rastreamentos. Os resumos de rastreamentos incluem informações que você pode usar para identificar rastreamentos cujo download total deseja fazer, incluindo anotações, informações de solicitação e resposta e IDs.
Há duas bandeiras `TimeRangeType` disponíveis ao chamar `aws xray get-trace-summaries`:
+ **TraceID**: a pesquisa `GetTraceSummaries` padrão usa o tempo do TraceID e retorna os rastreamentos iniciados dentro do intervalo `[start_time, end_time)` computado. Esse intervalo de timestamps é calculado com base na codificação do timestamp dentro do TraceID ou pode ser definido manualmente.
+ **Horário do evento**: para pesquisar eventos à medida que eles acontecem ao longo do tempo, o AWS X-Ray permite pesquisar rastreamentos usando registros de data e hora dos eventos. A hora do evento retorna traços ativos durante o intervalo `[start_time, end_time)`, independentemente de quando o rastreamento começou.
Use o comando `aws xray get-trace-summaries` para obter uma lista dos resumos de rastreamentos. Os comandos a seguir obtêm uma lista de resumos de rastreamento entre 1 e 2 minutos no passado usando o tempo de TraceID padrão.
**Example Script para obter resumos de rastreamentos**
```
EPOCH=$(date +%s)
aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60))
```
**Example Saída do GetTraceSummaries**
```
{
"TraceSummaries": [
{
"HasError": false,
"Http": {
"HttpStatus": 200,
"ClientIp": "205.255.255.183",
"HttpURL": "http://scorekeep.elasticbeanstalk.com/api/session",
"UserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36",
"HttpMethod": "POST"
},
"Users": [],
"HasFault": false,
"Annotations": {},
"ResponseTime": 0.084,
"Duration": 0.084,
"Id": "1-59602606-a43a1ac52fc7ee0eea12a82c",
"HasThrottle": false
},
{
"HasError": false,
"Http": {
"HttpStatus": 200,
"ClientIp": "205.255.255.183",
"HttpURL": "http://scorekeep.elasticbeanstalk.com/api/user",
"UserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36",
"HttpMethod": "POST"
},
"Users": [
{
"UserName": "5M388M1E"
}
],
"HasFault": false,
"Annotations": {
"UserID": [
{
"AnnotationValue": {
"StringValue": "5M388M1E"
}
}
],
"Name": [
{
"AnnotationValue": {
"StringValue": "Ola"
}
}
]
},
"ResponseTime": 3.232,
"Duration": 3.232,
"Id": "1-59602603-23fc5b688855d396af79b496",
"HasThrottle": false
}
],
"ApproximateTime": 1499473304.0,
"TracesProcessedCount": 2
}
```
Use o ID de rastreamento da saída para recuperar um rastreamento completo com a API do [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html).
**Example Comando BatchGetTraces**
```
$ aws xray batch-get-traces --trace-ids 1-596025b4-7170afe49f7aa708b1dd4a6b
```
**Example Saída do BatchGetTraces**
```
{
"Traces": [
{
"Duration": 3.232,
"Segments": [
{
"Document": "{\"id\":\"1fb07842d944e714\",\"name\":\"random-name\",\"start_time\":1.499473411677E9,\"end_time\":1.499473414572E9,\"parent_id\":\"0c544c1b1bbff948\",\"http\":{\"response\":{\"status\":200}},\"aws\":{\"request_id\":\"ac086670-6373-11e7-a174-f31b3397f190\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::Lambda\",\"resource_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\"}",
"Id": "1fb07842d944e714"
},
{
"Document": "{\"id\":\"194fcc8747581230\",\"name\":\"Scorekeep\",\"start_time\":1.499473411562E9,\"end_time\":1.499473414794E9,\"http\":{\"request\":{\"url\":\"http://scorekeep.elasticbeanstalk.com/api/user\",\"method\":\"POST\",\"user_agent\":\"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36\",\"client_ip\":\"205.251.233.183\"},\"response\":{\"status\":200}},\"aws\":{\"elastic_beanstalk\":{\"version_label\":\"app-abb9-170708_002045\",\"deployment_id\":406,\"environment_name\":\"scorekeep-dev\"},\"ec2\":{\"availability_zone\":\"us-west-2c\",\"instance_id\":\"i-0cd9e448944061b4a\"},\"xray\":{\"sdk_version\":\"1.1.2\",\"sdk\":\"X-Ray for Java\"}},\"service\":{},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"user\":\"5M388M1E\",\"origin\":\"AWS::ElasticBeanstalk::Environment\",\"subsegments\":[{\"id\":\"0c544c1b1bbff948\",\"name\":\"Lambda\",\"start_time\":1.499473411629E9,\"end_time\":1.499473414572E9,\"http\":{\"response\":{\"status\":200,\"content_length\":14}},\"aws\":{\"log_type\":\"None\",\"status_code\":200,\"function_name\":\"random-name\",\"invocation_type\":\"RequestResponse\",\"operation\":\"Invoke\",\"request_id\":\"ac086670-6373-11e7-a174-f31b3397f190\",\"resource_names\":[\"random-name\"]},\"namespace\":\"aws\"},{\"id\":\"071684f2e555e571\",\"name\":\"## UserModel.saveUser\",\"start_time\":1.499473414581E9,\"end_time\":1.499473414769E9,\"metadata\":{\"debug\":{\"test\":\"Metadata string from UserModel.saveUser\"}},\"subsegments\":[{\"id\":\"4cd3f10b76c624b4\",\"name\":\"DynamoDB\",\"start_time\":1.49947341469E9,\"end_time\":1.499473414769E9,\"http\":{\"response\":{\"status\":200,\"content_length\":57}},\"aws\":{\"table_name\":\"scorekeep-user\",\"operation\":\"UpdateItem\",\"request_id\":\"MFQ8CGJ3JTDDVVVASUAAJGQ6NJ82F738BOB4KQNSO5AEMVJF66Q9\",\"resource_names\":[\"scorekeep-user\"]},\"namespace\":\"aws\"}]}]}",
"Id": "194fcc8747581230"
},
{
"Document": "{\"id\":\"00f91aa01f4984fd\",\"name\":\"random-name\",\"start_time\":1.49947341283E9,\"end_time\":1.49947341457E9,\"parent_id\":\"1fb07842d944e714\",\"aws\":{\"function_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\",\"resource_names\":[\"random-name\"],\"account_id\":\"123456789012\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::Lambda::Function\",\"subsegments\":[{\"id\":\"e6d2fe619f827804\",\"name\":\"annotations\",\"start_time\":1.499473413012E9,\"end_time\":1.499473413069E9,\"annotations\":{\"UserID\":\"5M388M1E\",\"Name\":\"Ola\"}},{\"id\":\"b29b548af4d54a0f\",\"name\":\"SNS\",\"start_time\":1.499473413112E9,\"end_time\":1.499473414071E9,\"http\":{\"response\":{\"status\":200}},\"aws\":{\"operation\":\"Publish\",\"region\":\"us-west-2\",\"request_id\":\"a2137970-f6fc-5029-83e8-28aadeb99198\",\"retries\":0,\"topic_arn\":\"arn:aws:sns:us-west-2:123456789012:awseb-e-ruag3jyweb-stack-NotificationTopic-6B829NT9V5O9\"},\"namespace\":\"aws\"},{\"id\":\"2279c0030c955e52\",\"name\":\"Initialization\",\"start_time\":1.499473412064E9,\"end_time\":1.499473412819E9,\"aws\":{\"function_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\"}}]}",
"Id": "00f91aa01f4984fd"
},
{
"Document": "{\"id\":\"17ba309b32c7fbaf\",\"name\":\"DynamoDB\",\"start_time\":1.49947341469E9,\"end_time\":1.499473414769E9,\"parent_id\":\"4cd3f10b76c624b4\",\"inferred\":true,\"http\":{\"response\":{\"status\":200,\"content_length\":57}},\"aws\":{\"table_name\":\"scorekeep-user\",\"operation\":\"UpdateItem\",\"request_id\":\"MFQ8CGJ3JTDDVVVASUAAJGQ6NJ82F738BOB4KQNSO5AEMVJF66Q9\",\"resource_names\":[\"scorekeep-user\"]},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::DynamoDB::Table\"}",
"Id": "17ba309b32c7fbaf"
},
{
"Document": "{\"id\":\"1ee3c4a523f89ca5\",\"name\":\"SNS\",\"start_time\":1.499473413112E9,\"end_time\":1.499473414071E9,\"parent_id\":\"b29b548af4d54a0f\",\"inferred\":true,\"http\":{\"response\":{\"status\":200}},\"aws\":{\"operation\":\"Publish\",\"region\":\"us-west-2\",\"request_id\":\"a2137970-f6fc-5029-83e8-28aadeb99198\",\"retries\":0,\"topic_arn\":\"arn:aws:sns:us-west-2:123456789012:awseb-e-ruag3jyweb-stack-NotificationTopic-6B829NT9V5O9\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::SNS\"}",
"Id": "1ee3c4a523f89ca5"
}
],
"Id": "1-59602603-23fc5b688855d396af79b496"
}
],
"UnprocessedTraceIds": []
}
```
O rastreamento completo inclui um documento para cada segmento, compilado a partir de todos os documentos de segmento recebidos com a mesma ID de rastreamento. Esses documentos não representam os dados como eles foram enviados para o X-Ray pelo aplicativo. Em vez disso, eles representam os documentos processados e gerados pelo serviço X-Ray. O X-Ray cria o documento de rastreamento completo compilando os documentos de segmentos enviados pelo aplicativo e removendo os dados que não estão em conformidade com o [esquema do documento de segmento](xray-api-segmentdocuments.md).
O X-Ray também cria *segmentos inferidos* para chamadas subsequentes para os serviços que não enviam segmentos por conta própria. Por exemplo, quando você faz chamadas para o DynamoDB com um cliente instrumentado, o X-Ray SDK grava um subsegmento com detalhes sobre a chamada de acordo com o ponto de vista dele. No entanto, o DynamoDB não envia um segmento correspondente. O X-Ray usa as informações no subsegmento para criar um segmento inferido para representar o recurso DynamoDB no mapa de rastreamento e o adiciona ao documento de rastreamento.
Para obter vários rastreamentos da API, você precisa de uma lista de IDs de rastreamento, que pode ser extraída da saída de um `get-trace-summaries` com uma [AWS CLI consulta](https://docs.aws.amazon.com/cli/latest/userguide/controlling-output.html#controlling-output-filter). Redirecione a lista para a entrada `batch-get-traces` para obter rastreamentos completos de um período específico.
**Example Script para obter rastreamentos completos de um período de um minuto**
```
EPOCH=$(date +%s)
TRACEIDS=$(aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Id' --output text)
aws xray batch-get-traces --trace-ids $TRACEIDS --query 'Traces[*]'
```
## Recuperar e refinar a análise da causa raiz
Ao gerar um resumo de rastreamentos com a [API do GetTraceSummaries](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html), os resumos de rastreamentos parciais podem ser reutilizados em seu formato JSON para criar uma expressão de filtro refinada com base nas causas raiz. Veja os exemplos abaixo para obter uma demonstração das etapas de refinamento.
**Example Exemplo de saída do GetTraceSummaries: seção de causa raiz do tempo de resposta**
```
{
"Services": [
{
"Name": "GetWeatherData",
"Names": ["GetWeatherData"],
"AccountId": 123456789012,
"Type": null,
"Inferred": false,
"EntityPath": [
{
"Name": "GetWeatherData",
"Coverage": 1.0,
'Remote": false
},
{
"Name": "get_temperature",
"Coverage": 0.8,
"Remote": false
}
]
},
{
"Name": "GetTemperature",
"Names": ["GetTemperature"],
"AccountId": 123456789012,
"Type": null,
"Inferred": false,
"EntityPath": [
{
"Name": "GetTemperature",
"Coverage": 0.7,
"Remote": false
}
]
}
]
}
```
Ao editar e omitir a saída acima, esse JSON pode se tornar um filtro para entidades de causa raiz correspondentes. Para cada campo presente no JSON, qualquer correspondência de candidato deve ser exata ou o rastreamento não será retornado. Os campos removidos se tornam valores curinga, um formato compatível com a estrutura de consulta da expressão de filtro.
**Example Causa raiz de tempo de resposta reformatada**
```
{
"Services": [
{
"Name": "GetWeatherData",
"EntityPath": [
{
"Name": "GetWeatherData"
},
{
"Name": "get_temperature"
}
]
},
{
"Name": "GetTemperature",
"EntityPath": [
{
"Name": "GetTemperature"
}
]
}
]
}
```
Este JSON é usado como parte de uma expressão de filtro por meio de uma chamada para `rootcause.json = #[{}]`. Consulte o capítulo [Filter Expressions (Filtrar Expressões)](xray-console-filters.md) para obter mais detalhes sobre a consulta com expressões de filtro.
**Example Exemplo de filtro JSON**
```
rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]
```
# Definindo configurações de amostragem, grupos e criptografia com a API AWS X-Ray
AWS X-Ray fornece APIs a configuração de regras de [amostragem, regras](xray-console-sampling.md) de grupo e configurações de [criptografia](xray-console-encryption.md).
**Topics**
+ [Configurações de criptografia](#xray-api-configuration-encryption)
+ [Regras de amostragem](#xray-api-configuration-sampling)
+ [Groups (Grupos)](#xray-api-configuration-groups)
## Configurações de criptografia
Use [https://docs.aws.amazon.com/xray/latest/api/API_PutEncryptionConfig.html](https://docs.aws.amazon.com/xray/latest/api/API_PutEncryptionConfig.html)para especificar uma chave AWS Key Management Service (AWS KMS) a ser usada para criptografia.
**nota**
O X-Ray não aceita chaves do KMS assimétricas.
```
$ aws xray put-encryption-config --type KMS --key-id alias/aws/xray
{
"EncryptionConfig": {
"KeyId": "arn:aws:kms:us-east-2:123456789012:key/c234g4e8-39e9-4gb0-84e2-b0ea215cbba5",
"Status": "UPDATING",
"Type": "KMS"
}
}
```
Para o ID de chave, você pode usar um alias (conforme mostrado no exemplo), um ID de chave ou um nome de recurso da Amazon (ARN).
Use [https://docs.aws.amazon.com/xray/latest/api/API_GetEncryptionConfig.html](https://docs.aws.amazon.com/xray/latest/api/API_GetEncryptionConfig.html) para obter a configuração atual. Quando o X-Ray termina de aplicar as configurações, o status é alterado de `UPDATING` para `ACTIVE`.
```
$ aws xray get-encryption-config
{
"EncryptionConfig": {
"KeyId": "arn:aws:kms:us-east-2:123456789012:key/c234g4e8-39e9-4gb0-84e2-b0ea215cbba5",
"Status": "ACTIVE",
"Type": "KMS"
}
}
```
Para deixar de usar uma chave do KMS e usar a criptografia padrão, defina o tipo de criptografia como `NONE`.
```
$ aws xray put-encryption-config --type NONE
{
"EncryptionConfig": {
"Status": "UPDATING",
"Type": "NONE"
}
}
```
## Regras de amostragem
Você pode gerenciar as [regras de amostragem](xray-console-sampling.md) em sua conta com a API do X-Ray. Para obter mais informações sobre como adicionar e gerenciar tags, consulte [Marcar grupos e regras de amostragem do X-Ray](xray-tagging.md).
Obtenha todas as regras de amostragem com [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html).
```
$ aws xray get-sampling-rules
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-2:123456789012:sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.05,
"ReservoirSize": 1,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1529959993.0
}
]
}
```
A regra padrão se aplica a todas as solicitações que não correspondem a nenhuma outra regra. Ela é a regra de prioridade mais baixa e não pode ser excluída. No entanto, você pode alterar a taxa e o tamanho do reservatório com a [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html).
**Example Entrada de API para [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html): 10000-default.json**
```
{
"SamplingRuleUpdate": {
"RuleName": "Default",
"FixedRate": 0.01,
"ReservoirSize": 0
}
}
```
O exemplo a seguir usa o arquivo anterior como entrada para alterar a regra padrão para um por cento, sem reservatório. As tags são opcionais. Se você optar por adicionar tags, uma chave de tag será necessária e os valores da tag serão opcionais. Para remover as tags existentes de uma regra de amostragem, use [UntagResource](https://docs.aws.amazon.com/xray/latest/api/API_UntagResource.html)
```
$ aws xray update-sampling-rule --cli-input-json file://1000-default.json --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-2:123456789012:sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.01,
"ReservoirSize": 0,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1529959993.0
},
```
Crie regras de amostragem adicionais com a [https://docs.aws.amazon.com/xray/latest/api/API_CreateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_CreateSamplingRule.html). Ao criar uma regra, a maioria dos campos da regra são obrigatórios. O exemplo a seguir cria duas regras. Esta primeira regra define uma taxa de base para o aplicativo de exemplo do Scorekeep. Ela faz a correspondência de todas as solicitações atendidas pela API que não correspondem a uma regra de prioridade mais alta.
**Example Entrada de API para [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html): 9000-base-scorekeep.json**
```
{
"SamplingRule": {
"RuleName": "base-scorekeep",
"ResourceARN": "*",
"Priority": 9000,
"FixedRate": 0.1,
"ReservoirSize": 5,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1
}
}
```
A segunda regra também se aplica ao Scorekeep, mas tem uma prioridade mais alta e é mais específica. Essa regra define uma taxa de amostragem muito baixa para solicitações de sondagem. Essas são solicitações GET feitas pelo cliente a cada poucos segundos para verificar a existência de alterações no estado do jogo.
**Example Entrada de API para [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html): 5000-polling-scorekeep.json**
```
{
"SamplingRule": {
"RuleName": "polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1
}
}
```
As tags são opcionais. Se você optar por adicionar tags, uma chave de tag será necessária e os valores da tag serão opcionais.
```
$ aws xray create-sampling-rule --cli-input-json file://5000-polling-scorekeep.json --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574399.0,
"ModifiedAt": 1530574399.0
}
}
$ aws xray create-sampling-rule --cli-input-json file://9000-base-scorekeep.json
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "base-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/base-scorekeep",
"ResourceARN": "*",
"Priority": 9000,
"FixedRate": 0.1,
"ReservoirSize": 5,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574410.0,
"ModifiedAt": 1530574410.0
}
}
```
Para excluir uma regra de amostragem, use a [https://docs.aws.amazon.com/xray/latest/api/API_DeleteSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_DeleteSamplingRule.html).
```
$ aws xray delete-sampling-rule --rule-name polling-scorekeep
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574399.0,
"ModifiedAt": 1530574399.0
}
}
```
## Groups (Grupos)
Você pode usar a API do X-Ray para gerenciar grupos em sua conta. Os grupos são uma coleção de rastreamentos definidos por uma expressão de filtro. Você pode usar grupos para gerar gráficos de serviços adicionais e fornecer CloudWatch métricas da Amazon. Consulte [Obter dados do AWS X-Ray](xray-api-gettingdata.md) para obter mais detalhes sobre como trabalhar com métricas e gráficos de serviço por meio da API do X-Ray. Para obter mais informações sobre grupos, consulte [Configurar grupos](xray-console-groups.md). Para obter mais informações sobre como adicionar e gerenciar tags, consulte [Marcar grupos e regras de amostragem do X-Ray](xray-tagging.md).
Criar um grupo com `CreateGroup`. As tags são opcionais. Se você optar por adicionar tags, uma chave de tag será necessária e os valores da tag serão opcionais.
```
$ aws xray create-group --group-name "TestGroup" --filter-expression "service(\"example.com\") {fault}" --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
"GroupName": "TestGroup",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
"FilterExpression": "service(\"example.com\") {fault OR error}"
}
```
Obtenha todos os grupos existentes `GetGroups`.
```
$ aws xray get-groups
{
"Groups": [
{
"GroupName": "TestGroup",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
"FilterExpression": "service(\"example.com\") {fault OR error}"
},
{
"GroupName": "TestGroup2",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup2/UniqueID",
"FilterExpression": "responsetime > 2"
}
],
"NextToken": "tokenstring"
}
```
Atualizar um grupo com `UpdateGroup`. As tags são opcionais. Se você optar por adicionar tags, uma chave de tag será necessária e os valores da tag serão opcionais. Para remover tags existentes de um grupo, use [UntagResource](https://docs.aws.amazon.com/xray/latest/api/API_UntagResource.html).
```
$ aws xray update-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID" --filter-expression "service(\"example.com\") {fault OR error}" --tags [{"Key": "Stage","Value": "Prod"},{"Key": "Department","Value": "QA"}]
{
"GroupName": "TestGroup",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
"FilterExpression": "service(\"example.com\") {fault OR error}"
}
```
Excluir um grupo com `DeleteGroup`.
```
$ aws xray delete-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID"
{
}
```
# Usar regras de amostragem com a API do X-Ray
O AWS X-Ray SDK usa a API do X-Ray para obter regras de amostragem, informar os resultados da amostragem e obter cotas. Você pode usar essas APIs para compreender melhor como as regras de amostragem funcionam ou para implementar a amostragem em uma linguagem que não seja compatível com o X-Ray SDK.
Comece obtendo todas as regras de amostragem com [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html).
```
$ aws xray get-sampling-rules
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.01,
"ReservoirSize": 0,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1530558121.0
},
{
"SamplingRule": {
"RuleName": "base-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/base-scorekeep",
"ResourceARN": "*",
"Priority": 9000,
"FixedRate": 0.1,
"ReservoirSize": 2,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530573954.0,
"ModifiedAt": 1530920505.0
},
{
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530918163.0,
"ModifiedAt": 1530918163.0
}
]
}
```
A saída inclui a regra padrão e regras personalizadas. Consulte [Regras de amostragem](xray-api-configuration.md#xray-api-configuration-sampling) se você ainda não tiver criado regras de amostragem.
Avalie as regras em relação às solicitações de entrada em ordem crescente de prioridade. Quando houver uma correspondência de regras, use a taxa fixa e o tamanho de reservatório para tomar uma decisão de amostragem. Registre as solicitações amostradas e ignore (para fins de rastreamento) as solicitações não amostradas. Pare de avaliar as regras quando uma decisão de amostragem for tomada.
O tamanho de um reservatório de regras é o número de destino de rastreamentos a serem registrados por segundo antes do aplicativo da taxa fixa. O reservatório é aplicado em todos os serviços cumulativamente. Portanto, você não pode usá-lo diretamente. No entanto, se ele for diferente de zero, você poderá tomar emprestado um rastreamento por segundo do reservatório até que o X-Ray atribua uma cota. Antes de receber uma cota, registre a primeira solicitação a cada segundo, e aplique a taxa fixa nas solicitações adicionais. A taxa fixa é um valor decimal entre 0 e 1,00 (100%).
O exemplo a seguir mostra uma chamada para [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html) com detalhes sobre as decisões de amostragem tomadas nos últimos 10 segundos.
```
$ aws xray get-sampling-targets --sampling-statistics-documents '[
{
"RuleName": "base-scorekeep",
"ClientID": "ABCDEF1234567890ABCDEF10",
"Timestamp": "2018-07-07T00:20:06",
"RequestCount": 110,
"SampledCount": 20,
"BorrowCount": 10
},
{
"RuleName": "polling-scorekeep",
"ClientID": "ABCDEF1234567890ABCDEF10",
"Timestamp": "2018-07-07T00:20:06",
"RequestCount": 10500,
"SampledCount": 31,
"BorrowCount": 0
}
]'
{
"SamplingTargetDocuments": [
{
"RuleName": "base-scorekeep",
"FixedRate": 0.1,
"ReservoirQuota": 2,
"ReservoirQuotaTTL": 1530923107.0,
"Interval": 10
},
{
"RuleName": "polling-scorekeep",
"FixedRate": 0.003,
"ReservoirQuota": 0,
"ReservoirQuotaTTL": 1530923107.0,
"Interval": 10
}
],
"LastRuleModification": 1530920505.0,
"UnprocessedStatistics": []
}
```
A resposta do X-Ray inclui uma cota para ser usada no lugar de empréstimos do reservatório. Neste exemplo, o serviço tomou emprestado 10 rastreamentos do reservatório em 10 segundos e aplicou a taxa fixa de 10% para as outras 100 solicitações, o que resulta em um total de 20 solicitações amostradas. A cota é válida por cinco minutos (indicada pela vida útil) ou até que uma nova cota seja atribuída. O X-Ray também pode atribuir um intervalo de emissão de relatórios maior do que o padrão, embora isso não ocorra aqui.
**nota**
A resposta do X-Ray pode não incluir uma cota na primeira vez em que você chamá-lo. Continue fazendo empréstimos do reservatório até que você receba uma cota.
Os outros dois campos na resposta podem indicar problemas com a entrada. Compare a `LastRuleModification` com a data da última vez em que você chamou as [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html). Se ela for mais recente, obtenha uma nova cópia das regras. `UnprocessedStatistics` pode incluir erros que indicam que uma regra foi excluída, que o documento de estatísticas na entrada era muito antigo ou erros de permissões.
# AWS X-RayDocumentos de segmento do
Um **segmento de rastreamento** é uma representação JSON de uma solicitação que seu aplicativo atende. Um segmento de rastreamento registra informações sobre a solicitação original, informações sobre o trabalho que o aplicativo faz localmente e **subsegmentos** com informações sobre chamadas subsequentes que o aplicativo faz a APIs HTTP, bancos de dados SQL e recursos da AWS.
Um **documento de segmentos** transmite informações sobre um segmento ao X-Ray. Um documento de segmentos pode ser até 64 kB e conter um segmento inteiro com subsegmentos, um fragmento de um segmento que indica que uma solicitação está em andamento ou um único subsegmento enviado separadamente. Você pode enviar documentos de segmentos diretamente ao X-Ray usando a API [https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html).
O X-Ray compila e processa documentos de segmentos para gerar **resumos de rastreamento** e **rastreamentos completos**, os quais podem ser acessados usando as APIs [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) e [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html), respectivamente. Além de segmentos e subsegmentos que você envia ao X-Ray, o serviço usa informações em subsegmentos para gerar **segmentos inferidos** e os adiciona ao rastreamento completo. Segmentos inferidos representam serviços e recursos subsequentes no mapa de rastreamento.
O X-Ray fornece um **esquema JSON** para documentos de segmentos. Você pode baixar o schema aqui: [xray-segmentdocument-schema-v1.0.0](samples/xray-segmentdocument-schema-v1.0.0.zip). Os campos e objetos listados no schema são descritos em mais detalhes nas seções a seguir.
Um subconjunto de campos de segmento é indexado pelo X-Ray para ser usado com expressões de filtro. Por exemplo, se você definir o campo `user` em um segmento para um identificador exclusivo, poderá pesquisar segmentos associados a usuários específicos no console do X-Ray ou usando a API `GetTraceSummaries`. Para obter mais informações, consulte [Usar expressões de filtro](xray-console-filters.md).
Quando você instrumenta o aplicativo com o X-Ray SDK, o SDK gera documentos de segmentos para você. Em vez de enviar documentos de segmentos diretamente ao X-Ray, o SDK transmite-os por meio de uma porta UDP local para o [daemon do X-Ray](xray-daemon.md). Para obter mais informações, consulte [Enviar documentos de segmentos para o daemon do X-Ray](xray-api-sendingdata.md#xray-api-daemon).
**Topics**
+ [Campos de segmento](#api-segmentdocuments-fields)
+ [Subsegmentos](#api-segmentdocuments-subsegments)
+ [Dados HTTP de solicitação](#api-segmentdocuments-http)
+ [Anotações](#api-segmentdocuments-annotations)
+ [Metadados](#api-segmentdocuments-metadata)
+ [Dados de recursos da AWS](#api-segmentdocuments-aws)
+ [Erros e exceções](#api-segmentdocuments-errors)
+ [Consultas SQL](#api-segmentdocuments-sql)
## Campos de segmento
Um segmento registra informações de rastreamento sobre uma solicitação que o seu aplicativo atende. No mínimo, um segmento registra nome, ID, horário de início, ID de rastreamento e horário de término da solicitação.
**Example Segmento completo mínimo**
```
{
"name" : "example.com",
"id" : "70de5b6f19ff9a0a",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"end_time" : 1.478293361449E9
}
```
Os seguintes campos são obrigatórios ou condicionalmente necessários, por segmento.
**nota**
Os valores devem ser strings (até 250 caracteres), a menos que indicado o contrário.
**Campos obrigatórios de segmento**
+ `name`: o nome lógico do serviço que processou a solicitação, com até **200 caracteres**. Por exemplo, o nome do aplicativo ou o nome de domínio. Os nomes podem conter letras unicode, números e espaço em branco e os seguintes símbolos: `_`, `.`, `:`, `/`, `%`, `&`, `#`, `=`, `+`, `\`, `-`, `@`
+ `id`: um identificador de 64 bits para o segmento, exclusivo entre segmentos no mesmo rastreamento, com **16 dígitos hexadecimais**.
+ `trace_id`: um identificador exclusivo que conecta todos os segmentos e subsegmentos provenientes de uma única solicitação do cliente.
**Formato do ID de rastreamento do X-Ray**
Um `trace_id` do X-Ray consiste em três números separados por hifens. Por exemplo, `1-58406520-a006649127e371903a2de979`. Isso inclui:
+ O número da versão, que é `1`.
+ A hora da solicitação original, em horário epoch Unix, com **8 dígitos hexadecimais**.
Por exemplo, 10h no dia 1º de dezembro de 2016 PST equivale a `1480615200` segundos em horário epoch ou a `58406520` em dígitos hexadecimais.
+ Um identificador globalmente exclusivo de 96 bits para o rastreamento com **24 dígitos hexadecimais**.
**nota**
O X-Ray agora aceita IDs de rastreamento criados usando o OpenTelemetry ou qualquer outro framework que esteja em conformidade com a [especificação W3C Trace Context](https://www.w3.org/TR/trace-context/). Um ID de rastreamento do W3C deve ser formatado conforme o ID de rastreamento do X-Ray ao ser enviado ao X-Ray. Por exemplo, o ID de rastreamento `4efaaf4d1e8720b39541901950019ee5` do W3C deve ser formatado como `1-4efaaf4d-1e8720b39541901950019ee5` quando enviado ao X-Ray. Os IDs de rastreamento do X-Ray incluem o carimbo de data e hora da solicitação original no horário epoch Unix, mas isso não é necessário ao enviar IDs de rastreamento do W3C no formato do X-Ray.
**Segurança de ID de Rastreamento**
IDs de rastreamento são visíveis nos [cabeçalhos de resposta](xray-concepts.md#xray-concepts-tracingheader). Gere IDs de rastreamento com um algoritmo aleatório seguro para garantir que invasores não possam calcular futuras IDs de rastreamento e enviar solicitações com aqueles IDs para seu aplicativo.
+ `start_time`: um **número** que representa o momento em que o segmento foi criado, em segundos de ponto flutuante na hora de época. Por exemplo, `1480615200.010` ou `1.480615200010E9`. Use o máximo de casas decimais que precisar. A resolução em microssegundos é recomendada quando disponível.
+ `end_time`: um **número** que representa o momento em que o segmento foi encerrado. Por exemplo, `1480615200.090` ou `1.480615200090E9`. Especifique um `end_time` ou `in_progress`.
+ `in_progress`: um valor **booliano**, definido como `true`, em vez de especificar um `end_time` para registrar que um segmento foi iniciado e não foi concluído. Envie um segmento em andamento quando seu aplicativo receber uma solicitação que levará muito tempo para atender, para rastrear o recebimento da solicitação. Quando a resposta é encaminhada, envie o segmento completo para substituir o segmento em andamento. Envie apenas um segmento completo e um ou nenhum segmento em andamento, por solicitação.
**Nomes de serviço**
O `name` de um segmento deve corresponder ao nome de domínio ou nome lógico do serviço que gera o segmento. No entanto, isso não é aplicado. Qualquer aplicativo que tenha permissão para [https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html) pode enviar segmentos com qualquer nome.
Os seguintes campos são opcionais para segmentos.
**Campos opcionais de segmento**
+ `service`: um objeto com informações sobre o aplicativo.
+ `version`: uma string que identifica a versão do aplicativo que atendeu à solicitação.
+ `user`: uma string que identifica o usuário que enviou a solicitação.
+ `origin`: o tipo de recurso da AWS que executa o aplicativo.
**Valores suportados**
+ `AWS::EC2::Instance`: uma instância do Amazon EC2.
+ `AWS::ECS::Container`: um contêiner do Amazon ECS.
+ `AWS::ElasticBeanstalk::Environment`: um ambiente do Elastic Beanstalk.
Quando vários valores são aplicáveis à seu aplicativo, use o que é mais específico. Por exemplo, um ambiente do Docker de vários contêineres no Elastic Beanstalk executa o aplicativo em um contêiner do Amazon ECS, que, por sua vez, é executado em uma instância do Amazon EC2. Neste caso, você define a origem para `AWS::ElasticBeanstalk::Environment` como o ambiente pai dos outros dois recursos.
+ `parent_id`: um ID de subsegmento que você especifica se a solicitação tiver se originado de um aplicativo instrumentada. O X-Ray SDK adiciona a ID do subsegmento principal ao [cabeçalho de rastreamento](xray-concepts.md#xray-concepts-tracingheader) para chamadas HTTP subsequentes. No caso de subsegmentos aninhados, um subsegmento pode ter um segmento ou um subsegmento como seu pai.
+ `http`: objetos [`http`](#api-segmentdocuments-http) com informações sobre a solicitação HTTP original.
+ `aws`: objeto [`aws`](#api-segmentdocuments-aws) com informações sobre o recurso da AWS no qual o aplicativo atendeu à solicitação.
+ `error`, `throttle`, `fault` e `cause`: campos de [erro](#api-segmentdocuments-errors) que indicam um erro ocorrido e que incluem informações sobre a exceção que causou o erro.
+ `annotations` – [`annotations`](#api-segmentdocuments-annotations) o objeto com os pares de chave-valor que você deseja que o X-Ray indexe para pesquisa.
+ `metadata` – [`metadata`](#api-segmentdocuments-metadata) objeto com qualquer dado adicional que você deseja armazenar no segmento.
+ `subsegments`: **matriz** de objetos [`subsegment`](#api-segmentdocuments-subsegments).
## Subsegmentos
Você pode criar subsegmentos para registrar chamadas a recursos e Serviços da AWS que você faz com o SDK da AWS, chamadas de APIs da web HTTP internas ou externas ou consultas SQL de banco de dados. Você também pode criar subsegmentos para depurar ou anotar blocos de código em seu aplicativo. Subsegmentos podem conter outros subsegmentos, portanto, um subsegmento personalizado que registra metadados sobre uma chamada de função interna pode conter outros subsegmentos personalizados e subsegmentos para chamadas de downstream.
Um subsegmento registra uma chamada subsequente do ponto de vista do serviço que faz a chamada. O X-Ray usa subsegmentos para identificar serviços subsequentes que não enviam segmentos e criam entradas para eles no gráfico de serviço.
Um subsegmento pode ser incorporado em um documento de segmento completo ou enviado de forma independente. Envie subsegmentos separadamente para chamadas downstream de rastreamento de forma assíncrona para solicitações de longo prazo, ou para evitar exceder o tamanho máximo do documento de segmento.
**Example Segmento com subsegmento incorporado**
Um subsegmento independente tem um `type` de `subsegment` e uma `parent_id` que identifica o segmento pai.
```
{
"trace_id" : "1-5759e988-bd862e3fe1be46a994272793",
"id" : "defdfd9912dc5a56",
"start_time" : 1461096053.37518,
"end_time" : 1461096053.4042,
"name" : "www.example.com",
"http" : {
"request" : {
"url" : "https://www.example.com/health",
"method" : "GET",
"user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/601.7.7",
"client_ip" : "11.0.3.111"
},
"response" : {
"status" : 200,
"content_length" : 86
}
},
"subsegments" : [
{
"id" : "53995c3f42cd8ad8",
"name" : "api.example.com",
"start_time" : 1461096053.37769,
"end_time" : 1461096053.40379,
"namespace" : "remote",
"http" : {
"request" : {
"url" : "https://api.example.com/health",
"method" : "POST",
"traced" : true
},
"response" : {
"status" : 200,
"content_length" : 861
}
}
}
]
}
```
Para solicitações de longa duração, você pode enviar um segmento em andamento para notificar o X-Ray de que a solicitação foi recebida e, em seguida, enviar subsegmentos separadamente para rastreá-los antes de concluir a solicitação original.
**Example Segmento em andamento**
```
{
"name" : "example.com",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"in_progress": true
}
```
**Example Subsegmento independente**
Um subsegmento independente tem um `type` de `subsegment`, um `trace_id` e um `parent_id` que identifica o segmento pai.
```
{
"name" : "api.example.com",
"id" : "53995c3f42cd8ad8",
"start_time" : 1.478293361271E9,
"end_time" : 1.478293361449E9,
"type" : "subsegment",
"trace_id" : "1-581cf771-a006649127e371903a2de979"
"parent_id" : "defdfd9912dc5a56",
"namespace" : "remote",
"http" : {
"request" : {
"url" : "https://api.example.com/health",
"method" : "POST",
"traced" : true
},
"response" : {
"status" : 200,
"content_length" : 861
}
}
}
```
Quando a solicitação for concluída, feche o segmento reenviando-o com um `end_time`. O segmento completo substituirá o segmento em andamento.
Você também pode enviar subsegmentos separadamente para solicitações concluídas que acionaram fluxos de trabalho assíncronos. Por exemplo, uma API da Web pode retornar uma resposta `OK 200` imediatamente antes de iniciar o trabalho que o usuário solicitou. Você pode enviar um segmento completo para o X-Ray assim que a resposta for enviada e, depois, subsegmentos para o trabalho concluído em um momento posterior. Assim como ocorre com segmentos, você também pode enviar um fragmento de subsegmento para registrar que o subsegmento foi iniciado e, em seguida, sobregravá-lo com um subsegmento completo assim que a chamada de downstream for concluída.
Os seguintes campos são obrigatórios ou condicionalmente necessários, por subsegmento.
**nota**
Os valores são strings de até 250 caracteres, a menos que indicado o contrário.
**Campos obrigatórios de subsegmento**
+ `id`: um identificador de 64 bits para o subsegmento, exclusivo entre segmentos no mesmo rastreamento, com **16 dígitos hexadecimais**.
+ `name`: o nome lógico do subsegmento. Para chamadas de downstream, nomeie o subsegmento após o recurso ou serviço chamado. Para subsegmentos personalizados, nomeie o subsegmento depois do código que ele instrumenta (por exemplo, um nome de função).
+ `start_time`: um **número** que representa o momento em que o subsegmento foi criado, em segundos de ponto flutuante no horário de época, com precisão de milissegundos. Por exemplo, `1480615200.010` ou `1.480615200010E9`.
+ `end_time`: um **número** que representa o momento em que o subsegmento foi encerrado. Por exemplo, `1480615200.090` ou `1.480615200090E9`. Especifique um `end_time` ou `in_progress`.
+ `in_progress`: um valor **booliano**, definido como `true`, em vez de especificar um `end_time` para registrar que um subsegmento foi iniciado e não foi concluído. Envie apenas um subsegmento completo e um ou nenhum subsegmento em andamento, por solicitação de downstream.
+ `trace_id`: ID de rastreamento do segmento principal do subsegmento. Obrigatório apenas ao enviar um subsegmento separadamente.
**Formato do ID de rastreamento do X-Ray**
Um `trace_id` do X-Ray consiste em três números separados por hifens. Por exemplo, `1-58406520-a006649127e371903a2de979`. Isso inclui:
+ O número da versão, que é `1`.
+ A hora da solicitação original, em horário epoch Unix, com **8 dígitos hexadecimais**.
Por exemplo, 10h no dia 1º de dezembro de 2016 PST equivale a `1480615200` segundos em horário epoch ou a `58406520` em dígitos hexadecimais.
+ Um identificador globalmente exclusivo de 96 bits para o rastreamento com **24 dígitos hexadecimais**.
**nota**
O X-Ray agora aceita IDs de rastreamento criados usando o OpenTelemetry ou qualquer outro framework que esteja em conformidade com a [especificação W3C Trace Context](https://www.w3.org/TR/trace-context/). Um ID de rastreamento do W3C deve ser formatado conforme o ID de rastreamento do X-Ray ao ser enviado ao X-Ray. Por exemplo, o ID de rastreamento `4efaaf4d1e8720b39541901950019ee5` do W3C deve ser formatado como `1-4efaaf4d-1e8720b39541901950019ee5` quando enviado ao X-Ray. Os IDs de rastreamento do X-Ray incluem o carimbo de data e hora da solicitação original no horário epoch Unix, mas isso não é necessário ao enviar IDs de rastreamento do W3C no formato do X-Ray.
+ `parent_id`: ID do segmento principal do subsegmento. Obrigatório apenas ao enviar um subsegmento separadamente. No caso de subsegmentos aninhados, um subsegmento pode ter um segmento ou um subsegmento como seu pai.
+ `type`: `subsegment`. Obrigatório apenas ao enviar um subsegmento separadamente.
Os seguintes campos são opcionais para subsegmentos.
**Campos opcionais de subsegmento**
+ `namespace`: `aws` para chamadas de SDK da AWS; `remote` para outras chamadas subsequentes.
+ `http`: objeto [`http`](#api-segmentdocuments-http) com informações sobre uma chamada HTTP de saída.
+ `aws`: objeto [`aws`](#api-segmentdocuments-aws) com informações sobre o recurso da AWS subsequente que o aplicativo chamou.
+ `error`, `throttle`, `fault` e `cause`: campos de [erro](#api-segmentdocuments-errors) que indicam um erro ocorrido e que incluem informações sobre a exceção que causou o erro.
+ `annotations`: o objeto [`annotations`](#api-segmentdocuments-annotations) com os pares de chave-valor que você deseja que o X-Ray indexe para pesquisa.
+ `metadata`: objeto [`metadata`](#api-segmentdocuments-metadata) com qualquer dado adicional que você deseja armazenar no segmento.
+ `subsegments`: **matriz** de objetos [`subsegment`](#api-segmentdocuments-subsegments).
+ `precursor_ids`: **matriz** de IDs de subsegmentos que identifica subsegmentos com o mesmo pai que foram concluídos antes deste subsegmento.
## Dados HTTP de solicitação
Use um bloco HTTP para registrar detalhes sobre uma solicitação HTTP que seu aplicativo atendeu (em um segmento) ou que seu aplicativo realizou para uma API HTTP downstream (em um subsegmento). A maioria dos campos deste objeto são mapeados para informações encontrados em uma solicitação e uma resposta HTTP.
**`http`**
Todos os campos são opcionais.
+ `request`: informações sobre uma solicitação.
+ `method`: o método de solicitação. Por exemplo, `GET`.
+ `url`: o URL completo da solicitação, compilado com base no protocolo, no nome do host e no caminho da solicitação.
+ `user_agent`: a string do agente de usuário do cliente do solicitante.
+ `client_ip`: o endereço IP do solicitante. Pode ser recuperado do `Source Address` do pacote IP ou, para solicitações encaminhadas, a partir de um `X-Forwarded-For` cabeçalho.
+ `x_forwarded_for`: (apenas para segmentos) um **booliano** indicando que o `client_ip` foi lido de um cabeçalho `X-Forwarded-For` e não é confiável, pois ele pode ter sido falsificado.
+ `traced`: (apenas para subsegmentos) um **booliano** indicando que a chamada subsequente é para outro serviço rastreado. Se este campo estiver definido como `true`, o X-Ray considerará o rastreamento como dividido até que o serviço subsequente carregue um segmento com um `id` que corresponda ao `parent_id` do subsegmento que contém esse bloco.
+ `response`: informações sobre uma resposta.
+ `status`: **número inteiro** indicando o status HTTP da resposta.
+ `content_length`: **número inteiro** indicando o tamanho do corpo da resposta em bytes.
Ao instrumentar uma chamada subsequente de API da web, registre um subsegmento com informações sobre a solicitação e a resposta HTTP. O X-Ray usa o subsegmento para gerar um segmento inferido para a API remota.
**Example Segmento para chamada HTTP servido por um aplicativo em execução no Amazon EC2**
```
{
"id": "6b55dcc497934f1a",
"start_time": 1484789387.126,
"end_time": 1484789387.535,
"trace_id": "1-5880168b-fd5158284b67678a3bb5a78c",
"name": "www.example.com",
"origin": "AWS::EC2::Instance",
"aws": {
"ec2": {
"availability_zone": "us-west-2c",
"instance_id": "i-0b5a4678fc325bg98"
},
"xray": {
"sdk_version": "2.11.0 for Java"
},
},
"http": {
"request": {
"method": "POST",
"client_ip": "78.255.233.48",
"url": "http://www.example.com/api/user",
"user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
"x_forwarded_for": true
},
"response": {
"status": 200
}
}
```
**Example Subsegmento para uma chamada HTTP downstream**
```
{
"id": "004f72be19cddc2a",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"name": "names.example.com",
"namespace": "remote",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
}
}
```
**Example Segmento inferido para uma chamada HTTP de downstream**
```
{
"id": "168416dc2ea97781",
"name": "names.example.com",
"trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"parent_id": "004f72be19cddc2a",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
},
"inferred": true
}
```
## Anotações
Os segmentos e subsegmentos podem incluir um objeto `annotations` contendo um ou mais campos que o X-Ray indexa para serem usados com expressões de filtro. Os campos podem ter string, número ou valores boolianos (sem objetos ou matrizes). O X-Ray indexa até cinquenta anotações por rastreamento.
**Example Segmento para chamada HTTP com anotações**
```
{
"id": "6b55dcc497932f1a",
"start_time": 1484789187.126,
"end_time": 1484789187.535,
"trace_id": "1-5880168b-fd515828bs07678a3bb5a78c",
"name": "www.example.com",
"origin": "AWS::EC2::Instance",
"aws": {
"ec2": {
"availability_zone": "us-west-2c",
"instance_id": "i-0b5a4678fc325bg98"
},
"xray": {
"sdk_version": "2.11.0 for Java"
},
},
"annotations": {
"customer_category" : 124,
"zip_code" : 98101,
"country" : "United States",
"internal" : false
},
"http": {
"request": {
"method": "POST",
"client_ip": "78.255.233.48",
"url": "http://www.example.com/api/user",
"user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
"x_forwarded_for": true
},
"response": {
"status": 200
}
}
```
As chaves devem ser alfanuméricas para funcionar com filtros. Sublinhado é permitido. Outros símbolos e espaço em branco não são permitidos.
## Metadados
Os segmentos e subsegmentos podem incluir um objeto `metadata` contendo um ou mais campos com valores de qualquer tipo, incluindo objetos e matrizes. O X-Ray não indexa metadados, e os valores podem ser de qualquer tamanho, desde que o documento de segmentos não ultrapasse o tamanho máximo (64 kB). Você pode visualizar os metadados no documento de segmento completo retornado pela API [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html). As chaves de campo (`debug` no exemplo a seguir) que começam com `AWS.` são reservadas para serem usadas por SDKs e clientes fornecidos pela AWS.
**Example Subsegmento personalizado com metadados**
```
{
"id": "0e58d2918e9038e8",
"start_time": 1484789387.502,
"end_time": 1484789387.534,
"name": "## UserModel.saveUser",
"metadata": {
"debug": {
"test": "Metadata string from UserModel.saveUser"
}
},
"subsegments": [
{
"id": "0f910026178b71eb",
"start_time": 1484789387.502,
"end_time": 1484789387.534,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 58,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "3AIENM5J4ELQ3SPODHKBIRVIC3VV4KQNSO5AEMVJF66Q9ASUAAJG",
"resource_names": [
"scorekeep-user"
]
}
}
]
}
```
## Dados de recursos da AWS
Para segmentos, o objeto `aws` contém informações sobre o recurso no qual seu aplicativo é executado. Vários campos podem ser aplicados a um único recurso. Por exemplo, um aplicativo em execução em um ambiente do Docker de vários contêineres no Elastic Beanstalk poderia ter informações sobre a instância do Amazon EC2, o contêiner do Amazon ECS em execução na instância e o próprio ambiente do Elastic Beanstalk.
**`aws` (Segmentos)**
Todos os campos são opcionais.
+ `account_id`: se o aplicativo envia segmentos para uma outra Conta da AWS, registre o ID da conta que está executando o aplicativo.
+ `cloudwatch_logs`: conjunto de objetos que descrevem um único grupo de logs do CloudWatch.
+ `log_group`: o nome do grupo de logs do CloudWatch.
+ `arn`: o ARN do grupo de logs do CloudWatch.
+ `ec2`: informações sobre uma instância do EC2.
+ `instance_id`: o ID da instância do EC2.
+ `instance_size`: o tipo da instância do EC2.
+ `ami_id`: o ID da imagem de máquina da Amazon.
+ `availability_zone`: a zona de disponibilidade na qual a instância está sendo executada.
+ `ecs`: informações sobre um contêiner do Amazon ECS.
+ `container`: o nome do host do contêiner.
+ `container_id`: o ID completo do contêiner.
+ `container_arn`: o ARN da instância de contêiner.
+ `eks`: informações sobre um cluster do Amazon EKS.
+ `pod`: o nome do host do pod do EKS.
+ `cluster_name`: o nome do cluster do EKS.
+ `container_id`: o ID completo do contêiner.
+ `elastic_beanstalk`: informações sobre um ambiente do Elastic Beanstalk. Você encontra essas informações em um arquivo chamado `/var/elasticbeanstalk/xray/environment.conf` nas plataformas mais recentes do Elastic Beanstalk.
+ `environment_name`: o nome do ambiente.
+ `version_label`: o nome da versão do aplicativo que está implantada no momento na instância que atendeu à solicitação.
+ `deployment_id`: um **número** que indica o ID da última implantação bem-sucedida na instância que atendeu à solicitação.
+ `xray`: metadados sobre o tipo e a versão da instrumentação usada.
+ `auto_instrumentation`: booliano que indica se a instrumentação automática foi usada (por exemplo, o agente do Java).
+ `sdk_version`: a versão do SDK ou do agente que está sendo usada.
+ `sdk`: o tipo de SDK.
**Example Bloco da AWS com plug-ins**
```
"aws":{
"elastic_beanstalk":{
"version_label":"app-5a56-170119_190650-stage-170119_190650",
"deployment_id":32,
"environment_name":"scorekeep"
},
"ec2":{
"availability_zone":"us-west-2c",
"instance_id":"i-075ad396f12bc325a",
"ami_id":
},
"cloudwatch_logs":[
{
"log_group":"my-cw-log-group",
"arn":"arn:aws:logs:us-west-2:012345678912:log-group:my-cw-log-group"
}
],
"xray":{
"auto_instrumentation":false,
"sdk":"X-Ray for Java",
"sdk_version":"2.8.0"
}
}
```
Para subsegmentos, registre informações sobre os recursos e Serviços da AWS que o aplicativo acessa. O X-Ray usa essas informações para criar segmentos inferidos que representam os serviços subsequentes no mapa de serviço.
**`aws` (Subsegmentos)**
Todos os campos são opcionais.
+ `operation`: o nome da ação de API invocada para um recurso ou AWS service (Serviço da AWS).
+ `account_id`: se o aplicativo acessa recursos em uma outra conta ou envia segmentos para uma conta diferente, registre o ID da conta que controla o recurso da AWS que o aplicativo acessou.
+ `region`: se o recurso estiver em uma região diferente do aplicativo, registre a região. Por exemplo, `us-west-2`.
+ `request_id`: identificador exclusivo da solicitação.
+ `queue_url`: para operações em uma fila do Amazon SQS, o URL da fila.
+ `table_name`: para operações em uma tabela do DynamoDB, o nome da tabela.
**Example Subsegmento para uma chamada ao DynamoDB para salvar um item**
```
{
"id": "24756640c0d0978a",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 60,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
}
}
```
## Erros e exceções
Quando ocorrer um erro, você pode registrar detalhes sobre o erro e as exceções que foram gerados. Registre erros em segmentos quando o seu aplicativo retornar um erro para o usuário e em subsegmentos quando uma chamada de downstream retornar um erro.
**tipos de erro**
Defina um ou mais dos seguintes campos do `true` para indicar que ocorreu um erro. Vários tipos podem ser aplicados se erros ocorrerem. Por exemplo, um `429 Too Many Requests` erro de uma chamada de downstream pode fazer com que seu aplicativo retorne `500 Internal Server Error`, caso em que os três tipos são aplicáveis.
+ `error`: um **booliano** indicando a ocorrência de um erro de cliente (o código de status de resposta foi 4XX Erro de cliente).
+ `throttle`: um **booliano** indicando que uma solicitação foi suspensa (o código de status de resposta foi *429 Solicitações em excesso*).
+ `fault`: um **booliano** indicando a ocorrência de um erro de servidor (o código de status de resposta foi 5XX Erro de servidor).
Indique a causa do erro, incluindo o objeto da **causa** no segmento ou subsegmento.
**`cause`**
Uma causa pode ser um ID de exceção de **16 caracteres** ou um objeto com os seguintes campos:
+ `working_directory`: o caminho completo do diretório de trabalho quando a exceção ocorreu.
+ `paths`: a **matriz** de caminhos para bibliotecas ou módulos em uso quando a exceção ocorreu.
+ `exceptions`: a **matriz** de objetos de **exceção**.
Incluir informações detalhadas sobre o erro em um ou mais objetos de **exceção**.
**`exception`**
Todos os campos são opcionais.
+ `id`: um identificador de 64 bits para a exceção, exclusivo entre segmentos no mesmo rastreamento, com **16 dígitos hexadecimais**.
+ `message`: a mensagem de exceção.
+ `type`: o tipo de exceção.
+ `remote`: um **booliano** indicando que a exceção foi causada por um erro retornado por um serviço subsequente.
+ `truncated`: um **inteiro** indicando o número de estruturas de pilhas que são omitidas da `stack`.
+ `skipped`: um **inteiro** indicando o número de exceções que foram ignoradas entre essa exceção e a exceção secundária, ou seja, a exceção que ela causou.
+ `cause`: o ID da exceção principal, ou seja, a exceção que causou essa exceção.
+ `stack`: a **matriz** de objetos **stackFrame**.
Se disponíveis, registre informações sobre a pilha de chamadas nos objetos **stackFrame**.
**`stackFrame`**
Todos os campos são opcionais.
+ `path`: o caminho relativo para o arquivo.
+ `line`: a linha no arquivo.
+ `label`: a função ou o nome do método.
## Consultas SQL
Você pode criar subsegmentos para consultas que seu aplicativo faz em um banco de dados SQL.
**`sql`**
Todos os campos são opcionais.
+ `connection_string`: para o SQL Server ou outras conexões de banco de dados que não usam strings de conexão de URL, registre a string de conexão sem as senhas.
+ `url`: para uma conexão de banco de dados que usa uma string de conexão, registre o URL sem as senhas.
+ `sanitized_query`: a consulta de banco de dados, com os valores fornecidos pelo usuário removidos ou substituídos por um espaço reservado.
+ `database_type`: o nome do mecanismo de banco de dados.
+ `database_version`: o número da versão do mecanismo de banco de dados.
+ `driver_version`: o nome e o número da versão do driver do mecanismo de banco de dados que o aplicativo utiliza.
+ `user`: o nome de usuário do banco de dados.
+ `preparation`: `call` se a consulta usou uma `PreparedCall`; `statement` se a consulta usou uma `PreparedStatement`.
**Example Subsegmento com uma consulta SQL**
```
{
"id": "3fd8634e78ca9560",
"start_time": 1484872218.696,
"end_time": 1484872218.697,
"name": "ebdb@aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com",
"namespace": "remote",
"sql" : {
"url": "jdbc:postgresql://aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com:5432/ebdb",
"preparation": "statement",
"database_type": "PostgreSQL",
"database_version": "9.5.4",
"driver_version": "PostgreSQL 9.4.1211.jre7",
"user" : "dbuser",
"sanitized_query" : "SELECT * FROM customers WHERE customer_id=?;"
}
}
```