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á.
Usar a API do X-Ray
Se o X-Ray SDK não for compatível com sua linguagem de programação, você poderá usar as APIs X-Ray diretamente ou o AWS Command Line Interface (AWS CLI) para chamar os comandos da API X-Ray. Use as orientações a seguir para escolher como você interage com a API:
-
Use a sintaxe AWS CLI para simplificar usando comandos pré-formatados ou com opções dentro de sua solicitação.
-
Use a API X-Ray diretamente para obter o máximo de flexibilidade e personalização das solicitações feitas ao X-Ray.
Se você usar a X-Ray API diretamente em vez da AWS CLI, deverá parametrizar sua solicitação no formato de dados correto e talvez também precise configurar a autenticação e o tratamento de erros.
O diagrama a seguir mostra orientações para escolher como interagir com a API X-Ray:
Use a API X-Ray para enviar dados de rastreamento diretamente para o X-Ray. A API X-Ray é compatível com todas as funções disponíveis no X-Ray SDK, incluindo as seguintes ações comuns:
-
PutTraceSegments— Carrega documentos do segmento para o X-Ray.
-
BatchGetTraces— Recupera uma lista de traços em uma lista de IDs de rastreamento. Cada rastreamento recuperado é uma coleção de documentos do segmento de uma única solicitação.
-
GetTraceSummaries— Recupera IDs e anotações para rastreamentos. Você pode especificar um
FilterExpressionpara recuperar um subconjunto de resumos de rastreamento. -
GetTraceGraph— Recupera um gráfico de serviço para um ID de rastreamento específico.
-
GetServiceGraph— recupera um documento JSON formatado que descreve serviços que processam solicitações recebidas e ligam para solicitações posteriores.
Você também pode usar o AWS Command Line Interface (AWS CLI) dentro do código do aplicativo para interagir programaticamente com o X-Ray. O AWS CLI suporta todas as funções disponíveis no X-Ray SDK, incluindo aquelas para outras 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
— Carrega documentos do segmento para o X-Ray. -
batch-get-traces
— Recupera uma lista de traços em uma lista de IDs de rastreamento. Cada rastreamento recuperado é uma coleção de documentos do segmento de uma única solicitação. -
get-trace-summaries
— Recupera IDs e anotações para rastreamentos. Você pode especificar um FilterExpressionpara recuperar um subconjunto de resumos de rastreamento. -
get-trace-graph
— Recupera um gráfico de serviço para um ID de rastreamento específico. -
get-service-graph
— recupera um documento JSONformatado que descreve serviços que processam solicitações recebidas e ligam para solicitações posteriores.
Para começar, você deve instalar o AWS CLIpara o seu sistema operacional. AWS Linuxsuportes macOS e sistemas Windows operacionais. Para obter mais informações sobre a lista de comandos X-Ray, consulte o guia de referência de AWS CLI comandos para X-Ray
Explore a API X-Ray
A API X-Ray fornece acesso a todas as funcionalidades do X-Ray por meio do AWS SDK ou diretamente por HTTPS. AWS Command Line Interface A Referência de API do X-Ray documenta os parâmetros de entrada de cada ação de API e os campos e tipos de dados que eles retornam.
Você pode usar o AWS SDK para desenvolver programas que usam a API X-Ray. Tanto o console X-Ray quanto o daemon X-Ray usam o AWS SDK para se comunicar com o X-Ray. O AWS SDK de cada linguagem tem um documento de referência para classes e métodos mapeados para ações e tipos da API X-Ray.
AWS Referências do SDK
-
Java: AWS SDK for Java
-
JavaScript – AWS SDK for JavaScript
-
.NET: AWS SDK for .NET
-
Ruby: AWS SDK for Ruby
-
Go: AWS SDK para Go
-
PHP: AWS SDK for PHP
-
Python: AWS SDK for Python (Boto)
AWS Command Line Interface É uma ferramenta de linha de comando que usa o SDK para Python para AWS chamar APIs. Quando você está aprendendo uma AWS API pela primeira vez, AWS CLI ela fornece uma maneira fácil de explorar os parâmetros disponíveis e visualizar a saída do serviço em JSON ou em formato de texto.
Consulte a Referência de AWS CLI Comandos para obter detalhes sobre aws xray subcomandos.
A AWS CLI permite que você acesse o serviço X-Ray diretamente e use as mesmas APIs que o console X-Ray usa para recuperar o gráfico do serviço e os dados brutos de rastreamentos. O aplicativo de amostra 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 exemplo de tutorial do aplicativo para iniciar o aplicativo.
Este tutorial usa o AWS CLI para mostrar o uso básico da API X-Ray. A AWS CLI, disponível para Windows, Linux e OS-X, fornece acesso à linha de comando às APIs públicas para todos. Serviços da AWS
nota
Você deve verificar se o seu AWS CLI está configurado na mesma região em que seu aplicativo de amostra 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 fazer download do executável jq a partir de stedolan.github.iocurl a partir de https://curl.haxx.se/download.html
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
Abra o console do Elastic Beanstalk
. Navegue até o console de gerenciamento do seu ambiente.
-
Copie o URL de ambiente do cabeçalho da página.
-
Abra
bin/test-api.she substitua o valor para API com o URL do seu ambiente.#!/bin/bash API=scorekeep.9hbtbm23t2.us-west-2.elasticbeanstalk.com/api -
Execute o script para gerar tráfego para a API.
~/debugger-tutorial$./bin/test-api.shCreating 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 e. GetServiceGraphGetTraceSummaries Consulte a AWS X-Ray Referência da API para mais informações sobre todas as ações suportadas e os tipos de dados que usam.
exemplo bin/service-graph.sh
EPOCH=$(date +%s)
aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCHO 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",
...exemplo 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"
]exemplo 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
Abra o console do Elastic Beanstalk
. Navegue até o console de gerenciamento do seu ambiente.
-
Escolha Ações.
-
Escolha Terminate Environment.
-
Escolha Encerrar.
Os dados de rastreamento são excluídos automaticamente do X-Ray após 30 dias.
É 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. Pelo menos um segmento registra o tempo gasto em uma tarefa, um nome e duas 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.
exemplo 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.
exemplo 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 ou , por meio do daemon do X-Ray.
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).
exemplo 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 Documentos do segmento X-Ray.
Para enviar dados para o X-Ray, você deve gerar um ID de rastreamento exclusivo para cada solicitação.
Formato de identificação de rastreamento 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 no Unix epoch time usando 8 dígitos hexadecimais.
Por exemplo, às 10h de 1º de dezembro de 2016 PST em tempo de época é de
1480615200segundos ou58406520em dígitos hexadecimais. -
Um identificador globalmente exclusivo de 96 bits para o rastreamento em 24 dígitos hexadecimais.
nota
O X-Ray agora suporta IDs de rastreamento que são criados usando OpenTelemetry qualquer outra estrutura que esteja em conformidade com a especificação W3C Trace4efaaf4d1e8720b39541901950019ee5 deve ser formatado como 1-4efaaf4d-1e8720b39541901950019ee5 quando enviado para o X-Ray. Os IDs de rastreamento do X-Ray incluem a data e hora da solicitação original no Unix epoch time, mas isso não é necessário ao enviar IDs de rastreamento do W3C no formato X-Ray.
Você pode gravar um script para gerar IDs de rastreamento do X-Ray para testes. 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 a aplicação de exemplo Scorekeep para scripts que criam IDs de rastreamento e enviam segmentos ao daemon do X-Ray.
-
Python:
xray_start.py -
Bash:
xray_start.sh
É possível fazer upload de documentos segmentados com a API PutTraceSegments. 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 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"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 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/2000exemplo 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 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)O X-Ray processa os dados de rastreamento que você envia para gerar rastreamentos completos, resumos de rastreamento e gráficos de serviço em JSON. Você pode recuperar os dados gerados diretamente da API com a AWS CLI.
Você pode usar a API do GetServiceGraph 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
1499394617date +%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.
exemplo 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.
exemplo GetServiceGraph saída
{ "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 } ] } ] }
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.
exemplo Script para recuperar um gráfico de serviço por nome para o grupo Example1
aws xray get-service-graph --group-name "Example1"
Você pode usar a API do GetTraceSummaries 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
GetTraceSummariespesquisa padrão usa o tempo do TraceID e retorna os rastreamentos iniciados dentro do intervalo calculado.[start_time, end_time)Esse intervalo de timestamps é calculado com base na codificação do timestamp dentro do TraceId, ou pode ser definido manualmente. -
Hora do evento — Para pesquisar eventos à medida que eles acontecem ao longo do tempo, o AWS X-Ray permite pesquisar traços usando registros de data e hora de 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 de entre 1 e 2 minutos no passado usando o TraceId horário padrão.
exemplo Script para obter resumos de rastreamentos
EPOCH=$(date +%s) aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60))
exemplo GetTraceSummaries saída
{
"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 BatchGetTraces.
exemplo BatchGetTraces comando
$ aws xray batch-get-traces --trace-ids 1-596025b4-7170afe49f7aa708b1dd4a6bexemplo BatchGetTraces saída
{
"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 pela aplicação. 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 pela aplicação e removendo os dados que não estão em conformidade com o esquema do documento de segmento. Para ter mais informações, consulte Documentos do segmento X-Ray.
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 do 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. Redirecione a lista para a entrada batch-get-traces para obter rastreamentos completos de um período específico.
exemplo 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[*]'
Ao gerar um resumo de rastreamento com a GetTraceSummaries API, resumos parciais de rastreamento podem ser reutilizados em seu formato JSON para criar uma expressão de filtro refinada com base nas causas principais. Veja os exemplos abaixo para obter uma demonstração das etapas de refinamento.
exemplo Exemplo GetTraceSummaries de saída - 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.
exemplo 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 a seção Usar expressões de filtro no console Explore o X-Ray para obter mais detalhes sobre a consulta com expressões de filtro.
exemplo Exemplo de filtro JSON
rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]
O X-Ray fornece APIs para definir regras de amostragem, regras de grupo e configurações de criptografia.
Configurações de criptografia
Use PutEncryptionConfigpara 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 GetEncryptionConfig 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"
}
}Você pode gerenciar as regras de amostragem em sua conta com a API do X-Ray. Para obter mais informações sobre amostragem, consulteConfigurar regras de amostragem. Para obter mais informações sobre como adicionar e gerenciar tags, consulte Marcar grupos e regras de amostragem do X-Ray.
Obtenha todas as regras de amostragem com GetSamplingRules.
$ 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 UpdateSamplingRule.
exemplo Entrada de API para UpdateSamplingRule: 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.
$ 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 CreateSamplingRule. 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.
exemplo Entrada de API para UpdateSamplingRule: 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.
exemplo Entrada de API para UpdateSamplingRule: 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 DeleteSamplingRule.
$ 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
}
}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 Obtendo dados do X-Ray 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. Para obter mais informações sobre como adicionar e gerenciar tags, consulte Marcar grupos e regras de amostragem do X-Ray.
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.
$ 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"
{
}
O X-Ray SDK usa a X-Ray API para obter regras de amostragem, relatar resultados de 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 GetSamplingRules.
$ 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 Definindo configurações de amostragem, grupos e criptografia com a API X-Ray 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 da aplicação 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 GetSamplingTargets 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 GetSamplingRules. 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.
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 a aplicação faz localmente e subsegmentos com informações sobre chamadas subsequentes que a aplicação 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 PutTraceSegments.
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 GetTraceSummaries e BatchGetTraces, 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. Os segmentos inferidos representam serviços e recursos posteriores no mapa de rastreamento.
O X-Ray fornece um esquema JSON para documentos de segmentos. Você pode baixar o esquema aqui: xray-segmentdocument-schema-v1.0.0. 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 ter mais informações, consulte Use expressões de filtro.
Quando você instrumenta a aplicação 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. Para ter mais informações, consulte Enviar documentos de segmentos para o daemon do X-Ray.
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.
exemplo 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, em 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 de identificação de rastreamento X-Ray
Um
trace_iddo 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 no Unix epoch time usando 8 dígitos hexadecimais.
Por exemplo, às 10h de 1º de dezembro de 2016 PST em tempo de época é de
1480615200segundos ou58406520em dígitos hexadecimais. -
Um identificador globalmente exclusivo de 96 bits para o rastreamento em 24 dígitos hexadecimais.
nota
O X-Ray agora suporta IDs de rastreamento que são criados usando OpenTelemetry qualquer outra estrutura que esteja em conformidade com a especificação W3C Trace
Context. Um ID de rastreamento do W3C deve ser formatado no formato X-Ray trace ID ao ser enviado para o X-Ray. Por exemplo, o ID de rastreamento do W3C 4efaaf4d1e8720b39541901950019ee5deve ser formatado como1-4efaaf4d-1e8720b39541901950019ee5quando enviado para o X-Ray. Os IDs de rastreamento do X-Ray incluem a data e hora da solicitação original no Unix epoch time, mas isso não é necessário ao enviar IDs de rastreamento do W3C no formato X-Ray.Segurança de ID de Rastreamento
IDs de rastreamento são visíveis nos cabeçalhos de resposta. 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, o1480615200.010ou o1.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, o1480615200.090ou o1.480615200090E9. Especifique umend_timeouin_progress. -
in_progress: um valor booliano, definido comotrue, em vez de especificar umend_timepara 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 aplicação que tenha permissão para PutTraceSegments 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 a aplicação.-
version: uma string que identifica a versão da aplicação que atendeu à solicitação.
-
-
user: uma string que identifica o usuário que enviou a solicitação. -
origin— O tipo de AWS recurso que executa seu 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 à sua aplicação, use o que é mais específico. Por exemplo, um ambiente do Docker de vários contêineres no Elastic Beanstalk executa a aplicação 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::Environmentcomo o ambiente pai dos outros dois recursos. -
-
parent_id: um ID de subsegmento que você especifica se a solicitação tiver se originado de uma aplicação instrumentada. O X-Ray SDK adiciona a ID do subsegmento principal ao cabeçalho de rastreamento para chamadas HTTP subsequentes. No caso de subsegmentos aninhados, um subsegmento pode ter um segmento ou um subsegmento como seu pai. -
http: objetos http com informações sobre a solicitação HTTP original. -
aws— awsobjeto com informações sobre o AWS recurso no qual seu aplicativo atendeu à solicitação. -
error,throttle,faultecause: campos de erro que indicam um erro ocorrido e que incluem informações sobre a exceção que causou o erro. -
annotations: o objeto annotations com os pares de chave-valor que você deseja que o X-Ray indexe para pesquisa. -
metadata: objeto metadata com qualquer dado adicional que você deseja armazenar no segmento. -
subsegments: matriz de objetos subsegment.
Você pode criar subsegmentos para registrar chamadas Serviços da AWS e recursos que você faz com o AWS SDK, chamadas para APIs Web HTTP internas ou externas ou consultas ao banco de dados SQL. 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.
exemplo 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.
exemplo Segmento em andamento
{
"name" : "example.com",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"in_progress": true
}exemplo 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, o1480615200.010ou o1.480615200010E9. -
end_time: um número que representa o momento em que o subsegmento foi encerrado. Por exemplo, o1480615200.090ou o1.480615200090E9. Especifique umend_timeouin_progress. -
in_progress: um valor booliano, definido comotrue, em vez de especificar umend_timepara 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 de identificação de rastreamento X-Ray
Um
trace_iddo 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 no Unix epoch time usando 8 dígitos hexadecimais.
Por exemplo, às 10h de 1º de dezembro de 2016 PST em tempo de época é de
1480615200segundos ou58406520em dígitos hexadecimais. -
Um identificador globalmente exclusivo de 96 bits para o rastreamento em 24 dígitos hexadecimais.
nota
O X-Ray agora suporta IDs de rastreamento que são criados usando OpenTelemetry qualquer outra estrutura que esteja em conformidade com a especificação W3C Trace
Context. Um ID de rastreamento do W3C deve ser formatado no formato X-Ray trace ID ao ser enviado para o X-Ray. Por exemplo, o ID de rastreamento do W3C 4efaaf4d1e8720b39541901950019ee5deve ser formatado como1-4efaaf4d-1e8720b39541901950019ee5quando enviado para o X-Ray. Os IDs de rastreamento do X-Ray incluem a data e hora da solicitação original no Unix epoch time, mas isso não é necessário ao enviar IDs de rastreamento do W3C no formato 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:awspara chamadas de SDK da AWS;remotepara outras chamadas subsequentes. -
http: objeto http com informações sobre uma chamada HTTP de saída. -
aws— awsobjeto com informações sobre o AWS recurso downstream que seu aplicativo chamou. -
error,throttle,faultecause: campos de erro que indicam um erro ocorrido e que incluem informações sobre a exceção que causou o erro. -
annotations: o objeto annotations com os pares de chave-valor que você deseja que o X-Ray indexe para pesquisa. -
metadata: objeto metadata com qualquer dado adicional que você deseja armazenar no segmento. -
subsegments: matriz de objetos subsegment. -
precursor_ids: matriz de IDs de subsegmentos que identifica subsegmentos com o mesmo pai que foram concluídos antes deste subsegmento.
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 doSource Addressdo pacote IP ou, para solicitações encaminhadas, a partir de umX-Forwarded-Forcabeçalho. -
x_forwarded_for: (apenas para segmentos) um booliano indicando que oclient_ipfoi lido de um cabeçalhoX-Forwarded-Fore 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 comotrue, o X-Ray considerará o rastreamento como dividido até que o serviço subsequente carregue um segmento com umidque corresponda aoparent_iddo 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.
exemplo 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
}
}exemplo 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
}
}
}exemplo 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
}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 booleanos (sem objetos ou matrizes). O X-Ray indexa até cinquenta anotações por rastreamento.
exemplo 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.
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 BatchGetTraces. As chaves de campo (debugno exemplo a seguir) que começam com AWS. são reservadas para uso por SDKs e clientes AWS fornecidos.
exemplo 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"
]
}
}
]
}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, uma aplicação 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 a aplicação envia segmentos para uma outra Conta da AWS, registre o ID da conta que está executando a aplicação. -
cloudwatch_logs— Matriz de objetos que descrevem um único grupo de CloudWatch registros.-
log_group— O nome do grupo de CloudWatch registros. -
arn— O ARN do grupo de CloudWatch registros.
-
-
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.confnas plataformas mais recentes do Elastic Beanstalk.-
environment_name: o nome do ambiente. -
version_label: o nome da versão da aplicação 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.
-
exemplo AWS bloquear 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 as informações sobre os recursos Serviços da AWS e os quais seu 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 seu aplicativo acessar recursos em uma conta diferente ou enviar segmentos para uma conta diferente, registre o ID da conta que possui o AWS recurso que seu aplicativo acessou. -
region: se o recurso estiver em uma região diferente da aplicação, 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.
exemplo 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",
}
}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 dastack. -
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.
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 a aplicação utiliza. -
user: o nome de usuário do banco de dados. -
preparation:callse a consulta usou umaPreparedCall;statementse a consulta usou umaPreparedStatement.
exemplo 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=?;"
}
}