Usa l'API X-Ray

Se l'SDK X-Ray non supporta il tuo linguaggio di programmazione, puoi utilizzare direttamente le API X-Ray o ( AWS Command Line Interface )AWS CLI per chiamare i comandi dell'API X-Ray. Utilizza le seguenti indicazioni per scegliere come interagire con l'API:

Utilizza la sintassi AWS CLI per una sintassi più semplice utilizzando comandi preformattati o con opzioni all'interno della richiesta.
Utilizza direttamente l'API X-Ray per la massima flessibilità e personalizzazione per le richieste che invii a X-Ray.

Se si utilizza direttamente l'API X-Ray anziché AWS CLI, è necessario parametrizzare la richiesta nel formato di dati corretto e potrebbe anche essere necessario configurare l'autenticazione e la gestione degli errori.

Il diagramma seguente mostra le linee guida per scegliere come interagire con l'API X-Ray:

X-Ray visualizza informazioni dettagliate sulle richieste delle applicazioni.

Utilizza l'API X-Ray per inviare i dati di traccia direttamente a X-Ray. L'API X-Ray supporta tutte le funzioni disponibili in X-Ray SDK, incluse le seguenti azioni comuni:

PutTraceSegments— Carica i documenti dei segmenti su X-Ray.
BatchGetTraces— Recupera un elenco di tracce in un elenco di ID di traccia. Ogni traccia recuperata è una raccolta di documenti di segmento provenienti da una singola richiesta.
GetTraceSummaries— Recupera gli ID e le annotazioni per le tracce. È possibile specificare FilterExpression a per recuperare un sottoinsieme di riepiloghi delle tracce.
GetTraceGraph— Recupera un grafico di servizio per un ID di traccia specifico.
GetServiceGraph— Recupera un documento JSON formattato che descrive i servizi che elaborano le richieste in entrata e chiamano le richieste a valle.

Puoi anche usare il AWS Command Line Interface (AWS CLI) all'interno del codice dell'applicazione per interagire a livello di codice con X-Ray. AWS CLI Supporta tutte le funzioni disponibili nell'X-Ray SDK, comprese quelle per altri. Servizi AWS Le seguenti funzioni sono versioni delle operazioni API elencate in precedenza con un formato più semplice:

put-trace-segments— Carica i documenti dei segmenti su X-Ray.
batch-get-traces— Recupera un elenco di tracce in un elenco di ID di traccia. Ogni traccia recuperata è una raccolta di documenti di segmento provenienti da una singola richiesta.
get-trace-summaries— Recupera gli ID e le annotazioni per le tracce. È possibile specificare FilterExpression a per recuperare un sottoinsieme di riepiloghi delle tracce.
get-trace-graph— Recupera un grafico di servizio per un ID di traccia specifico.
get-service-graph— Recupera un documento JSON formattato che descrive i servizi che elaborano le richieste in entrata e chiamano le richieste a valle.

Per iniziare, è necessario installare il file AWS CLIper il proprio sistema operativo. AWS supporti Linux macOS e sistemi Windows operativi. Per ulteriori informazioni sull'elenco dei comandi X-Ray, vedere la guida di riferimento ai AWS CLI comandi per X-Ray.

Esplora l'API X-Ray

L'API X-Ray fornisce l'accesso a tutte le funzionalità X-Ray tramite l' AWS SDK o direttamente tramite HTTPS AWS Command Line Interface. L'X-Ray API Reference documenta i parametri di input per ogni azione API e i campi e i tipi di dati che restituiscono.

Puoi utilizzare l' AWS SDK per sviluppare programmi che utilizzano l'API X-Ray. La console X-Ray e il daemon X-Ray utilizzano entrambi l'SDK AWS per comunicare con X-Ray. L' AWS SDK per ogni lingua ha un documento di riferimento per le classi e i metodi che mappano le azioni e i tipi dell'API X-Ray.

AWS Riferimenti SDK

Java — AWS SDK for Java
JavaScript – AWS SDK for JavaScript
.NET: AWS SDK for .NET
Ruby: AWS SDK for Ruby
Go — AWS SDK per Go
PHP: AWS SDK for PHP
Python – AWS SDK for Python (Boto)

AWS Command Line Interface È uno strumento da riga di comando che utilizza l'SDK per Python per chiamare le AWS API. Quando apprendi per la prima volta un' AWS API, questa AWS CLI fornisce un modo semplice per esplorare i parametri disponibili e visualizzare l'output del servizio in formato JSON o testo.

Vedi AWS CLI Command Reference per i dettagli sui aws xray sottocomandi.

La AWS CLI consente di accedere direttamente al servizio X-Ray e di utilizzare le stesse API utilizzate dalla console X-Ray per recuperare il grafico del servizio e i dati grezzi delle tracce. L'applicazione di esempio include script che mostrano come utilizzare queste API con la CLI AWS .

Prerequisiti

Questo tutorial utilizza l'applicazione di esempio Scorekeep e gli script in essa inclusi per generare dei dati di tracciamento e una mappa del servizio. Segui le istruzioni riportate nel tutorial di esempio dell'applicazione per avviare l'applicazione.

Questo tutorial utilizza AWS CLI per mostrare l'uso di base dell'API X-Ray. La AWS CLI, disponibile per Windows, Linux e OS-X, fornisce l'accesso da riga di comando alle API pubbliche per tutti. Servizi AWS

Nota

È necessario verificare che sia configurato nella stessa regione in cui AWS CLI è stata creata l'applicazione di esempio.

Gli script incluso per testare l'applicazione di esempio utilizzano cURL per inviare il traffico verso l'API e jq per analizzare l'output. Puoi scaricare l'eseguibile di jq da stedolan.github.io e l'eseguibile di curl da https://curl.haxx.se/download.html. La maggior parte delle installazioni Linux e OS X include cURL.

Generare i dati di tracciamento

Mentre il gioco è in corso, l'applicazione web genera continuamente traffico verso l'API ogni pochi secondi, ma genera solo un tipo di richiesta. Utilizza lo script test-api.sh per eseguire scenari completi e generare dati di tracciamento più eterogeni mentre testi l'API.

Per usare lo script `test-api.sh`

Apri la console Elastic Beanstalk.
Accedi alla console di gestione del tuo ambiente.
Copiare l'URL di ambiente dall'intestazione della pagina.
Aprire bin/test-api.sh e sostituire il valore per l’API con l'URL del proprio ambiente.
```
#!/bin/bash
API=scorekeep.9hbtbm23t2.us-west-2.elasticbeanstalk.com/api
```

Eseguire lo script per generare il traffico verso l'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"]}

Usa l'API X-Ray

La AWS CLI fornisce comandi per tutte le azioni API fornite da X-Ray, tra cui e. GetServiceGraphGetTraceSummaries Per ulteriori informazioni su tutte le operazioni supportate e i tipi di dati che utilizzano, consulta la Guida di riferimento delle API di AWS X-Ray.

Esempio bin/service-graph.sh


EPOCH=$(date +%s)
aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH

Lo script recupera un grafo del servizio relativo agli ultimi 10 minuti.


~/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",
...

Esempio bin/trace-urls.sh


EPOCH=$(date +%s)
aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Http.HttpURL'

Lo script recupera l'URL dei tracciamenti generati tra uno e due minuti fa.


~/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"
]

Esempio 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[*]'

Lo script recupera i tracciamenti completi generati tra uno e due minuti fa.


~/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
    }
...

Rimozione

Termina il tuo ambiente Elastic Beanstalk per chiudere le istanze Amazon EC2, le tabelle DynamoDB e altre risorse.

Per terminare l'ambiente Elastic Beanstalk

Apri la console Elastic Beanstalk.
Accedi alla console di gestione del tuo ambiente.
Scegli Azioni.
Scegliere Terminate Environment (Termina ambiente).
Scegliere Terminate (Termina).

I dati di traccia vengono eliminati automaticamente da X-Ray dopo 30 giorni.

È possibile inviare dati di traccia a X-Ray sotto forma di documenti di segmento. Un documento di segmento è una stringa in formato JSON che contiene le informazioni sull'attività eseguita dalla tua applicazione per il soddisfacimento di una richiesta. La tua applicazione può memorizzare i dati sull'attività che svolge in segmenti, oppure le attività che utilizzano i servizi e le risorse a valle possono creare dei sottosegmenti.

I segmenti registrano le informazioni sull'attività svolta dalla tua applicazione. Un segmento, come minimo, memorizza il tempo speso per un'attività, un nome e due identificativi. L'ID di tracciamento monitora la richiesta durante il suo passaggio tra i servizi. L'ID segmento monitora l'attività svolta per la richiesta proveniente da uno specifico servizio.

Esempio Segmento completo minimale


{
  "name" : "Scorekeep",
  "id" : "70de5b6f19ff9a0a",
  "start_time" : 1.478293361271E9,
  "trace_id" : "1-581cf771-a006649127e371903a2de979",
  "end_time" : 1.478293361449E9
}

Quando ricevi una richiesta, puoi inviare un segmento in esecuzione come segnaposto fino al completamento della richiesta.

Esempio Segmento in esecuzione


{
  "name" : "Scorekeep",
  "id" : "70de5b6f19ff9a0b",
  "start_time" : 1.478293361271E9,
  "trace_id" : "1-581cf771-a006649127e371903a2de979",
  “in_progress”: true
}

È possibile inviare segmenti a X-Ray direttamente, PutTraceSegmentscon o tramite il demone X-Ray.

La maggior parte delle applicazioni richiama altri servizi o accede a risorse con l'SDK. AWS Registra le informazioni sulle chiamate downstream in sottosegmenti. X-Ray utilizza i sottosegmenti per identificare i servizi a valle che non inviano segmenti e creare le relative voci nel grafico dei servizi.

Un sottosegmento può essere incorporato in un documento di segmento completo oppure può essere inviato in modo separato. Invia i sottosegmenti separatamente per tracciare in modo asincrono le chiamate downstream per richieste di lunga durata o per evitare di superare la dimensione massima del documento del segmento (64 kB).

Esempio Segmento secondario

Un sottosegmento presenta un type valorizzato a subsegment e un parent_id che identifica il segmento padre.


{
  "name" : "www2.example.com",
  "id" : "70de5b6f19ff9a0c",
  "start_time" : 1.478293361271E9,
  "trace_id" : "1-581cf771-a006649127e371903a2de979"
  “end_time” : 1.478293361449E9,
  “type” : “subsegment”,
  “parent_id” : “70de5b6f19ff9a0b”
}

Per ulteriori informazioni sui campi e i valori che puoi includere in segmenti e sottosegmenti, consulta Documenti relativi al segmento X-Ray.

Per inviare dati a X-Ray, è necessario generare un ID di traccia univoco per ogni richiesta.

Formato ID di traccia X-Ray

Una radiografia trace_id è composta da tre numeri separati da trattini. Ad esempio, 1-58406520-a006649127e371903a2de979. Questo include:

Il numero di versione, che è. 1
L'ora della richiesta originale in Unix epoch time utilizzando 8 cifre esadecimali.

Ad esempio, il fuso orario PST delle 10:00 del 1° dicembre 2016 è espresso in secondi o in cifre esadecimali. 1480615200 58406520
Un identificatore a 96 bit univoco a livello globale per la traccia in 24 cifre esadecimali.

Nota

X-Ray ora supporta gli ID di traccia creati utilizzando OpenTelemetry e qualsiasi altro framework conforme alla specifica W3C Trace Context. Un ID di traccia W3C deve essere formattato nel formato X-Ray Trace ID quando viene inviato a X-Ray. Ad esempio, l'ID di traccia W3C 4efaaf4d1e8720b39541901950019ee5 deve essere formattato come 1-4efaaf4d-1e8720b39541901950019ee5 quando si invia a X-Ray. Gli ID di traccia X-Ray includono il timestamp originale della richiesta in Unix epoch time, ma questo non è necessario quando si inviano gli ID di traccia W3C in formato X-Ray.

È possibile scrivere uno script per generare ID di traccia X-Ray per i test. Qui di seguito sono riportati due esempi.

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"

Vedi l'applicazione di esempio Scorekeep per gli script che creano ID di traccia e inviano segmenti al demone X-Ray.

Python: xray_start.py
Bash — xray_start.sh

Puoi caricare i documenti di segmento tramite l'API PutTraceSegments. L'API dispone di un singolo parametro, TraceSegmentDocuments, che richiede un elenco di documenti di segmento in formato JSON.

Con l'AWS CLI, usa il aws xray put-trace-segments comando per inviare documenti di segmento direttamente a 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

Windows Command Processor e Windows PowerShell hanno requisiti diversi per la citazione e l'escape delle virgolette nelle stringhe JSON. Per i dettagli, consulta Utilizzo delle virgolette nelle stringhe nella Guida per l'utente della AWS CLI .

L'output elenca tutti i segmenti per i quali l'elaborazione non è riuscita. Ad esempio, se la data nell'ID di tracciamento è troppo remota nel passato, verrà visualizzato un errore come il seguente.


{
    "UnprocessedTraceSegments": [
        {
            "ErrorCode": "InvalidTraceId",
            "Message": "Invalid segment. ErrorCode: InvalidTraceId",
            "Id": "6226467e3f845502"
        }
    ]
}

Puoi passare più documenti di segmento insieme, separati da spazi.


$ aws xray put-trace-segments --trace-segment-documents "$DOC1" "$DOC2"

Invece di inviare documenti di segmento all'API X-Ray, puoi inviare segmenti e sottosegmenti al daemon X-Ray, che li memorizzerà nel buffer e li caricherà sull'API X-Ray in batch. L'X-Ray SDK invia i documenti dei segmenti al demone per evitare di effettuare chiamate dirette. AWS

Nota

Per istruzioni sull'esecuzione del daemon, consulta Esecuzione locale del demone X-Ray.

Invia il segmento in formato JSON tramite la porta UDP 2000, anteponendo l'intestazione per il 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"}

Su Linux, puoi inviare documenti di segmento al daemon tramite un terminale Bash. Salva l'intestazione e il documento di segmento in un file di testo e reindirizzalo verso /dev/udp con cat.


$ cat segment.txt > /dev/udp/127.0.0.1/2000

Esempio 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"}

Controllate il registro del demone per verificare che abbia inviato il segmento a 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)

X-Ray elabora i dati di traccia inviati per generare tracce complete, riepiloghi delle tracce e grafici di servizio in JSON. Puoi recuperare i dati generati direttamente dall'API con la AWS CLI.

Puoi utilizzare l'API GetServiceGraph per recuperare il grafico del servizio in formato JSON. L'API richiede un'ora di inizio e di fine, che puoi calcolare in un terminale Linux con il comando date.


$ date +%s
1499394617

date +%s converte una data in secondi. Utilizza questo numero come ora finale e sottrai da esso il tempo necessario per ottenere un'ora di inizio.

Esempio Script per recuperare un grafico del servizio relativo agli ultimi 10 minuti


EPOCH=$(date +%s)
aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH

L'esempio seguente mostra un grafico di servizio con 4 nodi, tra cui un nodo client, un'istanza EC2, una tabella DynamoDB e un argomento Amazon SNS.

Esempio GetServiceGraph uscita


{
    "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
                }
            ]
        }
    ]
}

Per effettuare la chiamata a un grafico del servizio in base al contenuto di un gruppo, includi groupName o groupARN. L'esempio seguente mostra una chiamata del grafico del servizio a un gruppo denominato Example1.

Esempio Script per recuperare un grafico del servizio in base al nome del gruppo Example1


aws xray get-service-graph --group-name "Example1"

Puoi utilizzare l'API GetTraceSummaries per ottenere un elenco di riepiloghi dei tracciamenti. I riepiloghi dei tracciamenti includono informazioni che è puoi utilizzare per identificare i tracciamenti da scaricare in modo completo, tra cui annotazioni, informazioni su richiesta e risposta e ID.

Ci sono due flag TimeRangeType disponibili quando si chiama aws xray get-trace-summaries:

TraceId— La GetTraceSummaries ricerca predefinita utilizza l'ora TraceID e restituisce le tracce iniziate all'interno dell'intervallo calcolato. [start_time, end_time) Questo intervallo di timestamp viene calcolato in base alla codifica del timestamp all'interno di o può essere definito manualmente. TraceId
Ora dell'evento: per cercare gli eventi man mano che si verificano nel tempo, AWS X-Ray consente di cercare le tracce utilizzando i timestamp degli eventi. L'ora dell'evento restituisce i tracciamenti attivi durante l'intervallo [start_time, end_time), indipendentemente dall'inizio del tracciamento.

Utilizza il comando aws xray get-trace-summaries per ottenere un elenco di riepiloghi di tracciamento. I seguenti comandi ottengono un elenco di riepiloghi delle tracce relative a un periodo compreso tra 1 e 2 minuti nel passato utilizzando l'ora predefinita. TraceId

Esempio Script per ottenere i riepiloghi dei tracciamenti


EPOCH=$(date +%s)
aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60))

Esempio GetTraceSummaries uscita


{
    "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
}

Utilizza l'ID di tracciamento nell'output per recuperare un tracciamento completo con l'API BatchGetTraces.

Esempio BatchGetTraces comando


$ aws xray batch-get-traces --trace-ids 1-596025b4-7170afe49f7aa708b1dd4a6b

Esempio BatchGetTraces uscita


{
    "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": []
}

Il tracciamento completo include un documento per ogni segmento, creato a partire da tutti i documenti di segmento con lo stesso ID di tracciamento ricevuti. Questi documenti non rappresentano i dati inviati a X-Ray dall'applicazione. Rappresentano invece i documenti elaborati generati dal servizio X-Ray. X-Ray crea il documento di traccia completo compilando i documenti dei segmenti inviati dall'applicazione e rimuovendo i dati che non sono conformi allo schema del documento del segmento. Per ulteriori informazioni, consulta Documenti relativi al segmento X-Ray.

X-Ray crea anche segmenti dedotti per le chiamate downstream verso servizi che non inviano segmenti di per sé. Ad esempio, quando si chiama DynamoDB con un client strumentato, l'SDK X-Ray registra un sottosegmento con dettagli sulla chiamata dal suo punto di vista. Tuttavia, DynamoDB non invia un segmento corrispondente. X-Ray utilizza le informazioni nel sottosegmento per creare un segmento dedotto che rappresenti la risorsa DynamoDB nella mappa di traccia e lo aggiunge al documento di traccia.

Per ottenere più tracciamenti tramite le API, hai bisogno di un elenco di ID di tracciamento, che puoi estrarre dall'output di get-trace-summaries tramite una query AWS CLI. Reindirizza l'elenco all'input di per ottenere tracce complete batch-get-traces per un periodo di tempo specifico.

Esempio Script per ottenere i tracciamenti completi per un periodo di un 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[*]'

Dopo aver generato un riepilogo delle tracce con l'GetTraceSummaries API, è possibile riutilizzare i riepiloghi delle tracce parziali nel formato JSON per creare un'espressione di filtro raffinata basata sulle cause principali. Consulta gli esempi riportati di seguito per una procedura guidata per le fasi di definizione.

Esempio GetTraceSummaries di output: sezione relativa al tempo di risposta e alla causa principale


{
  "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
        }
      ]
    }
  ] 
}

Modificando e apportando omissioni all'output precedente, questo JSON può diventare un filtro per le entità di cause principali corrispondenti. Per tutti i campi presenti nel JSON, ogni corrispondenza dei candidati deve essere esatta o il tracciamento non verrà restituito. I campi rimossi diventano valori jolly, un formato compatibile con la struttura di query dell’espressione di filtro.

Esempio Causa principale del tempo di risposta riformattata


{
  "Services": [
    {
      "Name": "GetWeatherData",
      "EntityPath": [
        {
          "Name": "GetWeatherData"
        },
        {
          "Name": "get_temperature"
        }
      ]
    },
    {
      "Name": "GetTemperature",
      "EntityPath": [
        {
          "Name": "GetTemperature"
        }
      ]
    }
  ]
}

Questo JSON viene quindi utilizzato come parte di un'espressione di filtro tramite una chiamata a rootcause.json = #[{}]. Consultate la sezione Usa le espressioni di filtro in Esplora la console X-Ray per maggiori dettagli sulle interrogazioni con le espressioni di filtro.

Esempio di filtro JSON


rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]

X-Ray fornisce API per la configurazione delle regole di campionamento, delle regole di gruppo e delle impostazioni di crittografia.

Impostazioni di crittografia

Si usa PutEncryptionConfigper specificare una chiave AWS Key Management Service (AWS KMS) da usare per la crittografia.

Nota

X-Ray non supporta le chiavi KMS asimmetriche.


$ 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"
    }
}

Come ID della chiave, puoi utilizzare un alias (come illustrato nell'esempio), una ID della chiave o di un ARN (Amazon Resource Name).

Utilizza GetEncryptionConfig per recuperare la configurazione corrente. Quando X-Ray termina di applicare le impostazioni, lo stato cambia da aUPDATING. 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"
    }
}

Per interrompere l'utilizzo di una chiave KMS e utilizzare la crittografia predefinita, imposta il tipo di crittografia su. NONE


$ aws xray put-encryption-config --type NONE
{
    "EncryptionConfig": {
        "Status": "UPDATING",
        "Type": "NONE"
    }
}

Puoi gestire le regole di campionamento nel tuo account con l'API X-Ray. Per ulteriori informazioni sul campionamento, vedere. Configura le regole di campionamento Per ulteriori informazioni sull'aggiunta e la gestione dei tag, vedereEtichettatura delle regole e dei gruppi di campionamento a raggi X.

Recupera tutte le regole di campionamento utilizzando l'API 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
        }
    ]
}

La regola di default si applica a tutte le richieste che non soddisfano nessun'altra regola. Si tratta della regola a priorità più bassa e non può essere eliminata. Puoi, tuttavia, modificare la percentuale e la dimensione della riserva utilizzando UpdateSamplingRule.

Esempio Input API per: `UpdateSamplingRule`10000-default.json


{
    "SamplingRuleUpdate": {
        "RuleName": "Default",
        "FixedRate": 0.01,
        "ReservoirSize": 0
    }
}

L'esempio seguente utilizza il file precedente come input per modificare la regola di default impostando una percentuale dell'1% senza riserva. I tag sono opzionali. Se scegli di aggiungere tag, è necessaria una chiave di tag e i valori dei tag sono facoltativi. Per rimuovere i tag esistenti da una regola di campionamento, usa 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
        },

Crea regole di campionamento aggiuntive con CreateSamplingRule. Quando crei una regola, la maggior parte dei campi della regola sono obbligatori. L'esempio seguente crea due regole. Questa prima regola imposta una percentuale fissa per l'applicazione di esempio Scorekeep. Si applica a tutte le richieste elaborate dall'API alle quali non si applicano regole di priorità maggiore.

Esempio Input API per `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
    }
}

Anche la seconda regola si applica a Scorekeep, ma le è assegnata una priorità maggiore ed è più specifica. Questa regola consente di impostare una percentuale di campionamento molto bassa per le richieste di polling. Queste sono le richieste GET effettuate dal client ogni pochi secondi per verificare la presenza di modifiche allo stato del gioco.

Esempio Input API per `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
    }
}

I tag sono opzionali. Se scegli di aggiungere tag, è necessaria una chiave di tag e i valori dei tag sono facoltativi.


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

Per eliminare una regola di campionamento, utilizza 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
    }
}

Puoi utilizzare l'API X-Ray per gestire i gruppi nel tuo account. I gruppi costituiscono una raccolta di tracciamenti definiti da un'espressione di filtro. Puoi utilizzare i gruppi per generare grafici di servizio aggiuntivi e fornire CloudWatch metriche Amazon. Vedi Acquisizione di dati da X-Ray per maggiori dettagli sull'utilizzo dei grafici e delle metriche dei servizi tramite l'API X-Ray. Per ulteriori informazioni sui gruppi, vedere. Configura i gruppi Per ulteriori informazioni sull'aggiunta e la gestione dei tag, consultaEtichettatura delle regole e dei gruppi di campionamento a raggi X.

Crea un gruppo con CreateGroup. I tag sono opzionali. Se scegli di aggiungere tag, è necessaria una chiave di tag e i valori dei tag sono facoltativi.


$ 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}"
}

Ottieni tutti i gruppi esistenti con 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"
}

Aggiorna un gruppo con UpdateGroup. I tag sono opzionali. Se scegli di aggiungere tag, è necessaria una chiave di tag e i valori dei tag sono facoltativi. Per rimuovere i tag esistenti da un gruppo, usa 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}"
}

Elimina un gruppo con DeleteGroup.


$ aws xray delete-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID" 
    {
    }

L'SDK X-Ray utilizza l'API X-Ray per ottenere regole di campionamento, riportare i risultati del campionamento e ottenere quote. Puoi utilizzare queste API per comprendere meglio come funzionano le regole di campionamento o per implementare il campionamento in un linguaggio non supportato da X-Ray SDK.

Inizia a recuperare tutte le regole di campionamento con 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
        }
    ]
}

L'output include la regola di default e regole personalizzate. Se non hai ancora creato nessuna regola di campionamento, consulta Configurazione delle impostazioni di campionamento, gruppi e crittografia con l'API X-Ray.

Valuta le regole rispetto alle richieste in entrata in ordine crescente di priorità. Quando una regola viene soddisfatta, utilizza la percentuale fissa e la dimensione della riserva per prendere una decisione sul campionamento. Registra le richieste campionate e ignora (ai fini del tracciamento) le richieste non campionate. Interrompe la valutazione delle regole nel momento un cui viene assunta una decisione sul campionamento.

La dimensione della riserva di una regola è il numero di tracciamenti al secondo da registrare prima di applicare la percentuale fissa. La riserva è conteggiata su tutti i servizi in modo cumulativo, quindi non puoi utilizzarla direttamente. Tuttavia, se è diverso da zero, è possibile prendere in prestito una traccia al secondo dal serbatoio fino a quando X-Ray non assegna una quota. Prima di ricevere una quota, registra la prima richiesta ogni secondo e applica la percentuale fissa per ulteriori richieste. La percentuale fissa è un numero decimale tra 0 e 1,00 (100%).

L'esempio seguente mostra una chiamata a GetSamplingTargets con dettagli sulle decisioni di campionamento effettuate negli ultimi 10 secondi.


$ 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": []
}

La risposta di X-Ray include una quota da utilizzare invece di prendere in prestito dal serbatoio. In questo esempio, il servizio ha prelevato 10 tracciamenti dalla riserva durante i 10 secondi, e viene applicata la percentuale fissa del 10% per le altre 100 richieste, generando un totale di 20 richieste campionate. La quota è valida per cinque minuti (indicata dal periodo di vita) o fino all'assegnazione di una nuova quota. X-Ray può anche assegnare un intervallo di segnalazione più lungo di quello predefinito, anche se qui non è così.

Nota

La risposta di X-Ray potrebbe non includere una quota la prima volta che viene chiamata. Continua a prelevare dalla riserva finché non viene assegnata una quota.

Gli altri due campi della risposta possono indicare dei problemi con l'input. Controlla LastRuleModification rispetto all'ultima chiamata di GetSamplingRules. Se è più recente, scarica una nuova copia delle regole. UnprocessedStatistics può includere errori che indicano che una regola è stata eliminata, che il documento delle statistiche di input era troppo vecchio o che sono presenti dei problemi con le autorizzazioni.

Un segmento di tracciamento è una rappresentazione JSON di una richiesta elaborata dalla tua applicazione. Un segmento di traccia registra informazioni sulla richiesta originale, informazioni sul lavoro svolto localmente dall'applicazione e sottosegmenti con informazioni sulle chiamate downstream effettuate dall'applicazione a AWS risorse, API HTTP e database SQL.

Un documento di segmento trasmette informazioni su un segmento a X-Ray. Un documento di segmento può pesare fino a 64 kB e contenere un intero segmento con sottosegmenti, un frammento di segmento che indica che una richiesta è in corso o un singolo sottosegmento inviato separatamente. È possibile inviare documenti segmentati direttamente a X-Ray utilizzando l'PutTraceSegmentsAPI.

X-Ray compila ed elabora i documenti dei segmenti per generare riepiloghi di tracce interrogabili e tracce complete a cui è possibile accedere utilizzando rispettivamente le API e. GetTraceSummariesBatchGetTraces Oltre ai segmenti e ai sottosegmenti inviati a X-Ray, il servizio utilizza le informazioni nei sottosegmenti per generare segmenti dedotti e li aggiunge alla traccia completa. I segmenti dedotti rappresentano i servizi e le risorse a valle nella mappa di traccia.

X-Ray fornisce uno schema JSON per i documenti di segmento. È possibile scaricare lo schema qui: xray-segmentdocument-schema-v 1.0.0. I campi e gli oggetti elencati nello schema sono descritti in modo dettagliato nelle sezioni seguenti.

Un sottoinsieme di campi di segmento viene indicizzato da X-Ray per essere utilizzato con le espressioni di filtro. Ad esempio, se imposti il user campo su un segmento su un identificatore univoco, puoi cercare segmenti associati a utenti specifici nella console X-Ray o utilizzando l'API. GetTraceSummaries Per ulteriori informazioni, consulta Usa le espressioni di filtro.

Quando strumentate la vostra applicazione con l'SDK X-Ray, l'SDK genera documenti di segmento per voi. Invece di inviare i documenti segmentati direttamente a X-Ray, l'SDK li trasmette tramite una porta UDP locale al demone X-Ray. Per ulteriori informazioni, consulta Invio di documenti di segmento al demone X-Ray.

Un segmento memorizza le informazioni di tracciamento relative a una richiesta elaborata dalla tua applicazione. Come minimo, un segmento memorizza nome, ID, ora di inizio, ID di tracciamento e ora di fine della richiesta.

Esempio Segmento completo minimale


{
  "name" : "example.com",
  "id" : "70de5b6f19ff9a0a",
  "start_time" : 1.478293361271E9,
  "trace_id" : "1-581cf771-a006649127e371903a2de979",
  "end_time" : 1.478293361449E9
}

Di seguito sono elencati i campi obbligatori, o condizionalmente obbligatori, per i segmenti.

Nota

I valori devono essere stringhe (lunghe fino a un massimo di 250 caratteri) a meno che non sia indicato altrimenti.

Campi del segmento obbligatori

name— Il nome logico del servizio che ha gestito la richiesta, fino a 200 caratteri. Ad esempio, il nome dell'applicazione o il nome di dominio. I nomi possono contenere lettere in formato Unicode, numeri e spazi e i seguenti simboli: _, ., :, /, %, &, #, =, +, \, -, @
id— Un identificatore a 64 bit per il segmento, unico tra i segmenti della stessa traccia, in 16 cifre esadecimali.
trace_id— Un identificatore univoco che collega tutti i segmenti e i sottosegmenti provenienti da una singola richiesta del client.
Formato ID di traccia X-Ray

Una radiografia trace_id è composta da tre numeri separati da trattini. Ad esempio, 1-58406520-a006649127e371903a2de979. Questo include:
- Il numero di versione, che è. 1
- L'ora della richiesta originale in Unix epoch time utilizzando 8 cifre esadecimali.
  
  Ad esempio, il fuso orario PST delle 10:00 del 1° dicembre 2016 è espresso in secondi o in cifre esadecimali. 1480615200 58406520
- Un identificatore a 96 bit univoco a livello globale per la traccia in 24 cifre esadecimali.
Nota
X-Ray ora supporta gli ID di traccia creati utilizzando OpenTelemetry e qualsiasi altro framework conforme alla specifica W3C Trace Context. Un ID di traccia W3C deve essere formattato nel formato X-Ray Trace ID quando viene inviato a X-Ray. Ad esempio, l'ID di traccia W3C 4efaaf4d1e8720b39541901950019ee5 deve essere formattato come 1-4efaaf4d-1e8720b39541901950019ee5 quando si invia a X-Ray. Gli ID di traccia X-Ray includono il timestamp originale della richiesta in Unix epoch time, ma questo non è necessario quando si inviano gli ID di traccia W3C in formato X-Ray.

Sicurezza dell'ID di tracciamento
Gli ID di tracciamento sono visibili nelle intestazioni di risposta. Genera gli ID di tracciamento con un algoritmo di generazione dei numeri casuali sicuro per assicurare che gli aggressori non siano in grado di calcolare futuri ID di tracciamento e di inviare le richieste con tali ID verso la tua applicazione.
start_time— numero che indica l'ora in cui il segmento è stato creato, in secondi a virgola mobile nell'ora dell'epoca. Ad esempio 1480615200.010 o 1.480615200010E9. Utilizza il numero di cifre decimali di cui hai bisogno. Quando disponibile, è consigliata la risoluzione al microsecondo.
end_time— numero che indica l'ora in cui il segmento è stato chiuso. Ad esempio 1480615200.090 o 1.480615200090E9. Specifica un end_time oppure il valore in_progress.
in_progress— booleano, impostato su true invece di specificare an end_time per registrare che un segmento è iniziato, ma non è completo. Invia la segnalazione di un segmento in elaborazione per memorizzare la richiesta ricevuta quando l'applicazione riceve una richiesta la cui esecuzione richiede molto tempo. Quando viene inviata la risposta, invia il completamento del segmento per sovrascrivere il segmento in elaborazione. Per ogni richiesta, invia un solo segmento completo e uno o nessun segmento in esecuzione.

Nomi dei servizi

I segmenti name devono corrispondere al nome di dominio o al nome logico del servizio che genera il segmento. Tuttavia, questo non viene applicato. Qualsiasi applicazione autorizzata PutTraceSegmentspuò inviare segmenti con qualsiasi nome.

I seguenti campi dei segmenti sono facoltativi.

Campi del segmento facoltativi

service— Un oggetto con informazioni sull'applicazione.
- version— Una stringa che identifica la versione dell'applicazione che ha fornito la richiesta.
user— Una stringa che identifica l'utente che ha inviato la richiesta.
origin— Il tipo di AWS risorsa che esegue l'applicazione.
Valori supportati
- AWS::EC2::Instance— Un'istanza Amazon EC2.
- AWS::ECS::Container— Un contenitore Amazon ECS.
- AWS::ElasticBeanstalk::Environment— Un ambiente Elastic Beanstalk.
Quando, per la tua applicazione, sono validi più valori, utilizza quello più specifico. Ad esempio, un ambiente Docker Elastic Beanstalk Multicontainer esegue l'applicazione su un contenitore Amazon ECS, che a sua volta viene eseguito su un'istanza Amazon EC2. In questo caso, è possibile impostare l'origine a AWS::ElasticBeanstalk::Environment poiché l'ambiente è il padre delle altre due risorse.
parent_id— Un ID di sottosegmento che specifichi se la richiesta proviene da un'applicazione strumentata. L'X-Ray SDK aggiunge l'ID del sottosegmento principale all'intestazione di tracciamento per le chiamate HTTP downstream. Nel caso di sottosegmenti nidificati, un sottosegmento può avere come padre un segmento o un sottosegmento.
http— httpoggetti con informazioni sulla richiesta HTTP originale.
aws— awsoggetto con informazioni sulla AWS risorsa su cui l'applicazione ha fornito la richiesta.
error, throttlefault, e cause — campi di errore che indicano che si è verificato un errore e che includono informazioni sull'eccezione che ha causato l'errore.
annotations— annotationsoggetto con coppie chiave-valore che si desidera che X-Ray indicizzi per la ricerca.
metadata— metadataoggetto con eventuali dati aggiuntivi che si desidera memorizzare nel segmento.
subsegments— matrice di subsegmentoggetti.

È possibile creare sottosegmenti per registrare le chiamate Servizi AWS e le risorse effettuate con l' AWS SDK, le chiamate alle API Web HTTP interne o esterne o le query del database SQL. Puoi anche creare dei sottosegmenti per eseguire il debug o annotare blocchi di codice dell'applicazione. I sottosegmenti possono contenere a loro volta altri sottosegmenti, perciò un sottosegmento personalizzato che memorizza i metadati su una chiamata ad una funzione interna può contenere altri sottosegmenti personalizzati o sottosegmenti relativi alle chiamate a valle.

Un sottosegmento registra una chiamata a valle dal punto di vista del servizio che la chiama. X-Ray utilizza i sottosegmenti per identificare i servizi a valle che non inviano segmenti e creare le relative voci nel grafico dei servizi.

Un sottosegmento può essere incorporato in un intero documento di segmento oppure può essere inviato in modo indipendente. Invia sottosegmenti separatamente per tracciare in modo asincrono le chiamate a valle in caso di richieste di lunga durata, oppure per evitare di superare la dimensione massima del documento di segmento.

Esempio Segmento con sottosegmento incorporato

Un sottosegmento indipendente presenta un type valorizzato a subsegment e un parent_id che identifica il segmento padre.


{
  "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
        }
      }
    }
  ]
}

Per le richieste di lunga durata, è possibile inviare un segmento in corso per notificare a X-Ray che la richiesta è stata ricevuta e quindi inviare i sottosegmenti separatamente per tracciarli prima di completare la richiesta originale.

Esempio Segmento in esecuzione


{
  "name" : "example.com",
  "id" : "70de5b6f19ff9a0b",
  "start_time" : 1.478293361271E9,
  "trace_id" : "1-581cf771-a006649127e371903a2de979",
  "in_progress": true
}

Esempio Sottosegmento indipendente

Un sottosegmento presenta un type valorizzato a subsegment, un trace_id e un parent_id che identifica il segmento padre.


{
  "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 la richiesta viene completata, chiudi il segmento inviandolo nuovamente con il campo end_time valorizzato. Il segmento completato sovrascrive il segmento in elaborazione.

Puoi anche inviare i sottosegmenti separatamente per richieste completate che hanno attivato flussi di lavoro asincroni. Ad esempio, un'API web potrebbe restituire immediatamente una risposta OK 200 prima di avviare l'attività richiesta dall'utente. È possibile inviare un segmento completo a X-Ray non appena viene inviata la risposta, seguito da sottosegmenti per il lavoro completato in un secondo momento. Come nel caso dei segmenti, puoi anche inviare un sottosegmento per memorizzare l'inizio del sottosegmento stesso e quindi sovrascriverlo con un sottosegmento completo una volta completata la chiamata a valle.

Di seguito sono elencati i campi obbligatori, o condizionalmente obbligatori, per i sottosegmenti.

Nota

I valori devono essere stringhe lunghe fino a un massimo di 250 caratteri, a meno che non sia indicato altrimenti.

Campi del sottosegmento obbligatori

id— Un identificatore a 64 bit per il sottosegmento, unico tra i segmenti della stessa traccia, in 16 cifre esadecimali.
name— Il nome logico del sottosegmento. Nel caso di chiamate a valle, denominare il sottosegmento in base alla risorsa o al servizio chiamati. Nel caso di sottosegmenti personalizzati, denominare il sottosegmento in base al codice che viene analizzato (ad esempio utilizzando un nome di funzione).
start_time— numero che indica l'ora in cui è stato creato il sottosegmento, in secondi a virgola mobile in base all'ora dell'epoca, preciso in millisecondi. Ad esempio 1480615200.010 o 1.480615200010E9.
end_time— numero che indica l'ora in cui il sottosegmento è stato chiuso. Ad esempio 1480615200.090 o 1.480615200090E9. Specificare un end_time o il valore in_progress.
in_progress— valore booleano impostato su true anziché specificare an per end_time registrare che un sottosegmento è iniziato, ma non è completo. Per ogni richiesta a valle, invia un solo sottosegmento completo e uno o nessun sottosegmento in lavorazione.
trace_id— ID di traccia del segmento principale del sottosegmento. Obbligatorio solo nel caso in cui si invii un sottosegmento in modo separato.
Formato ID di traccia X-Ray

Una radiografia trace_id è composta da tre numeri separati da trattini. Ad esempio, 1-58406520-a006649127e371903a2de979. Questo include:
- Il numero di versione, che è. 1
- L'ora della richiesta originale in Unix epoch time utilizzando 8 cifre esadecimali.
  
  Ad esempio, il fuso orario PST delle 10:00 del 1° dicembre 2016 è espresso in secondi o in cifre esadecimali. 1480615200 58406520
- Un identificatore a 96 bit univoco a livello globale per la traccia in 24 cifre esadecimali.
Nota
X-Ray ora supporta gli ID di traccia creati utilizzando OpenTelemetry e qualsiasi altro framework conforme alla specifica W3C Trace Context. Un ID di traccia W3C deve essere formattato nel formato X-Ray Trace ID quando viene inviato a X-Ray. Ad esempio, l'ID di traccia W3C 4efaaf4d1e8720b39541901950019ee5 deve essere formattato come 1-4efaaf4d-1e8720b39541901950019ee5 quando si invia a X-Ray. Gli ID di traccia X-Ray includono il timestamp originale della richiesta in Unix epoch time, ma questo non è necessario quando si inviano gli ID di traccia W3C in formato X-Ray.
parent_id— ID del segmento principale del sottosegmento. Obbligatorio solo nel caso in cui si invii un sottosegmento in modo separato. Nel caso di sottosegmenti nidificati, un sottosegmento può avere come padre un segmento o un sottosegmento.
type—subsegment. Richiesto solo se si invia un sottosegmento separatamente.

I seguenti campi dei sottosegmenti sono facoltativi.

Campi del sottosegmento facoltativi

namespace— aws per le chiamate SDK AWS; remote per altre chiamate downstream.
http— httpoggetto con informazioni su una chiamata HTTP in uscita.
aws— awsoggetto con informazioni sulla AWS risorsa downstream chiamata dall'applicazione.
error, throttlefault, e cause — campi di errore che indicano che si è verificato un errore e che includono informazioni sull'eccezione che ha causato l'errore.
annotations— annotationsoggetto con coppie chiave-valore che si desidera che X-Ray indicizzi per la ricerca.
metadata— metadataoggetto con eventuali dati aggiuntivi che si desidera memorizzare nel segmento.
subsegments— matrice di subsegmentoggetti.
precursor_ids— matrice di ID di sottosegmento che identifica i sottosegmenti con lo stesso elemento principale completati prima di questo sottosegmento.

Utilizza un blocco HTTP per memorizzare i dettagli relativi a una richiesta HTTP che la tua applicazione ha elaborato (in un segmento) oppure che la tua applicazione ha eseguito a valle verso un'API HTTP (in un sottosegmento). La maggior parte dei campi di questo oggetto corrispondono alle informazioni di una richiesta HTTP e della relativa risposta.

`http`

Tutti i campi sono facoltativi.

request— Informazioni su una richiesta.
- method— Il metodo di richiesta. Ad esempio, GET.
- url— L'URL completo della richiesta, compilato a partire dal protocollo, dal nome host e dal percorso della richiesta.
- user_agent— La stringa dell'agente utente proveniente dal client del richiedente.
- client_ip— L'indirizzo IP del richiedente. Può essere recuperato dal campo Source Address del pacchetto IP o, in caso di richieste inoltrate, da un'intestazione X-Forwarded-For.
- x_forwarded_for— (solo segmenti) booleano che indica che client_ip è stato letto da un'X-Forwarded-Forintestazione e non è affidabile in quanto avrebbe potuto essere falsificato.
- traced— (solo sottosegmenti) booleano che indica che la chiamata a valle è verso un altro servizio tracciato. Se questo campo è impostato sutrue, X-Ray considera la traccia interrotta finché il servizio downstream non carica un segmento con a parent_id che corrisponde al sottosegmento che id contiene questo blocco.
response— Informazioni su una risposta.
- status— numero intero che indica lo stato HTTP della risposta.
- content_length— numero intero che indica la lunghezza del corpo della risposta in byte.

Quando effettui una chiamata a un'API Web a valle, registra un sottosegmento con informazioni sulla richiesta e sulla risposta HTTP. X-Ray utilizza il sottosegmento per generare un segmento dedotto per l'API remota.

Esempio Segmento per chiamata HTTP elaborata da un'applicazione in esecuzione su 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
    }
  }

Esempio Sottosegmento per una chiamata HTTP a valle


{
  "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
    }
  }
}

Esempio Segmento dedotto per una chiamata HTTP a valle


{
  "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
}

I segmenti e i sottosegmenti possono includere un annotations oggetto contenente uno o più campi indicizzati da X-Ray per l'uso con le espressioni di filtro. I campi possono avere valori di tipo stringa, numerico o booleano (senza oggetti o matrici). X-Ray indica fino a 50 annotazioni per traccia.

Esempio Segmento per chiamata HTTP con annotazioni


{
  "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
    }
  }

Per funzionare con i filtri, le chiavi devono essere di tipo alfanumerico. Il trattino basso è ammesso. Altri simboli e gli spazi non sono ammessi.

I segmenti e i sottosegmenti possono includere un metadata oggetto contenente uno o più campi con valori di qualsiasi tipo, inclusi oggetti e matrici. X-Ray non indicizza i metadati e i valori possono avere qualsiasi dimensione, purché il documento del segmento non superi la dimensione massima (64 kB). Puoi visualizzare i metadati nel documento di segmento completo restituito dall'API BatchGetTraces. Le chiavi di campo (debugnell'esempio seguente) che iniziano con AWS. sono riservate all'uso da parte di SDK e AWS client forniti.

Esempio Sottosegmento personalizzato con metadati


{
  "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"
        ]
      }
    }
  ]
}

Nel caso dei segmenti, l'oggetto aws contiene informazioni sulla risorsa su cui è in esecuzione l'applicazione. A una singola risorsa possono essere associati molteplici campi. Ad esempio, un'applicazione in esecuzione in un ambiente Docker multicontainer su Elastic Beanstalk potrebbe contenere informazioni sull'istanza Amazon EC2, sul contenitore Amazon ECS in esecuzione sull'istanza e sull'ambiente Elastic Beanstalk stesso.

`aws` (Segmenti)

Tutti i campi sono facoltativi.

account_id— Se l'applicazione invia segmenti a un altro, registra l'ID dell'account su cui è in esecuzione l'applicazione. Account AWS
cloudwatch_logs— Matrice di oggetti che descrivono un singolo gruppo di CloudWatch log.
- log_group— Il nome del gruppo di CloudWatch log.
- arn— L' CloudWatch ARN del gruppo Log.
ec2— Informazioni su un'istanza Amazon EC2.
- instance_id— L'ID dell'istanza EC2.
- instance_size— Il tipo di istanza EC2.
- ami_id— L'Amazon Machine Image ID.
- availability_zone— La zona di disponibilità in cui è in esecuzione l'istanza.
ecs— Informazioni su un container Amazon ECS.
- container— Il nome host del contenitore.
- container_id— L'ID completo del contenitore.
- container_arn— L'ARN dell'istanza del contenitore.
eks— Informazioni su un cluster Amazon EKS.
- pod— Il nome host del tuo pod EKS.
- cluster_name— Il nome del cluster EKS.
- container_id— L'ID completo del contenitore.
elastic_beanstalk— Informazioni su un ambiente Elastic Beanstalk. Puoi trovare queste informazioni in un file denominato /var/elasticbeanstalk/xray/environment.conf sulle più recenti piattaforme Elastic Beanstalk.
- environment_name: il nome dell'ambiente.
- version_label— Il nome della versione dell'applicazione attualmente distribuita sull'istanza che ha fornito la richiesta.
- deployment_id— numero che indica l'ID dell'ultima distribuzione riuscita nell'istanza che ha fornito la richiesta.
xray— Metadati relativi al tipo e alla versione della strumentazione utilizzata.
- auto_instrumentation— Booleano che indica se è stata utilizzata la strumentazione automatica (ad esempio, l'agente Java).
- sdk_version— La versione dell'SDK o dell'agente in uso.
- sdk— Il tipo di SDK.

Esempio AWS blocco con plugin


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

Per i sottosegmenti, registra le informazioni sulle risorse Servizi AWS e sulle risorse a cui l'applicazione accede. X-Ray utilizza queste informazioni per creare segmenti dedotti che rappresentano i servizi a valle nella mappa dei servizi.

`aws` (Sottosegmenti)

Tutti i campi sono facoltativi.

operation— Il nome dell'azione API richiamata contro una risorsa or. Servizio AWS
account_id— Se l'applicazione accede alle risorse di un account diverso o invia segmenti a un account diverso, registra l'ID dell'account proprietario della AWS risorsa a cui l'applicazione ha avuto accesso.
region— Se la risorsa si trova in una regione diversa dall'applicazione, registra la regione. Ad esempio, us-west-2.
request_id— Identificatore univoco per la richiesta.
queue_url— Per le operazioni su una coda Amazon SQS, l'URL della coda.
table_name— Per le operazioni su una tabella DynamoDB, il nome della tabella.

Esempio Sottosegmento per una chiamata a DynamoDB per salvare un elemento


{
  "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 si verifica un errore, puoi memorizzare le informazioni relative all'errore e le eccezioni generate. Memorizza gli errori nei segmenti quando l'applicazione restituisce un errore all'utente, e nei sottosegmenti quando l'errore è restituito da una chiamata a valle.

tipi di errore

Imposta uno o più dei seguenti campi a true per indicare che si è verificato un errore. In caso di errori composti è possibile associare molteplici tipi. Ad esempio, un errore 429 Too Many Requests da una chiamata a valle può far sì che la tua applicazione ritorni un errore 500 Internal Server Error, nel qual caso possono essere associati tutti e tre i tipi di errore.

error— booleano che indica che si è verificato un errore del client (il codice di stato della risposta era 4XX Client Error).
throttle— booleano che indica che una richiesta è stata limitata (il codice di stato della risposta era 429 Too Many Requests).
fault— booleano che indica che si è verificato un errore del server (il codice di stato della risposta era 5XX Server Error).

Indica la causa dell'errore includendo un oggetto cause nel segmento o nel sottosegmento.

`cause`

A causa può essere un ID di eccezione lungo 16 caratteri o un oggetto con i campi riportati qui di seguito:

working_directory— Il percorso completo della directory di lavoro quando si è verificata l'eccezione.
paths— L'array di percorsi alle librerie o ai moduli in uso quando si è verificata l'eccezione.
exceptions— La matrice di oggetti di eccezione.

Includi informazioni dettagliate sull'errore in uno o più oggetti exception.

`exception`

Tutti i campi sono facoltativi.

id— Un identificatore a 64 bit per l'eccezione, unico tra i segmenti della stessa traccia, in 16 cifre esadecimali.
message— Il messaggio di eccezione.
type— Il tipo di eccezione.
remote— booleano che indica che l'eccezione è stata causata da un errore restituito da un servizio a valle.
truncated— numero intero che indica il numero di stack frame omessi da. stack
skipped— numero intero che indica il numero di eccezioni che sono state saltate tra questa eccezione e la relativa eccezione figlia, ovvero l'eccezione che ha causato.
cause— ID dell'eccezione principale dell'eccezione, ovvero l'eccezione che ha causato l'eccezione.
stack— matrice di oggetti StackFrame.

Se disponibili, memorizza le informazioni sullo stack delle chiamate negli oggetti stackFrame.

`stackFrame`

Tutti i campi sono facoltativi.

path— Il percorso relativo al file.
line— La riga del file.
label— Il nome della funzione o del metodo.

Puoi creare o sottosegmenti per le query che la tua applicazione esegue su un database SQL.

`sql`

Tutti i campi sono facoltativi.

connection_string— Per SQL Server o altre connessioni al database che non utilizzano stringhe di connessione URL, registrare la stringa di connessione, escluse le password.
url— Per una connessione al database che utilizza una stringa di connessione URL, registrare l'URL, escluse le password.
sanitized_query— L'interrogazione del database, con tutti i valori forniti dall'utente rimossi o sostituiti da un segnaposto.
database_type— Il nome del motore del database.
database_version— Il numero di versione del motore di database.
driver_version— Il nome e il numero di versione del driver del motore di database utilizzato dall'applicazione.
user— Il nome utente del database.
preparation— call se la query utilizzava unPreparedCall; statement se l'interrogazione utilizzava unPreparedStatement.

Esempio Sottosegmento con una query 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=?;"
  }
}

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Usa un SDK

Demone X-Ray

Usa l'API X-Ray

Esplora l'API X-Ray

AWS Riferimenti SDK

Prerequisiti

Nota

Generare i dati di tracciamento

Per usare lo script test-api.sh

Usa l'API X-Ray

Esempio bin/service-graph.sh

Esempio bin/trace-urls.sh

Esempio bin/full-traces.sh

Rimozione

Per terminare l'ambiente Elastic Beanstalk

Esempio Segmento completo minimale

Esempio Segmento in esecuzione

Esempio Segmento secondario

Formato ID di traccia X-Ray

Nota

Nota

Nota

Esempio segment.txt

Esempio Script per recuperare un grafico del servizio relativo agli ultimi 10 minuti

Esempio GetServiceGraph uscita

Esempio Script per recuperare un grafico del servizio in base al nome del gruppo Example1

Esempio Script per ottenere i riepiloghi dei tracciamenti

Esempio GetTraceSummaries uscita

Esempio BatchGetTraces comando

Esempio BatchGetTraces uscita

Esempio Script per ottenere i tracciamenti completi per un periodo di un minuto

Esempio GetTraceSummaries di output: sezione relativa al tempo di risposta e alla causa principale

Esempio Causa principale del tempo di risposta riformattata

Esempio di filtro JSON

Impostazioni di crittografia

Nota

Esempio Input API per: UpdateSamplingRule10000-default.json

Esempio Input API per UpdateSamplingRule— 9000-base-scorekeep.json

Esempio Input API per UpdateSamplingRule— 5000-polling-scorekeep.json

Nota

Esempio Segmento completo minimale

Nota

Campi del segmento obbligatori

Formato ID di traccia X-Ray

Nota

Sicurezza dell'ID di tracciamento

Nomi dei servizi

Campi del segmento facoltativi

Valori supportati

Esempio Segmento con sottosegmento incorporato

Esempio Segmento in esecuzione

Esempio Sottosegmento indipendente

Nota

Campi del sottosegmento obbligatori

Formato ID di traccia X-Ray

Nota

Campi del sottosegmento facoltativi

http

Esempio Segmento per chiamata HTTP elaborata da un'applicazione in esecuzione su Amazon EC2

Esempio Sottosegmento per una chiamata HTTP a valle

Esempio Segmento dedotto per una chiamata HTTP a valle

Esempio Segmento per chiamata HTTP con annotazioni

Esempio Sottosegmento personalizzato con metadati

aws (Segmenti)

Esempio AWS blocco con plugin

aws (Sottosegmenti)

Esempio Sottosegmento per una chiamata a DynamoDB per salvare un elemento

tipi di errore

cause

exception

stackFrame

sql

Esempio Sottosegmento con una query SQL

Per usare lo script `test-api.sh`

Esempio Input API per: `UpdateSamplingRule`10000-default.json

Esempio Input API per `UpdateSamplingRule`— 9000-base-scorekeep.json

Esempio Input API per `UpdateSamplingRule`— 5000-polling-scorekeep.json

`http`

`aws` (Segmenti)

`aws` (Sottosegmenti)

`cause`

`exception`

`stackFrame`

`sql`