Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# Uso de la API de X-Ray
Si el SDK de X-Ray no es compatible con su lenguaje de programación, puede usar las API de X-Ray directamente o la AWS Command Line Interface (AWS CLI) para llamar a los comandos de la API de X-Ray. Emplee las siguientes directrices para escoger la forma de interactuar con la API:
+ Utilice la AWS CLI para simplificar la sintaxis mediante comandos preformateados o con opciones incluidas en su solicitud.
+ Utilice la API de X-Ray directamente para flexibilizar y personalizar al máximo las solicitudes que haga a X-Ray.
Si usa la [API de X-Ray](https://docs.aws.amazon.com/xray/latest/api/Welcome.html) directamente en lugar de la AWS CLI, deberá parametrizar la solicitud en el formato de datos correcto y es posible que también tenga que configurar la autenticación y la gestión de errores.
El siguiente diagrama muestra una guía para elegir cómo interactuar con la API de X-Ray:
![\[X-Ray muestra información detallada sobre las solicitudes de aplicaciones.\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/api-vs-cli.png)
Utilice la API de X-Ray para enviar datos de rastreo directamente a X-Ray. La API de X-Ray admite todas las funciones disponibles en el SDK de X-Ray, incluidas las siguientes acciones comunes:
+ [PutTraceSegments](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html): carga documentos de segmentos a X-Ray.
+ [BatchGetTraces](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html): recupera una lista de rastros en una lista de ID de rastros. Cada rastro recuperado es una recopilación de documentos de segmentos de una única solicitud.
+ [GetTraceSummaries](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html): recupera los ID y las anotaciones de los rastros. Puede especificar un `FilterExpression` para recuperar un subconjunto de resúmenes de rastreo.
+ [GetTraceGraph](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceGraph.html): recupera un gráfico de servicio para un ID de rastro específico.
+ [GetServiceGraph](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html): recupera un documento con formato JSON que describe los servicios que procesan las solicitudes entrantes y las solicitudes posteriores a la llamada.
También puede usar la AWS Command Line Interface (AWS CLI) dentro del código de su aplicación para interactuar mediante programación con X-Ray. La AWS CLI es compatible con todas las funciones disponibles en el SDK de X-Ray, incluidas las de otros Servicios de AWS. Las siguientes funciones son versiones de las operaciones de la API indicadas anteriormente, pero con un formato más simple:
+ [put-trace-segments](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/put-trace-segments.html): carga documentos de segmentos a X-Ray.
+ [batch-get-traces](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/batch-get-traces.html): recupera una lista de rastros en una lista de ID de rastros. Cada rastro recuperado es una recopilación de documentos de segmentos de una única solicitud.
+ [get-trace-summaries](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-trace-summaries.html): recupera los ID y las anotaciones de los rastros. Puede especificar un `FilterExpression` para recuperar un subconjunto de resúmenes de rastreo.
+ [get-trace-graph](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-trace-graph.html): recupera un gráfico de servicio para un ID de rastro específico.
+ [get-service-graph](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-service-graph.html): recupera un documento con formato `JSON` que describe los servicios que procesan las solicitudes entrantes y las solicitudes posteriores a la llamada.
Para empezar, debe instalar la [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) para su sistema operativo. AWS es compatible con sistemas operativos Linux, macOS y Windows. Para obtener más información sobre la lista de comandos de X-Ray, consulte la [AWS CLI Command Reference guide for X-Ray](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/index.html).
**Topics**
+ [Uso de la API de AWS X-Ray con la CLI de AWS](xray-api-tutorial.md)
+ [Envío de datos de rastreo a AWS X-Ray](xray-api-sendingdata.md)
+ [Obtención de datos de AWS X-Ray](xray-api-gettingdata.md)
+ [Configuración de los ajustes de muestreo, grupos y cifrado con la AWS X-Ray API](xray-api-configuration.md)
+ [Using sampling rules with the X-Ray API (Uso de reglas de muestreo con la API de X-Ray)](xray-api-sampling.md)
+ [AWS X-RayDocumentos de segmentos de](xray-api-segmentdocuments.md)
# Uso de la API de AWS X-Ray con la CLI de AWS
La interfaz de línea de comandos (CLI) de AWS le permite acceder al servicio de X-Ray directamente y utilizar las mismas API que la consola de X-Ray utiliza para recuperar los gráficos de servicios y los datos de rastro sin procesar. La aplicación de ejemplo incluye scripts que muestran cómo utilizar estas API con la CLI de AWS.
## Requisitos previos
Este tutorial utiliza la aplicación de ejemplo Scorekeep e incluye scripts para generar datos de rastreo y un mapa de servicio. Siga las instrucciones en el [tutorial de introducción](xray-gettingstarted.md) para iniciar la aplicación.
Este tutorial utiliza la AWS CLI para mostrar el uso básico de la API de X-Ray. La CLI de AWS, [disponible para Windows, Linux y OS-X](https://docs.aws.amazon.com/cli/latest/userguide/installing.html), proporciona acceso de línea de comandos a las API públicas de todos los Servicios de AWS.
**nota**
Debe verificar que la AWS CLI esté configurada en la misma región en la que se creó la aplicación de ejemplo Scorekeep.
Los scripts incluidos para probar la aplicación de ejemplo utiliza `cURL` para enviar tráfico a la API y `jq` para analizar la salida. Puede descargar el ejecutable de `jq` desde [stedolan.github.io](https://stedolan.github.io/jq/) y el ejecutable de `curl` desde [https://curl.haxx.se/download.html](https://curl.haxx.se/download.html). La mayoría de las instalaciones en Linux y OS X instalaciones incluyen cURL.
## Generación de datos de rastreo
La aplicación web sigue funcionando para generar tráfico a la API cada pocos segundos mientras que la instalación está en curso, pero solo genera un tipo de solicitud. Utilice el script `test-api.sh` para ejecutar escenarios de un extremo a otro y generar datos de rastreo más diversos mientras prueba la API.
**Para usar el script `test-api.sh`**
1. Abra la [consola de Elastic Beanstalk](https://console.aws.amazon.com/elasticbeanstalk).
1. Desplácese hasta la [consola de administración](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-console.html) del entorno.
1. Copie la **URL** del entorno del encabezado de la página.
1. Abra el script `bin/test-api.sh` y reemplace el valor de la API con el URL del entorno.
```
#!/bin/bash
API=scorekeep.9hbtbm23t2.us-west-2.elasticbeanstalk.com/api
```
1. Ejecute el script para generar tráfico a la 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"]}
```
## Uso de la API de X-Ray
La CLI de AWS proporciona comandos para todas las acciones de API que X-Ray ofrece, incluidos los comandos [https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html) y [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html). Consulte la [Referencia de la API de AWS X-Ray](https://docs.aws.amazon.com/xray/latest/api/Welcome.html) para obtener más información acerca de todas las acciones admitidas y los tipos de datos que utilizan.
**Example bin/service-graph.sh**
```
EPOCH=$(date +%s)
aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH
```
El script recupera un gráfico de servicios de los últimos 10 minutos.
```
~/eb-java-scorekeep$ ./bin/service-graph.sh | less
{
"StartTime": 1479068648.0,
"Services": [
{
"StartTime": 1479068648.0,
"ReferenceId": 0,
"State": "unknown",
"EndTime": 1479068651.0,
"Type": "client",
"Edges": [
{
"StartTime": 1479068648.0,
"ReferenceId": 1,
"SummaryStatistics": {
"ErrorStatistics": {
"ThrottleCount": 0,
"TotalCount": 0,
"OtherCount": 0
},
"FaultStatistics": {
"TotalCount": 0,
"OtherCount": 0
},
"TotalCount": 2,
"OkCount": 2,
"TotalResponseTime": 0.054000139236450195
},
"EndTime": 1479068651.0,
"Aliases": []
}
]
},
{
"StartTime": 1479068648.0,
"Names": [
"scorekeep.elasticbeanstalk.com"
],
"ReferenceId": 1,
"State": "active",
"EndTime": 1479068651.0,
"Root": true,
"Name": "scorekeep.elasticbeanstalk.com",
...
```
**Example bin/trace-urls.sh**
```
EPOCH=$(date +%s)
aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Http.HttpURL'
```
El script recupera las URL de rastros generados hace uno o dos minutos.
```
~/eb-java-scorekeep$ ./bin/trace-urls.sh
[
"http://scorekeep.elasticbeanstalk.com/api/game/6Q0UE1DG/5FGLM9U3/endtime/1479069438",
"http://scorekeep.elasticbeanstalk.com/api/session/KH4341QH",
"http://scorekeep.elasticbeanstalk.com/api/game/GLQBJ3K5/153AHDIA",
"http://scorekeep.elasticbeanstalk.com/api/game/VPDL672J/G2V41HM6/endtime/1479069466"
]
```
**Example bin/full-traces.sh**
```
EPOCH=$(date +%s)
TRACEIDS=$(aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Id' --output text)
aws xray batch-get-traces --trace-ids $TRACEIDS --query 'Traces[*]'
```
El script recupera los rastros completos generados hace uno o dos minutos.
```
~/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
}
...
```
## Eliminación
Finalice el entorno de Elastic Beanstalk para desactivar las instancias de Amazon EC2, las tablas de DynamoDB y otros recursos.
**Para terminar su entorno de Elastic Beanstalk**
1. Abra la [consola de Elastic Beanstalk](https://console.aws.amazon.com/elasticbeanstalk).
1. Desplácese hasta la [consola de administración](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-console.html) del entorno.
1. Elija **Acciones**.
1. Elija **Terminate Environment (Terminar entorno)**.
1. Elija **Finalizar**.
Los datos de rastro se eliminan automáticamente de X-Ray después de 30 días.
# Envío de datos de rastreo a AWS X-Ray
Puede enviar datos de rastro a X-Ray en forma de documentos de segmento. Un documento de segmento es una cadena con formato JSON que contiene información sobre el trabajo que su aplicación realiza en respuesta a una solicitud. La aplicación puede registrar en segmentos los datos sobre el trabajo que realiza o bien registrar en subsegmentos los datos sobre el trabajo que utiliza servicios y recursos posteriores.
Los segmentos contienen información sobre el trabajo que realiza su aplicación. Un segmento, como mínimo, registra el tiempo dedicado a una tarea, un nombre y dos IDs. El ID de rastro permite controlar la solicitud mientras va de un servicio a otro. El ID de segmento permite controlar el trabajo que realiza un único servicio para la solicitud.
**Example Segmento completo mínimo**
```
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0a",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"end_time" : 1.478293361449E9
}
```
Cuando se recibe una solicitud, puede enviar un segmento en curso como marcador hasta que se complete la solicitud.
**Example Segmento en curso**
```
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
“in_progress”: true
}
```
Puede enviar los segmentos a X-Ray directamente con [`PutTraceSegments`](#xray-api-segments) o [a través del daemon de X-Ray](#xray-api-daemon).
La mayoría de las aplicaciones llaman a otros servicios o acceden a recursos con el AWS SDK. Registre información acerca de las llamadas posteriores en *subsegmentos*. X-Ray utiliza subsegmentos para identificar los servicios posteriores que no envían segmentos y crean entradas para segmentos en el gráfico de servicios.
Un subsegmento puede incrustarse en un documento de segmentos completos o enviarse por separado. Envíe subsegmentos por separado para realizar un rastreo asíncrono de las llamadas posteriores para realizar solicitudes de larga ejecución o para evitar superar el tamaño máximo del documento de segmentos (64 kB).
**Example Subsegmento**
Un subsegmento tiene un `type` de `subsegment` y una `parent_id` que identifica el segmento de origen.
```
{
"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 obtener más información acerca de los campos y valores que puede incluir en los segmentos y subsegmentos, consulte [AWS X-RayDocumentos de segmentos de](xray-api-segmentdocuments.md).
**Topics**
+ [Generando rastreo IDs](#xray-api-traceids)
+ [Usando PutTraceSegments](#xray-api-segments)
+ [Envío de documentos de segmento al daemon de X-Ray](#xray-api-daemon)
## Generando rastreo IDs
Para enviar datos a X-Ray, debe generar un ID de rastro único para cada solicitud.
**Formato de ID de rastro de X-Ray**
Un `trace_id` de X-Ray consta de tres números separados por guiones. Por ejemplo, `1-58406520-a006649127e371903a2de979`. Esto incluye:
+ El número de versión, que es `1`.
+ La hora en que se realizó la solicitud original, en formato de tiempo Unix, en **8 dígitos hexadecimales**.
Por ejemplo, las 10:00 del 1 de diciembre de 2016, PST en formato de tiempo Unix es `1480615200` segundos o `58406520` en formato hexadecimal.
+ Un identificador 96 bits del rastro, único a nivel global, en **24 dígitos hexadecimales**.
**nota**
X-Ray ahora admite las trazas IDs que se crean utilizando OpenTelemetry y cualquier otro marco que cumpla con la especificación [Trace Context del W3C](https://www.w3.org/TR/trace-context/). Un ID de rastro conforme a la especificación de W3C debe estar formateado en el formato de ID de rastro de X-Ray cuando se envía a X-Ray. Por ejemplo, el ID de rastro `4efaaf4d1e8720b39541901950019ee5` conforme a la especificación de W3C debe tener el formato `1-4efaaf4d-1e8720b39541901950019ee5` cuando se envíe a X-Ray. El rastreo de rayos X IDs incluye la marca de tiempo de la solicitud original en Unix epoch Time, pero esto no es obligatorio cuando se envía el rastreo del W3C en IDs formato X-Ray.
Puede escribir un script para generar trazas de rayos X IDs para realizar pruebas. A continuación se incluyen dos ejemplos.
**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 la aplicación de ejemplo Scorekeep para ver los scripts que crean trazas IDs y envían segmentos al daemon X-Ray.
+ Python: [https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.py](https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.py)
+ Bash: [https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.sh](https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.sh)
## Usando PutTraceSegments
Puede cargar documentos de segmento con la API de [https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html). La API tiene un único parámetro, `TraceSegmentDocuments`, que obtiene una lista de documentos de segmento JSON.
Con la CLI de AWS, utilice el comando `aws xray put-trace-segments` para enviar documentos de segmento directamente 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**
El procesador de comandos de Windows y Windows PowerShell tienen requisitos diferentes para citar y escapar de las comillas en las cadenas JSON. Consulte [Entrecomillado de cadenas](https://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html#quoting-strings) en la Guía del usuario de la AWS CLI para obtener más información.
En la salida se indican los segmentos que no se han procesado correctamente; por ejemplo, si la fecha del ID de rastro es demasiado antigua, verá un error como el siguiente.
```
{
"UnprocessedTraceSegments": [
{
"ErrorCode": "InvalidTraceId",
"Message": "Invalid segment. ErrorCode: InvalidTraceId",
"Id": "6226467e3f845502"
}
]
}
```
Puede transferir varios documentos de segmento al mismo tiempo, separados por espacios.
```
$ aws xray put-trace-segments --trace-segment-documents "$DOC1" "$DOC2"
```
## Envío de documentos de segmento al daemon de X-Ray
En lugar de enviar documentos de segmento a la API de X-Ray, puede enviar segmentos y subsegmentos al daemon de X-Ray, que se encargará de almacenarlos en búfer y cargarlos en la API de X-Ray en lotes. El SDK de X-Ray envía documentos de segmento al daemon para evitar llamar directamente a AWS .
**nota**
Consulte [Ejecución del daemon de X-Ray localmente](xray-daemon-local.md) para obtener instrucciones sobre cómo ejecutar el demonio.
Envíe el segmento en formato JSON a través del puerto UDP 2000, anteponiéndole el encabezado del demonio, `{"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"}
```
En Linux, puede enviar documentos de segmento al demonio desde un terminal Bash. Guarde el encabezado y el documento de segmento en un archivo de texto y envíelo a `/dev/udp` con `cat`.
```
$ cat segment.txt > /dev/udp/127.0.0.1/2000
```
**Example segment.txt**
```
{"format": "json", "version": 1}
{"trace_id": "1-594aed87-ad72e26896b3f9d3a27054bb", "id": "6226467e3f845502", "start_time": 1498082657.37518, "end_time": 1498082695.4042, "name": "test.elasticbeanstalk.com"}
```
Consulte el [registro del daemon](xray-daemon.md#xray-daemon-logging) para comprobar que ha enviado el 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)
```
# Obtención de datos de AWS X-Ray
AWS X-Ray procesa los datos de rastreo que usted le envía para generar registros de seguimiento completos, resúmenes de registros de seguimiento y gráficos de servicios en JSON. Puede recuperar los datos generados directamente desde la API con la CLI de AWS.
**Topics**
+ [Recuperación del gráfico de servicios](#xray-api-servicegraph)
+ [Recuperación del gráfico de servicios por grupo](#xray-api-servicegraphgroup)
+ [Recuperación de registros de seguimiento](#xray-api-traces)
+ [Recuperación y ajuste de las causas raíz de Analytics](#xray-api-analytics)
## Recuperación del gráfico de servicios
Puede utilizar la API de [https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html) para recuperar el gráfico de servicios de JSON. La API requiere una hora de inicio y de finalización, que se puede calcular a partir de un terminal de Linux con el comando `date`.
```
$ date +%s
1499394617
```
`date +%s` imprime una fecha en cuestión de segundos. Utilice este número como hora de finalización y réstele el tiempo para obtener una hora de inicio.
**Example Script para recuperar un gráfico de servicios de los últimos 10 minutos**
```
EPOCH=$(date +%s)
aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH
```
En el siguiente ejemplo, se muestra un gráfico de servicio con cuatro nodos que incluye un nodo cliente, una instancia de EC2, una tabla de DynamoDB y un tema de Amazon SNS.
**Example Salida de GetServiceGraph**
```
{
"Services": [
{
"ReferenceId": 0,
"Name": "xray-sample.elasticbeanstalk.com",
"Names": [
"xray-sample.elasticbeanstalk.com"
],
"Type": "client",
"State": "unknown",
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"Edges": [
{
"ReferenceId": 2,
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"SummaryStatistics": {
"OkCount": 3,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 1,
"TotalCount": 1
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 4,
"TotalResponseTime": 0.273
},
"ResponseTimeHistogram": [
{
"Value": 0.005,
"Count": 1
},
{
"Value": 0.015,
"Count": 1
},
{
"Value": 0.157,
"Count": 1
},
{
"Value": 0.096,
"Count": 1
}
],
"Aliases": []
}
]
},
{
"ReferenceId": 1,
"Name": "awseb-e-dixzws4s9p-stack-StartupSignupsTable-4IMSMHAYX2BA",
"Names": [
"awseb-e-dixzws4s9p-stack-StartupSignupsTable-4IMSMHAYX2BA"
],
"Type": "AWS::DynamoDB::Table",
"State": "unknown",
"StartTime": 1528317583.0,
"EndTime": 1528317589.0,
"Edges": [],
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.12
},
"DurationHistogram": [
{
"Value": 0.076,
"Count": 1
},
{
"Value": 0.044,
"Count": 1
}
],
"ResponseTimeHistogram": [
{
"Value": 0.076,
"Count": 1
},
{
"Value": 0.044,
"Count": 1
}
]
},
{
"ReferenceId": 2,
"Name": "xray-sample.elasticbeanstalk.com",
"Names": [
"xray-sample.elasticbeanstalk.com"
],
"Root": true,
"Type": "AWS::EC2::Instance",
"State": "active",
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"Edges": [
{
"ReferenceId": 1,
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.12
},
"ResponseTimeHistogram": [
{
"Value": 0.076,
"Count": 1
},
{
"Value": 0.044,
"Count": 1
}
],
"Aliases": []
},
{
"ReferenceId": 3,
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.125
},
"ResponseTimeHistogram": [
{
"Value": 0.049,
"Count": 1
},
{
"Value": 0.076,
"Count": 1
}
],
"Aliases": []
}
],
"SummaryStatistics": {
"OkCount": 3,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 1,
"TotalCount": 1
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 4,
"TotalResponseTime": 0.273
},
"DurationHistogram": [
{
"Value": 0.005,
"Count": 1
},
{
"Value": 0.015,
"Count": 1
},
{
"Value": 0.157,
"Count": 1
},
{
"Value": 0.096,
"Count": 1
}
],
"ResponseTimeHistogram": [
{
"Value": 0.005,
"Count": 1
},
{
"Value": 0.015,
"Count": 1
},
{
"Value": 0.157,
"Count": 1
},
{
"Value": 0.096,
"Count": 1
}
]
},
{
"ReferenceId": 3,
"Name": "SNS",
"Names": [
"SNS"
],
"Type": "AWS::SNS",
"State": "unknown",
"StartTime": 1528317583.0,
"EndTime": 1528317589.0,
"Edges": [],
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.125
},
"DurationHistogram": [
{
"Value": 0.049,
"Count": 1
},
{
"Value": 0.076,
"Count": 1
}
],
"ResponseTimeHistogram": [
{
"Value": 0.049,
"Count": 1
},
{
"Value": 0.076,
"Count": 1
}
]
}
]
}
```
## Recuperación del gráfico de servicios por grupo
Para obtener un gráfico de servicios en función del contenido de un grupo, incluya un `groupName` o `groupARN`. En el ejemplo siguiente, se muestra una llamada a un gráfico de servicios para un grupo denominado Example1.
**Example Script para recuperar un gráfico de servicios por nombre para el grupo Example1**
```
aws xray get-service-graph --group-name "Example1"
```
## Recuperación de registros de seguimiento
Puede utilizar la API de [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) para obtener una lista de resúmenes de rastros. Estos resúmenes incluyen información que puede utilizar para identificar los registros de seguimiento que desee descargar en su totalidad, y que incluyen anotaciones, información de solicitud y respuesta e identificadores.
Existen dos indicadores `TimeRangeType` disponibles al llamar `aws xray get-trace-summaries`:
+ **TraceId**: la búsqueda predeterminada con `GetTraceSummaries` utiliza el tiempo de TraceID y devuelve los registros de seguimiento iniciados dentro del intervalo `[start_time, end_time)` calculado. Este rango de marcas de tiempo se calcula en función de la codificación de la marca de tiempo en TraceId o se puede definir de forma manual.
+ **Hora del evento**: para buscar eventos a medida que ocurren a lo largo del tiempo, AWS X-Ray permite buscar registros de seguimiento mediante marcas de tiempo de eventos. El tiempo de evento devuelve registros de seguimiento activos durante el intervalo `[start_time, end_time)`, independientemente del cuándo se inició el seguimiento.
Utilice el comando `aws xray get-trace-summaries` para obtener una lista de resúmenes de registros de seguimiento. Los siguientes comandos le permiten obtener una lista de resúmenes de registros de seguimiento con una antigüedad de entre 1 y 2 minutos mediante el tiempo predeterminado de TraceId.
**Example Script para obtener resúmenes de rastreo**
```
EPOCH=$(date +%s)
aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60))
```
**Example Salida de GetTraceSummaries**
```
{
"TraceSummaries": [
{
"HasError": false,
"Http": {
"HttpStatus": 200,
"ClientIp": "205.255.255.183",
"HttpURL": "http://scorekeep.elasticbeanstalk.com/api/session",
"UserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36",
"HttpMethod": "POST"
},
"Users": [],
"HasFault": false,
"Annotations": {},
"ResponseTime": 0.084,
"Duration": 0.084,
"Id": "1-59602606-a43a1ac52fc7ee0eea12a82c",
"HasThrottle": false
},
{
"HasError": false,
"Http": {
"HttpStatus": 200,
"ClientIp": "205.255.255.183",
"HttpURL": "http://scorekeep.elasticbeanstalk.com/api/user",
"UserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36",
"HttpMethod": "POST"
},
"Users": [
{
"UserName": "5M388M1E"
}
],
"HasFault": false,
"Annotations": {
"UserID": [
{
"AnnotationValue": {
"StringValue": "5M388M1E"
}
}
],
"Name": [
{
"AnnotationValue": {
"StringValue": "Ola"
}
}
]
},
"ResponseTime": 3.232,
"Duration": 3.232,
"Id": "1-59602603-23fc5b688855d396af79b496",
"HasThrottle": false
}
],
"ApproximateTime": 1499473304.0,
"TracesProcessedCount": 2
}
```
Utilice el ID de rastro del resultado para recuperar un registro de seguimiento completo con la API de [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html).
**Example Comando BatchGetTraces**
```
$ aws xray batch-get-traces --trace-ids 1-596025b4-7170afe49f7aa708b1dd4a6b
```
**Example Salida de BatchGetTraces**
```
{
"Traces": [
{
"Duration": 3.232,
"Segments": [
{
"Document": "{\"id\":\"1fb07842d944e714\",\"name\":\"random-name\",\"start_time\":1.499473411677E9,\"end_time\":1.499473414572E9,\"parent_id\":\"0c544c1b1bbff948\",\"http\":{\"response\":{\"status\":200}},\"aws\":{\"request_id\":\"ac086670-6373-11e7-a174-f31b3397f190\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::Lambda\",\"resource_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\"}",
"Id": "1fb07842d944e714"
},
{
"Document": "{\"id\":\"194fcc8747581230\",\"name\":\"Scorekeep\",\"start_time\":1.499473411562E9,\"end_time\":1.499473414794E9,\"http\":{\"request\":{\"url\":\"http://scorekeep.elasticbeanstalk.com/api/user\",\"method\":\"POST\",\"user_agent\":\"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36\",\"client_ip\":\"205.251.233.183\"},\"response\":{\"status\":200}},\"aws\":{\"elastic_beanstalk\":{\"version_label\":\"app-abb9-170708_002045\",\"deployment_id\":406,\"environment_name\":\"scorekeep-dev\"},\"ec2\":{\"availability_zone\":\"us-west-2c\",\"instance_id\":\"i-0cd9e448944061b4a\"},\"xray\":{\"sdk_version\":\"1.1.2\",\"sdk\":\"X-Ray for Java\"}},\"service\":{},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"user\":\"5M388M1E\",\"origin\":\"AWS::ElasticBeanstalk::Environment\",\"subsegments\":[{\"id\":\"0c544c1b1bbff948\",\"name\":\"Lambda\",\"start_time\":1.499473411629E9,\"end_time\":1.499473414572E9,\"http\":{\"response\":{\"status\":200,\"content_length\":14}},\"aws\":{\"log_type\":\"None\",\"status_code\":200,\"function_name\":\"random-name\",\"invocation_type\":\"RequestResponse\",\"operation\":\"Invoke\",\"request_id\":\"ac086670-6373-11e7-a174-f31b3397f190\",\"resource_names\":[\"random-name\"]},\"namespace\":\"aws\"},{\"id\":\"071684f2e555e571\",\"name\":\"## UserModel.saveUser\",\"start_time\":1.499473414581E9,\"end_time\":1.499473414769E9,\"metadata\":{\"debug\":{\"test\":\"Metadata string from UserModel.saveUser\"}},\"subsegments\":[{\"id\":\"4cd3f10b76c624b4\",\"name\":\"DynamoDB\",\"start_time\":1.49947341469E9,\"end_time\":1.499473414769E9,\"http\":{\"response\":{\"status\":200,\"content_length\":57}},\"aws\":{\"table_name\":\"scorekeep-user\",\"operation\":\"UpdateItem\",\"request_id\":\"MFQ8CGJ3JTDDVVVASUAAJGQ6NJ82F738BOB4KQNSO5AEMVJF66Q9\",\"resource_names\":[\"scorekeep-user\"]},\"namespace\":\"aws\"}]}]}",
"Id": "194fcc8747581230"
},
{
"Document": "{\"id\":\"00f91aa01f4984fd\",\"name\":\"random-name\",\"start_time\":1.49947341283E9,\"end_time\":1.49947341457E9,\"parent_id\":\"1fb07842d944e714\",\"aws\":{\"function_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\",\"resource_names\":[\"random-name\"],\"account_id\":\"123456789012\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::Lambda::Function\",\"subsegments\":[{\"id\":\"e6d2fe619f827804\",\"name\":\"annotations\",\"start_time\":1.499473413012E9,\"end_time\":1.499473413069E9,\"annotations\":{\"UserID\":\"5M388M1E\",\"Name\":\"Ola\"}},{\"id\":\"b29b548af4d54a0f\",\"name\":\"SNS\",\"start_time\":1.499473413112E9,\"end_time\":1.499473414071E9,\"http\":{\"response\":{\"status\":200}},\"aws\":{\"operation\":\"Publish\",\"region\":\"us-west-2\",\"request_id\":\"a2137970-f6fc-5029-83e8-28aadeb99198\",\"retries\":0,\"topic_arn\":\"arn:aws:sns:us-west-2:123456789012:awseb-e-ruag3jyweb-stack-NotificationTopic-6B829NT9V5O9\"},\"namespace\":\"aws\"},{\"id\":\"2279c0030c955e52\",\"name\":\"Initialization\",\"start_time\":1.499473412064E9,\"end_time\":1.499473412819E9,\"aws\":{\"function_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\"}}]}",
"Id": "00f91aa01f4984fd"
},
{
"Document": "{\"id\":\"17ba309b32c7fbaf\",\"name\":\"DynamoDB\",\"start_time\":1.49947341469E9,\"end_time\":1.499473414769E9,\"parent_id\":\"4cd3f10b76c624b4\",\"inferred\":true,\"http\":{\"response\":{\"status\":200,\"content_length\":57}},\"aws\":{\"table_name\":\"scorekeep-user\",\"operation\":\"UpdateItem\",\"request_id\":\"MFQ8CGJ3JTDDVVVASUAAJGQ6NJ82F738BOB4KQNSO5AEMVJF66Q9\",\"resource_names\":[\"scorekeep-user\"]},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::DynamoDB::Table\"}",
"Id": "17ba309b32c7fbaf"
},
{
"Document": "{\"id\":\"1ee3c4a523f89ca5\",\"name\":\"SNS\",\"start_time\":1.499473413112E9,\"end_time\":1.499473414071E9,\"parent_id\":\"b29b548af4d54a0f\",\"inferred\":true,\"http\":{\"response\":{\"status\":200}},\"aws\":{\"operation\":\"Publish\",\"region\":\"us-west-2\",\"request_id\":\"a2137970-f6fc-5029-83e8-28aadeb99198\",\"retries\":0,\"topic_arn\":\"arn:aws:sns:us-west-2:123456789012:awseb-e-ruag3jyweb-stack-NotificationTopic-6B829NT9V5O9\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::SNS\"}",
"Id": "1ee3c4a523f89ca5"
}
],
"Id": "1-59602603-23fc5b688855d396af79b496"
}
],
"UnprocessedTraceIds": []
}
```
El registro de seguimiento completo incluye un documento para cada segmento, compilado a partir de todos los documentos de segmento recibidos que tienen el mismo ID de registro de seguimiento. Estos documentos no representan los datos tal y como la aplicación se los envió a X-Ray, sino que representan los documentos procesados generados por el servicio de X-Ray. X-Ray crea el documento de rastro completo compilando los documentos de segmento que envía la aplicación, y eliminando los datos que no se ajustan al [esquema de documentos de segmento](xray-api-segmentdocuments.md).
X-Ray también crea *segmentos inferidos* para las llamadas posteriores a los servicios que no envían los segmentos propiamente dichos. Por ejemplo, si llama a DynamoDB con un cliente instrumentado, el SDK de X-Ray registra un subsegmento con detalles sobre la llamada desde su punto de vista, pero no envía el segmento correspondiente. X-Ray utiliza la información del subsegmento con el fin de crear un segmento inferido para representar el recurso de DynamoDB en el mapa de rastros y lo añade al documento de rastro.
Para obtener varios registros de seguimiento desde la API, se necesita una lista de ID de registros de seguimiento, que se puede extraer de la salida de `get-trace-summaries` con una [consulta de la AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/controlling-output.html#controlling-output-filter). Redirija la lista a la entrada de `batch-get-traces` para obtener registros de seguimiento completos de un período específico.
**Example Script para obtener registros de seguimiento completos de un período de 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[*]'
```
## Recuperación y ajuste de las causas raíz de Analytics
Al generar un resumen de registros de seguimiento con la API [GetTraceSummaries](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html). se pueden reutilizar los resúmenes de rastros parciales en formato JSON para crear una expresión de filtro más precisa en función de las causas raíz. Consulte los ejemplos que aparecen a continuación para ver el procedimiento de ajuste.
**Example Ejemplo de salida de GetTraceSummaries: sección de causa raíz de tiempo de respuesta**
```
{
"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
}
]
}
]
}
```
Al editar y crear omisiones en la salida anterior, este JSON puede actuar de filtro para las entidades de causa raíz coincidentes. Para cada campo presente en el JSON, todas las coincidencias candidatas deben ser exactas o no se devolverá el registro de seguimiento. Los campos eliminados se convierten en valores comodín, un formato que es compatible con la estructura de consultas de expresión de filtro.
**Example Causa raíz de tiempo de respuesta reformateado**
```
{
"Services": [
{
"Name": "GetWeatherData",
"EntityPath": [
{
"Name": "GetWeatherData"
},
{
"Name": "get_temperature"
}
]
},
{
"Name": "GetTemperature",
"EntityPath": [
{
"Name": "GetTemperature"
}
]
}
]
}
```
Este JSON se utiliza como parte de una expresión de filtro a través de una llamada a `rootcause.json = #[{}]`. Consulte el capítulo [Expresiones de filtro](xray-console-filters.md) para obtener más información sobre cómo ejecutar consultas con expresiones de filtro.
**Example Ejemplo de filtro JSON**
```
rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]
```
# Configuración de los ajustes de muestreo, grupos y cifrado con la AWS X-Ray API
AWS X-Ray permite configurar APIs las [reglas de muestreo, las](xray-console-sampling.md) reglas de grupo y los [ajustes de cifrado](xray-console-encryption.md).
**Topics**
+ [Configuración de cifrado](#xray-api-configuration-encryption)
+ [Reglas de muestreo](#xray-api-configuration-sampling)
+ [Groups](#xray-api-configuration-groups)
## Configuración de cifrado
Se utiliza [https://docs.aws.amazon.com/xray/latest/api/API_PutEncryptionConfig.html](https://docs.aws.amazon.com/xray/latest/api/API_PutEncryptionConfig.html)para especificar una clave AWS Key Management Service (AWS KMS) que se utilizará para el cifrado.
**nota**
X-Ray no es compatible con claves de KMS asimétricas.
```
$ aws xray put-encryption-config --type KMS --key-id alias/aws/xray
{
"EncryptionConfig": {
"KeyId": "arn:aws:kms:us-east-2:123456789012:key/c234g4e8-39e9-4gb0-84e2-b0ea215cbba5",
"Status": "UPDATING",
"Type": "KMS"
}
}
```
Para el ID de clave, puede utilizar un alias (tal y como se muestra en el ejemplo), un ID de clave o un nombre de recurso de Amazon (ARN).
Utilice [https://docs.aws.amazon.com/xray/latest/api/API_GetEncryptionConfig.html](https://docs.aws.amazon.com/xray/latest/api/API_GetEncryptionConfig.html) para obtener la configuración actual. Cuando X-Ray termina de aplicar la configuración, el estado cambia de `UPDATING` a `ACTIVE`.
```
$ aws xray get-encryption-config
{
"EncryptionConfig": {
"KeyId": "arn:aws:kms:us-east-2:123456789012:key/c234g4e8-39e9-4gb0-84e2-b0ea215cbba5",
"Status": "ACTIVE",
"Type": "KMS"
}
}
```
Para dejar de usar una clave de KMS y utilizar el cifrado predeterminado, establezca el tipo de cifrado en `NONE`.
```
$ aws xray put-encryption-config --type NONE
{
"EncryptionConfig": {
"Status": "UPDATING",
"Type": "NONE"
}
}
```
## Reglas de muestreo
Puede administrar las [reglas de muestreo](xray-console-sampling.md) en su cuenta con la API de X-Ray. Para obtener más información acerca de cómo añadir y administrar etiquetas, consulte [Etiquetado de reglas de muestreo y grupos de X-Ray](xray-tagging.md).
Obtener todas las reglas de muestreo con [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html).
```
$ aws xray get-sampling-rules
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-2:123456789012:sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.05,
"ReservoirSize": 1,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1529959993.0
}
]
}
```
La regla predeterminada se aplica a todas las solicitudes que no coinciden con otra regla. Es la regla con prioridad más baja y no se puede eliminar. Sin embargo, puede cambiar el porcentaje y el tamaño de depósito con [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html).
**Example Entrada de la API para [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html) – 10000-default.json**
```
{
"SamplingRuleUpdate": {
"RuleName": "Default",
"FixedRate": 0.01,
"ReservoirSize": 0
}
}
```
En el siguiente ejemplo se utiliza el archivo anterior como entrada para cambiar la regla predeterminada a uno por ciento sin depósito. Las etiquetas son opcionales. Si decide añadir etiquetas, tenga en cuenta que le hará falta una clave de etiqueta y que los valores de etiqueta son opcionales. Para eliminar las etiquetas existentes de una regla de muestreo, utilice [UntagResource](https://docs.aws.amazon.com/xray/latest/api/API_UntagResource.html)
```
$ aws xray update-sampling-rule --cli-input-json file://1000-default.json --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-2:123456789012:sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.01,
"ReservoirSize": 0,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1529959993.0
},
```
Crear reglas de muestreo adicionales con [https://docs.aws.amazon.com/xray/latest/api/API_CreateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_CreateSamplingRule.html). Al crear una regla, la mayoría de los campos de la regla son obligatorios. En el siguiente ejemplo se crean dos reglas. Esta primera regla establece un porcentaje de base para la aplicación de ejemplo Scorekeep. Empareja todas las solicitudes servidas por la API que no coinciden con una regla de prioridad superior.
**Example Entrada de la API para [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html) – 9000-base-scorekeep.json**
```
{
"SamplingRule": {
"RuleName": "base-scorekeep",
"ResourceARN": "*",
"Priority": 9000,
"FixedRate": 0.1,
"ReservoirSize": 5,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1
}
}
```
La segunda regla también se aplica a Scorekeep, pero tiene una prioridad mayor y es más específica. Esta regla establece un porcentaje de muestreo muy bajo para las solicitudes de sondeo. Estas son las solicitudes GET realizadas por el cliente cada pocos segundos para comprobar si hay cambios en el estado del juego.
**Example Entrada de la API para [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html) – 5000-polling-scorekeep.json**
```
{
"SamplingRule": {
"RuleName": "polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1
}
}
```
Las etiquetas son opcionales. Si decide añadir etiquetas, tenga en cuenta que le hará falta una clave de etiqueta y que los valores de etiqueta son opcionales.
```
$ aws xray create-sampling-rule --cli-input-json file://5000-polling-scorekeep.json --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574399.0,
"ModifiedAt": 1530574399.0
}
}
$ aws xray create-sampling-rule --cli-input-json file://9000-base-scorekeep.json
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "base-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/base-scorekeep",
"ResourceARN": "*",
"Priority": 9000,
"FixedRate": 0.1,
"ReservoirSize": 5,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574410.0,
"ModifiedAt": 1530574410.0
}
}
```
Para eliminar una regla de muestreo, utilice [https://docs.aws.amazon.com/xray/latest/api/API_DeleteSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_DeleteSamplingRule.html).
```
$ aws xray delete-sampling-rule --rule-name polling-scorekeep
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574399.0,
"ModifiedAt": 1530574399.0
}
}
```
## Groups
Puede utilizar la API de X-Ray para administrar los grupos de su cuenta. Los grupos son una colección de rastros que se definen mediante una expresión de filtro. Puedes usar grupos para generar gráficos de servicios adicionales y proporcionar CloudWatch métricas de Amazon. Consulte [Obtención de datos de AWS X-Ray](xray-api-gettingdata.md) para obtener más detalles sobre cómo utilizar las métricas y los gráficos de servicios mediante la API de X-Ray. Para obtener más información acerca de los grupos, consulte [Configuración de grupos](xray-console-groups.md). Para obtener más información acerca de cómo añadir y administrar etiquetas, consulte [Etiquetado de reglas de muestreo y grupos de X-Ray](xray-tagging.md).
Utilice `CreateGroup` para crear un grupo. Las etiquetas son opcionales. Si decide añadir etiquetas, tenga en cuenta que le hará falta una clave de etiqueta y que los valores de etiqueta son opcionales.
```
$ 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}"
}
```
Utilice `GetGroups` para obtener todos los grupos existentes.
```
$ 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"
}
```
Utilice `UpdateGroup` para actualizar un grupo. Las etiquetas son opcionales. Si decide añadir etiquetas, tenga en cuenta que le hará falta una clave de etiqueta y que los valores de etiqueta son opcionales. Para eliminar las etiquetas existentes de un grupo, usa [UntagResource](https://docs.aws.amazon.com/xray/latest/api/API_UntagResource.html).
```
$ aws xray update-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID" --filter-expression "service(\"example.com\") {fault OR error}" --tags [{"Key": "Stage","Value": "Prod"},{"Key": "Department","Value": "QA"}]
{
"GroupName": "TestGroup",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
"FilterExpression": "service(\"example.com\") {fault OR error}"
}
```
Utilice `DeleteGroup` para eliminar un grupo.
```
$ aws xray delete-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID"
{
}
```
# Using sampling rules with the X-Ray API (Uso de reglas de muestreo con la API de X-Ray)
El SDK de AWS X-Ray utiliza la API de X-Ray para obtener reglas de muestreo, notificar resultados de muestreo y obtener las cuotas. Puede utilizar estas API para entender mejor cómo funcionan las reglas de muestreo o para implementar muestras en un lenguaje que el SDK de X-Ray no admita.
Comience por obtener todas las reglas de muestreo con [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html).
```
$ aws xray get-sampling-rules
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.01,
"ReservoirSize": 0,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1530558121.0
},
{
"SamplingRule": {
"RuleName": "base-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/base-scorekeep",
"ResourceARN": "*",
"Priority": 9000,
"FixedRate": 0.1,
"ReservoirSize": 2,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530573954.0,
"ModifiedAt": 1530920505.0
},
{
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530918163.0,
"ModifiedAt": 1530918163.0
}
]
}
```
El resultado incluye la regla predeterminada y las reglas personalizadas. Consulte [Reglas de muestreo](xray-api-configuration.md#xray-api-configuration-sampling) si aún no ha creado reglas de muestreo.
Evalúe las reglas frente a las solicitudes entrantes en orden de prioridad ascendente. Cuando una regla coincida, utilice el porcentaje fijo y el tamaño de depósito para tomar una decisión de muestreo. Registre solicitudes muestreadas y pase por alto (para fines de rastreo) las solicitudes sin muestrear. Deje de evaluar las reglas cuando tome una decisión de muestreo.
El tamaño de un depósito de reglas es el número objetivo de rastreos que registrar por segundo antes de aplicar el porcentaje fijo. El depósito se aplica en todos los servicios acumulativamente, por lo que no se puede utilizar directamente. Sin embargo, si es distinto de cero, podrá tomar prestado un rastro por segundo desde el depósito hasta que X-Ray asigne una cuota. Antes de recibir una cuota, registre la primera solicitud cada segundo y aplique el porcentaje fijo a las solicitudes adicionales. El porcentaje fijo es un número decimal entre 0 y 1,00 (100 %).
El siguiente ejemplo muestra una llamada a [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html) con información detallada sobre las decisiones de muestreo tomadas durante los últimos 10 segundos.
```
$ aws xray get-sampling-targets --sampling-statistics-documents '[
{
"RuleName": "base-scorekeep",
"ClientID": "ABCDEF1234567890ABCDEF10",
"Timestamp": "2018-07-07T00:20:06",
"RequestCount": 110,
"SampledCount": 20,
"BorrowCount": 10
},
{
"RuleName": "polling-scorekeep",
"ClientID": "ABCDEF1234567890ABCDEF10",
"Timestamp": "2018-07-07T00:20:06",
"RequestCount": 10500,
"SampledCount": 31,
"BorrowCount": 0
}
]'
{
"SamplingTargetDocuments": [
{
"RuleName": "base-scorekeep",
"FixedRate": 0.1,
"ReservoirQuota": 2,
"ReservoirQuotaTTL": 1530923107.0,
"Interval": 10
},
{
"RuleName": "polling-scorekeep",
"FixedRate": 0.003,
"ReservoirQuota": 0,
"ReservoirQuotaTTL": 1530923107.0,
"Interval": 10
}
],
"LastRuleModification": 1530920505.0,
"UnprocessedStatistics": []
}
```
La respuesta de X-Ray incluye una cuota que utilizar en lugar de tomarla prestada del depósito. En este ejemplo, el servicio ha tomado prestados 10 rastros desde el depósito en 10 segundos y ha aplicado el porcentaje fijo del 10 por ciento a las otras 100 solicitudes, lo que se traduce en un total de 20 solicitudes muestreadas. La cuota es buena durante cinco minutos (que se indica mediante el tiempo de vida) o hasta que se asigna una nueva cuota. X-Ray también podría asignar un intervalo de informes más largo que el predeterminado, aunque no aquí.
**nota**
La respuesta de X-Ray podría no incluir una cuota la primera vez que llama. Continue tomando prestado del depósito hasta que se les asigne una cuota.
Los otros dos campos de la respuesta podrían indicar problemas con la entrada. Compruebe `LastRuleModification` respecto a la última vez que llamó a [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html). Si es más reciente, obtenga una nueva copia de las reglas. `UnprocessedStatistics` puede incluir errores que indican que una regla se ha eliminado, que el documento de estadísticas en la entrada era demasiado antiguo o errores de permisos.
# AWS X-RayDocumentos de segmentos de
Un **segmento de rastreo** es una representación JSON de una solicitud que atiende su aplicación. Un segmento de rastro registra información sobre la solicitud original, información sobre el trabajo que su aplicación realiza localmente y **subsegmentos** con información sobre las llamadas posteriores que su aplicación realiza a los recursos de AWS, las API HTTP y las bases de datos SQL.
Un **documento de segmento** transmite información sobre un segmento a X-Ray. Un documento de segmento puede tener un tamaño de hasta 64 kB y contener un segmento completo con subsegmentos, un fragmento de un segmento que indique que una solicitud está en curso o un único subsegmento que se envía por separado. Puede enviar documentos de segmento directamente a X-Ray mediante la API de [https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html).
X-Ray compila y procesa los documentos de segmento para generar **resúmenes de rastros** y **rastros completos** que admiten consultas a los que puede obtener acceso mediante las API de [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) y [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html), respectivamente. Además de los segmentos y subsegmentos que envía a X-Ray, el servicio utiliza la información de los subsegmentos para generar **segmentos inferidos**, que se añaden al rastro completo. Los segmentos inferidos representan servicios y recursos posteriores en el mapa de rastros.
X-Ray proporciona un **esquema JSON** para los documentos de segmento. Puede descargar el esquema aquí: [xray-segmentdocument-schema-v1.0.0](samples/xray-segmentdocument-schema-v1.0.0.zip). Los campos y objetos incluidos en el esquema se describen con más detalle en las secciones siguientes.
X-Ray indexa un subconjunto de los campos de segmento para su uso con expresiones de filtro. Por ejemplo, si establece el campo `user` de un segmento en un identificador único, puede buscar los segmentos asociados a usuarios específicos en la consola de X-Ray o mediante la API de `GetTraceSummaries`. Para obtener más información, consulte [Uso de expresiones de filtro](xray-console-filters.md).
Cuando instrumente su aplicación con el SDK de X-Ray, el SDK generará automáticamente los documentos de segmento. En lugar de enviar documentos directamente a X-Ray, el SDK los transmite a través de un puerto UDP local al [daemon de X-Ray](xray-daemon.md). Para obtener más información, consulte [Envío de documentos de segmento al daemon de X-Ray](xray-api-sendingdata.md#xray-api-daemon).
**Topics**
+ [Campos de segmentos](#api-segmentdocuments-fields)
+ [Subsegmentos](#api-segmentdocuments-subsegments)
+ [Datos de solicitudes HTTP](#api-segmentdocuments-http)
+ [Anotaciones](#api-segmentdocuments-annotations)
+ [Metadatos](#api-segmentdocuments-metadata)
+ [Datos de recursos de AWS](#api-segmentdocuments-aws)
+ [Errores y excepciones](#api-segmentdocuments-errors)
+ [Consultas SQL](#api-segmentdocuments-sql)
## Campos de segmentos
Un segmento registra información de rastreo sobre una solicitud que atiende su aplicación. Como mínimo, un segmento registra el nombre, ID, hora de inicio, ID de rastro y el tiempo total de la solicitud.
**Example Segmento completo mínimo**
```
{
"name" : "example.com",
"id" : "70de5b6f19ff9a0a",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"end_time" : 1.478293361449E9
}
```
Los siguientes campos son obligatorios o necesarios en determinadas circunstancias para los segmentos.
**nota**
Los valores deben ser cadenas (de hasta 250 caracteres), a menos que se indique lo contrario.
**Campos de segmentos obligatorios**
+ `name`: nombre lógico del servicio que gestiona la solicitud (hasta **200 caracteres**). Por ejemplo, el nombre de su aplicación o el nombre de dominio. Los nombres pueden contener letras Unicode, números y espacios en blanco, así como los siguientes símbolos: `_`, `.`, `:`, `/`, `%`, `&`, `#`, `=`, `+`, `\`, `-`, `@`
+ `id`: un identificador de 64 bits para el segmento, único entre otros segmentos del mismo rastro, en **16 dígitos hexadecimales**.
+ `trace_id`: un identificador único que conecta todos los segmentos y subsegmentos procedentes de una única solicitud de cliente.
**Formato de ID de rastro de X-Ray**
Un `trace_id` de X-Ray consta de tres números separados por guiones. Por ejemplo, `1-58406520-a006649127e371903a2de979`. Esto incluye:
+ El número de versión, que es `1`.
+ La hora en que se realizó la solicitud original, en formato de tiempo Unix, en **8 dígitos hexadecimales**.
Por ejemplo, las 10:00 del 1 de diciembre de 2016, PST en formato de tiempo Unix es `1480615200` segundos o `58406520` en formato hexadecimal.
+ Un identificador 96 bits del rastro, único a nivel global, en **24 dígitos hexadecimales**.
**nota**
Ahora X-Ray admite ID de rastro creados mediante OpenTelemetry o cualquier otro marco que se ajuste a la [especificación Trace Context de W3C](https://www.w3.org/TR/trace-context/). Un ID de rastro conforme a la especificación de W3C debe estar formateado en el formato de ID de rastro de X-Ray cuando se envía a X-Ray. Por ejemplo, el ID de rastro `4efaaf4d1e8720b39541901950019ee5` conforme a la especificación de W3C debe tener el formato `1-4efaaf4d-1e8720b39541901950019ee5` cuando se envíe a X-Ray. Si bien los ID de rastro de X-Ray incluyen la marca de tiempo de la solicitud original en formato de tiempo Unix, no es obligatorio cuando se envían ID de rastro conforme a la especificación de W3C en el formato de X-Ray.
**Seguridad de ID de rastro**
Los ID de rastro se pueden ver en los [encabezados de respuesta](xray-concepts.md#xray-concepts-tracingheader). Genere ID de rastro con algoritmo aleatorio seguro para garantizar que los atacantes no puedan calcular futuros ID de rastro y enviar solicitudes con esos ID a su aplicación.
+ `start_time`: **número** que representa el momento en que se creó el segmento, en segundos de punto flotante en formato de tiempo Unix. Por ejemplo, `1480615200.010` o `1.480615200010E9`. Use tantos decimales como necesite. Se recomienda una precisión de microsegundos cuando sea posible.
+ `end_time`: **número** que representa el momento en que se cerró el segmento. Por ejemplo, `1480615200.090` o `1.480615200090E9`. Especifique un `end_time` o `in_progress`.
+ `in_progress`: **booleano** que se establece en `true` en lugar de especificar un `end_time` para registrar que se inició un subsegmento pero que no se completó. Envíe un segmento en curso cuando su aplicación reciba una solicitud que llevará tiempo atender, para rastrear la recepción de la solicitud. Cuando la respuesta se envía, envíe el segmento completo para sobrescribir el segmento en curso. Envíe solo un segmento completo o uno o cero segmentos en curso por solicitud.
**Nombres de servicio**
El `name` de un segmento debe coincidir con el nombre de dominio o el nombre lógico del servicio que genere el segmento. Sin embargo, este requisito no se exige. Cualquier aplicación que tenga permiso para [https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html) puede enviar segmentos con cualquier nombre.
Los siguientes campos son opcionales para los segmentos.
**Campos de segmentos opcionales**
+ `service`: un objeto con información sobre su aplicación.
+ `version`: una cadena que identifica la versión de la aplicación que atiende la solicitud.
+ `user`: una cadena que identifica el usuario que envía la solicitud.
+ `origin`: el tipo de recurso de AWS que ejecuta la aplicación.
**Valores admitidos**
+ `AWS::EC2::Instance`: una instancia de Amazon EC2.
+ `AWS::ECS::Container`: un contenedor de Amazon ECS.
+ `AWS::ElasticBeanstalk::Environment`: un entorno de Elastic Beanstalk
Si hay varios valores que sean aplicables a su aplicación, utilice el que sea más específico. Por ejemplo, supongamos que un Docker multicontenedor en Elastic Beanstalk ejecuta su aplicación en un contenedor de Amazon ECS que, a su vez, se ejecuta en una instancia de Amazon EC2. En este caso, el origen se establecería en `AWS::ElasticBeanstalk::Environment`, puesto que es el elemento principal de los otros dos recursos.
+ `parent_id`: un ID de subsegmento que especifica si la solicitud se originó desde una aplicación instrumentada. El SDK de X-Ray añade el ID del subsegmento principal al [encabezado de rastreo](xray-concepts.md#xray-concepts-tracingheader) para las llamadas HTTP posteriores. En el caso de subsegmentos anidados, un subsegmento puede tener un segmento o un subsegmento como padre.
+ `http`: objetos [`http`](#api-segmentdocuments-http) con información sobre la solicitud HTTP original.
+ `aws`: objeto [`aws`](#api-segmentdocuments-aws) con información sobre el recurso de AWS en el que la aplicación atiende la solicitud.
+ `error`, `throttle`, `fault` y `cause`: campos de [error](#api-segmentdocuments-errors) que indican que se ha producido un error y que incluyen información sobre la excepción que ha causado el error.
+ `annotations` – [`annotations`](#api-segmentdocuments-annotations) objeto con pares de clave-valor que X-Ray debe indexar para las búsquedas.
+ `metadata` – [`metadata`](#api-segmentdocuments-metadata) objeto con los datos adicionales que desea almacenar en el segmento.
+ `subsegments`: **matriz** de objetos [`subsegment`](#api-segmentdocuments-subsegments).
## Subsegmentos
Puede crear subsegmentos para registrar las llamadas a los recursos y Servicios de AWS que ha realizado con el SDK de AWS, las llamadas a las API web HTTP internas o externas, o las consultas de base de datos SQL. También puede crear subsegmentos para depurar o anotar bloques de código en su aplicación. Los subsegmentos pueden contener otros subsegmentos, por lo que un subsegmento personalizado que registre los metadatos de una llamada a una función interna puede contener otros subsegmentos personalizados y subsegmentos para llamadas posteriores.
Un subsegmento registra una llamada posterior desde el punto de vista del servicio que llama. X-Ray utiliza subsegmentos para identificar los servicios posteriores que no envían segmentos y crean entradas para segmentos en el gráfico de servicios.
Un subsegmento puede incrustarse en un documento de segmentos completos o enviarse por separado. Envíe subsegmentos por separado para realizar un rastreo asíncrono de las llamadas posteriores para realizar solicitudes de larga ejecución o para evitar superar el tamaño máximo del documento de segmentos.
**Example Segmento con un subsegmento incrustado**
Un subsegmento independiente tiene un `type` de `subsegment` y un `parent_id` que identifica el segmento principal.
```
{
"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
}
}
}
]
}
```
En el caso de las solicitudes de larga ejecución, puede enviar un segmento en curso para notificar a X-Ray que la solicitud se ha recibido y, a continuación, enviar por separado los subsegmentos para que se rastreen antes de que se complete la solicitud original.
**Example Segmento en curso**
```
{
"name" : "example.com",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"in_progress": true
}
```
**Example Subsegmentos independientes**
Un subsegmento independiente tiene un `type` de `subsegment`, un `trace_id` y un `parent_id` que identifica el segmento principal.
```
{
"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
}
}
}
```
Cuando se complete la solicitud, cierre el segmento reenviándolo con un `end_time`. El segmento completo sobrescribe el segmento en curso.
También puede enviar subsegmentos por separado para solicitudes realizadas que activen flujos de trabajo asíncronos. Por ejemplo, una API web puede devolver una respuesta `OK 200` inmediatamente antes de iniciar el trabajo que el usuario ha solicitado. Puede enviar un segmento completo a X-Ray en cuanto se envíe la respuesta, seguido de subsegmentos para el trabajo realizado más adelante. Al igual que con los segmentos, también puede enviar un fragmento de un subsegmento para registrar que el subsegmento se ha iniciado y, a continuación, sobrescribirlo con un subsegmento completo una vez que se haya completado la llamada posterior.
Los siguientes campos son obligatorios o necesarios en determinadas circunstancias para los subsegmentos.
**nota**
Los valores son cadenas (de hasta 250 caracteres), a menos que se indique lo contrario.
**Campos de subsegmentos obligatorios**
+ `id`: un identificador de 64 bits para el subsegmento, único entre otros segmentos del mismo rastro, en **16 dígitos hexadecimales**.
+ `name`: nombre lógico del subsegmento. En el caso de las llamadas posteriores, asigne un nombre al subsegmento detrás del recurso o servicio llamado. Para los subsegmentos personalizados, asigne el nombre al subsegmento detrás del código que lo instrumenta (por ejemplo, un nombre de función).
+ `start_time`: **número** que representa el momento en que se creó el subsegmento, en segundos de punto flotante en tiempo Unix, con una precisión de milisegundos. Por ejemplo, `1480615200.010` o `1.480615200010E9`.
+ `end_time`: **número** que representa el momento en que se cerró el subsegmento. Por ejemplo, `1480615200.090` o `1.480615200090E9`. Especifique un valor para `end_time` o `in_progress`.
+ `in_progress`: **booleano** que se establece en `true` en lugar de especificar un `end_time` para registrar que se inició un subsegmento pero que no se completó. Envíe solo un subsegmento completo y uno o cero subsegmentos en curso por solicitud posterior.
+ `trace_id`: ID de rastro del segmento principal del subsegmento. Solo es necesario si el envío del subsegmento se realiza por separado.
**Formato de ID de rastro de X-Ray**
Un `trace_id` de X-Ray consta de tres números separados por guiones. Por ejemplo, `1-58406520-a006649127e371903a2de979`. Esto incluye:
+ El número de versión, que es `1`.
+ La hora en que se realizó la solicitud original, en formato de tiempo Unix, en **8 dígitos hexadecimales**.
Por ejemplo, las 10:00 del 1 de diciembre de 2016, PST en formato de tiempo Unix es `1480615200` segundos o `58406520` en formato hexadecimal.
+ Un identificador 96 bits del rastro, único a nivel global, en **24 dígitos hexadecimales**.
**nota**
Ahora X-Ray admite ID de rastro creados mediante OpenTelemetry o cualquier otro marco que se ajuste a la [especificación Trace Context de W3C](https://www.w3.org/TR/trace-context/). Un ID de rastro conforme a la especificación de W3C debe estar formateado en el formato de ID de rastro de X-Ray cuando se envía a X-Ray. Por ejemplo, el ID de rastro `4efaaf4d1e8720b39541901950019ee5` conforme a la especificación de W3C debe tener el formato `1-4efaaf4d-1e8720b39541901950019ee5` cuando se envíe a X-Ray. Si bien los ID de rastro de X-Ray incluyen la marca de tiempo de la solicitud original en formato de tiempo Unix, no es obligatorio cuando se envían ID de rastro conforme a la especificación de W3C en el formato de X-Ray.
+ `parent_id`: ID del segmento principal del subsegmento. Solo es necesario si el envío del subsegmento se realiza por separado. En el caso de subsegmentos anidados, un subsegmento puede tener un segmento o un subsegmento como padre.
+ `type` – `subsegment`. Solo es necesario si el envío del subsegmento se realiza por separado.
Los siguientes campos son opcionales para los subsegmentos.
**Campos de subsegmentos opcionales**
+ `namespace`: `aws` para las llamadas al SDK de AWS; `remote` para las demás llamadas posteriores.
+ `http`: objeto [`http`](#api-segmentdocuments-http) con información sobre una llamada HTTP saliente.
+ `aws`: objeto [`aws`](#api-segmentdocuments-aws) con información sobre el recurso de AWS posterior al que ha llamado la aplicación.
+ `error`, `throttle`, `fault` y `cause`: campos de [error](#api-segmentdocuments-errors) que indican que se ha producido un error y que incluyen información sobre la excepción que ha causado el error.
+ `annotations`: objeto [`annotations`](#api-segmentdocuments-annotations) con pares de clave-valor que X-Ray debe indexar para las búsquedas.
+ `metadata`: objeto [`metadata`](#api-segmentdocuments-metadata) con los datos adicionales que desea almacenar en el segmento.
+ `subsegments`: **matriz** de objetos [`subsegment`](#api-segmentdocuments-subsegments).
+ `precursor_ids`: **matriz** de identificadores de subsegmento que identifica los subsegmentos con el mismo segmento principal que se completó antes de este subsegmento.
## Datos de solicitudes HTTP
Utilice un bloque HTTP para registrar los detalles de una solicitud HTTP que ha atendido su aplicación (en un segmento) o que ha realizado la aplicación en una API HTTP posterior (en un subsegmento). La mayoría de los campos de este objeto se asignan a la información proporcionada en una solicitud y respuesta HTTP.
**`http`**
Todos los campos son opcionales.
+ `request`: información sobre una solicitud.
+ `method`: el método de solicitud. Por ejemplo, `GET`.
+ `url`: la dirección URL completa, obtenida del protocolo, nombre de host y ruta de la solicitud.
+ `user_agent`: la cadena de agente de usuario del cliente del solicitante.
+ `client_ip`: la dirección IP del solicitante. Se puede recuperar del `Source Address` del paquete de direcciones IP o, en el caso de las solicitudes reenviadas, de un encabezado `X-Forwarded-For`.
+ `x_forwarded_for`: (solo segmentos) **booleano** que indica que se ha leído el `client_ip` desde un encabezado `X-Forwarded-For` y no es fiable, ya que podría haberse falsificado.
+ `traced`: (solo subsegmentos) **booleano** que indica que la llamada posterior es a otro servicio rastreado. Si este campo está establecido en `true`, X-Ray considera que el rastro se debe dividir hasta que el servicio posterior cargue el segmento con un `parent_id` que coincida con el `id` del subsegmento que contiene este bloque.
+ `response`: información sobre una respuesta.
+ `status`: **entero** que indica el estado HTTP de la respuesta.
+ `content_length`: **entero** que indica la longitud del cuerpo de la respuesta en bytes.
Cuando instrumente una llamada a una API web posterior, este campo registra un subsegmento con información sobre la solicitud HTTP y la respuesta. X-Ray utiliza el subsegmento para generar un segmento inferido de la API remota.
**Example Segmento para las llamadas HTTP atendidas por una aplicación en ejecución en Amazon EC2**
```
{
"id": "6b55dcc497934f1a",
"start_time": 1484789387.126,
"end_time": 1484789387.535,
"trace_id": "1-5880168b-fd5158284b67678a3bb5a78c",
"name": "www.example.com",
"origin": "AWS::EC2::Instance",
"aws": {
"ec2": {
"availability_zone": "us-west-2c",
"instance_id": "i-0b5a4678fc325bg98"
},
"xray": {
"sdk_version": "2.11.0 for Java"
},
},
"http": {
"request": {
"method": "POST",
"client_ip": "78.255.233.48",
"url": "http://www.example.com/api/user",
"user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
"x_forwarded_for": true
},
"response": {
"status": 200
}
}
```
**Example Subsegmento para una llamada HTTP posterior**
```
{
"id": "004f72be19cddc2a",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"name": "names.example.com",
"namespace": "remote",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
}
}
```
**Example Segmento inferido para una llamada HTTP posterior**
```
{
"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
}
```
## Anotaciones
Los segmentos y subsegmentos pueden incluir un objeto `annotations` con uno o varios campos que X-Ray indexa para su uso con expresiones de filtro. Los campos pueden tener valores de cadena, numéricos o booleanos (pero no objetos ni matrices). X-Ray indexa hasta 50 anotaciones por rastro.
**Example Segmento para llamadas HTTP con anotaciones**
```
{
"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
}
}
```
Para que las claves funcionen con filtros, deben estar en orden alfanumérico. Se admite el guion bajo, pero no otros símbolos ni espacios en blanco.
## Metadatos
Los segmentos y subsegmentos pueden incluir un objeto `metadata` que contenga uno o varios campos con valores de cualquier tipo, incluidos objetos y matrices. X-Ray no indexa los metadatos, y los valores pueden ser de cualquier tamaño siempre que el documento del segmento no supere el tamaño máximo (64 kB). Puede ver los metadatos en el documento del segmento completo devuelto por la API de [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html). Las claves de campo (`debug` en el siguiente ejemplo) empezando por `AWS.` están reservadas para su uso por los SDK y los clientes proporcionados por AWS.
**Example Subsegmento personalizado con metadatos**
```
{
"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"
]
}
}
]
}
```
## Datos de recursos de AWS
Para los segmentos, el objeto `aws` contiene información sobre el recurso en el que se ejecuta la aplicación. Se pueden aplicar varios campos a un solo recurso. Por ejemplo, una aplicación que se ejecute en un entorno Docker multicontenedor en Elastic Beanstalk podría tener información sobre la instancia de Amazon EC2, el contenedor de Amazon ECS que se ejecuta en la instancia y el propio entorno de Elastic Beanstalk.
**`aws` (Segmentos)**
Todos los campos son opcionales.
+ `account_id`: si la aplicación envía segmentos a una Cuenta de AWS diferente, este campo registra el ID de la cuenta que ejecuta la aplicación.
+ `cloudwatch_logs`: matriz de objetos que describen un único grupo de registro de CloudWatch.
+ `log_group`: el nombre del grupo de registro de CloudWatch.
+ `arn`— El ARN del grupo de registro de CloudWatch.
+ `ec2`: información sobre una instancia de Amazon EC2.
+ `instance_id`: el ID de la instancia de EC2.
+ `instance_size`: el tipo de la instancia de EC2.
+ `ami_id`: el ID de imagen de máquina de Amazon.
+ `availability_zone`: la zona de disponibilidad en la que se ejecuta la instancia.
+ `ecs`: información sobre un contenedor de Amazon ECS.
+ `container`: el nombre de host de su contenedor.
+ `container_id`: el ID completo de su contenedor.
+ `container_arn`: el ARN de su instancia de contenedor.
+ `eks`: la información acerca de un clúster de Amazon EKS.
+ `pod`: el nombre de host de su pod de EKS.
+ `cluster_name`: el nombre del clúster de EKS.
+ `container_id`: el ID completo de su contenedor.
+ `elastic_beanstalk`: información sobre un entorno de Elastic Beanstalk. Puede encontrar esta información en un archivo denominado `/var/elasticbeanstalk/xray/environment.conf` en las plataformas más recientes de Elastic Beanstalk.
+ `environment_name`: el nombre del entorno.
+ `version_label`: el nombre de la versión de la aplicación que está implementada actualmente en la instancia que ha atendido la solicitud.
+ `deployment_id`: **número** que indica el ID de la última implementación satisfactoria en la instancia que ha atendido la solicitud.
+ `xray`: metadatos sobre el tipo y la versión de la instrumentación utilizada.
+ `auto_instrumentation`: booleano que indica si se utilizó la instrumentación automática (por ejemplo, el agente Java).
+ `sdk_version`. La versión del SDK o del agente que se está utilizando.
+ `sdk`: el tipo de SDK.
**Example Bloque de AWS con complementos**
```
"aws":{
"elastic_beanstalk":{
"version_label":"app-5a56-170119_190650-stage-170119_190650",
"deployment_id":32,
"environment_name":"scorekeep"
},
"ec2":{
"availability_zone":"us-west-2c",
"instance_id":"i-075ad396f12bc325a",
"ami_id":
},
"cloudwatch_logs":[
{
"log_group":"my-cw-log-group",
"arn":"arn:aws:logs:us-west-2:012345678912:log-group:my-cw-log-group"
}
],
"xray":{
"auto_instrumentation":false,
"sdk":"X-Ray for Java",
"sdk_version":"2.8.0"
}
}
```
Para los subsegmentos, este campo registra información acerca de los recursos y Servicios de AWS a los que obtiene acceso la aplicación. X-Ray utiliza esta información para crear segmentos inferidos que representan los servicios posteriores del mapa de servicio.
**`aws` (subsegmentos)**
Todos los campos son opcionales.
+ `operation`: el nombre de la acción de la API invocada para un recurso o Servicio de AWS.
+ `account_id`: si la aplicación obtiene acceso a recursos en una cuenta diferente o envía segmentos a una cuenta diferente, este campo registra el ID de la cuenta propietaria del recurso de AWS al que obtiene acceso la aplicación.
+ `region`: si el recurso está en una región diferente a la de la aplicación, este campo registra la región. Por ejemplo, `us-west-2`.
+ `request_id`: un identificador único para la solicitud.
+ `queue_url`: para las operaciones incluidas en una cola de Amazon SQS, la dirección URL de la cola.
+ `table_name`: para las operaciones de una tabla de DynamoDB, el nombre de la tabla.
**Example Subsegmento para una llamada a DynamoDB con el fin de guardar 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",
}
}
```
## Errores y excepciones
Cuando se produzca un error, puede registrar información sobre el error y las excepciones que se generan. Registre los errores en los segmentos cuando la aplicación devuelva un error al usuario, y en los subsegmentos cuando una llamada posterior devuelva un error.
**tipos de error**
Establezca uno o varios de los campos siguientes en `true` para indicar que se ha producido un error. Se pueden aplicar varios tipos si se trata de errores compuestos. Por ejemplo, un error `429 Too Many Requests` de una llamada posterior podría hacer que la aplicación devolviera un error `500 Internal Server Error`, en cuyo caso se aplicarían los tres tipos.
+ `error`: **booleano** que indica que se ha producido un error del cliente (el código de estado de la respuesta fue 4XX Client Error).
+ `throttle`: **booleano** que indica que se ha limitado una solicitud (el código de estado de la respuesta fue *429 Too Many Requests*).
+ `fault`: **booleano** que indica que se ha producido un error del servidor (el código de estado de la respuesta fue 5XX Server Error).
Indique la causa del error incluyendo un objeto **cause** en el segmento o subsegmento.
**`cause`**
Una causa puede ser un ID de excepción de **16 caracteres** o un objeto con los siguientes campos:
+ `working_directory`: la ruta completa del directorio de trabajo donde se produjo la excepción.
+ `paths`: la **matriz** de rutas a las bibliotecas o módulos que se estaban usando cuando se produjo la excepción.
+ `exceptions`: la **matriz** de objetos **exception**.
Incluya información detallada sobre el error en uno o varios objetos **exception**.
**`exception`**
Todos los campos son opcionales.
+ `id`: un identificador de 64 bits para la excepción, único entre otros segmentos del mismo rastro, en **16 dígitos hexadecimales**.
+ `message`: el mensaje de excepción.
+ `type`: el tipo de excepción.
+ `remote`: **booleano** que indica que la excepción se produjo por un error devuelto por un servicio posterior.
+ `truncated`: **entero** que indica el número de marcos de pila que se han omitido de `stack`.
+ `skipped`: **entero** que indica el número de excepciones que se omitieron entre esta excepción y su excepción secundaria, es decir, la excepción que la ha causado.
+ `cause`: ID de excepción del elemento principal de la excepción, es decir, la excepción que provocó esta excepción.
+ `stack`: **matriz** de objetos **stackFrame**.
Si está disponible, registre la información acerca de la pila de llamada en objetos **stackFrame**.
**`stackFrame`**
Todos los campos son opcionales.
+ `path`: la ruta relativa al archivo.
+ `line`: la línea dentro del archivo.
+ `label`: el nombre de la función o método.
## Consultas SQL
Puede crear subsegmentos para las consultas que la aplicación realiza en una base de datos SQL.
**`sql`**
Todos los campos son opcionales.
+ `connection_string`: para SQL Server u otras conexiones de base de datos que no usen cadenas de conexión URL, este campo registra la cadena de conexión, sin incluir las contraseñas.
+ `url`: para una conexión a la base de datos que utilice una cadena de conexión URL, este campo registra la dirección URL, sin incluir las contraseñas.
+ `sanitized_query`: la consulta a la base de datos, con todos los valores proporcionados por el usuario eliminados o reemplazados con un marcador de posición.
+ `database_type`: el nombre del motor de base de datos.
+ `database_version`: el número de versión del motor de base de datos.
+ `driver_version`: el nombre y número de versión del controlador del motor de base de datos que usa la aplicación.
+ `user`: el nombre de usuario de la base de datos.
+ `preparation`: `call` si la consulta utiliza un `PreparedCall`; `statement` si la consulta utiliza un `PreparedStatement`.
**Example Subsegmento con una consulta SQL**
```
{
"id": "3fd8634e78ca9560",
"start_time": 1484872218.696,
"end_time": 1484872218.697,
"name": "ebdb@aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com",
"namespace": "remote",
"sql" : {
"url": "jdbc:postgresql://aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com:5432/ebdb",
"preparation": "statement",
"database_type": "PostgreSQL",
"database_version": "9.5.4",
"driver_version": "PostgreSQL 9.4.1211.jre7",
"user" : "dbuser",
"sanitized_query" : "SELECT * FROM customers WHERE customer_id=?;"
}
}
```