Envio de 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. 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 AWS X-Ray documentos do segmento.

Gerar IDs de rastreamento

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 1480615200 segundos ou 58406520 em 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 4efaaf4d1e8720b39541901950019ee5 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

Usando PutTraceSegments

É 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"

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 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

exemplo 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)