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.
# Elección de una interfaz
AWS X-Ray puede proporcionar información sobre cómo funciona su aplicación y qué tan bien interactúa con otros servicios y recursos. Después de instrumentar o configurar la aplicación, X-Ray recopila los datos de rastro a medida que la aplicación atiende solicitudes. Puede analizar estos datos de rastro para identificar problemas de rendimiento, solucionar errores y optimizar sus recursos. Esta guía le indica cómo interactuar con X-Ray siguiendo las siguientes pautas:
+ Utilice una Consola de administración de AWS si quiere empezar rápidamente o si puede utilizar visualizaciones prediseñadas para realizar tareas básicas.
+ Elija la CloudWatch consola Amazon para disfrutar de una experiencia de usuario más actualizada que contenga todas las funciones de la consola X-Ray.
+ Utilice la consola de X-Ray si desea una interfaz más sencilla o no quiere cambiar la forma en que interactúa con X-Ray.
+ Usa un SDK si necesitas más funciones de rastreo, monitoreo o registro personalizadas de las que te Consola de administración de AWS puede ofrecer.
+ Elija el SDK de ADOT si quiere un SDK independiente del proveedor y basado en el SDK de OpenTelemetry de código abierto con capas adicionales de optimización y seguridad de AWS .
+ Elija el SDK de X-Ray si prefiere un SDK más sencillo o no quiere actualizar el código de su aplicación.
+ Use las operaciones de la API de X-Ray si un SDK no es compatible con el lenguaje de programación de su aplicación.
El siguiente diagrama le ayudará a elegir cómo quiere interactuar con X-Ray:
![\[X-Ray muestra información detallada sobre las solicitudes de aplicaciones.\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/xray-choose-interface.png)
**Topics**
+ [Uso de un SDK](aws-xray-interface-sdk.md)
+ [Uso de una consola](aws-xray-interface-console.md)
+ [Uso de la API de X-Ray](xray-api.md)
# Uso de un SDK
**nota**
Aviso de SDK/Daemon mantenimiento de X-Ray: el 25 de febrero de 2026, el AWS X-Ray SDKs/Daemon entrará en modo de mantenimiento, donde AWS se limitarán las versiones de X-Ray SDK y Daemon para abordar únicamente los problemas de seguridad. Para obtener más información sobre la cronología del soporte, consulte [Cronología de X-Ray SDK y Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar a. OpenTelemetry Para obtener más información sobre la migración a OpenTelemetry, consulte [Migración de una instrumentación de rayos X a una instrumentación](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry
Utilice un SDK si desea utilizar una interfaz de línea de comandos o si necesita más funciones personalizadas de rastreo, supervisión o registro de las que están disponibles en una Consola de administración de AWS. También puede usar un AWS SDK para desarrollar programas que usen el X-Ray APIs. Puede usar el SDK AWS Distro for OpenTelemetry (ADOT) o el SDK X-Ray.
Si utiliza un SDK, puede añadir personalizaciones a su flujo de trabajo tanto al instrumentar su aplicación como al configurar su recopilador o agente. Utilice un SDK para efectuar las siguientes tareas que no puede llevar a cabo con una Consola de administración de AWS:
+ Publicar métricas personalizadas: tome muestras de métricas en resoluciones altas de hasta 1 segundo, use varias dimensiones para agregar información sobre una métrica y agregue puntos de datos en un conjunto de estadísticas.
+ Personalizar su recopilador: personalice la configuración de cualquier parte de un recopilador, incluidos el receptor, el procesador, el exportador y el conector.
+ Personalizar su instrumentación: personalice segmentos y subsegmentos, añada pares clave-valor personalizados como atributos y cree métricas personalizadas.
+ Crear y actualizar las reglas de muestreo mediante programación.
Use el ADOT SDK si desea la flexibilidad de usar un OpenTelemetry SDK estandarizado con niveles adicionales de AWS seguridad y optimización. El SDK AWS Distro for OpenTelemetry (ADOT) es un paquete independiente del proveedor que permite la integración con back-ends de otros proveedores y no relacionados con los AWS servicios sin tener que reorganizar el código.
Utilice el SDK de X-Ray si ya lo hace y solo se integra con backends de AWS y no pretenda cambiar la forma en que interactúa con X-Ray o con el código de su aplicación.
Para obtener más información acerca de cada una de las características, consulte [Cómo elegir entre AWS Distro for OpenTelemetry y X-Ray SDKs](xray-instrumenting-your-app.md#xray-instrumenting-choosing).
## Uso del SDK de ADOT
El ADOT SDK es un conjunto de bibliotecas y agentes de código abierto que envían APIs datos a los servicios de backend. ADOTes compatible con varios backends y agentes AWS, se integra con ellos y proporciona un gran número de bibliotecas de código abierto mantenidas por la OpenTelemetry comunidad. Utilice el SDK de ADOT para instrumentar su aplicación y recopilar registros, metadatos, métricas y rastros. También puedes usarlo ADOT para monitorear los servicios y configurar una alarma en función de tus métricas. CloudWatch
Si utiliza el SDK de ADOT, dispone de las siguientes opciones, en combinación con un agente:
+ Usa el ADOT SDK con el [CloudWatch agente](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html) (se recomienda).
+ Utilice el ADOT SDK con el [ADOTrecopilador](https://aws-otel.github.io/docs/getting-started/collector), lo que se recomienda si desea utilizar software independiente del proveedor con AWS niveles de seguridad y optimización.
Para utilizar el SDK de ADOT, haga lo siguiente:
+ Instrumente su aplicación con el SDK de ADOT. Para obtener más información, consulte la documentación de su lenguaje de programación en la [documentación técnica de ADOT](https://aws-otel.github.io/docs/introduction).
+ Configure un recopilador de ADOT para que le indique dónde enviar los datos que recopila.
Una vez que el ADOT recopilador recibe los datos, los envía al servidor que especifiques en la ADOT configuración. ADOTpuede enviar datos a varios backends, incluso a proveedores externos AWS, como se muestra en el siguiente diagrama:
![\[Puede personalizar el recopilador de ADOT al instrumentar su aplicación y configurar el recopilador.\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/adot-sdk.png)
AWS se actualiza periódicamente ADOT para añadir funcionalidad y alinearse con el [OpenTelemetry](https://opentelemetry.io/docs/)marco. Las actualizaciones y los planes futuros para el desarrollo de ADOT forman parte de una [hoja de ruta](https://github.com/orgs/aws-observability/projects/4) que está disponible públicamente. ADOT admite varios lenguajes de programación, entre los que se incluyen los siguientes:
+ Go
+ Java
+ JavaScript
+ Python
+ .NET
+ Ruby
+ PHP
Si está utilizando Python, ADOT puede instrumentar automáticamente su aplicación. Para empezar a ADOT utilizarla, consulte [Introducción y introducción](https://aws-otel.github.io/docs/introduction) [a la AWS distribución de OpenTelemetry Collector](https://aws-otel.github.io/docs/getting-started/collector).
## Uso del SDK de X-Ray
El SDK de X-Ray es un conjunto de AWS APIs bibliotecas que envían datos a los servicios de AWS backend. Utilice el SDK de X-Ray con el fin de instrumentar su aplicación y recopilar datos de rastro. No puede utilizar el SDK de X-Ray para recopilar datos de registro o de métricas.
Si utiliza el SDK de X-Ray, dispone de las siguientes opciones, en combinación con un agente:
+ Uso del SDK de X-Ray con el [AWS X-Ray demonio](xray-daemon.md): utilícelo si no desea actualizar el código de la aplicación.
+ Utilice el SDK de X-Ray con el CloudWatch agente: (recomendado) El CloudWatch agente es compatible con el SDK de X-Ray.
Para usar el SDK de X-Ray, haga lo siguiente:
+ Instrumente su aplicación con el SDK de X-Ray.
+ Configure un recopilador para que le indique dónde enviar los datos que recopila. Puede utilizar el CloudWatch agente o el daemon de X-Ray para recopilar la información de rastreo.
Una vez que el recopilador o el agente reciben los datos, los envían a un AWS servidor que usted especifique en la configuración del agente. El SDK de X-Ray solo puede enviar datos a un backend de AWS , tal como se muestra en el siguiente diagrama:
![\[Utilice el SDK de X-Ray con el CloudWatch agente o el daemon de X-Ray.\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/xray-sdk.png)
Si está utilizando Java, puede emplear el SDK de X-Ray para instrumentar automáticamente su aplicación. Para empezar a usar el SDK de X-Ray, consulte las bibliotecas asociadas a los siguientes lenguajes de programación:
+ [Go](xray-go.md)
+ [Java](xray-java.md)
+ [Node.js](xray-nodejs.md)
+ [Python](xray-python.md)
+ [.NET](xray-dotnet.md)
+ [Ruby](xray-ruby.md)
# Uso de una consola
Utilice una consola si quiere emplear una interfaz gráfica de usuario (GUI) que requiera un mínimo de programación. Los usuarios que acaban de comenzar en X-Ray pueden ponerse manos a la obra rápidamente mediante las visualizaciones prediseñadas con las que llevar a cabo tareas básicas. Puede hacer lo siguiente directamente desde la consola:
+ Habilite X-Ray.
+ Consultar los resúmenes de alto nivel del rendimiento de su aplicación.
+ Comprobar el estado de sus aplicaciones.
+ Identificar errores de alto nivel.
+ Consultar los resúmenes de rastreo básicos.
Para interactuar con X-Ray, puede utilizar tanto la consola de Amazon CloudWatch en [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) como la consola de X-Ray en [https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home).
## Uso de la consola de Amazon CloudWatch
La consola de CloudWatch incluye una nueva funcionalidad de X-Ray que se ha rediseñado a partir de la consola X-Ray para facilitar su uso. Si usa la consola de CloudWatch, puede ver los registros y las métricas de CloudWatch junto con los datos de rastros de X-Ray. Utilice la consola de CloudWatch para ver y analizar datos, incluidos los siguientes:
+ Rastros de X-Ray: vea, analice y filtre los rastros asociados a su aplicación mientras se atiende una solicitud. Utilice estos rastros para encontrar latencias altas, depurar errores y optimizar el flujo de trabajo de su aplicación. Consulte mapas de rastros y de servicios para ver representaciones visuales del flujo de trabajo de su aplicación.
+ Registros: consulte, analice y filtre los registros que produce la aplicación. Utilice los registros para solucionar errores y configurar la supervisión en función de valores de registro específicos.
+ Métricas: calcule y supervise el rendimiento de su aplicación mediante las métricas que emiten sus recursos o cree sus propias métricas. Consulte estas métricas en gráficos o diagramas.
+ Supervisión de redes e infraestructuras: supervise las redes principales para detectar interrupciones y comprobar el estado y el rendimiento de su infraestructura, incluidas las aplicaciones en contenedores, otros servicios de AWS y los clientes.
+ Todas las funciones de la consola de X-Ray que se enumeran en la siguiente sección **Uso de la consola de X-Ray.**
Para obtener más información sobre la consola de CloudWatch, consulte [Introducción a Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/GettingStarted.html).
Inicie sesión en la consola de Amazon CloudWatch desde [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
## Uso de la consola de X-Ray
La consola de X-Ray ofrece un rastreo distribuido para las solicitudes de aplicaciones. Utilice la consola de X-Ray si quiere trabajar con una consola de la forma más sencilla o si no quiere actualizar el código de la aplicación. AWS ha dejado de desarrollar la consola de X-Ray. La consola de X-Ray contiene las siguientes características para aplicaciones instrumentadas:
+ [Información](xray-console-insights.md): detecta automáticamente las anomalías en el rendimiento de su aplicación y encuentra las causas subyacentes. Esta información se incluye en la consola de CloudWatch, en la sección **Información**. Para obtener más información, consulte **Uso de Información de X-Ray** en la [Uso de la consola de X-Ray](#xray-console).
+ Mapa de servicios: vea una estructura gráfica de su aplicación y sus conexiones con los clientes, los recursos, los servicios y las dependencias.
+ Rastros: consulte un resumen de los rastros que genera su aplicación cuando atiende una solicitud. Utilice los datos de rastro para comprender el rendimiento de su aplicación en comparación con las métricas básicas, como la respuesta HTTP y el tiempo de respuesta.
+ Análisis: interprete, explore y analice los datos de rastro mediante gráficos para distribuir el tiempo de respuesta.
+ Configuración: cree rastros personalizados para cambiar las configuraciones predeterminadas de lo siguiente:
+ Muestreo: cree una regla que defina la frecuencia con la que debe tomar una muestra de su solicitud para recibir la información de rastro. Para obtener más información, consulte **Configuración de reglas de muestreo** en la [Uso de la consola de X-Ray](#xray-console).
+ [Cifrado](xray-console-encryption.md): cifra los datos en reposo con una clave que se puede auditar o deshabilitar con AWS Key Management Service.
+ Grupos: utilice una expresión de filtro para definir un grupo de rastros con una característica común, como el nombre de una URL o el tiempo de respuesta. Para obtener más información, consulte [Configuración de grupos](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-groups).
Inicie sesión en la consola de X-Ray en [https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home).
## Exploración de la consola de X-Ray
Utilice la consola de X-Ray para ver un mapa de los servicios y rastros asociadas a las solicitudes que atienden sus aplicaciones, y para configurar grupos y reglas de muestreo que afecten a la forma en que se envían los rastros a X-Ray.
**nota**
El mapa de servicio X-Ray y el mapa ServiceLens de CloudWatch se han combinado en el mapa de rastros de X-Ray de la consola de Amazon CloudWatch. Abra la [consola de CloudWatch](https://console.aws.amazon.com/cloudwatch/) y seleccione **Mapa de rastros** en **Rastros de X-Ray**, en el panel de navegación izquierdo.
Ahora, CloudWatch se integra con [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html), que puede detectar y supervisar los servicios de aplicaciones, los clientes, los canarios de Synthetics y las dependencias de los servicios. Use Application Signals para ver una lista o un mapa visual de sus servicios, ver las métricas del estado en función de los objetivos de nivel de servicio (SLO) y profundizar para ver los seguimientos de X-Ray correlacionados para una solución de problemas más detallada.
La página principal de la consola principal de X-Ray es el mapa de rastros, que es una representación visual del gráfico de servicios de JSON que X-Ray genera a partir de los datos de rastro que sus aplicaciones generan. El mapa se compone de nodos de servicios para cada aplicación en su cuenta que atiende solicitudes, nodos cliente principales que representan los orígenes de las solicitudes, y nodos de servicios posteriores que representan los servicios web y los recursos utilizados por una aplicación mientras procesa una solicitud. Hay páginas adicionales para ver rastros y sus detalles, y para configurar grupos y reglas de muestreo.
Vea la experiencia de la consola de X-Ray y compárela con la consola de CloudWatch en las siguientes secciones.
**Topics**
+ [Uso de la consola de Amazon CloudWatch](#aws-xray-interface-console-cw)
+ [Uso de la consola de X-Ray](#xray-console)
+ [Exploración de la consola de X-Ray](#xray-console-explore)
+ [Uso del mapa de rastros de X-Ray](xray-console-servicemap.md)
+ [Visualización de rastros y detalles de rastros](xray-console-traces.md)
+ [Uso de expresiones de filtro](xray-console-filters.md)
+ [Rastreo entre cuentas](xray-console-crossaccount.md)
+ [Rastreo de aplicaciones basadas en eventos](xray-tracelinking.md)
+ [Uso de histogramas de latencia](xray-console-histograms.md)
+ [Uso de información en X-Ray](xray-console-insights.md)
+ [Interacción con la consola de Analytics](xray-console-analytics.md)
+ [Configuración de grupos](xray-console-groups.md)
+ [Configuración de reglas de muestreo de](xray-console-sampling.md)
+ [Configuración de muestreo flexible](xray-adaptive-sampling.md)
+ [Enlace profundo de la consola](xray-console-deeplinks.md)
# Uso del mapa de rastros de X-Ray
Utilice el mapa de rastros en la consola de X-Ray para identificar los servicios donde ocurran errores, donde haya conexiones con alta latencia o rastros de solicitudes que dieron error.
**nota**
Ahora, CloudWatch se integra con [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html), que puede detectar y supervisar los servicios de aplicaciones, los clientes, los canarios de Synthetics y las dependencias de los servicios. Use Application Signals para ver una lista o un mapa visual de sus servicios, ver las métricas del estado en función de los objetivos de nivel de servicio (SLO) y profundizar para ver los seguimientos de X-Ray correlacionados para una solución de problemas más detallada.
El mapa de servicio X-Ray y el mapa ServiceLens de CloudWatch se han combinado en el mapa de rastros de X-Ray de la consola de Amazon CloudWatch. Abra la [consola de CloudWatch](https://console.aws.amazon.com/cloudwatch/) y seleccione **Mapa de rastros** en **Rastros de X-Ray**, en el panel de navegación izquierdo.
## Consulta del mapa de rastros
El mapa de rastros es una representación visual de los datos de rastro que sus aplicaciones generan. El mapa muestra nodos de servicios que atienden solicitudes, nodos cliente principales que representan los orígenes de las solicitudes, y nodos de servicios posteriores que representan los servicios web y los recursos utilizados porque utiliza una aplicación mientras procesa una solicitud.
El mapa de rastros muestra una vista conectada de los rastros de las aplicaciones basadas en eventos que utilizan Amazon SQS y Lambda. Para obtener más información, consulte [Rastreo de aplicaciones basadas en eventos](xray-tracelinking.md). El mapa de rastros también admite el [rastreo entre cuentas](xray-console-crossaccount.md), ya que muestra los nodos de varias cuentas en un solo mapa.
------
#### [ CloudWatch console ]
**Visualización del mapa de rastros en la consola CloudWatch**
1. [Abra la consola de CloudWatch](https://console.aws.amazon.com/cloudwatch/). Elija **mapa de rastros** en la sección **Rastros de X-Ray** en el panel de navegación izquierdo.
![\[Página del mapa de rastros de la consola de CloudWatch\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/console-servicemap-cw.png)
1. Seleccione un nodo de servicio para ver sus solicitudes o un límite entre dos nodos para ver las solicitudes que pasaron por esa conexión.
1. Debajo del mapa de rastros se muestra información adicional, como pestañas para las métricas, alertas y la distribución del tiempo de respuesta. En la pestaña **Métricas**, seleccione un rango dentro de cada gráfico para desglosarlo y ver más detalles, o elija las opciones **Fallos** o **Errores** para filtrar los rastros. En la pestaña **Distribución del tiempo de respuesta**, seleccione un rango dentro del gráfico para filtrar los rastros por tiempo de respuesta.
![\[Dashboard showing latency, requests, and faults metrics for an ElasticBeanstalk environment.\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/console-cw-servicemap-node-detail.png)
1. Para ver los rastros, elija **Ver rastros** o, si ha aplicado un filtro, elija **Ver rastros filtrados**.
1. Seleccione **Ver registros** para ver los registros de CloudWatch asociados al nodo seleccionado. No todos los nodos del mapa de rastros permiten ver los registros. Consulte la [solución de problemas de los registros de CloudWatch](xray-troubleshooting.md#xray-troubleshooting-Nologs) para obtener más información.
El mapa de rastros indica los problemas en cada nodo delineándolo con colores:
+ El **rojo** se usa para fallos de servidor (errores de la serie 500)
+ El **amarillo** se usa para los errores del cliente (errores de la serie 400)
+ El **morado** indica los errores de limitación de solicitudes (429: demasiadas solicitudes)
Si el mapa de rastros es demasiado grande, utilice los controles que aparecen en pantalla o el ratón para ampliar y reducir el mapa o para moverlo por la pantalla.
------
#### [ X-Ray console ]
**Visualización del mapa de servicio**
1. Abra la [consola de X-Ray](https://console.aws.amazon.com/xray/home#). El mapa de servicio se muestra de forma predeterminada. También puede elegir **mapa de servicio** en el panel de navegación izquierdo.
![\[Página del mapa de servicio de la consola de X-Ray\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/console-servicemap-xray.png)
1. Seleccione un nodo de servicio para ver sus solicitudes o un límite entre dos nodos para ver las solicitudes que pasaron por esa conexión.
1. Utilice el [histograma](xray-console-histograms.md) que representa la distribución del tiempo de respuesta para filtrar los rastros por duración y seleccione los códigos de estado cuyos rastros desee ver. Después elija **Ver rastros** para abrir la lista de rastros con la expresión de filtro aplicada.
![\[Response distribution graph showing latency peaks and service details for Scorekeep AWS ECS container.\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/console-servicemap-nodedetail-xray.png)
El mapa de servicio indica el estado de cada nodo mediante el uso de colores en función de la proporción de llamadas correctas y errores o fallos:
+ El **verde** se utiliza para las llamadas realizadas con éxito
+ El **rojo** se usa para fallos de servidor (errores de la serie 500)
+ El **amarillo** se usa para los errores del cliente (errores de la serie 400)
+ El **morado** indica los errores de limitación de solicitudes (429: demasiadas solicitudes)
Si el mapa de servicio es demasiado grande, utilice los controles que aparecen en pantalla o el ratón para ampliar y reducir el mapa o para moverlo por la pantalla.
------
**nota**
El mapa de rastros de X-Ray puede mostrar hasta 10 000 nodos. En raras ocasiones, en las que el número total de nodos de servicio supere este límite, es posible que reciba un mensaje de error reciba y no pueda visualizar un mapa de rastros completo en la consola.
## Filtrado del mapa de rastros por grupo
Mediante una [expresión de filtro](xray-console-filters.md), puede definir los criterios por los que incluir rastros en un grupo. Siga los pasos que se indican a continuación para mostrar ese grupo específico en el mapa de rastros.
------
#### [ CloudWatch console ]
Elija un nombre de grupo en el filtro de grupo situado en la parte superior izquierda del mapa de rastros.
![\[Search bar for filtering by X-Ray group, with "TestGroup" displayed as an option.\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/console-servicemap-groups-cw.png)
------
#### [ X-Ray console ]
Elija un nombre de grupo en el menú desplegable situado a la izquierda de la barra de búsqueda.
![\[Drop-down menu showing Default, TestGroup, Create group, and Learn more options.\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/group-select-console.png)
------
Entonces se filtrará el mapa de servicio para mostrar los rastros que coincidan con la expresión de filtro del grupo seleccionado.
## Leyenda y opciones del mapa de rastros
El mapa de rastros incluye una leyenda y varias opciones para personalizar la visualización del mapa.
------
#### [ CloudWatch console ]
Seleccione el menú desplegable **Leyenda y opciones** en la parte superior derecha del mapa. Elija lo que se muestra dentro de los nodos, por ejemplo:
+ **Métricas** muestra el tiempo medio de respuesta y el número de rastros enviados por minuto durante el intervalo de tiempo elegido.
+ **Nodos** muestra el icono de servicio dentro de cada nodo.
Seleccione otros ajustes del mapa en el panel **Preferencias**, al que se puede acceder mediante el icono con forma de engranaje situado en la parte superior derecha del mapa. Estos ajustes incluyen seleccionar qué métrica se utiliza para determinar el tamaño de cada nodo y qué valores controlados deben mostrarse en el mapa.
------
#### [ X-Ray console ]
Para ver la leyenda del mapa de servicio, seleccione el enlace **Leyenda del mapa** en la parte superior derecha del mapa. Las siguientes opciones se pueden elegir en la parte inferior derecha del mapa de rastros:
+ **Iconos de servicio** cambia lo que se muestra en cada nodo y muestra el icono del servicio o el tiempo medio de respuesta y el número de rastros enviados por minuto durante el intervalo de tiempo elegido.
+ **Tamaño de los nodos: ninguno** establece el mismo tamaño para todos los nodos.
+ **Tamaño de los nodos: estado** dimensiona los nodos en función del número de solicitudes afectadas por errores, fallos o solicitudes limitadas.
+ **Tamaño de los nodos: tráfico** dimensiona los nodos según el número total de solicitudes.
------
# Visualización de rastros y detalles de rastros
Utilice la página **Rastros** de la consola de X-Ray para encontrar rastros por URL, código de respuesta u otros datos a partir del resumen de rastros. Tras seleccionar un rastro de la lista de rastros, la página de **Detalles de rastreo** muestra un mapa de los nodos de servicio asociados con el rastro seleccionado, junto con una escala de tiempo de los segmentos del rastro.
## Consulta de registros de seguimiento
------
#### [ CloudWatch console ]
**Para ver rastros en la consola de CloudWatch**
1. Inicie sesión en la Consola de administración de AWS y abra la consola de CloudWatch en [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. En el panel de navegación izquierdo, seleccione **Rastros de X-Ray** y, a continuación, **Rastros**. Puede filtrar por grupo o introducir una [expresión de filtro](xray-console-filters.md). De esta manera, se filtran los rastros que aparecen en la sección **Rastros**, en la parte inferior de la página.
También puede utilizar el mapa de servicio para ir a un nodo de servicio específico y, a continuación, ver los rastros. Esto abre la página de **rastros** con una consulta ya aplicada.
1. Acote su consulta en la sección **Limitadores de consultas**. Para filtrar los rastros por un atributo común, elija una opción en la flecha hacia abajo situada junto a **Ajustar consulta por**. Las opciones incluyen:
+ Nodo: filtra los rastros por nodo de servicio.
+ ARN del recurso: filtra los rastros por un recurso asociado a un rastro. Algunos ejemplos de estos recursos incluyen una instancia de Amazon Elastic Compute Cloud (Amazon EC2), una función de AWS Lambda o una tabla de Amazon DynamoDB.
+ Usuario: filtre los rastros con un ID de usuario.
+ Mensaje de causa raíz del error: filtra los rastros por la causa raíz del error.
+ URL: filtra los rastros por la ruta URL utilizada por la aplicación.
+ Código de estado HTTP: filtra los rastros por el código de estado HTTP devuelto por la aplicación. Puede especificar un código de respuesta personalizado o seleccionar una de las siguientes opciones:
+ `200`: la solicitud se ha realizado correctamente.
+ `401`: la solicitud carecía de credenciales de autenticación válidas.
+ `403`: la solicitud carecía de permisos válidos.
+ `404`: el servidor no pudo encontrar el recurso solicitado.
+ `500`: el servidor detectó una condición inesperada y generó un error interno.
Elija uno o más valores y seleccione **Agregar a consulta** para añadirlos a la expresión de filtro de la parte superior de la página.
1. Para encontrar un único rastro, escriba un [ID de rastro](xray-api-sendingdata.md#xray-api-traceids) directamente en el campo de consulta. Puede utilizar el formato de X-Ray o el formato del World Wide Web Consortium (W3C). Por ejemplo, un rastro que se crea con [AWS Distro para OpenTelemetry](xray-instrumenting-your-app.md#xray-instrumenting-opentel) tendrá el formato W3C.
**nota**
Al consultar rastros creados con un ID de rastro en formato W3C, la consola mostrará el rastro coincidente en formato X-Ray, por ejemplo. Por ejemplo, si realiza una consulta para `4efaaf4d1e8720b39541901950019ee5` en formato W3C, la consola muestra el equivalente de X-Ray: `1-4efaaf4d-1e8720b39541901950019ee5`.
1. Seleccione **Ejecutar consulta** en cualquier momento para visualizar una lista de rastros coincidentes en la sección **Rastros**, en la parte inferior de la página.
1. Elija un ID de rastro de la lista para mostrar la página **Detalles de la traza** de un solo rastro.
La siguiente imagen muestra un **mapa de rastros** que contiene los nodos de servicio asociados al rastro y la periferia entre los nodos que representan la ruta seguida por los segmentos que componen el rastro. Tras **Mapa de rastros**, aparece **Resumen de los rastros**. El resumen contiene información sobre una operación `GET` de ejemplo, su **código de respuesta**, la **duración** del rastreo y la **edad** de la solicitud. Tras **Resumen de los rastros** aparece **Línea temporal de los segmentos**, que muestra la duración de los segmentos y subsegmentos del rastro.
![\[La información de los nodos de servicio y los segmentos del rastro se detalla en un mapa de rastros, un resumen y el plazo de los segmentos.\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/xray-trace-details-cw.png)
Si tiene una aplicación basada en eventos que utiliza Amazon SQS y Lambda, puede ver una vista conectada de los rastros de cada solicitud en el **mapa de rastros**. En el mapa, los rastros de los productores de los mensajes están vinculados a los de los consumidores de AWS Lambda y se muestran como un borde discontinuo. Para obtener más información acerca de las aplicaciones basadas en eventos, consulte [Rastreo de aplicaciones basadas en eventos](xray-tracelinking.md).
Las páginas **Rastros** y **Detalles de rastros** también admiten el [rastreo entre cuentas](xray-console-crossaccount.md), ya que muestran los rastros de varias cuentas en la lista de rastros y en un solo mapa.
------
#### [ X-Ray console ]
**Para ver los rastros en la consola de X-Ray**
1. Abra la página [Rastros](https://console.aws.amazon.com/xray/home#/traces) de la consola de X-Ray. El panel **Información general del rastro** muestra una lista de rastros agrupados por características comunes, como las **causas raíz de los errores**, el **ARN de recurso** o el **InstanceID.**
1. Para seleccionar una característica común y ver un conjunto agrupado de rastros, expanda la flecha hacia abajo situada junto a **Agrupar por**. La siguiente ilustración muestra la información general de los rastros agrupados por URL en [AWS X-Ray ejemplo de aplicación](xray-scorekeep.md) y una lista de los rastros asociados.
![\[Ejemplo de información general del rastro agrupada por URL, seguida de una lista de rastros con detalles como el ID, el método y la respuesta.\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/scorekeep-traces.png)
1. Elija el **ID** de un rastro para verlo en la **lista de rastros**. También puede elegir **Mapa de servicios** en el panel de navegación para ver los rastros de un nodo de servicio en particular. A continuación, puede ver los rastros asociados a ese nodo.
La pestaña **Plazo** muestra el flujo de solicitudes del rastro e incluye lo siguiente:
+ Un mapa de la ruta de cada segmento del rastro.
+ Cuánto tiempo tarda el segmento en llegar a un nodo del mapa de rastros.
+ Cuántas solicitudes se realizaron al nodo del mapa de rastros.
En la siguiente ilustración se muestra un ejemplo de **mapa de rastros** asociado a una solicitud `GET` efectuada a una aplicación de ejemplo. Las flechas muestran la ruta que siguió cada segmento para completar la solicitud. Los nodos de servicio muestran el número de solicitudes realizadas durante la solicitud `GET`.
![\[Mapa de rastros seguido de una línea temporal con los segmentos, su duración, origen y final de uno respecto al otro.\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/xray-trace-details.png)
Para obtener más información sobre la pestaña **Plazo**, consulte la siguiente sección **Exploración de la escala de tiempo del rastro**.
La pestaña de **Datos sin formato** muestra información sobre el rastro y los segmentos y subsegmentos que lo componen, en formato `JSON`. Esta información puede incluir lo siguiente:
+ Marcas temporales
+ ID únicos
+ Recursos asociados al segmento o subsegmento
+ La fuente o el origen del segmento o subsegmento
+ Información adicional sobre la solicitud a su aplicación, como la respuesta de una solicitud HTTP
------
## Exploración de la escala de tiempo del rastro
La sección **Plazo** muestra una jerarquía de segmentos y subsegmentos junto a una barra horizontal que corresponde al tiempo que tardaron en completar sus tareas. La primera entrada de la lista es el segmento, que representa todos los datos registrados por el servicio para una misma solicitud. Los subsegmentos se representan tras una sangría y se enumeran a continuación del segmento. Las columnas contienen información sobre cada segmento.
------
#### [ CloudWatch console ]
En la consola de CloudWatch, **Línea temporal de los segmentos** proporciona la siguiente información:
+ La primera columna muestra los segmentos y subsegmentos del rastro seleccionado.
+ La columna **Estado del segmento** muestra el resultado del estado de cada segmento y subsegmento.
+ La columna **Código de respuesta** muestra un código de estado de respuesta HTTP a una solicitud del navegador realizada por el segmento o subsegmento, cuando está disponible.
+ La columna **Duración** muestra cuánto tiempo duró la ejecución del segmento o subsegmento.
+ La columna **Alojado en** muestra el espacio de nombre o el entorno en el que se ejecuta el segmento o subsegmento, si corresponde. Para obtener más información, consulte [Dimensions collected and dimension combinations](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AppSignals-StandardMetrics.html#AppSignals-StandardMetrics-Dimensions).
+ La última columna muestra barras horizontales que corresponden a la duración de la ejecución del segmento o subsegmento, en relación con los demás segmentos o subsegmentos de la línea de tiempo.
Para agrupar la lista de segmentos y subsegmentos por nodo de servicio, active **Agrupar por nodos**.
------
#### [ X-Ray console ]
En la página de detalles del rastro, seleccione la pestaña **Línea temporal** para ver la línea de tiempo de cada segmento y subsegmento que forma parte de un rastro.
En la consola de X-Ray, **Plazo** proporciona la siguiente información:
+ La columna **Nombre** muestra los nombres de los segmentos y subsegmentos del rastro.
+ La columna **Res.** muestra un código de estado de respuesta HTTP a una solicitud del navegador realizada por el segmento o subsegmento, cuando está disponible.
+ La columna **Duración** muestra cuánto tiempo duró la ejecución del segmento o subsegmento.
+ La columna **Estado** muestra el resultado del estado del segmento o subsegmento.
+ La última columna muestra barras horizontales que corresponden a la duración de la ejecución del segmento o subsegmento, en relación con los demás segmentos o subsegmentos de la línea de tiempo.
Para ver los datos de rastro sin procesar que la consola utiliza para generar la línea de tiempo, seleccione la pestaña **Datos sin formato**. Los datos sin procesar muestran información sobre el rastro y los segmentos y subsegmentos que lo componen en formato `JSON`. Esta información puede incluir lo siguiente:
+ Marcas temporales
+ ID únicos
+ Recursos asociados al segmento o subsegmento
+ La fuente o el origen del segmento o subsegmento
+ Información adicional sobre la solicitud a su aplicación, como la respuesta de una solicitud HTTP.
------
Cuando se utiliza un cliente del SDK de AWS, HTTP o SQL para realizar llamadas a recursos externos. el SDK de X-Ray registra los subsegmentos automáticamente. También puede emplear el SDK de X-Ray para registrar los subsegmentos personalizados de cualquier bloque de código o de funciones. Los subsegmentos adicionales que se registran mientras hay subsegmentos abiertos se convierten en elementos secundarios del subsegmento personalizado.
## Consulta de detalles de segmentos
En la sección **Plazo** del rastro, elija el nombre de un segmento para ver sus detalles.
El panel **Detalles del segmento** muestra las pestañas **Descripción general**, **Recursos**, **Anotaciones**, **Metadatos**, **Excepciones** y **SQL**. Se aplica lo siguiente:
+ En **Overview (Información general)** se muestra información acerca de la solicitud y la respuesta. La información incluye el nombre, la hora de inicio, la hora de finalización, la duración, la URL de la solicitud, la operación de la solicitud, el código de respuesta de la solicitud y cualquier error o fallo.
+ La pestaña **Recursos** de un segmento muestra información del SDK de X-Ray y sobre los recursos de AWS que se utilizan para ejecutar la aplicación. Utilice los complementos Amazon EC2, AWS Elastic Beanstalk o Amazon ECS para que el SDK de X-Ray registre información sobre los recursos específicos de los servicios. Para obtener más información sobre complementos, consulte **Complementos de servicio** en la [Configuración del SDK de X-Ray para Java](xray-sdk-java-configuration.md).
+ En las pestañas restantes (**Anotaciones**, **Metadatos** y **Excepciones**), se muestran las anotaciones, los metadatos y las excepciones que se registran en el segmento. Las excepciones se capturan automáticamente cuando las genera una solicitud instrumentada. Las anotaciones y los metadatos contienen información adicional que se registra utilizando las operaciones proporcionadas por el SDK de X-Ray. Para añadir anotaciones y metadatos a sus segmentos, use el SDK de X-Ray. Para obtener más información, consulte el enlace específico del idioma que aparece en la sección Cómo instrumentar su aplicación con los SDK de AWS X-Ray en [Instrumentación de su solicitud para AWS X-Ray](xray-instrumenting-your-app.md).
## Consulta de detalles de subsegmentos
En la escala de tiempo del rastro, elija el nombre de un segmento para ver sus detalles:
+ En la pestaña **Información general** se muestra información acerca de la solicitud y su respuesta. Incluye el nombre, la hora de inicio, la hora de finalización, la duración, la solicitud URL, la operación de solicitud, el código de respuesta a la solicitud y cualquier error o fallo. Para los subsegmentos generados con clientes instrumentados, la pestaña **Overview (Información general)** contiene información acerca de la solicitud y la respuesta desde el punto de vista de la aplicación.
+ La pestaña **Recursos** de un subsegmento muestra detalles sobre los recursos de AWS que se emplearon para ejecutar el subsegmento. Por ejemplo, la pestaña de recursos puede incluir un ARN de función de AWS Lambda, información sobre una tabla de DynamoDB, cualquier operación a la que se llame o un ID de solicitud.
+ En las pestañas restantes (**Anotaciones**, **Metadatos** y **Excepciones**), se muestran las anotaciones, los metadatos y las excepciones registrados en el subsegmento. Las excepciones se capturan automáticamente cuando las genera una solicitud instrumentada. Las anotaciones y los metadatos contienen información adicional que se registra utilizando las operaciones proporcionadas por el SDK de X-Ray. Utilice el SDK de X-Ray para agregar anotaciones o metadatos a sus segmentos. Para obtener más información, consulte el enlace específico del idioma que aparece en la sección Cómo instrumentar su aplicación con los SDK de AWS X-Ray en [Instrumentación de su solicitud para AWS X-Ray](xray-instrumenting-your-app.md).
En los subsegmentos personalizados, la pestaña **Información general** muestra el nombre del subsegmento, que se puede establecer de modo que especifique el área de código o la función que registra. Para obtener más información, consulte el enlace específico del idioma que aparece en la sección Cómo instrumentar su aplicación con los SDK de AWS X-Ray en [Generación de subsegmentos personalizados con el SDK de X-Ray para Java](xray-sdk-java-subsegments.md).
La siguiente imagen muestra la pestaña **Información general** de un subsegmento personalizado. El resumen contiene el ID del subsegmento, el ID principal, el nombre, las horas de inicio y finalización, la duración, el estado y los errores o fallos.
![\[Información general sobre un subsegmento, incluidos el ID, el ID principal, el nombre, las horas, los errores y los fallos.\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/scorekeep-PUTrules-customsubsegment-overview.png)
La pestaña **Metadatos** de un subsegmento personalizado contiene información en formato JSON sobre los recursos utilizados por ese subsegmento.
# Uso de expresiones de filtro
Utilice *expresiones de filtro* para ver un mapa de rastros o los rastros de una solicitud específica, un servicio específico o una conexión entre dos servicios (una periferia) o solicitudes que respondan a una condición. X-Ray proporciona un lenguaje de expresiones de filtro para filtrar solicitudes, servicios y periferias teniendo en cuenta los datos presentes en los encabezados de la solicitud, el estado de la respuesta y los campos indexados en los segmentos originales.
Al elegir un periodo de tiempo de registros de seguimiento para ver en la consola de X-Ray, puede obtener más resultados que los que la consola puede mostrar. En la esquina superior derecha, la consola muestra el número de registros de seguimiento que analiza y si hay más registros de seguimiento disponibles. Puede utilizar una expresión de filtro para reducir el número de resultados a tan solo los rastros que desea encontrar.
**Topics**
+ [Detalles de expresión de filtro](#xray-console-filters-details)
+ [Uso de expresiones de filtro con grupos](#groups)
+ [Sintaxis de expresiones de filtro](#console-filters-syntax)
+ [Palabras clave booleanas](#console-filters-boolean)
+ [Palabras clave numéricas](#console-filters-number)
+ [Palabras clave de cadenas](#console-filters-string)
+ [Palabras clave complejas](#console-filters-complex)
+ [función id](#console-filters-functions)
## Detalles de expresión de filtro
Cuando [elige un nodo en el mapa de rastros](xray-console-servicemap.md), la consola construye una expresión de filtro en función del nombre de servicio del nodo y los tipos de errores presentes en función de su selección. Para encontrar registros de seguimiento que muestren problemas de rendimiento o relacionados con solicitudes específicas, puede ajustar la expresión proporcionada por la consola, o bien crear la suya propia. Si añade anotaciones con el SDK de X-Ray, también puede filtrar en función de la presencia de una clave de anotación o el valor de una clave.
**nota**
Si elige un intervalo de tiempo relativo en el mapa de rastros y elige un nodo, la consola convierte el intervalo de tiempo a una hora absoluta de inicio y finalización. Para asegurarse de que los registros de seguimiento del nodo aparezcan en los resultados de búsqueda y evitar los tiempos de examen cuando el nodo no estaba activo, el intervalo de tiempo solo incluye las horas a las que el nodo envió registros de seguimiento. Si desea buscar con relación a la hora actual, puede volver a un intervalo de tiempo relativo en la página de registros de seguimiento y volver a analizar.
Si sigue habiendo más resultados disponibles de los que la consola puede mostrar, la consola muestra cuántos registros de seguimiento han coincidido y el número de registros de seguimiento analizados. El porcentaje que se muestra es el porcentaje del marco temporal seleccionado que se analizó. Para asegurarse de ver todos los registros de seguimiento coincidentes representados en los resultados, filtre aún más la expresión de filtro o seleccione un marco temporal más corto.
Para obtener los resultados más recientes en primer lugar, la consola comienza a analizar al final del intervalo de tiempo y va hacia atrás. Si hay un gran número de registros de seguimiento, pero pocos resultados, la consola divide el intervalo de tiempo en porciones y las analiza en paralelo. La barra de progreso muestra las partes del intervalo de tiempo que se han analizado.
![\[Progress bar showing 52% of time range scanned, with 49 matching traces found.\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/console-tracescan-parallel.png)
## Uso de expresiones de filtro con grupos
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.
Los grupos se identifican por su nombre o un nombre de recurso de Amazon (ARN) y contienen una expresión de filtro. El servicio compara los registros de seguimiento de entrada con la expresión y los almacena en consecuencia.
Puede crear y modificar grupos mediante el menú desplegable situado a la izquierda de la barra de búsqueda de expresiones de filtro.
**nota**
Si el servicio encuentra un error al evaluar un grupo, ese grupo deja de estar incluido en el procesamiento de los registros de seguimiento de entrada y se registra una métrica de error.
Para obtener más información acerca de los grupos, consulte [Configuración de grupos](xray-console-groups.md).
## Sintaxis de expresiones de filtro
Las expresiones de filtro pueden incluir una *palabra clave*, un *operador* único o binario y un *valor* para la comparación.
```
keyword operator value
```
Cada tipo de palabra clave tiene sus propios operadores. Por ejemplo, `responsetime` es una palabra clave numérica que se puede comparar con operadores relacionados con números.
**Example – solicitudes con tiempo de respuesta de más de 5 segundos**
```
responsetime > 5
```
Puede combinar varias expresiones en una expresión compuesta utilizando los operadores `AND` u `OR`.
**Example – solicitudes con duración total de 5 a 8 segundos**
```
duration >= 5 AND duration <= 8
```
Solo se detectan problemas con las palabras clave y los operadores sencillos en el nivel de registro de seguimiento. Si se produce un error posterior, pero la aplicación lo gestiona y no se muestra al usuario, este problema no se detectará al buscar con la palabra `error`.
Para encontrar registros de seguimiento con problemas posteriores, use las [palabras clave complejas](#console-filters-complex) `service()` y `edge()`. Estas palabras clave permiten aplicar un filtro de expresión a todos los nodos posteriores, a un único nodo posterior o a un límite entre dos nodos. Para obtener un mayor nivel de detalle, puede filtrar los servicios y los bordes con [la función id()](#console-filters-functions).
## Palabras clave booleanas
Los valores de palabra clave booleana son true o false. Utilícelas para encontrar registros de seguimiento que resultaron erróneos.
**Palabras clave booleanas**
+ `ok`: el código de estado de la respuesta fue 2XX Success.
+ `error`: el código de estado de la respuesta fue 4XX Client Error.
+ `throttle`: el código de estado de la respuesta fue 429 Too Many Requests.
+ `fault`: el código de estado de la respuesta fue 5XX Server Error.
+ `partial`: la solicitud tiene segmentos incompletos.
+ `inferred`: la solicitud tiene segmentos inferidos.
+ `first`: el elemento es el primero de una lista enumerada.
+ `last`: el elemento es el último de una lista enumerada.
+ `remote`: la entidad de causa raíz es remota.
+ `root`: la solicitud es el punto de entrada o el segmento raíz de un registro de seguimiento.
Los operadores booleanos encuentran aquellos segmentos en los que la clave especificada es `true` o `false`.
**Operadores booleanos**
+ none: la expresión es verdadera si la palabra clave es verdadera.
+ `!`: la expresión es verdadera si la palabra clave es falsa.
+ `=`,`!=`: compara el valor de la palabra clave con la cadena `true` o `false`. Estos operadores actúan igual que los demás, pero son más explícitos.
**Example – estado de respuesta es 2XX OK**
```
ok
```
**Example – el estado de respuesta no es 2XX OK**
```
!ok
```
**Example – el estado de respuesta no es 2XX OK**
```
ok = false
```
**Example – el último registro de seguimiento de error enumerado tiene el nombre de error "deserialize"**
```
rootcause.fault.entity { last and name = "deserialize" }
```
**Example – solicitudes con segmentos remotos donde la cobertura es mayor que 0.7 y el nombre del servicio es "rastros"**
```
rootcause.responsetime.entity { remote and coverage > 0.7 and name = "traces" }
```
**Example : solicitudes con segmentos inferidos donde el tipo de servicio "AWS:DynamoDB"**
```
rootcause.fault.service { inferred and name = traces and type = "AWS::DynamoDB" }
```
**Example – solicitudes que tienen un segmento con el nombre "data-plane" como raíz.**
```
service("data-plane") {root = true and fault = true}
```
## Palabras clave numéricas
Utilice palabras clave numéricas para buscar solicitudes con un tiempo de respuesta, duración o estado de respuesta específico.
**Palabras clave numéricas**
+ `responsetime`: tiempo que tardó el servidor en enviar una respuesta.
+ `duration`: duración total de la solicitud, incluidas las llamadas posteriores.
+ `http.status`: código de estado de respuesta.
+ `index`: posición de un elemento en una lista.
+ `coverage`: porcentaje decimal del tiempo de respuesta de una entidad con respecto al tiempo de respuesta del segmento raíz. Aplicable únicamente a las entidades de causa raíz de tiempo de respuesta.
**Operadores numéricos**
Las palabras clave numéricas usan los operadores de comparación y de igualdad estándar.
+ `=`,`!=`: la palabra clave es igual o no a un valor numérico.
+ `<`,`<=`, `>`,`>=`: la palabra clave es menor o igual a un valor numérico.
**Example – el estado de respuesta no es 200 OK**
```
http.status != 200
```
**Example – solicitud con duración total de 5 a 8 segundos**
```
duration >= 5 AND duration <= 8
```
**Example – solicitudes que se completaron sin errores en menos de 3 segundos, incluidas todas las llamadas posteriores**
```
ok !partial duration <3
```
**Example – entidad de lista enumerada que tiene un índice mayor que 5**
```
rootcause.fault.service { index > 5 }
```
**Example : solicitudes en las que la última entidad tiene una cobertura superior a 0.8**
```
rootcause.responsetime.entity { last and coverage > 0.8 }
```
## Palabras clave de cadenas
Usa cadenas de palabras clave para encontrar trazas con un texto específico en los encabezados de las solicitudes o para encontrar un usuario IDs específico.
**Palabras clave de cadenas**
+ `http.url`: URL de solicitud.
+ `http.method`: método de solicitud.
+ `http.useragent`: cadena del agente de usuario de la solicitud.
+ `http.clientip`: dirección IP del solicitante.
+ `user`: valor del campo de usuario en cualquier segmento incluido en el registro de seguimiento.
+ `name`: el nombre de un servicio o excepción.
+ `type`: tipo de servicio.
+ `message`: mensaje de excepción.
+ `availabilityzone`: valor del campo availabilityzone de cualquier segmento incluido en el registro de seguimiento
+ `instance.id`: valor del campo de ID de instancia de cualquier segmento incluido en el registro de seguimiento
+ `resource.arn`: valor de campo ARN del recurso de cualquier segmento incluido en el registro de seguimiento
Los operadores de cadena permiten encontrar valores iguales a un texto determinado o que contienen dicho texto. Estos valores se deben escribir siempre entre comillas.
**Operadores de cadena**
+ `=`,`!=`: la palabra clave es igual o no a un valor numérico.
+ `CONTAINS`: la palabra clave contiene una cadena concreta.
+ `BEGINSWITH` , `ENDSWITH`: la palabra clave comienza o termina con una cadena concreta.
**Example – filtro http.url**
```
http.url CONTAINS "/api/game/"
```
Para probar si un registro de seguimiento incluye un campo, independientemente de su valor, compruebe si la cadena está vacía.
**Example – filtro user**
Encuentra todos los rastros con el usuario IDs.
```
user CONTAINS ""
```
**Example – seleccione los registros de seguimiento con una causa raíz de error que incluyan el servicio denominado "Auth"**
```
rootcause.fault.service { name = "Auth" }
```
**Example – seleccione los registros de seguimiento con una causa raíz de tiempo de respuesta cuyo último servicio tenga un tipo de DynamoDB**
```
rootcause.responsetime.service { last and type = "AWS::DynamoDB" }
```
**Example – seleccione los registros de seguimiento con una causa raíz de error cuya última excepción tenga el mensaje "access denied for account\$1id: 1234567890"**
```
rootcause.fault.exception { last and message = "Access Denied for account_id: 1234567890"
```
## Palabras clave complejas
Utilice palabras clave complejas para buscar solicitudes basadas en nombre del servicio, nombre de borde o valor de anotación. Para servicios y límites, puede especificar una expresión de filtro adicional que se aplica al servicio o al límite. Para anotaciones, puede filtrar por el valor de una anotación con una clave específica, utilizando operadores booleanos, numéricos o de cadena.
**Palabras clave complejas**
+ `annotation[key]`— Valor de una anotación con campo. *key* Una anotación puede tener un valor booleano, numérico o de cadena, por lo que puede usar cualquiera de estos tipos de operadores de comparación. Puede utilizar esta palabra clave en combinación con la palabra clave `service` o `edge`. Una clave de anotación que contenga puntos debe aparecer entre corchetes (**[ ]**).
+ `edge(source, destination) {filter}`— Conexión entre servicios *source* y. *destination* Las llaves opcionales pueden contener una expresión de filtro que se aplica a los segmentos de esta conexión.
+ `group.name / group.arn`:l valor de la expresión de filtro de un grupo, al que se hace referencia mediante el nombre del grupo o el ARN del grupo.
+ `json`: objeto de causa raíz JSON. Consulte [Obtener datos de AWS X-Ray](xray-api-gettingdata.md) para ver los pasos para crear entidades JSON mediante programación.
+ `service(name) {filter}`— Servicio con nombre. *name* Las llaves opcionales pueden contener una expresión de filtro que se aplica a los segmentos que creó el servicio.
Utilice la palabra clave service para encontrar los rastros de las solicitudes que se encuentran en un nodo determinado de su mapa de rastros.
Los operadores de palabras clave complejas buscan segmentos en los que se haya establecido o no se haya establecido la clave especificada.
**Operadores de palabras clave complejas**
+ none: la expresión es verdadera si la palabra clave está establecida. Si la palabra clave es de tipo booleano, se evaluará en función del valor booleano.
+ `!`: la expresión es verdadera si la palabra clave no está establecida. Si la palabra clave es de tipo booleano, se evaluará en función del valor booleano.
+ `=`,`!=`: compara el valor de la palabra clave.
+ `edge(source, destination) {filter}`— Conexión entre servicios *source* y*destination*. Las llaves opcionales pueden contener una expresión de filtro que se aplica a los segmentos de esta conexión.
+ `annotation[key]`— Valor de una anotación con campo. *key* Una anotación puede tener un valor booleano, numérico o de cadena, por lo que puede usar cualquiera de estos tipos de operadores de comparación. Puede utilizar esta palabra clave en combinación con la palabra clave `service` o `edge`.
+ `json`: objeto de causa raíz JSON. Consulte [Obtener datos de AWS X-Ray](xray-api-gettingdata.md) para ver los pasos para crear entidades JSON mediante programación.
Utilice la palabra clave service para encontrar los rastros de las solicitudes que se encuentran en un nodo determinado de su mapa de rastros.
**Example – filtro Service**
Solicitudes que incluyen una llamada a `api.example.com` con un error (error de la serie 500).
```
service("api.example.com") { fault }
```
Puede excluir el nombre del servicio para aplicar un filtro de expresión a todos los nodos de su mapa de servicios.
**Example – filtro service**
Solicitudes que provocan un error en cualquier ubicación de su mapa de rastros.
```
service() { fault }
```
La palabra clave edge aplica una expresión de filtro a una conexión entre dos nodos.
**Example – filtro edge**
Solicitud en la que el servicio `api.example.com` hizo una llamada a `backend.example.com` que resultó errónea.
```
edge("api.example.com", "backend.example.com") { error }
```
También puede utilizar el operador `!` con las palabras clave service y edge para excluir un servicio o un límite de los resultados de otra expresión de filtro.
**Example – filtro service y de solicitud**
Solicitud cuya URL comienza por `http://api.example.com/` y contiene `/v2/`, pero no llega al servicio denominado `api.example.com`.
```
http.url BEGINSWITH "http://api.example.com/" AND http.url CONTAINS "/v2/" AND !service("api.example.com")
```
**Example — filtro service y de tiempo de respuesta**
Busque rastros en los que esté establecido `http url` y el tiempo de respuesta sea superior a 2 segundos.
```
http.url AND responseTime > 2
```
Para las anotaciones, puede llamar a todos los rastros en los que esté establecido `annotation[key]` o utilizar los operadores de comparación que correspondan al tipo de valor.
**Example – anotación con un valor de cadena**
Las solicitudes con una anotación denominada `gameid` que tiene el valor de cadena `"817DL6VO"`.
```
annotation[gameid] = "817DL6VO"
```
**Example – la anotación está establecida**
Solicitudes que tienen establecida una anotación denominada `age`.
```
annotation[age]
```
**Example – la anotación no está establecida**
Solicitudes que no tienen establecida una anotación denominada `age`.
```
!annotation[age]
```
**Example – anotación con un valor numérico**
Solicitudes con una edad de anotación con valor numérico mayor que 29.
```
annotation[age] > 29
```
**Example – anotación en combinación con service o edge**
```
service { annotation[request.id] = "917DL6VO" }
```
```
edge { source.annotation[request.id] = "916DL6VO" }
```
```
edge { destination.annotation[request.id] = "918DL6VO" }
```
**Example – grupo con usuario**
Solicitudes en las que los rastros cumplan los criterios del filtro de grupo `high_response_time` (p. ej.`responseTime > 3`) y el nombre del usuario sea Alice.
```
group.name = "high_response_time" AND user = "alice"
```
**Example – JSON con entidad de causa raíz**
Solicitudes con entidades de causa raíz coincidentes.
```
rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]
```
## función id
Cuando se proporciona un nombre de servicio a las palabras clave `service` o `edge`, se obtienen resultados de todos los nodos que tienen ese nombre. Si desea filtrar de manera más precisa, puede utilizar la función `id` para especificar un tipo de servicio, además de un nombre, para diferenciar los nodos con el mismo nombre.
Utilice la función `account.id` para especificar una cuenta concreta para el servicio cuando consulte rastros de varias cuentas de una cuenta de supervisión.
```
id(name: "service-name", type:"service::type", account.id:"account-ID")
```
Puede utilizar la función `id` en lugar de un nombre de servicio en los filtros service y edge.
```
service(id(name: "service-name", type:"service::type")) { filter }
```
```
edge(id(name: "service-one", type:"service::type"), id(name: "service-two", type:"service::type")) { filter }
```
Por ejemplo, AWS Lambda las funciones dan como resultado dos nodos en el mapa de rastreo: uno para la invocación de la función y otro para el servicio Lambda. Los dos nodos tienen el mismo nombre pero son de diferente tipo. Un filtro service estándar permite encontrar registros de seguimiento para ambos.
**Example – filtro service**
Solicitudes que incluyen un error en cualquier servicio denominado `random-name`.
```
service("random-name") { error }
```
Utilice la función `id` para limitar la búsqueda a los errores de la propia función, sin incluir los errores del servicio.
**Example – filtro service con la función id**
Solicitudes que incluyen un error en un servicio denominado `random-name` de tipo `AWS::Lambda::Function`.
```
service(id(name: "random-name", type: "AWS::Lambda::Function")) { error }
```
Si desea buscar nodos por tipo, también puede excluir el nombre por completo.
**Example – filtro service con la función id y tipo de servicio**
Solicitudes que incluyen un error en un servicio de tipo `AWS::Lambda::Function`.
```
service(id(type: "AWS::Lambda::Function")) { error }
```
Para buscar nodos para un nodo concreto Cuenta de AWS, especifique un ID de cuenta.
**Example – filtro service con función id e ID de cuenta**
Solicitudes que incluyen un servicio dentro de un identificador de cuenta específico `AWS::Lambda::Function`.
```
service(id(account.id: "account-id"))
```
# Rastreo entre cuentas
AWS X-Ray admite la *observabilidad entre cuentas*, lo que permite al usuario supervisar y solucionar problemas en las aplicaciones que abarcan varias cuentas de una Región de AWS. Puede buscar, visualizar y analizar sin problemas sus métricas, registros y rastros en cualquiera de las cuentas vinculadas, como si estuviera operando en una sola cuenta. Eso le proporciona una vista completa de las solicitudes que se transfieren a varias cuentas. Puede ver los rastros entre cuentas en el mapa de rastros de X-Ray y en las páginas de rastros de la [consola de CloudWatch](https://console.aws.amazon.com/cloudwatch/).
Los datos de observabilidad compartidos pueden incluir cualquiera de los siguientes tipos de telemetría:
+ Métricas en Amazon CloudWatch
+ Grupos de registro de Amazon CloudWatch Logs
+ Trazas en AWS X-Ray
+ Aplicaciones en Información de aplicaciones de Amazon CloudWatch
## Configuración de la observabilidad entre cuentas
Para activar la observabilidad entre cuentas, configure una o más cuentas de *supervisión* de AWS y vincúlelas a varias cuentas de *origen*. Una cuenta de supervisión es una Cuenta de AWS central que puede ver los datos de observabilidad generados a partir de las cuentas de origen e interactuar con ellos. Una cuenta de origen es una Cuenta de AWS individual que genera datos de observabilidad para los recursos que residen en ella.
Las cuentas de origen comparten sus datos de observabilidad con cuentas de supervisión. Los rastros de cada cuenta de origen se copian en un máximo de cinco cuentas de supervisión. Las copias de los rastros de las cuentas de origen en la primera cuenta de supervisión son gratuitas. Las copias de rastros enviadas a cuentas de supervisión adicionales se cargan a cada cuenta de origen, según el precio estándar. Para obtener más información consulte [Precios de AWS X-Ray](https://aws.amazon.com/xray/pricing/) y [Precios de Amazon CloudWatch](https://aws.amazon.com/cloudwatch/pricing/).
Para crear enlaces entre las cuentas de supervisión y las de origen, use la consola de CloudWatch o los nuevos comandos de Observability Access Manager de la AWS CLI y la API. Para obtener más información, consulte [(Observabilidad entre cuentas de CloudWatch)](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Unified-Cross-Account.html).
**nota**
Los rastros de X-Ray se cargan en la Cuenta de AWS en la que se reciben. Si una solicitud [muestreada](xray-concepts.md#xray-concepts-sampling) abarca varios servicios de más de una Cuenta de AWS, cada cuenta registra un rastro independiente y todos los rastros comparten el mismo ID de rastro. Para obtener más información sobre los precios de la observabilidad entre cuentas, consulte [Preciso de AWS X-Ray](https://aws.amazon.com/xray/pricing/) y [Precios de Amazon CloudWatch](https://aws.amazon.com/cloudwatch/pricing/).
## Visualización de rastros entre cuentas
Los rastros entre cuentas se muestran en la cuenta de supervisión. Cada cuenta de origen muestra solo los rastros locales de esa cuenta específica. En las siguientes secciones se presupone que ha iniciado sesión en la cuenta de supervisión y ha abierto la consola de Amazon CloudWatch. Tanto en el mapa de rastros como en la página de rastros, aparece una insignia de cuenta de supervisión en la esquina superior derecha.
![\[Insignia de la cuenta de supervisión\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/crossaccount-monitoring-account.png)
### Mapa de rastros
En la consola de CloudWatch, seleccione **Mapa de rastros** en **Rastros de X-Ray**, en el panel de navegación izquierdo. De forma predeterminada, el mapa de rastros muestra los nodos de todas las cuentas de origen que envían rastros a la cuenta de supervisión y los nodos de la propia cuenta de supervisión. En el mapa de rastros, elija **Filtros** en la esquina superior izquierda para filtrar dicho mapa mediante el menú desplegable **Cuentas**. Una vez que se aplica un filtro de cuenta, los nodos de servicio de las cuentas que no coincidan con el filtro actual aparecen en color gris.
![\[Mapa de rastros filtrado\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/crossaccount-servicemap-account-filter.png)
Al elegir un nodo de servicio, el panel de detalles del nodo incluye el identificador de cuenta y la etiqueta del servicio.
![\[Panel de detalles del nodo\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/crossaccount-servicemap-node-detail.png)
En la esquina superior derecha del mapa de rastros, elija **Vista de lista** para ver una lista de nodos de servicio. La lista de nodos de servicio incluye los servicios de la cuenta de supervisión y todas las cuentas de origen configuradas. Filtre la lista de nodos por **Etiqueta de cuenta** o por **ID de cuenta** seleccionándolos en el filtro de **Nodos**.
![\[Lista de servicios filtrada\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/crossaccount-servicelist-account-filter.png)
### Registros de seguimiento
Para ver los detalles de los rastros que abarcan varias cuentas, abra la consola de CloudWatch desde la cuenta de supervisión y elija **Rastros** en **Rastros de X-Ray** en el panel de navegación izquierdo. Para abrir esta página también puede seleccionar un nodo en el **mapa de rastros** de X-Ray y, a continuación, seleccionar **Ver rastros** en el panel de detalles del nodo.
La página **Rastros** permite realizar consultas por ID de cuenta. Para empezar, [introduzca una consulta](xray-console-filters.md) que incluya uno o más ID de cuenta. En el siguiente ejemplo se consultan rastros que hayan pasado por el ID de cuenta X* *o *Y*:
```
service(id(account.id:"X")) OR service(id(account.id:"Y"))
```
![\[Consulta de rastros por cuenta\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/crossaccount-traces-query-by-account.png)
Acote su consulta por **Cuenta**. Seleccione una o más cuentas de la lista y elija **Añadir a la consulta**.
![\[Consulta de rastros acotada por cuenta\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/crossaccount-traces-refine-by-account.png)
### Detalles de rastros
Para ver los detalles de una rastro, selecciónelo en la lista **Rastros** situada en la parte inferior de la página de **Rastros**. Se muestran los **detalles de rastro**, incluido un mapa de detalles del rastro con los nodos de servicio de todas las cuentas por las que ha pasado el rastro. Elija un nodo de servicio específico para ver su cuenta correspondiente.
La sección **Escala de tiempo de los segmentos** muestra los detalles de la cuenta de cada segmento en la escala de tiempo.
![\[Escala de tiempo de los segmentos\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/crossaccount-traces-segment-timeline.png)
# Rastreo de aplicaciones basadas en eventos
AWS X-Ray admite el rastreo de aplicaciones basadas en eventos mediante Amazon SQS y AWS Lambda. Utilice la consola de CloudWatch para ver una vista conectada de cada solicitud a medida que se pone en cola con Amazon SQS y la procesa una o más funciones de Lambda. Los rastros de los productores de mensajes anteriores se vinculan automáticamente a los rastros de los nodos de consumidor de Lambda posteriores, lo que crea una vista integral de toda la aplicación.
**nota**
Cada segmento de rastro se puede vincular a un máximo de 20 rastros, mientras que un rastro puede incluir un máximo de 100 enlaces. En algunos escenarios, vincular rastros adicionales puede hacer que se exceda el [tamaño máximo de documento de rastro](https://docs.aws.amazon.com/general/latest/gr/xray.html#limits_xray), lo que podría provocar un rastro incompleto. Esto puede suceder, por ejemplo, cuando una función de Lambda con el rastreo habilitado envía muchos mensajes SQS a una cola en una única invocación. Si se produce este problema, hay disponible una solución de mitigación que utiliza los SDK de X-Ray. Consulte el SDK de X-Ray para [Java](https://github.com/aws/aws-xray-sdk-java#oversampling-mitigation), [Node.js](https://github.com/aws/aws-xray-sdk-node/tree/master/packages/core#oversampling-mitigation), [Python](https://github.com/aws/aws-xray-sdk-python#oversampling-mitigation), [Go](https://github.com/aws/aws-xray-sdk-go#oversampling-mitigation) o [o.NET](https://github.com/aws/aws-xray-sdk-dotnet#oversampling-mitigation) para obtener más información.
## Visualización de rastros vinculados en el mapa de rastros
Utilice la página **mapa de rastros** de la [consola de CloudWatch](https://console.aws.amazon.com/cloudwatch/) para ver un mapa de rastros con los rastros de los productores de mensajes que están vinculados a los rastros de los consumidores de Lambda. Estos vínculos se muestran con un borde discontinuo que conecta el nodo de Amazon SQS y los nodos de consumidores de Lambda posteriores.
![\[Borde entre los nodos de Amazon SQS y Lambda.\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/console-batch-servicemap-linkededge.png)
Seleccione un borde discontinuo para mostrar un histograma de *antigüedad del evento recibido*, que correlaciona la distribución de la antigüedad del evento cuando lo reciben los consumidores. La antigüedad se calcula cada vez que se recibe un evento.
![\[Borde con el histograma de antigüedad del evento recibido.\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/console-servicemap-linkededgedetails-cw.png)
## Visualización de detalles de rastro vinculados
**Vea los detalles de rastro enviados desde un productor de mensajes, una cola de Amazon SQS o un consumidor de Lambda:**
1. Utilice el **mapa de rastros** para seleccionar un nodo de productor de mensajes, Amazon SQS o consumidor de Lambda.
1. Seleccione **Ver rastros** en el panel de detalles del nodo para ver una lista de rastros. También puede ir directamente a la página **Rastros** en la consola de CloudWatch.
1. Elija un rastro específico de la lista para abrir la página de detalles de ese rastro. La página de detalles del rastro muestra un mensaje cuando el rastro seleccionado forma parte de un conjunto de rastros vinculados.
![\[Detalles de rastros vinculados\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/console-batch-tracedetails-header.png)
Los datos del mapa de rastros muestra el rastro actual, junto con los rastros vinculados precedentes y posteriores, cada uno de las cuales se encuentra dentro de un recuadro que indica los límites de cada rastro. Si el rastro actualmente seleccionado está vinculado a varios rastros precedentes o posteriores, los nodos que están dentro de los rastros vinculados precedentes o posteriores se apilan y aparece el botón **Seleccionar rastro**.
![\[Varios rastros precedentes vinculados\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/console-batch-tracedetails-tracemap.png)
Debajo de los datos del mapa de rastros, se muestra una escala de tiempo de los segmentos de rastros, incluidos los rastros precedentes y posteriores vinculados. Si hay varios rastros precedentes y posteriores vinculados, no se pueden mostrar los detalles de sus segmentos. Para ver los detalles del segmento de una solo rastro dentro de un conjunto de rastros vinculados, [seleccione un solo rastro](#xray-tracelinking-filterbatch) como se describe a continuación.
![\[Escala de tiempo de segmentos en la que se pueden ver los rastros vinculados\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/console-batch-tracedetails-timeline.png)
## Selección de un solo rastro dentro de un conjunto de rastros vinculados
**Filtre un conjunto vinculado de rastros para seleccionar un solo rastro y ver los detalles del segmento en la escala de tiempo.**
1. Elija **Seleccionar rastro** debajo de los rastros vinculados en el mapa de datos del rastro. Aparece una lista de rastros.
![\[Lista de rastros vinculados\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/console-batch-tracedetails-tracelist.png)
1. Seleccione el botón de opción situado junto al rastro para el rastro en el mapa de datos de rastro.
1. Elija **Cancelar la selección de rastro** para ver todo el conjunto de rastros vinculados.
![\[Un solo rastro vinculado\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/console-batch-tracedetails-filteredbatch.png)
# Uso de histogramas de latencia
Al seleccionar un nodo o un borde en un [mapa de rastros](xray-console-servicemap.md) de AWS X-Ray, la consola de X-Ray muestra un histograma de distribución de latencias.
## Latencia
La latencia es el tiempo que transcurre entre el momento de iniciar una solicitud y el momento de completarla. Los histogramas muestran una distribución de las latencias. Muestran la duración en el eje x y el porcentaje de solicitudes de cada duración en el eje y.
Este histograma muestra un servicio que completa la mayor parte de las solicitudes en menos de 300 ms. Un pequeño porcentaje de solicitudes tarda hasta 2 segundos y unos cuantos casos atípicos tardan más tiempo.
![\[Histograma de latencias con la duración en el eje x y el porcentaje de solicitudes de cada duración en el eje y.\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/scorekeep-servicemap-histogram.png)
## Interpretación de los detalles del servicio
Los histogramas de servicio y los histogramas de límites constituyen una representación visual de latencia desde el punto de vista de un servicio o de un solicitante.
+ Elija un *nodo de servicio* haciendo clic en el círculo. X-Ray muestra un histograma de las solicitudes que atiende el servicio. Las latencias son las que registra el servicio y no incluyen ninguna latencia de red entre el servicio y el solicitante.
+ Elija un *borde* haciendo clic en la línea o en la punta de flecha del borde entre dos servicios. X-Ray muestra un histograma de las solicitudes del solicitante atendidas por el servicio posterior. Las latencias son las que ha registrado el solicitante e incluyen la latencia de la conexión de red entre los dos servicios.
Para interpretar el panel de histograma **Service details**, puede buscar los valores que más difieran de la mayoría de valores del histograma. Estos *valores atípicos* pueden aparecer como picos o puntas en el histograma y puede analizar los rastros de un área específica para averiguar lo que sucede.
Para ver los rastros filtrados por latencia, seleccione un intervalo en la histograma. Haga clic donde desee iniciar la selección y arrastre de izquierda a derecha para resaltar el intervalo de latencias que quiera incluir en el filtro de rastros.
![\[Seleccione un intervalo cuyos rastros desea ver haciendo clic en el punto inicial y arrastrando de izquierda a derecha para crear el intervalo del filtro de trazos\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/scorekeep-servicemap-servicedetails-selection.png)
Una vez seleccionado el intervalo, puede elegir **Zoom (Zoom)** para ver solo esa parte del histograma y retocar la selección.
![\[Elija zoom para ver el intervalo seleccionado en el histograma\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/scorekeep-servicemap-servicedetails-zoom.png)
Una vez establecido el enfoque en el área que desea, elija **View traces (Ver rastros)**.
# Uso de información en X-Ray
AWS X-Ray analiza continuamente los datos de rastro de su cuenta para identificar problemas emergentes en sus aplicaciones. Cuando las tasas de fallo superan el rango esperado, se crea una *información* que registra el problema y hace un seguimiento de su impacto hasta que se resuelve. Con la información, puede:
+ Identificar en qué parte de su aplicación se ha producido el problema, la causa raíz del problema y el impacto asociado. El análisis de impacto que proporciona la información le permite deducir la gravedad y la prioridad de un problema.
+ Reciba notificaciones a medida que el problema cambie con el tiempo. Puede integrar las notificaciones de información en su solución de supervisión y alertas mediante Amazon EventBridge. Esta integración le permite enviar correos electrónicos o alertas automatizados en función de la gravedad del problema.
La consola de X-Ray identifica los nodos con incidentes en curso en el mapa de rastros. Para ver un resumen de la información, elija el nodo afectado. También puede ver y filtrar la seleccionando **Información** en el panel de navegación de la izquierda.
![\[Nodo del mapa de rastros con resumen de información.\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/console-insights-servicemap.png)
X-Ray crea información cuando detecta una *anomalía* en uno o más nodos del mapa de servicio. El servicio utiliza modelos estadísticos para predecir las tasas de fallo que cabe esperar de los servicios de su aplicación. En el ejemplo anterior, la anomalía es un aumento de los fallos de AWS Elastic Beanstalk. El servidor de Elastic Beanstalk agotó varias veces los tiempos de espera de llamadas a la API, lo que provocó una anomalía en los nodos posteriores.
## Habilitación de la información en la consola de X-Ray
La información debe estar habilitada para cada grupo con el que desee utilizar las características de información. Puede activar la información desde la página **Grupos**.
1. Abra la [consola de X-Ray](https://console.aws.amazon.com/xray/home#).
1. Seleccione un grupo existente o cree uno nuevo seleccionando **Crear grupo** y, a continuación, seleccione **Habilitar Información**. Para obtener más información acerca de la configuración de grupos en la consola de X-Ray, consulte [Configuración de grupos](xray-console-groups.md).
1. En el panel de navegación de la izquierda, elija **Información** y, luego, elija la información que desee ver.
![\[Lista de informaciones en la consola de X-Ray\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/console-insights.png)
**nota**
X-Ray utiliza las operaciones de las API de GetInsightSummaries, GetInsight, GetInsightEvents y GetInsightImpactGraph API para recuperar datos de la información.
Para obtener más información, consulte [Cómo AWS X-Ray funciona con IAM](security_iam_service-with-iam.md).
## Habilitación de notificaciones de la información
Con las notificaciones de información, se crea una notificación para cada evento de información, por ejemplo, cuando se crea una información, cambia significativamente o se cierra. Los clientes pueden recibir estas notificaciones a través de eventos de Amazon EventBridge y utilizar reglas condicionales para realizar acciones como la notificación de SNS, la invocación a Lambda, la publicación de mensajes en una cola de SQS o cualquiera de los destinos compatibles con EventBridge. Las notificaciones de información se emiten en la medida de lo posible, pero no están garantizadas. Para obtener más información sobre destinos, consulte [Destinos de Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-targets.html).
En la página **Grupos** puede habilitar las notificaciones de información para cualquier grupo que tenga información habilitada.
**Habilitación de notificaciones para un grupo de X-Ray**
1. Abra la [consola de X-Ray](https://console.aws.amazon.com/xray/home#).
1. Seleccione un grupo existente o cree uno nuevo seleccionando **Crear grupo**, asegúrese de que **Habilitar información** esté seleccionado y, a continuación, seleccione **Habilitar Información**. Para obtener más información acerca de la configuración de grupos en la consola de X-Ray, consulte [Configuración de grupos](xray-console-groups.md).
**Configuración de las reglas condicionales de Amazon EventBridge**
1. Abra la [consola de Amazon EventBridge](https://console.aws.amazon.com/events/home).
1. Vaya a **Reglas** en la barra de navegación izquierda y elija **Crear regla**.
1. Escriba un nombre y una descripción para la regla.
1. Elija **Patrón de eventos** y, a continuación, **Patrón personalizado**. Proporcione un patrón que contenga `"source": [ "aws.xray" ]` y `"detail-type": [ "AWS X-Ray Insight Update" ]`. A continuación se muestran algunos ejemplos de posibles patrones.
+ Patrón de eventos que coincide con todos los eventos entrantes de información de X-Ray:
```
{
"source": [ "aws.xray" ],
"detail-type": [ "AWS X-Ray Insight Update" ]
}
```
+ Patrón de eventos que coincide con un valor especificado de **state** y **category**:
```
{
"source": [ "aws.xray" ],
"detail-type": [ "AWS X-Ray Insight Update" ],
"detail": {
"State": [ "ACTIVE" ],
"Category": [ "FAULT" ]
}
}
```
1. Seleccione y configure los destinos que desee invocar cuando un evento cumpla esta regla.
1. (Opcional) Proporcione etiquetas para identificar y seleccionar esta regla con mayor facilidad.
1. Seleccione **Crear**.
**nota**
Las notificaciones de información de X-Ray envían eventos a Amazon EventBridge, que actualmente no admite claves administradas por el cliente. Para obtener más información, consulte [Protección de los datos en AWS X-Ray](xray-console-encryption.md).
## Visión general acerca de la información
En la página de información general de una información se intenta responder a tres preguntas clave:
+ ¿Cuál es el problema de fondo?
+ ¿Cuál es la causa raíz?
+ ¿Cuál es el impacto?
La sección **Servicios anómalos** muestra una escala de tiempo para cada servicio que ilustra el cambio en las tasas de fallo durante el incidente. La escala de tiempo muestra el número de rastros con fallos superpuestos en una banda continua que indica el número esperado de fallos en función de la cantidad de tráfico registrada. La duración de la información se visualiza en la *ventana de incidentes*. La ventana de incidentes comienza cuando X-Ray observa que la métrica se vuelve anómala y persiste mientras la información está activa.
En el siguiente ejemplo se muestra un aumento en el número de fallos, lo que ha provocado un incidente:
![\[Página de información general de una información de X-Ray\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/console-insights-overview.png)
La sección **Causa raíz** muestra un mapa de rastros centrado en el servicio de la causa raíz y la ruta afectada. Puede ocultar los nodos no afectados seleccionando el icono en forma de ojo en la parte superior derecha del mapa de la causa raíz. El servicio de causa raíz es el nodo posterior más alejado en el que X-Ray identificó una anomalía. Puede representar un servicio que usted instrumentó o un servicio externo al que su servicio llamó con un cliente instrumentado. Por ejemplo, si llama a Amazon DynamoDB con un cliente instrumentado del SDK de AWS, un aumento del número de falos de DynamoDB da como resultado una información con DynamoDB como causa principal.
Para investigar más a fondo la causa raíz, seleccione **Ver los detalles de la causa raíz** en el gráfico de la causa raíz. Puede usar la página **Análisis** para investigar la causa raíz y los mensajes relacionados con ella. Para obtener más información, consulte [Interacción con la consola de Analytics](xray-console-analytics.md).
![\[Página de información general de una información de X-Ray\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/console-insights-root-cause.png)
Los fallos que continúan hacia arriba en el mapa pueden afectar a varios nodos y provocar múltiples anomalías. Si un fallo se transfiere hasta el usuario que realizó la solicitud, el resultado es un *fallo de cliente*. Se trata de un fallo en el nodo raíz del mapa de rastros. El gráfico **Impacto** proporciona una escala de tiempo de la experiencia del cliente para todo el grupo. Esta experiencia se calcula en función de los porcentajes de los siguientes estados: **fallo**, **error**, **limitación** y **bien**.
![\[Gráfico de impacto de un incidente de X-Ray\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/console-insights-impact.png)
En este ejemplo se muestra un aumento en el número de rastros con un fallo en el nodo raíz durante el momento de un incidente. Los incidentes en los servicios posteriores no siempre se corresponden con un aumento de los errores de cliente.
Al elegir **Analizar información**, se abre la consola de X-Ray Analytics en una ventana en la que se puede profundizar en el conjunto de rastros que han generado la información. Para obtener más información, consulte [Interacción con la consola de Analytics](xray-console-analytics.md).
**Descripción del impacto**
AWS X-Ray mide el impacto causado por un problema en curso como parte de la generación de información y notificaciones. El impacto se mide de dos formas:
+ Impacto en el [grupo](xray-console-groups.md) de X-Ray
+ Impacto en el servicio de la causa raíz
Este impacto viene determinado por el porcentaje de solicitudes que fallan o que provocan un error en un período de tiempo determinado. Este análisis de impacto le permite determinar la gravedad y la prioridad del problema en función de su situación particular. Este impacto está disponible como parte de la experiencia con la consola, además de las notificaciones de información.
**Desduplicación**
La información de AWS X-Ray desduplica los problemas en varios microservicios. Utiliza la detección de anomalías para determinar el servicio que es la causa principal de un problema, determina si otros servicios relacionados con él presentan un comportamiento anómalo debido a la misma causa raíz y registra el resultado como una sola información.
## Revisión del progreso de una información
X-Ray reevalúa la información periódicamente hasta que se resuelve y registra cada cambio intermedio notable en forma de [notificación](#xray-console-insight-notifications), la cual se puede enviar como evento de Amazon EventBridge. Esto le permite crear procesos y flujos de trabajo para determinar cómo ha cambiado el problema a lo largo del tiempo y tomar las medidas adecuadas, como enviar un correo electrónico o integrarse en un sistema de alertas mediante EventBridge.
Puede revisar los eventos de los incidentes en **Plazo del impacto**, en la página **Inspeccionar**. De forma predeterminada, la escala de tiempo muestra el servicio más afectado hasta que el usuario elige un servicio diferente.
![\[Página Inspeccionar con el plazo de tiempo del impacto\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/console-insights-inspect.png)
Para ver un mapa y gráficos de rastros de un evento, elíjalo en el plazo de tiempo del impacto. El mapa de rastros muestra los servicios de su aplicación que se ven afectados por el incidente. En **Análisis del impacto**, los gráficos muestran las líneas de tiempo de los fallos correspondientes al nodo seleccionado y los clientes del grupo.
![\[Gráfico de análisis del impacto correspondiente a una información de X-Ray\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/console-insights-inspect-analysis.png)
Para analizar en profundidad los rastros implicados en un incidente, elija **Analizar evento** en la página **Inspeccionar**. Puede utilizar la página **Análisis** para acotar la lista de rastros e identificar a los usuarios afectados. Para obtener más información, consulte [Interacción con la consola de Analytics](xray-console-analytics.md).
# Interacción con la consola de Analytics
La consola de AWS X-Ray Analytics es una herramienta interactiva para interpretar rápidamente los datos de rastreo con el fin de conocer el rendimiento de la aplicación y sus servicios subyacentes. La consola le permite explorar, analizar y visualizar los registros de seguimiento a través de gráficos de tiempo de respuesta y series temporales.
Al realizar selecciones en la consola de Analytics, la consola crea filtros para reflejar el subconjunto seleccionado de registros de seguimiento. Puede acotar el conjunto de datos con filtros cada vez más detallados haciendo clic en los gráficos y los paneles de métricas y campos asociados al conjunto de registros de seguimiento actual.
**Topics**
+ [Características de la consola](#xray-console-analytics-features)
+ [Distribución del tiempo de respuesta](#xray-console-analytics-response)
+ [Actividad de series temporales](#xray-console-analytics-time)
+ [Ejemplos de flujo de trabajo](#xray-console-analytics-workflows)
+ [Observar errores en el gráfico de servicio](#xray-console-analytics-observe-faults)
+ [Identificar los picos de tiempo de respuesta](#xray-console-analytics-response-peaks)
+ [Consultar todos los registros de seguimiento marcados con un código de estado](#xray-console-analytics-response-peaks)
+ [Consultar todos los elementos de un subgrupo y asociados a un usuario](#xray-console-analytics-subgroups)
+ [Comparar dos conjuntos de registros de seguimiento con criterios diferentes](#xray-console-analytics-compare)
+ [Identificar un registro de seguimiento de su interés y ver sus detalles](#xray-console-analytics-identify)
## Características de la consola
La consola de X-Ray Analytics utiliza las siguientes características principales para agrupar, filtrar, comparar y cuantificar los datos de rastro.
### Características
| Característica | Descripción |
| --- | --- |
| **Grupos** | El grupo seleccionado inicial es `Default`. Para cambiar el grupo recuperado, seleccione un grupo diferente en el menú que se encuentra a la derecha de la barra de búsqueda principal de expresiones de filtro. Para obtener más información sobre los grupos, consulte [Uso de expresiones de filtro con grupos](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-filters.html#groups). |
| **Retrieved traces (Registros de seguimiento recuperados** | De forma predeterminada, la consola de Analytics genera gráficos basados en todos los registros de seguimiento del grupo seleccionado. Los registros de seguimiento recuperados representan todos los registros de seguimiento del conjunto de trabajo. Puede ver el número de registros de seguimiento en este icono. Las expresiones de filtro que se aplican a la barra de búsqueda principal acotan y actualizan los registros de seguimiento recuperados. |
| **Mostrar y ocultar de gráficos** | Un control de alternancia para comparar el grupo activo con los registros de seguimiento recuperados. Para comparar los datos relativos al grupo con los filtros activos, elija **Show in charts (Mostrar en gráficos)**. Para eliminar esta vista de los gráficos, elija **Hide from charts (Ocultar de gráficos)**. |
| **Filtered trace set A (Conjunto de registros de seguimiento filtrados A** | A través de interacciones con los gráficos y las tablas, aplique filtros para crear los criterios del **conjunto de rastros filtrados A**. Cuando se aplican los filtros, el número de rastros aplicables y el porcentaje de rastros que se recupera se calculan en este icono. Los filtros se rellenan como etiquetas dentro del icono **Filtered trace set A (Conjunto de registros de seguimiento A filtrados)** y también se pueden eliminar del icono. |
| **Refine (Acotar** | Esta función actualiza el conjunto de registros de seguimiento recuperados en función de los filtros aplicados al conjunto de registros de seguimiento A. Al reajustar el conjunto de registros de seguimiento recuperado se actualiza el conjunto de trabajo de todos los registros de seguimiento recuperados en función de los filtros del conjunto de registros de seguimiento A. El conjunto de trabajo de registros de seguimiento recuperados es un subconjunto muestreado de todos los registros de seguimiento del grupo. |
| **Filtered trace set B (Conjunto de registros de seguimiento filtrados B** | Cuando se crea, el **conjunto de rastros filtrados B** es una copia del **conjunto de rastros filtrados A**. Para comparar los dos conjuntos de rastros, seleccione nuevos filtros, que se aplicarán al conjunto de rastros B, mientras que el conjunto A permanece fijo. Cuando se aplican los filtros, se calcula el número de registros de seguimiento aplicables y el porcentaje de registros de seguimiento del total recuperado en este icono. Los filtros se rellenan como etiquetas dentro del icono **Filtered trace set B (Conjunto de registros de seguimiento B)** y también se pueden eliminar del icono. |
| **Response Time Root Cause Entity Paths (Rutas de entidad de causa raíz de tiempo de respuesta** | Una tabla de rutas de entidad registradas. X-ray determina qué ruta del rastro del usuario es la causa más probable del tiempo de respuesta. El formato indica una jerarquía de entidades detectadas, que termina en una causa raíz de tiempo de respuesta. Utilice estas filas para filtrar errores de tiempo de respuesta recurrentes. Para obtener más información sobre cómo personalizar un filtro de causa raíz y obtener los datos a través de la API, consulte [Recuperación y reajuste de análisis de causa raíz](https://docs.aws.amazon.com/xray/latest/devguide/xray-api-gettingdata.html#xray-api-analytics). |
| **Delta (**�**)** | Una columna que se agrega a las tablas de métricas cuando los conjuntos de registros de seguimiento A y B están activos. La columna Delta calcula la diferencia porcentual de los registros de seguimiento entre el conjunto de registros de seguimiento A y el conjunto de registros de seguimiento B. |
## Distribución del tiempo de respuesta
La consola de X-Ray Analytics genera dos gráficos principales que ayudan al usuario a visualizar rastros: **Distribución del tiempo de respuesta** y **Actividad de series temporales**. En esta sección y las siguientes se proporcionan ejemplos de cada uno y se explican los aspectos básicos de cómo leer los gráficos.
A continuación se indican los colores asociados al gráfico de líneas de tiempo de respuesta (el gráfico de series temporales utiliza la misma combinación de colores):
+ **Todos los rastros del grupo**: gris
+ **Rastros recuperados**: naranja
+ **Conjunto de rastros filtrados A**: verde
+ **Conjunto de rastros filtrados B**: azul
**Example – Distribución del tiempo de respuesta**
La distribución del tiempo de respuesta es un gráfico que muestra el número de registros de seguimiento con un tiempo de respuesta determinado. Haga clic y arrastre para realizar selecciones en la distribución del tiempo de respuesta. De esta forma, se selecciona y se crea un filtro del conjunto de registros de seguimiento de trabajo llamado `responseTime` para todos los registros de seguimiento de un tiempo de respuesta específico.
![\[Un gráfico que muestra la distribución del tiempo de respuesta de los rastros.\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/analytics-responseTime.png)
## Actividad de series temporales
El gráfico de actividad de series temporales muestra el número de registros de seguimiento en un período de tiempo determinado. Los indicadores de color reflejan los colores del gráfico de líneas de la distribución del tiempo de respuesta. Cuanto más oscuro y opaco es el bloque de color de las series de actividad, más registros de seguimiento se representan en el momento especificado.
**Example – Actividad de series temporales**
Haga clic y arrastre para realizar selecciones dentro del gráfico de actividad de series temporales. De esta forma, se selecciona y se crea un filtro llamado `timerange` en el conjunto de registros de seguimiento de trabajo para todos los registros de seguimiento en un período de tiempo específico.
![\[Realizar una selección y crear un filtro\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/analytics-timeSeries.png)
## Ejemplos de flujo de trabajo
Los siguientes ejemplos muestran casos de uso comunes de la consola de X-Ray Analytics. Cada ejemplo muestra una función clave de la experiencia de la consola. En su conjunto, los ejemplos siguen un flujo de trabajo de solución de problemas básico. Los pasos describen cómo detectar primero los nodos en mal estado y, a continuación, cómo interactuar con la consola de Analytics para generar automáticamente consultas comparativas. Una vez que haya reducido el alcance a través de las consultas, verá los detalles de los registros de seguimiento de interés para determinar qué está dañando el estado del servicio.
## Observar errores en el gráfico de servicio
El mapa de rastros indica el estado de cada nodo coloreándolo en función de la proporción entre las llamadas correctas y los errores. Cuando vea un porcentaje en rojo en el nodo, eso indica un error. Utilice la consola de X-Ray Analytics para investigar el problema.
Para obtener más información acerca de cómo leer el mapa de rastros, consulte [Consulta del mapa de rastro](https://docs.aws.amazon.com/xray/latest/devguide/xray-console.html#xray-console-servicemap).
![\[Observar un error\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/scorekeep-gettingstarted-servicemap-before-2021.png)
## Identificar los picos de tiempo de respuesta
Mediante la distribución del tiempo de respuesta, puede observar los picos de tiempo de respuesta. Al seleccionar el pico en el tiempo de respuesta, las tablas que se encuentran debajo de los gráficos se actualizarán para mostrar las métricas asociadas, como los códigos de estado.
Al hacer clic y arrastrar, X-Ray selecciona y crea un filtro. Se muestra sombreado en gris encima de las líneas gráficas. Ahora puede arrastrar ese elemento resaltado a la izquierda o a la derecha por la distribución para actualizar su selección y filtro.
![\[Realizar una selección y crear un filtro\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/analytics-showFilterf.png)
## Consultar todos los registros de seguimiento marcados con un código de estado
Puede analizar los registros de seguimiento dentro del pico seleccionado mediante las tablas de métricas que se encuentran debajo de los gráficos. Al hacer clic en una fila de la tabla **HTTP STATUS CODE**, se crea automáticamente un filtro en el conjunto de datos de trabajo. Por ejemplo, puede ver todos los registros de seguimiento de código de estado 500. Esto crea una etiqueta de filtro en el icono del conjunto de registros de seguimiento llamado `http.status`.
## Consultar todos los elementos de un subgrupo y asociados a un usuario
Examine el conjunto de errores en función del usuario, URL, causa raíz del tiempo de respuesta u otros atributos predefinidos. Por ejemplo, para filtrar más el conjunto de registros de seguimiento con un código de estado 500, seleccione una fila de la tabla **USERS**. Se obtienen dos etiquetas de filtro en el icono del conjunto de registros de seguimiento: `http.status`, tal y como se designó anteriormente, y `user`.
## Comparar dos conjuntos de registros de seguimiento con criterios diferentes
Compare varios usuarios y sus solicitudes POST para encontrar otras discrepancias y correlaciones. Aplique su primer conjunto de filtros. Estos filtros se definen por una línea azul en la distribución del tiempo de respuesta. A continuación, seleccione **Compare (Comparar)**. Inicialmente, esto crea una copia de los filtros del conjunto de registros de seguimiento A.
Para continuar, defina un nuevo conjunto de filtros que se aplique al conjunto de registros de seguimiento B. Este segundo conjunto se representa mediante una línea verde. En el siguiente ejemplo se muestran diferentes líneas en función de la combinación de colores azul y verde.
![\[Comparación de gráficos de líneas\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/analytics-compareLines.png)
## Identificar un registro de seguimiento de su interés y ver sus detalles
Cuando reduzca el alcance mediante los filtros de la consola, la lista de registros de seguimiento de debajo de las tablas de métricas le resultará más útil. La tabla de lista de registros de seguimiento combina información de **URL**, **USER (USUARIO)** y **STATUS CODE (CÓDIGO DE ESTADO)** en una sola consulta. Para obtener más información, seleccione una fila de esta tabla para abrir la página de detalles del registro de seguimiento y ver su escala de tiempo y sus datos sin procesar.
# Configuración de grupos
Los grupos son una colección de rastros que se definen mediante una expresión de filtro. Puede utilizar grupos para generar gráficos de servicios adicionales y suministrar métricas de Amazon CloudWatch. Puede usar la consola de AWS X-Ray o la API de X-Ray con el fin de crear y administrar grupos para sus servicios. En este tema se describe cómo crear y administrar grupos con la consola de X-Ray. Para obtener información sobre cómo administrar grupos con la API de X-Ray, consulte [Groups](xray-api-configuration.md#xray-api-configuration-groups).
Puede crear grupos de rastros para rastros, análisis o mapas de rastros. Al crear un grupo, este pasa a estar disponible como filtro en el menú desplegable del grupo en las tres páginas: **Mapa de rastros**, **Rastros** y **Análisis**.
![\[Menú Grupos\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/group-menu.png)
Los grupos se identifican por su nombre o un nombre de recurso de Amazon (ARN) y contienen una expresión de filtro. El servicio compara los registros de seguimiento de entrada con la expresión y los almacena en consecuencia. Para obtener más información acerca de cómo crear una expresión de filtro, consulte [Uso de expresiones de filtro](xray-console-filters.md).
La actualización de la expresión de filtro de un grupo no cambia los datos que ya se han registrado. La actualización se aplica únicamente a los rastros posteriores. Esto puede dar lugar a un gráfico que combina la expresión nueva con la anterior. Para evitarlo, elimine el grupo actual y cree uno nuevo.
**nota**
Los grupos se facturan por el número de rastros recuperados que coinciden con la expresión de filtro. Para más información, consulte [Precios de AWS X-Ray](https://aws.amazon.com/xray/pricing/).
**Topics**
+ [Creación de un grupo](#xray-console-group-create-console)
+ [Aplicar un grupo](#xray-console-group-apply)
+ [Editar un grupo](#xray-console-group-edit)
+ [Clonación de un grupo](#xray-console-group-clone)
+ [Eliminación de un grupo](#xray-console-group-delete)
+ [Visualización de las métricas de los grupos en Amazon CloudWatch](#xray-console-group-cloudwatch)
## Creación de un grupo
**nota**
Ahora puede configurar los grupos de X-Ray desde la consola de Amazon CloudWatch. También puede seguir utilizando la consola de X-Ray.
------
#### [ CloudWatch console ]
1. Inicie sesión en la Consola de administración de AWS y abra la consola de CloudWatch en [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Elija **Configuración** en el panel de navegación izquierdo.
1. Elija **Ver ajustes** en **Grupos** dentro de la sección de **Rastros de X-Ray**.
1. Seleccione **Crear grupo** en la parte superior de la lista de grupos.
1. En la página **Crear grupo** escriba un nombre para el grupo. Los nombres de grupo pueden tener un máximo de 32 caracteres y solo pueden contener caracteres alfanuméricos y guiones. En los nombres de grupo se distingue entre mayúsculas y minúsculas.
1. Introduzca una expresión de filtro. Para obtener más información acerca de cómo crear una expresión de filtro, consulte [Uso de expresiones de filtro](xray-console-filters.md). En el siguiente ejemplo, el grupo filtra los rastros de errores del servicio `api.example.com` y las solicitudes al servicio en las que el tiempo de respuesta fue superior o igual a cinco segundos.
```
fault = true AND http.url CONTAINS "example/game" AND responsetime >= 5
```
1. En **Información**, habilite o deshabilite el acceso a la información para el grupo. Para obtener más detalles acerca de la información, consulte [Uso de información en X-Ray](xray-console-insights.md).
![\[Casillas de verificación de información en la página Grupo\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/group-insights-cw.png)
1. En **Etiquetas**, elija **Añadir nueva etiqueta** para introducir una clave de etiqueta y, si lo desea, un valor de etiqueta. Siga añadiendo las etiquetas adicionales que desee. Cada clave de etiqueta debe ser única. Para eliminar una etiqueta, elija **Eliminar** debajo de cada etiqueta. Para obtener más información acerca de las etiquetas, consulte [Etiquetado de reglas de muestreo y grupos de X-Ray](xray-tagging.md).
![\[Campos de etiqueta en la página Grupo\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/group-tags-cw.png)
1. Elija **Crear grupo**.
------
#### [ X-Ray console ]
1. Inicie sesión en la Consola de administración de AWS y abra la consola de X-Ray en [https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home).
1. Abra la página **Crear grupo** desde la página **Grupos** del panel de navegación izquierdo o desde el menú de grupos de una de las siguientes páginas: **Mapa de rastros**, **Rastros** y **Análisis**.
1. En la página **Crear grupo** escriba un nombre para el grupo. Los nombres de grupo pueden tener un máximo de 32 caracteres y solo pueden contener caracteres alfanuméricos y guiones. En los nombres de grupo se distingue entre mayúsculas y minúsculas.
1. Introduzca una expresión de filtro. Para obtener más información acerca de cómo crear una expresión de filtro, consulte [Uso de expresiones de filtro](xray-console-filters.md). En el siguiente ejemplo, el grupo filtra los rastros de errores del servicio `api.example.com` y las solicitudes al servicio en las que el tiempo de respuesta fue superior o igual a cinco segundos.
```
fault = true AND http.url CONTAINS "example/game" AND responsetime >= 5
```
1. En **Información**, habilite o deshabilite el acceso a la información para el grupo. Para obtener más detalles acerca de la información, consulte [Uso de información en X-Ray](xray-console-insights.md).
![\[Casillas de verificación de información en la página Grupo\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/group-insights.png)
1. En **Etiquetas**, introduzca una clave de etiqueta y, si lo desea, un valor de etiqueta. Al añadir una etiqueta, aparece una nueva línea para que introduzca otra etiqueta. Cada clave de etiqueta debe ser única. Para eliminar una etiqueta, elija **X** al final de la fila de la etiqueta. Para obtener más información acerca de las etiquetas, consulte [Etiquetado de reglas de muestreo y grupos de X-Ray](xray-tagging.md).
![\[Campos de etiqueta en la página Grupo\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/group-tags.png)
1. Elija **Crear grupo**.
------
## Aplicar un grupo
------
#### [ CloudWatch console ]
1. Inicie sesión en la Consola de administración de AWS y abra la consola de CloudWatch en [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Abra una de las siguientes páginas del panel de navegación, en **Rastros de X-Ray**:
+ **Mapa de rastros**
+ **Rastros**
1. Introduzca un nombre de grupo en el **Filtrar por grupo de X-Ray**. Los datos que se muestran en la página cambian para coincidir con la expresión de filtro establecida en el grupo.
------
#### [ X-Ray console ]
1. Inicie sesión en la Consola de administración de AWS y abra la consola de X-Ray en [https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home).
1. Abra una de las siguientes páginas desde el panel de navegación:
+ **Mapa de rastros**
+ **Rastros**
+ **Analytics**
1. En el menú de grupos, elija el grupo que creó en la [Creación de un grupo](#xray-console-group-create-console). Los datos que se muestran en la página cambian para coincidir con la expresión de filtro establecida en el grupo.
------
## Editar un grupo
------
#### [ CloudWatch console ]
1. Inicie sesión en la Consola de administración de AWS y abra la consola de CloudWatch en [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Elija **Configuración** en el panel de navegación izquierdo.
1. Elija **Ver ajustes** en **Grupos** dentro de la sección de **Rastros de X-Ray**.
1. Elija un grupo de la sección **Grupos** y, a continuación, elija **Editar**.
1. Aunque no puede cambiar el nombre de un grupo, puede actualizar la expresión de filtro. Para obtener más información acerca de cómo crear una expresión de filtro, consulte [Uso de expresiones de filtro](xray-console-filters.md). En el siguiente ejemplo, el grupo filtra los rastros de errores del servicio `api.example.com` y las solicitudes cuya dirección URL contenga `example/game` y cuyo tiempo de respuesta fue superior o igual a cinco segundos.
```
fault = true AND http.url CONTAINS "example/game" AND responsetime >= 5
```
1. En **Información**, habilite o deshabilite el acceso a la información para el grupo. Para obtener más detalles acerca de la información, consulte [Uso de información en X-Ray](xray-console-insights.md).
![\[Casillas de verificación de información en la página Grupo\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/group-insights-cw.png)
1. En **Etiquetas**, elija **Añadir nueva etiqueta** para introducir una clave de etiqueta y, si lo desea, un valor de etiqueta. Siga añadiendo las etiquetas adicionales que desee. Cada clave de etiqueta debe ser única. Para eliminar una etiqueta, elija **Eliminar** debajo de cada etiqueta. Para obtener más información acerca de las etiquetas, consulte [Etiquetado de reglas de muestreo y grupos de X-Ray](xray-tagging.md).
![\[Campos de etiqueta en la página Grupo\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/group-tags-cw.png)
1. Cuando haya terminado de actualizar el grupo, elija **Actualizar grupo**.
------
#### [ X-Ray console ]
1. Inicie sesión en la Consola de administración de AWS y abra la consola de X-Ray en [https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home).
1. Siga uno de estos pasos para abrir la página **Editar grupo**.
1. En la página **Grupos**, elija el nombre de un grupo para editarlo.
1. En el menú de grupos de una de las páginas siguientes, elija un grupo y, a continuación, seleccione **Editar**.
+ **Mapa de rastros**
+ **Rastros**
+ **Analytics**
1. Aunque no puede cambiar el nombre de un grupo, puede actualizar la expresión de filtro. Para obtener más información acerca de cómo crear una expresión de filtro, consulte [Uso de expresiones de filtro](xray-console-filters.md). En el siguiente ejemplo, el grupo filtra los rastros de errores del servicio `api.example.com` y las solicitudes cuya dirección URL contenga `example/game` y cuyo tiempo de respuesta fue superior o igual a cinco segundos.
```
fault = true AND http.url CONTAINS "example/game" AND responsetime >= 5
```
1. En **Conocimientos**, habilite o deshabilite los conocimientos y las notificaciones de conocimientos para el grupo. Para obtener más detalles acerca de la información, consulte [Uso de información en X-Ray](xray-console-insights.md).
![\[Casillas de verificación de información en la página Grupo\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/group-insights.png)
1. En **Etiquetas**, edite las claves y los valores de las etiquetas. Cada clave de etiqueta debe ser única. Los valores de las etiquetas son opcionales; puede eliminarlos si lo desea. Para eliminar una etiqueta, elija **X** al final de la fila de la etiqueta. Para obtener más información acerca de las etiquetas, consulte [Etiquetado de reglas de muestreo y grupos de X-Ray](xray-tagging.md).
![\[Campos de etiqueta en la página Grupo\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/group-tags.png)
1. Cuando haya terminado de actualizar el grupo, elija **Actualizar grupo**.
------
## Clonación de un grupo
Al clonar un grupo, se crea un grupo nuevo que tiene la expresión de filtro y las etiquetas de un grupo existente. Cuando clona un grupo, el grupo nuevo tiene el mismo nombre que el grupo desde el que lo clone, con `-clone` anexado al nombre.
------
#### [ CloudWatch console ]
1. Inicie sesión en la Consola de administración de AWS y abra la consola de CloudWatch en [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Elija **Configuración** en el panel de navegación izquierdo.
1. Elija **Ver ajustes** en **Grupos** dentro de la sección de **Rastros de X-Ray**.
1. Elija un grupo de la sección **Grupos** y, a continuación, elija **Clonar**.
1. En la página **Crear grupo**, el nombre del grupo es *group-name*`-clone`. Si lo desea, puede introducir un nuevo nombre para el grupo. Los nombres de grupo pueden tener un máximo de 32 caracteres y solo pueden contener caracteres alfanuméricos y guiones. En los nombres de grupo se distingue entre mayúsculas y minúsculas.
1. Puede conservar la expresión de filtro del grupo existente o, si lo desea, introducir una nueva expresión de filtro. Para obtener más información acerca de cómo crear una expresión de filtro, consulte [Uso de expresiones de filtro](xray-console-filters.md). En el siguiente ejemplo, el grupo filtra los rastros de errores del servicio `api.example.com` y las solicitudes al servicio en las que el tiempo de respuesta fue superior o igual a cinco segundos.
```
service("api.example.com") { fault = true OR responsetime >= 5 }
```
1. En **Etiquetas**, edite las claves y los valores de las etiquetas, si es necesario. Cada clave de etiqueta debe ser única. Los valores de las etiquetas son opcionales; puede eliminarlos si lo desea. Para eliminar una etiqueta, elija **X** al final de la fila de la etiqueta. Para obtener más información acerca de las etiquetas, consulte [Etiquetado de reglas de muestreo y grupos de X-Ray](xray-tagging.md).
1. Elija **Crear grupo**.
------
#### [ X-Ray console ]
1. Inicie sesión en la Consola de administración de AWS y abra la consola de X-Ray en [https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home).
1. Abra la página **Grupos** desde el panel de navegación izquierdo y elija el nombre del grupo que desee clonar.
1. Seleccione **Clonar grupo** en el menú **Acciones**.
1. En la página **Crear grupo**, el nombre del grupo es *group-name*`-clone`. Si lo desea, puede introducir un nuevo nombre para el grupo. Los nombres de grupo pueden tener un máximo de 32 caracteres y solo pueden contener caracteres alfanuméricos y guiones. En los nombres de grupo se distingue entre mayúsculas y minúsculas.
1. Puede conservar la expresión de filtro del grupo existente o, si lo desea, introducir una nueva expresión de filtro. Para obtener más información acerca de cómo crear una expresión de filtro, consulte [Uso de expresiones de filtro](xray-console-filters.md). En el siguiente ejemplo, el grupo filtra los rastros de errores del servicio `api.example.com` y las solicitudes al servicio en las que el tiempo de respuesta fue superior o igual a cinco segundos.
```
service("api.example.com") { fault = true OR responsetime >= 5 }
```
1. En **Etiquetas**, edite las claves y los valores de las etiquetas, si es necesario. Cada clave de etiqueta debe ser única. Los valores de las etiquetas son opcionales; puede eliminarlos si lo desea. Para eliminar una etiqueta, elija **X** al final de la fila de la etiqueta. Para obtener más información acerca de las etiquetas, consulte [Etiquetado de reglas de muestreo y grupos de X-Ray](xray-tagging.md).
1. Elija **Crear grupo**.
------
## Eliminación de un grupo
Siga los pasos de esta sección para eliminar un grupo. No se puede eliminar el grupo **Predeterminado**.
------
#### [ CloudWatch console ]
1. Inicie sesión en la Consola de administración de AWS y abra la consola de CloudWatch en [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Elija **Configuración** en el panel de navegación izquierdo.
1. Elija **Ver ajustes** en **Grupos** dentro de la sección de **Rastros de X-Ray**.
1. Elija un grupo de la sección **Grupos** y, a continuación, elija **Eliminar**.
1. Cuando se le pida confirmación, elija **Eliminar**.
------
#### [ X-Ray console ]
1. Inicie sesión en la Consola de administración de AWS y abra la consola de X-Ray en [https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home).
1. Abra la página **Grupos** desde el panel de navegación izquierdo y elija el nombre del grupo que desee eliminar.
1. En el menú **Acciones**, elija **Eliminar**.
1. Cuando se le pida confirmación, elija **Eliminar**.
------
## Visualización de las métricas de los grupos en Amazon CloudWatch
Una vez que se crea un grupo, los rastros de entrada se comparan con la expresión de filtro del grupo a medida que se almacenan en el servicio de X-Ray. Las métricas para el número de rastros que coinciden con cada criterio se publican en Amazon CloudWatch cada minuto. Al seleccionar **Ver métrica** en la página **Editar grupo**, se abre la consola de CloudWatch en la página **Métrica**. Para obtener más información sobre cómo utilizar las métricas de CloudWatch, consulte [Uso de métricas de Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html) en la *Guía del usuario de Amazon CloudWatch*.
------
#### [ CloudWatch console ]
1. Inicie sesión en la Consola de administración de AWS y abra la consola de CloudWatch en [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Elija **Configuración** en el panel de navegación izquierdo.
1. Elija **Ver ajustes** en **Grupos** dentro de la sección de **Rastros de X-Ray**.
1. Elija un grupo de la sección **Grupos** y, a continuación, elija **Editar**.
1. En la página **Editar grupo**, elija **Ver métrica**.
La página **Métricas** de la consola de CloudWatch se abre en una nueva pestaña.
------
#### [ X-Ray console ]
1. Inicie sesión en la Consola de administración de AWS y abra la consola de X-Ray en [https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home).
1. Abra la página **Grupos** desde el panel de navegación izquierdo y elija el nombre del grupo cuyas métricas desee ver.
1. En la página **Editar grupo**, elija **Ver métrica**.
La página **Métricas** de la consola de CloudWatch se abre en una nueva pestaña.
------
# Configuración de reglas de muestreo de
Puede usar la AWS X-Ray consola para configurar las reglas de muestreo para sus servicios. La AWS distribución OpenTelemetry, el SDK de X-Ray y los Servicios de AWS que admiten el [rastreo activo](xray-services.md) con configuraciones de muestreo utilizan reglas de muestreo para determinar qué solicitudes registrar.
**Topics**
+ [Configuración de reglas de muestreo de](#xray-console-config)
+ [Personalización de reglas de muestreo](#xray-console-custom)
+ [Opciones de reglas de muestreo](#xray-console-sampling-options)
+ [Ejemplos de reglas de muestreo](#xray-console-sampling-examples)
+ [Configuración del servicio para utilizar reglas de muestreo](#xray-console-sampling-service)
+ [Visualización de resultados de muestreo](#xray-console-sampling-results)
+ [Siguientes pasos](#xray-console-sampling-nextsteps)
## Configuración de reglas de muestreo de
Puede configurar el muestreo para los siguientes casos de uso:
+ **Punto de entrada de API Gateway**: API Gateway admite el muestreo y el rastreo activo. Para habilitar el rastreo activo en una etapa de la API, consulte [Compatibilidad de Amazon API Gateway con el rastreo activo para AWS X-Ray](xray-services-apigateway.md).
+ **AWS AppSync**— AWS AppSync admite el muestreo y el rastreo activo. Para habilitar el rastreo activo en las AWS AppSync solicitudes, consulte [Rastreo con X-Ray AWS](https://docs.aws.amazon.com/appsync/latest/devguide/x-ray-tracing.html).
+ **AWS Step Functions**— AWS Step Functions admite el muestreo y el rastreo activo. Para habilitar el rastreo activo en las máquinas AWS Step Functions estatales, consulte [Rastreo de rayos X en Step Functions](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-xray-tracing.html).
+ ** AWS Distribución de instrumentos para OpenTelemetry plataformas informáticas**: cuando se utilizan plataformas informáticas como Amazon EC2, Amazon ECS o AWS Elastic Beanstalk, se admite el muestreo cuando la aplicación se ha equipado con la última versión de AWS Distro for o el SDK de OpenTelemetry X-Ray.
## Personalización de reglas de muestreo
Al personalizar las reglas de muestreo, puede controlar la cantidad de datos que va a registrar. También puede modificar el comportamiento del muestreo sin modificar ni volver a implementar el código. Las reglas de muestreo indican a la AWS Distro for OpenTelemetry (ADOT) o al X-Ray SDK cuántas solicitudes deben grabar para un conjunto de criterios. De forma predeterminada, el SDK registra la primera solicitud cada segundo y el cinco por ciento de las solicitudes adicionales. Una petición por segundo es el *depósito*. Esto garantiza que se registre al menos un registro de seguimiento cada segundo mientras el servicio atienda solicitudes. El cinco por ciento es el *porcentaje* al que se muestrean las solicitudes adicionales más allá del tamaño del depósito.
Puede configurar el SDK de X-Ray para leer reglas de muestreo desde un documento JSON que incluya con su código. Sin embargo, cuando ejecute varias instancias de su servicio, cada instancia realiza el muestreo de manera independiente. Esto hace que el porcentaje total de solicitudes muestreadas aumente, ya que los depósitos de todas las instancias se suman de forma efectiva. Además, para actualizar las reglas de muestreo locales, tiene que volver a implementar su código.
Al definir las reglas de muestreo en la consola de X-Ray y [configurar el SDK](#xray-console-sampling-service) para leer reglas desde el servicio de X-Ray, puede evitar ambos problemas. El servicio administra el depósito de cada regla y asigna cuotas a cada instancia de su servicio para distribuir el depósito de manera uniforme, en función del número de instancias que se ejecuten. El límite del depósito se calcula de acuerdo con las reglas que haya establecido. Dado que las reglas están configuradas en el servicio, puede administrar las reglas sin realizar implementaciones adicionales.
**nota**
Al configurar las reglas de muestreo, es fundamental entender que el muestreo por rayos X está «basado en los padres». Esto significa que la decisión de muestreo se toma una sola vez, por lo general, el primer X-Ray-enabled servicio que gestiona la solicitud (el servicio «raíz»).
Si un servicio descendente recibe una solicitud que ya contiene una decisión de muestreo de una empresa matriz anterior, respetará esa decisión independientemente de sus propias reglas de muestreo coincidentes.
Cuándo se aplican las normas: sus reglas de muestreo personalizadas solo entran en vigor en los servicios en los que aún no se ha tomado una decisión de muestreo. Por lo general, esto se aplica a:
El punto de entrada de su aplicación (p. ej., una API Gateway, un Load Balancer o el primer microservicio instrumentado).
Procesos o trabajadores asíncronos que inician una nueva trayectoria.
Error común: si crea una regla de muestreo estricta para el «Servicio B», pero siempre se llama «Servicio B» por «Servicio A», es probable que su regla para el Servicio B nunca se aplique porque simplemente se trata de seguir la decisión adoptada por el Servicio A. Para cambiar el muestreo de trazas para este flujo de trabajo, debe configurar la regla de muestreo para el servicio raíz (Servicio A).
**nota**
X-Ray aplica las reglas de muestreo en la medida de lo posible y, en algunos casos, el porcentaje de muestreo efectivo puede no coincidir exactamente con las reglas de muestreo configuradas. Sin embargo, con el tiempo, el número de solicitudes muestreadas debería estar cerca del porcentaje configurado.
Ahora puede configurar las reglas de muestreo de X-Ray desde la CloudWatch consola de Amazon.
**Para configurar las reglas de muestreo en la CloudWatch consola**
1. Inicie sesión en Consola de administración de AWS y abra la CloudWatch consola en [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Selecciona **Configuración** en el panel de navegación izquierdo, debajo **de Configuración**.
1. Seleccione **Ver configuración** en **Reglas de muestreo** en la sección de **Rastros de X-Ray**.
1. Para crear una regla, elija **Crear regla de muestreo**.
Para editar una regla, elija la regla y, a continuación, elija **Editar**.
Para eliminar una regla, elija la regla y, a continuación, elija la opción **Eliminar**.
## Opciones de reglas de muestreo
Las siguientes opciones están disponibles para cada regla. En los valores de cadena se pueden usar caracteres comodín para buscar coincidencias de un solo carácter (`?`) o cero o más caracteres (`*`).
**Opciones de reglas de muestreo**
+ **Nombre de la regla** (cadena): un nombre único para la regla.
+ **Prioridad** (entero comprendido entre el 1 y 9999): prioridad de la regla de muestreo. Los servicios evalúan las reglas en orden ascendente de prioridad y toman una decisión de muestreo con la primera regla coincidente.
+ **Depósito** (entero no negativo): número fijo de solicitudes coincidentes que se van a instrumentar por segundo, antes de aplicar el porcentaje fijo. Los servicios no utilizan directamente el depósito, sino que se aplica a todos los servicios que usan la regla en su conjunto.
+ **Porcentaje** (entero comprendido entre el 0 y el 100): porcentaje de solicitudes coincidentes que se van instrumentar, una vez que se ha agotado el depósito. Al configurar una regla de muestreo en la consola, elija un porcentaje entre 0 y 100. Al configurar una regla de muestreo en un SDK de cliente mediante un documento JSON, proporcione un valor porcentual entre 0 y 1.
+ **Nombre del servicio** (cadena): el nombre del servicio instrumentado, tal como aparece en el mapa de rastros.
+ SDK de X-Ray: el nombre del servicio que se configura en la grabadora.
+ Amazon API Gateway: `api-name/stage`.
+ **Tipo de servicio** (cadena): el tipo de servicio, tal como aparece en el mapa de rastros. Para el SDK de X-Ray, defina el tipo de servicio aplicando el complemento adecuado:
+ `AWS::ElasticBeanstalk::Environment`— Un AWS Elastic Beanstalk entorno (complemento).
+ `AWS::EC2::Instance`— Una EC2 instancia de Amazon (plugin).
+ `AWS::ECS::Container`: un contenedor de Amazon ECS (complemento).
+ `AWS::EKS::Container`— Un contenedor Amazon EKS (plugin).
+ `AWS::APIGateway::Stage`: una etapa de Amazon API Gateway.
+ `AWS::AppSync::GraphQLAPI `— Una solicitud AWS AppSync de API.
+ `AWS::StepFunctions::StateMachine`— Una máquina de AWS Step Functions estados.
+ **Host** (cadena): nombre de host del encabezado de host HTTP.
+ **Método HTTP** (cadena): el método de la solicitud HTTP.
+ **Ruta URL** (cadena): la ruta URL de la solicitud.
+ SDK de X-Ray: la parte de la ruta de la URL de la solicitud HTTP.
+ **ARN del recurso** (cadena): el ARN del AWS recurso que ejecuta el servicio.
+ SDK de X-Ray: no compatible. El SDK solo puede utilizar reglas con **Resource ARN (ARN de recurso)** configurado en `*`.
+ Amazon API Gateway: el ARN de etapa.
+ (Opcional) **Atributos** (clave y valor): atributos de segmento que se conocen cuando se toma la decisión de muestreo.
+ SDK de X-Ray: no compatible. El SDK omite las reglas que especifican atributos.
+ Amazon API Gateway: encabezados de la solicitud HTTP original.
+ (Opcional) **SamplingRateBoost**(objeto): controla el comportamiento de mejora del muestreo provocado por anomalías.
+ MaxRate (número entero entre 0 y 100): la frecuencia máxima de muestreo (0,0—1,0) Los rayos X pueden aumentar durante las anomalías
+ CooldownWindowMinutes (entero mayor que 0): intervalo de tiempo (minutos) en el que solo se puede activar un impulso, lo que evita que los amplificadores sean continuos
## Ejemplos de reglas de muestreo
**Example – Regla predeterminada sin depósito y con un porcentaje bajo**
Puede modificar el depósito predeterminado de la regla y el porcentaje. La regla predeterminada se aplica a las solicitudes que no coinciden con cualquier otra regla.
+ **Depósito**: **0**
+ **Porcentaje**: **5** (**0.05** si se configura mediante un documento JSON)
**Example – Regla de depuración para rastrear todas las solicitudes para una ruta problemática**
Una regla de alta prioridad aplicada temporalmente para depuración.
+ **Nombre de la regla**: **DEBUG – history updates**
+ **Prioridad**: **1**
+ **Depósito**: **1**
+ **Porcentaje**: **100** (**1** si se configura mediante un documento JSON)
+ **Nombre del servicio**: **Scorekeep**
+ **Tipo de servicio**: **\$1**
+ **Host**: **\$1**
+ **Método HTTP**: **PUT**
+ **Ruta URL**: **/history/\$1**
+ **ARN de recurso**: **\$1**
**Example — Tasa mínima más alta para POSTs**
+ **Nombre de la regla**: **POST minimum**
+ **Prioridad**: **100**
+ **Depósito**: **10**
+ **Porcentaje**: **10** (**.1** si se configura mediante un documento JSON)
+ **Nombre del servicio**: **\$1**
+ **Tipo de servicio**: **\$1**
+ **Host**: **\$1**
+ **Método HTTP**: **POST**
+ **Ruta URL**: **\$1**
+ **ARN de recurso**: **\$1**
**Example Habilitación de un aumento provocado por anomalías**
Configure una regla que desencadene un aumento de muestreo de hasta un 50 % durante las anomalías, con un tiempo de reutilización de 10 minutos.
+ **Nombre de la regla**: **MyAdaptiveRule**
+ **Prioridad**: **100**
+ **Depósito**: **1**
+ **FixedRate**: **0.0510**
+ **Nombre del servicio**: **\$1**
+ **Tipo de servicio**: **\$1**
+ **Host**: **\$1**
+ **Método HTTP**: **POST**
+ **Ruta URL**: **\$1**
+ **maxRate**: **0.5**
+ **cooldownWindowMinutes**: **10**
## Configuración del servicio para utilizar reglas de muestreo
La AWS distribución para OpenTelemetry (ADOT) y el SDK de X-Ray requieren una configuración adicional para utilizar las reglas de muestreo que se configuran en la consola. Consulte el tema de configuración para su lenguaje para obtener más información sobre cómo configurar una estrategia de muestreo.
+ Java: [Uso del muestreo remoto de rayos X](https://aws-otel.github.io/docs/getting-started/java-sdk/auto-instr#using-x-ray-remote-sampling) con ADOT Java
+ Go: [Configurar el muestreo](https://aws-otel.github.io/docs/getting-started/go-sdk/manual-instr#configuring-sampling) con ADOT Go
+ Node.js: [Uso del muestreo remoto de rayos X](https://aws-otel.github.io/docs/getting-started/js-sdk/trace-metric-auto-instr#using-x-ray-remote-sampling) con ADOT JavaScript
+ Python: [Uso del muestreo remoto de rayos X](https://aws-otel.github.io/docs/getting-started/python-sdk/auto-instr#using-x-ray-remote-sampling) con ADOT Python
+ Ruby: [Reglas de muestreo](xray-sdk-ruby-configuration.md#xray-sdk-ruby-configuration-sampling)
+ .NET: [Uso del muestreo remoto de rayos X](https://aws-otel.github.io/docs/getting-started/dotnet-sdk/auto-instr#using-x-ray-remote-sampling) con ADOT.NET
Para API Gateway, consulte: [Compatibilidad de Amazon API Gateway con el rastreo activo para AWS X-Ray](xray-services-apigateway.md).
## Visualización de resultados de muestreo
La página de **Muestreo** de la consola de X-Ray muestra información detallada sobre cómo los servicios del usuario utilizan cada regla de muestreo.
La columna **Trend (Tendencia)** muestra cómo se ha utilizado la regla en los últimos minutos. Cada columna muestra las estadísticas para una ventana de 10 segundos.
**Estadísticas de muestreo**
+ **Regla coincidente total**: el número de solicitudes que coincidieron con esta regla. Este número no incluye solicitudes que podrían haber coincidido con esta regla, pero coincidieron primero con una regla de prioridad más alta.
+ **Total muestreado**: el número de solicitudes registradas.
+ **Muestreadas con porcentaje fijo**: número de solicitudes muestreadas aplicando el porcentaje fijo de la regla.
+ **Muestreado con límite de depósito**: el número de solicitudes muestreadas utilizando una cuota asignada por X-Ray.
+ **Préstamos del depósito**: número de solicitudes muestreadas tomando prestado del depósito. La primera vez que un servicio hace coincidir una solicitud con una regla, X-Ray aún no le ha asignado una cuota. Sin embargo, si el depósito es al menos 1, el servicio toma prestado un rastro por segundo hasta que X-Ray asigna una cuota.
Para obtener más información acerca de cómo utilizar las estadísticas de muestreo y cómo utilizan las reglas de muestreo los servicios, consulte [Using sampling rules with the X-Ray API (Uso de reglas de muestreo con la API de X-Ray)](xray-api-sampling.md).
## Siguientes pasos
Puede usar la API de X-Ray para administrar reglas de muestreo. Con la API, puede crear y actualizar las reglas mediante programación de forma programada o en respuesta a alarmas o notificaciones. Consulte [Configuración de los ajustes de muestreo, grupos y cifrado con la AWS X-Ray API](xray-api-configuration.md) para obtener instrucciones y ejemplos de reglas adicionales.
The AWS Distro for OpenTelemetry, X-Ray SDK y Servicios de AWS también utilizan la API de X-Ray para leer las reglas de muestreo, informar los resultados del muestreo y obtener los objetivos de muestreo. Los servicios deben realizar un seguimiento de la frecuencia con la que se aplica cada regla, evaluar las reglas en función de la prioridad y tomar prestado del depósito cuando una solicitud coincide con una regla para la que X-Ray no ha asignado aún una cuota al servicio. Para obtener más información acerca de cómo utiliza un servicio la API para muestreo, consulte [Using sampling rules with the X-Ray API (Uso de reglas de muestreo con la API de X-Ray)](xray-api-sampling.md).
Cuando la AWS Distro for OpenTelemetry o el SDK de X-Ray llaman al muestreo APIs, utilizan el CloudWatch agente como proxy. Si ya utiliza el puerto TCP 2000, puede configurar el agente para que ejecute el proxy en un puerto diferente. Consulte la [guía de instalación del CloudWatch agente](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html) para obtener más información.
# Configuración de muestreo flexible
La falta de rastros críticos durante los picos de anomalías puede dificultar el análisis de la causa raíz. Sin embargo, mantener altas tasas de muestreo resulta caro. El muestreo adaptativo de X-Ray proporciona una visibilidad completa de las anomalías y controla los costos durante las operaciones normales. Con el muestreo adaptativo, se establece una frecuencia de muestreo máxima y X-Ray se ajusta automáticamente dentro de ese límite. X-Ray calcula el impulso mínimo necesario para capturar los rastros de errores. Si la velocidad de referencia captura suficientes datos, no se produce ningún aumento. Solo pagará por el muestreo adicional cuando sea necesario.
Beneficios de utilizar el muestreo adaptativo:
+ Visibilidad completa de los incidentes: obtenga un seguimiento completo de los incidentes sin intervención manual. X-Ray ajusta automáticamente las velocidades de muestreo para capturar los rastros de error y, a continuación, vuelve a las tasas normales.
+ Visibilidad de la causa raíz: compruebe siempre el origen de los problemas. X-Ray captura datos de errores críticos incluso cuando no se desencadena el muestreo de rastros completos.
+ Optimice los costos: los breves aumentos de muestreo (hasta 1 minuto) y los periodos de recuperación automáticos evitan el sobremuestreo. Solo pagará por los datos que necesite para diagnosticar problemas.
**Topics**
+ [Plataformas y SDK compatibles](#adaptive-sampling-supported-sdks)
+ [Elección del enfoque de muestreo adaptativo](#adaptive-sampling-features)
+ [Configuración de SDK local](#local-sdk-configuration)
## Plataformas y SDK compatibles
**SDK compatible**: el muestreo adaptativo requiere la versión más reciente del ADOT SDK.
**Lenguaje compatible**: Java (versión [2.11.5](https://github.com/aws-observability/aws-otel-java-instrumentation/releases/tag/v2.11.5) o superior)
La aplicación debe estar equipada con el ADOT SDK compatible y ejecutarse junto con el agente de Amazon CloudWatch o el recopilador de OpenTelemetry.
Por ejemplo, Amazon EC2, Amazon ECS y Amazon EKS son plataformas comunes en las que las señales de aplicación de AWS proporcionan orientación para habilitar ADOT SDK y el agente de Amazon CloudWatch.
## Elección del enfoque de muestreo adaptativo
El muestreo adaptativo admite dos enfoques: potenciación del muestreo y captura de intervalos de anomalías. Se pueden aplicar de forma independiente o se pueden combinar entre sí.
### Potenciación del muestreo
La potenciación del muestreo adaptativo se basa en las reglas de muestreo y funciona con el modelo de muestreo existente basado en encabezados de X-Ray. El muestreo basado en encabezados significa que las decisiones de muestreo se toman en el servicio raíz y el indicador de muestreo se transmite posteriormente a todos los servicios de la cadena de llamadas.
+ **Aumento basado en reglas**: el impulso siempre está vinculado a una regla específica de muestreo de X-Ray. Cada regla puede definir su propia velocidad máxima de aumento y comportamiento de enfriamiento.
+ **Muestreo basado en encabezados**: significa que las decisiones de muestreo se toman en el servicio raíz y el indicador de muestreo se transmite posteriormente a todos los servicios de la cadena de llamadas.
+ **Impulsado por anomalías**: X-Ray se basa en el SDK para informar de las estadísticas de anomalías. Cuando X-Ray detecta anomalías, como errores o una latencia alta, utiliza estas estadísticas para calcular una tasa de aumento adecuada (hasta el máximo configurado).
**Informes de anomalías**
Todos los servicios de aplicaciones de la cadena de llamadas pueden emitir estadísticas de anomalías a través del SDK necesario:
+ **Servicio raíz**: se debe ejecutar en una plataforma y un SDK compatibles para poder aumentar el muestreo. Si el servicio raíz no es compatible, no se producirá ningún impulso.
+ **Servicios posteriores**: los servicios posteriores solo informan de anomalías; no pueden tomar decisiones de muestreo. Cuando un servicio posterior ejecuta un SDK compatible, las anomalías detectadas pueden desencadenar un aumento del muestreo. Cuando un servicio posterior no es compatible (por ejemplo, si se ejecuta un SDK anterior), las anomalías de ese servicio no desencadenarán un aumento. Estos servicios aún pueden propagar el contexto posterior si siguen la propagación de contexto estándar (como el contexto y equipaje de rastros de W3C). Esto garantiza que los SDK compatibles en otros servicios posteriores puedan detectar anomalías que desencadenen un aumento.
**Aumento del tiempo y el alcance**
+ **Retraso de desencadenamiento**: puede esperar que el aumento de muestreo comience tan solo 10 segundos después de que X-Ray detecte una anomalía.
+ **Periodo de refuerzo**: después de que X-Ray desencadene un impulso, dura hasta 1 minuto antes de volver a la frecuencia de muestreo base.
+ **Aumentar el tiempo de enfriamiento**: después de que se produzca un aumento, X-Ray no desencadenará otro aumento con la misma regla hasta que haya pasado el periodo de enfriamiento.
Por ejemplo, si establece `cooldown` en 10 minutos, una vez que finalice un aumento, no se podrá desencadenar ningún nuevo impulso hasta que pasen los siguientes 10 minutos.
Caso especial: si establece `cooldown` en 1 minuto, y dado que un impulso en sí mismo puede durar hasta 1 minuto, los aumentos pueden desencadenarse de forma continua si la anomalía persiste.
**nota**
Use los SDK y las plataformas compatibles para el servicio raíz. La potenciación del muestreo solo funciona con los SDK y las plataformas compatibles. Aunque la potenciación del muestreo tiene una alta probabilidad de captar rastros de anomalías, es posible que no capte todos los rastros de anomalías.
**Aumento de la visibilidad**
Cuando se configura una regla de muestreo con un aumento de muestreo adaptativo, X-Ray emite automáticamente métricas vendidas que le permiten supervisar la actividad del aumento.
+ **Nombre de métrica** – `SamplingRate`
+ **Dimensión**: `RuleName` (establecida con el nombre real de la regla)
Cada regla con `SamplingRateBoost` habilitado publicará su frecuencia de muestreo efectiva, incluida la frecuencia de referencia y cualquier aumento temporal. Esto le permite:
+ Realización de un seguimiento de cuándo se desencadenan los aumentos
+ Supervisión de la frecuencia de muestreo efectiva de cada regla
+ Correlación de los aumentos con las anomalías de las aplicaciones (como picos de error o eventos de latencia)
Puede ver estas métricas en **Métricas de Amazon CloudWatch, en el espacio de nombres AWS/X-Ray. El valor de la métrica es un número de punto flotante entre 0 y 1, que representa la frecuencia de muestreo efectiva**.
**Configuración de potenciación de muestreo mediante reglas de muestreo de X-Ray**
Puede habilitar el muestreo adaptativo directamente en las reglas de muestreo de X-Ray existentes agregando un campo de `SamplingRateBoost` nuevo. Para obtener más información, consulte [Configuración de reglas de muestreo](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html#xray-console-custom). Esto proporciona una forma centralizada de habilitar el muestreo adaptativo sin modificar el código de la aplicación ni aplicar la implementación de la aplicación. Al habilitar el muestreo adaptativo, X-Ray aumenta automáticamente el muestreo durante anomalías como picos de error o valores atípicos de latencia, a la vez que mantiene las frecuencias de muestreo dentro del máximo configurado. `SamplingRateBoost` se puede aplicar a cualquier regla de muestreo personalizada, excepto a la regla de muestreo `Default`.
El campo `SamplingRateBoost` define el límite superior y el comportamiento del muestreo provocado por anomalías.
```
"SamplingRateBoost": {
"MaxRate": 0.25,
"CooldownWindowMinutes": 10
}
```
`MaxRate` define la frecuencia de muestreo máxima que aplicará X-Ray cuando detecte anomalías. El intervalo de valores es `0.0` a `1.0`. Por ejemplo, `"MaxRate": 0.25` permite que el muestreo aumente hasta un 25 % de las solicitudes durante un periodo de anomalías. X-Ray determina la frecuencia adecuada entre la línea base y la máxima, en función de la actividad de la anomalía.
`CooldownWindowMinutes` define el intervalo de tiempo (en minutos) en el que solo se puede desencadenar un aumento de la frecuencia de muestreo. Una vez que se produce un aumento, no se permiten más aumentos hasta la siguiente ventana. El tipo de valor es *entero (minutos)*.
**Regla de ejemplo con muestreo adaptativo**
```
{
"RuleName": "MyAdaptiveRule",
"Priority": 1,
"ReservoirSize": 1,
"FixedRate": 0.05,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"SamplingRateBoost": {
"MaxRate": 0.25,
"CooldownWindowMinutes": 10
}
}
```
En este ejemplo, el muestreo de referencia es del 5 % (`FixedRate: 0.05`). Durante las anomalías, X-Ray puede aumentar el muestreo hasta un 25 % (`MaxRate: 0.25`). Aumente solo una vez cada 10 minutos.
**Configuración de estado anómalo**
Cuando no se proporciona una configuración de condición de anomalía, el ADOT SDK utiliza los **códigos de error HTTP 5xx** como condición de anomalía predeterminada para desencadenar el aumento del muestreo.
También puede refinar las condiciones de las anomalías de forma local en el ADOT SDK compatible mediante variables de entorno. Para obtener más información, consulte [Configuración de SDK local](#local-sdk-configuration).
### Captura de intervalos de anomalías
La captura de intervalos de anomalías garantiza que los intervalos críticos que representan anomalías se registren siempre, incluso si no se ha muestreado todo el rastro. Esta característica complementa el impulso del muestreo al centrarse en capturar la anomalía en sí misma, en lugar de aumentar el muestreo para rastros futuros.
Cuando el ADOT SDK detecta una anomalía, emite ese intervalo inmediatamente, independientemente de la decisión de muestreo. Como el SDK solo emite intervalos relacionados con la anomalía, estos rastros son parciales, no transacciones completas integrales.
Una vez que ADOT SDK detecta un intervalo de anomalías, intenta emitir tantos intervalos como sea posible a partir del mismo rastro. Todos los intervalos emitidos en virtud de esta característica se etiquetan con el atributo, `aws.trace.flag.sampled = 0`. Esto le permite distinguir fácilmente los rastros parciales (captura de anomalías) de los rastros completos (muestreo normal) en la búsqueda y el análisis de las transacciones.
Recomendamos incorporar [Búsqueda de transacciones](https://docs.aws.amazon.com/xray/latest/devguide/xray-transactionsearch.html) para ver y consultar los rastros parciales. El siguiente ejemplo muestra una página de servicio en la consola de [señales de aplicaciones](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html). El ServiceC está configurado con la captura de intervalos de anomalías y forma parte de una cadena de llamadas en la que se aplica el aumento de muestreo. Esta configuración genera rastros completos y parciales. Puede utilizar el atributo `aws.trace.flag.sampled` para distinguir entre los tipos de rastros.
![\[Captura de intervalos de anomalías\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/adaptive-sampling.png)
La captura de intervalos de anomalías solo se puede habilitar o personalizar a través de [Configuración de SDK local](#local-sdk-configuration).
## Configuración de SDK local
Puede configurar las características de muestreo adaptativo en el ADOT SDK proporcionando una configuración YAML a través de una variable de entorno. La configuración local proporciona un control minucioso sobre las condiciones de anomalía y los umbrales.
Esto es necesario para la *captura de intervalos de anomalías* y es opcional para personalizar las condiciones de *potenciación del muestreo*. A continuación, se muestra un ejemplo de la configuración:
```
version: 1.0
anomalyConditions:
- errorCodeRegex: "^5\\d\\d$"
usage: both
- operations:
- "/api"
errorCodeRegex: "^429|5\\d\\d$"
highLatencyMs: 300
usage: sampling-boost
- highLatencyMs: 1000
usage: anomaly-span-capture
anomalyCaptureLimit:
anomalyTracesPerSecond: 1
```
Las definiciones de los campos son las siguientes:
+ `version`: versión esquemática del archivo de configuración
+ `anomalyConditions`: define las condiciones en las que se detectan las anomalías y cómo se utilizan
+ `errorCodeRegex`: expresión regular que define qué códigos de estado HTTP se consideran anomalías
+ `operations`: lista de operaciones o puntos de conexión a los que se aplica la condición
+ `highLatencyMs`: umbral de latencia (en milisegundos) por encima del cual los intervalos se consideran anomalías
+ `usage`: define a qué característica se aplica la condición:
+ `both`: se aplica a la **potenciación del muestreo** y a la **captura de intervalos de anomalías** (predeterminado si no se especifica el uso)
+ `sampling-boost`: se utiliza solo para desencadenar aumentos de muestreo
+ `anomaly-span-capture`: se utiliza solo para la captura de intervalos de anomalías
+ `anomalyCaptureLimit`: define los límites del número de rastros que se emiten con intervalos de anomalías.
`anomalyTracesPerSecond`: número máximo de rastros con intervalos de anomalías capturados por segundo, para evitar un volumen de intervalo excesivo (el valor predeterminado es 1 si anomalyCaptureLimit no está presente).
**nota**
`AnomalyConditions` **invalida** la condición de anomalía predeterminada para el aumento del muestreo (HTTP 5xx). Si desea retener la condición predeterminada mientras utiliza la configuración local, debe incluirla explícitamente en cualquier elemento de `AnomalyConditions`.
Para cada elemento `anomalyConditions`:
Cuando el campo `operations` **se omite**, la condición se aplica a **todas las operaciones** (nivel de servicio)
Cuando el campo `operations` está presente pero está configurado en una **lista vacía**, la condición no se aplica a **ninguna operación**, por lo que ese elemento no es operativo
Si se omite `errorCodeRegex` y `highLatencyMs`, la condición no tiene ningún criterio de anomalía que evaluar, por lo que ese elemento no es operativo
Relaciones lógicas:
Entre los elementos de `anomalyConditions`, la relación es **OR**.
Dentro de un único elemento, varios campos (por ejemplo, `errorCodeRegex` y `highLatencyMs`) se combinan con **AND**.
Por ejemplo:
```
errorCodeRegex: "^429|5\\d\\d$"
highLatencyMs: 300
```
Esta condición significa que **el código de estado coincide con 429 o 5xx Y una latencia ≥ 300 ms**.
### Aplicación de la configuración local al ADOT SDK
Puede aplicar la configuración local al ADOT SDK configurando la variable de entorno `AWS_XRAY_ADAPTIVE_SAMPLING_CONFIG`. El valor debe ser un documento YAML válido (integrado o anidado).
Por ejemplo, Amazon EC2 y Amazon ECS configuran la variable de entorno directamente:
```
AWS_XRAY_ADAPTIVE_SAMPLING_CONFIG="{version: 1.0, anomalyConditions: [{errorCodeRegex: \"^500$\", usage: \"sampling-boost\"}, {errorCodeRegex: \"^501$\", usage: \"anomaly-trace-capture\"}], anomalyCaptureLimit: {anomalyTracesPerSecond: 10}}"
```
Para Amazon EKS, defina la variable de entorno dentro de la especificación del pod como YAML anidado:
```
apiVersion: v1
kind: Pod
metadata:
name: adot-sample
spec:
containers:
- name: adot-app
image: my-app:latest
env:
- name: AWS_XRAY_ADAPTIVE_SAMPLING_CONFIG
value: |
version: 1.0
anomalyConditions:
- errorCodeRegex: "^500$"
usage: sampling-boost
- errorCodeRegex: "^501$"
usage: anomaly-trace-capture
anomalyCaptureLimit:
anomalyTracesPerSecond: 10
```
# Enlace profundo de la consola
Puede usar rutas y consultas para establecer un enlace profundo rastros específicos, o bien usar vistas filtradas de rastros y el mapa de rastros.
**Páginas de la consola**
+ Página principal: [xray/home\$1/welcome](https://console.aws.amazon.com/xray/home#/welcome)
+ Introducción: [xray/home\$1/getting-started](https://console.aws.amazon.com/xray/home#/getting-started)
+ Mapa de rastros: [xray/home\$1/service-map](https://console.aws.amazon.com/xray/home#/service-map)
+ Rastros: [xray/home\$1/traces](https://console.aws.amazon.com/xray/home#/traces)
## Registros de seguimiento
Puede generar enlaces a las vistas de escala de tiempo, sin procesar y mapa de los rastros individuales.
**Escala de tiempo de rastros**: `xray/home#/traces/trace-id`
**Datos de rastro sin procesar**: `xray/home#/traces/trace-id/raw`
**Example – datos de rastro sin procesar**
```
https://console.aws.amazon.com/xray/home#/traces/1-57f5498f-d91047849216d0f2ea3b6442/raw
```
## Expresiones de filtro
Enlazan con una lista filtrada de rastros.
**Vista de rastros filtrados**: `xray/home#/traces?filter=filter-expression`
**Example – expresión de filtro**
```
https://console.aws.amazon.com/xray/home#/traces?filter=service("api.amazon.com") { fault = true OR responsetime > 2.5 } AND annotation.foo = "bar"
```
**Example – expresión de filtro (URL codificada)**
```
https://console.aws.amazon.com/xray/home#/traces?filter=service(%22api.amazon.com%22)%20%7B%20fault%20%3D%20true%20OR%20responsetime%20%3E%202.5%20%7D%20AND%20annotation.foo%20%3D%20%22bar%22
```
Para obtener más información sobre las expresiones de filtro, consulte [Uso de expresiones de filtro](xray-console-filters.md).
## Intervalo de tiempo
Especifique un intervalo de tiempo o una hora de inicio y una hora de finalización en formato ISO8601. Los rangos de tiempo se indican en UTC y su duración máxima es de seis horas.
**Período de tiempo**: `xray/home#/page?timeRange=range-in-minutes`
**Example — mapa de rastros de la última hora**
```
https://console.aws.amazon.com/xray/home#/service-map?timeRange=PT1H
```
**Hora de inicio y finalización**: `xray/home#/page?timeRange=start~end`
**Example – intervalo de tiempo con una precisión de segundos**
```
https://console.aws.amazon.com/xray/home#/traces?timeRange=2023-7-01T16:00:00~2023-7-01T22:00:00
```
**Example – intervalo de tiempo con una precisión de minutos**
```
https://console.aws.amazon.com/xray/home#/traces?timeRange=2023-7-01T16:00~2023-7-01T22:00
```
## Región
Especifique una Región de AWS para enlazar a las páginas que haya en esa región. De lo contrario, la consola le redirige a la última región que ha visitado.
**Región**: `xray/home?region=region#/page`
**Example – mapa de rastros en el Oeste de EE. UU. (Oregón) (us-west-2)**
```
https://console.aws.amazon.com/xray/home?region=us-west-2#/service-map
```
Cuando se incluye una región con otros parámetros de consulta, la consulta de región va antes de la almohadilla y las consultas específicas de X-Ray van después del nombre de página.
**Example – mapa de rastros de la última hora en el Oeste de EE. UU. (Oregón) (us-west-2)**
```
https://console.aws.amazon.com/xray/home?region=us-west-2#/service-map?timeRange=PT1H
```
## En combinación
**Example – rastros recientes con un filtro de duración**
```
https://console.aws.amazon.com/xray/home#/traces?timeRange=PT15M&filter=duration%20%3E%3D%205%20AND%20duration%20%3C%3D%208
```
**Output**
+ Página — Rastros
+ Intervalo de tiempo: últimos 15 minutos
+ Filtro: duración >= 5 Y duración <= 8
# 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=?;"
}
}
```