AWS X-RayGuía para desarrolladores
AWS X-Ray Guía para desarrolladores
AWS X-Ray: Guía para desarrolladoresCopyright © Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's,in any manner that is likely to cause confusion among customers, or in any manner that disparages or discreditsAmazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may notbe affiliated with, connected to, or sponsored by Amazon.
AWS X-Ray Guía para desarrolladores
Table of Contents¿Qué es AWS X-Ray? ........................................................................................................................ 1Casos de uso .................................................................................................................................... 3
Lenguajes y marcos de trabajo admitidos ....................................................................................... 4Servicios compatibles AWS .......................................................................................................... 6Cambios en el código y la configuración ........................................................................................ 7
Introducción ....................................................................................................................................... 8Prerequisites .............................................................................................................................. 9Implementar en Elastic Beanstalk y generar datos de seguimiento .................................................... 10Consultar el mapa de servicios en la consola de X-Ray .................................................................. 11Configuración de notificaciones de Amazon SNS ........................................................................... 13Explorar la aplicación de ejemplo ................................................................................................ 15Opcional: política de privilegios mínimos ...................................................................................... 18Eliminar recursos ...................................................................................................................... 20Pasos siguientes ....................................................................................................................... 20
Conceptos ....................................................................................................................................... 21Segments ................................................................................................................................ 21Subsegments ........................................................................................................................... 22Gráfico de servicios .................................................................................................................. 24Traces ..................................................................................................................................... 25Sampling ................................................................................................................................. 26Encabezado de seguimiento ....................................................................................................... 26Expresiones de filtro .................................................................................................................. 27Groups .................................................................................................................................... 27Anotaciones y metadatos ........................................................................................................... 27Errores y excepciones ............................................................................................................... 28
Seguridad ........................................................................................................................................ 29.............................................................................................................................................. 29
Protección de los datos ............................................................................................................. 29Administración de identidades y accesos ...................................................................................... 30
Público ............................................................................................................................ 31Autenticación con identidades ............................................................................................. 31Administración de acceso mediante políticas ......................................................................... 33Cómo funciona AWS X-Ray con IAM ................................................................................... 35Ejemplos de políticas basadas en identidades ....................................................................... 40Solución de problemas ...................................................................................................... 47
Registro y monitorización ........................................................................................................... 49Validación de la conformidad ...................................................................................................... 49Resiliencia ............................................................................................................................... 50Seguridad de la infraestructura ................................................................................................... 50
X-RayConsola de .............................................................................................................................. 51Consulta del mapa de servicio .................................................................................................... 51
Ver el mapa de servicio por grupo ...................................................................................... 54Cambio de la presentación del nodo .................................................................................... 55
Consulta de registros de seguimiento .......................................................................................... 57Consulta del mapa de seguimiento .............................................................................................. 59Consulta de detalles de segmentos ............................................................................................. 60Consulta de detalles de subsegmentos ........................................................................................ 61Expresiones de filtro .................................................................................................................. 64
Detalles de expresión de filtro ............................................................................................. 64Uso de expresiones de filtro con grupos ............................................................................... 65Sintaxis de expresiones de filtro .......................................................................................... 65Palabras clave booleanas .................................................................................................. 66Palabras clave numéricas .................................................................................................. 67Palabras clave de cadenas ................................................................................................ 68
iii
AWS X-Ray Guía para desarrolladores
Palabras clave complejas ................................................................................................... 69id Función ........................................................................................................................ 71
Vinculación en profundidad ........................................................................................................ 73Rastros ............................................................................................................................ 73Expresiones de filtro .......................................................................................................... 73Intervalo de tiempo ........................................................................................................... 74Región ............................................................................................................................ 74En combinación ................................................................................................................ 74
Histogramas ............................................................................................................................. 75Latencia ........................................................................................................................... 75Interpretación de los detalles del servicio ............................................................................. 75
Muestreo ................................................................................................................................. 76Configuración de reglas de muestreo ................................................................................... 77Personalización de reglas de muestreo ................................................................................ 77Opciones de reglas de muestreo ......................................................................................... 78Ejemplos de reglas de muestreo ......................................................................................... 79Configuración del servicio para utilizar reglas de muestreo ...................................................... 79Visualización de resultados de muestreo .............................................................................. 80Pasos siguientes ............................................................................................................... 80
Insights .................................................................................................................................... 81Habilitar la información en la X-Ray consola de ..................................................................... 81Habilitar notificaciones de conocimientos .............................................................................. 82Información general de Insight ............................................................................................ 83Revisar el progreso de un conocimiento ............................................................................... 85
Analytics .................................................................................................................................. 87Características de la consola .............................................................................................. 87Distribución del tiempo de respuesta ................................................................................... 89Actividad de series temporales ........................................................................................... 90Ejemplos de flujo de trabajo ............................................................................................... 90Observar errores en el gráfico de servicio ............................................................................ 90Identificar los picos de tiempo de respuesta .......................................................................... 91Consultar todos los registros de seguimiento marcados con un código de estado ........................ 91Consultar todos los elementos de un subgrupo y asociados a un usuario ................................... 92Comparar dos conjuntos de registros de seguimiento con criterios diferentes .............................. 92Identificar un registro de seguimiento de su interés y ver sus detalles ........................................ 92
Grupos .................................................................................................................................... 92Crear un grupo en la X-Ray consola de ............................................................................... 93Aplicar un grupo ............................................................................................................... 94Editar un grupo ................................................................................................................ 95Clonar un grupo ............................................................................................................... 96Eliminar un grupo ............................................................................................................. 97Ver métricas de grupo de en Amazon CloudWatch ................................................................ 97
X-RayAPI de .................................................................................................................................... 99Tutorial .................................................................................................................................... 99
Prerequisites .................................................................................................................... 99Generar datos de seguimiento .......................................................................................... 100Uso de la API de X-Ray. .................................................................................................. 100Cleanup ......................................................................................................................... 102
Envío de datos ....................................................................................................................... 102Generación de identificadores de seguimiento ..................................................................... 104Uso de PutTraceSegments ............................................................................................... 104Envío de documentos de segmento al demonio de X-Ray ..................................................... 105
Obtención de datos ................................................................................................................. 106Recuperación del gráfico de servicios ................................................................................ 106Recuperación del gráfico de servicios por grupo .................................................................. 111Recuperación de registros de seguimiento .......................................................................... 111Recuperación y ajuste de las causas raíz de Analytics .......................................................... 114
iv
AWS X-Ray Guía para desarrolladores
Configuración ......................................................................................................................... 116Configuración de cifrado ................................................................................................... 116Reglas de muestreo ........................................................................................................ 117Groups .......................................................................................................................... 120
Muestreo ................................................................................................................................ 121Documentos de segmentos ...................................................................................................... 123
Campos de segmentos .................................................................................................... 124Subsegments .................................................................................................................. 126Datos de solicitudes HTTP ............................................................................................... 129Annotations .................................................................................................................... 131Metadata ........................................................................................................................ 131AWS Datos de recursos de .............................................................................................. 132Errores y excepciones ..................................................................................................... 134Consultas SQL ............................................................................................................... 135
Aplicación de muestra ...................................................................................................................... 137Introducción (CLI) .................................................................................................................... 141
Prerequisites .................................................................................................................. 142Crear la instancia Amazon EC2 ........................................................................................ 142Instale la CLI de AWS ..................................................................................................... 143Implementar Scorekeep .................................................................................................... 144Generar datos de seguimiento .......................................................................................... 146Obtener datos ................................................................................................................. 147Configurar las notificaciones de Amazon SNS ..................................................................... 151Eliminar recursos ............................................................................................................ 152Pasos siguientes ............................................................................................................. 152
AWS Clientes de SDK ............................................................................................................. 152Subsegmentos personalizados .................................................................................................. 153Anotaciones y metadatos ......................................................................................................... 153Clientes de HTTP ................................................................................................................... 154Clientes de SQL ..................................................................................................................... 155AWS LambdaFunciones de ...................................................................................................... 157
Nombre aleatorio ............................................................................................................. 158Worker ........................................................................................................................... 159
Amazon ECS .......................................................................................................................... 161Código de inicio ...................................................................................................................... 162Scripts ................................................................................................................................... 163Cliente ................................................................................................................................... 165Subprocesos de trabajo ........................................................................................................... 168Vinculación en profundidad ....................................................................................................... 170
X-RayDemonio de ........................................................................................................................... 171Descargar el demonio .............................................................................................................. 171Verificación de la firma del archivo de demonio ........................................................................... 172Ejecutar el demonio ................................................................................................................. 173Concesión de permiso al demonio para el envío de datos a X-Ray ................................................. 173X-RayRegistros del demonio de ................................................................................................ 174Configuración ......................................................................................................................... 174
Variables de entorno admitidas ......................................................................................... 175Uso de las opciones de la línea de comandos ..................................................................... 175Uso de un archivo de configuración ................................................................................... 176
Ejecución del demonio localmente ............................................................................................. 177Ejecución del demonio de X-Ray en Linux .......................................................................... 177Ejecución del demonio de X-Ray en un contenedor Docker ................................................... 178Ejecución del demonio de X-Ray en Windows ..................................................................... 179Ejecución del demonio de X-Ray en OS X .......................................................................... 179
En Elastic Beanstalk ................................................................................................................ 180Uso de la integración de Elastic Beanstalk en X-Ray para ejecutar el demonio de X-Ray ............. 180Descarga y ejecución del demonio de X-Ray manualmente (avanzado) ................................... 181
v
AWS X-Ray Guía para desarrolladores
En Amazon EC2 ..................................................................................................................... 183En Amazon ECS ..................................................................................................................... 184
Uso de la imagen de Docker oficial de la ............................................................................ 184Creación y compilación de una imagen de Docker ............................................................... 184Configuración de las opciones de línea de comandos en la consola de Amazon ECS ................. 186
Integración con los servicios de AWS ................................................................................................ 188API Gateway .......................................................................................................................... 188App Mesh .............................................................................................................................. 189AWS AppSync ........................................................................................................................ 191CloudTrail .............................................................................................................................. 191CloudWatch ............................................................................................................................ 193
CloudWatchSynthetics de ................................................................................................. 193AWS Config ........................................................................................................................... 199
Creación de un desencadenador de funciones Lambda ......................................................... 200Creación de una regla de AWS Config personalizada para X-Ray ........................................... 201Resultados de ejemplo ..................................................................................................... 201Notificaciones de Amazon SNS ......................................................................................... 202
Amazon EC2 .......................................................................................................................... 202Elastic Beanstalk ..................................................................................................................... 202Elastic Load Balancing ............................................................................................................. 203EventBridge ............................................................................................................................ 203
Visualización del origen y los destinos en el mapa de X-Ray servicio ....................................... 203Propagar el contexto de seguimiento a los destinos de eventos .............................................. 204
Lambda ................................................................................................................................. 208Amazon SNS .......................................................................................................................... 209
Requirements ................................................................................................................. 209Creación de una función de suscriptor Lambda .................................................................... 209Creación de un tema de Amazon SNS ............................................................................... 210Creación de una función de editor Lambda ......................................................................... 211Comprobación y validación de la propagación de contexto .................................................... 212
Step Functions ........................................................................................................................ 213Amazon SQS ......................................................................................................................... 214
Enviar el encabezado de seguimiento HTTP ....................................................................... 215Recuperar el encabezado y el contexto de seguimiento ........................................................ 215
Amazon S3 ............................................................................................................................ 216Configurar notificaciones Amazon S3 de eventos ................................................................. 216
Uso de Go ..................................................................................................................................... 218Requirements ......................................................................................................................... 219Documentación de referencia .................................................................................................... 219Configuración ......................................................................................................................... 219
Complementos del servicio ............................................................................................... 219Reglas de muestreo ........................................................................................................ 221Registro de .................................................................................................................... 222Variables de entorno ....................................................................................................... 223Uso de la opción configure ............................................................................................... 223
Solicitudes entrantes ................................................................................................................ 224Configuración de una estrategia de nomenclatura de segmentos ............................................ 225
AWS Clientes de SDK ............................................................................................................. 226Llamadas a HTTP salientes ...................................................................................................... 227Consultas SQL ....................................................................................................................... 228Subsegmentos personalizados .................................................................................................. 228Anotaciones y metadatos ......................................................................................................... 229
Registro de anotaciones con el SDK de X-Ray para Go ........................................................ 229Registro de metadatos con el SDK de X-Ray para Go .......................................................... 230Registro de ID de usuario con el SDK de X-Ray para Go ...................................................... 230
Uso de Java ................................................................................................................................... 231Submodules ........................................................................................................................... 232
vi
AWS X-Ray Guía para desarrolladores
Requirements ......................................................................................................................... 232Administración de dependencias ............................................................................................... 233AWS X-Ray Agente de instrucción automática de para Java .......................................................... 234
Aplicación de muestra ...................................................................................................... 235Introducción .................................................................................................................... 235Configuration .................................................................................................................. 235Troubleshooting .............................................................................................................. 241
Configuración ......................................................................................................................... 242Complementos del servicio ............................................................................................... 242Reglas de muestreo ........................................................................................................ 244Logging ......................................................................................................................... 246Agentes de escucha de segmento ..................................................................................... 249Variables de entorno ....................................................................................................... 250Propiedades del sistema .................................................................................................. 250
Solicitudes entrantes ................................................................................................................ 250Agregar un filtro de seguimiento a la aplicación (Tomcat) ...................................................... 251Agregar un filtro de seguimiento a la aplicación (Spring) ....................................................... 252Configuración de una estrategia de nomenclatura de segmentos ............................................ 252
AWS Clientes de SDK ............................................................................................................. 254Llamadas a HTTP salientes ...................................................................................................... 255Consultas SQL ....................................................................................................................... 257Subsegmentos de personalizados .............................................................................................. 258Anotaciones y metadatos ......................................................................................................... 260
Registro de anotaciones con el X-Ray SDK for Java ............................................................ 261Registro de metadatos con el X-Ray SDK for Java ............................................................... 262Registro de ID de usuario con el X-Ray SDK for Java .......................................................... 263
Monitorización ......................................................................................................................... 264Métricas de X-Ray para CloudWatch .................................................................................. 264Dimensiones de X-Ray para CloudWatch ............................................................................ 265Habilitar las métricas de X-Ray para CloudWatch ................................................................. 265
Multiproceso ........................................................................................................................... 266Uso de X-Ray con programación asíncrona ........................................................................ 267
AOP con Spring ...................................................................................................................... 267Configuración de Spring ................................................................................................... 267Agregar un filtro de rastreo a la aplicación .......................................................................... 268Anotación del código o implementación de una interfaz ......................................................... 268Activación de X-Ray en la aplicación ................................................................................. 268Example ........................................................................................................................ 268
Uso de Node.js ............................................................................................................................... 270Requirements ......................................................................................................................... 271Administración de dependencias ............................................................................................... 271Ejemplos de Node.js ................................................................................................................ 272Configuración ......................................................................................................................... 272
Complementos del servicio ............................................................................................... 272Reglas de muestreo ........................................................................................................ 273Registro de .................................................................................................................... 274Dirección del demonio de X-Ray ....................................................................................... 275Variables de entorno ....................................................................................................... 275
Solicitudes entrantes ................................................................................................................ 276Seguimiento de solicitudes entrantes con Express ................................................................ 277Seguimiento de solicitudes entrantes con Restify ................................................................. 277Configuración de una estrategia de nomenclatura de segmentos ............................................ 278
AWS Clientes de SDK ............................................................................................................. 279Llamadas a HTTP salientes ...................................................................................................... 280Consultas SQL ....................................................................................................................... 281
Inclusión de datos adicionales en subsegmentos SQL .......................................................... 282Subsegmentos de personalizados .............................................................................................. 282
vii
AWS X-Ray Guía para desarrolladores
Subsegmentos Express personalizados .............................................................................. 282Subsegmentos de Lambda personalizados .......................................................................... 283
Anotaciones y metadatos ......................................................................................................... 284Registro de anotaciones con el X-Ray SDK for Node.js ......................................................... 284Registro de metadatos con el X-Ray SDK for Node.js ........................................................... 285Registro de ID de usuario con el X-Ray SDK for Node.js ....................................................... 286
Uso de Python ................................................................................................................................ 287Requirements ......................................................................................................................... 288Administración de dependencias ............................................................................................... 289Configuración ......................................................................................................................... 289
Complementos del servicio ............................................................................................... 289Reglas de muestreo ........................................................................................................ 291Logging ......................................................................................................................... 292Configuración de la grabadora en código ............................................................................ 292Configuración de la grabadora con Django .......................................................................... 293Variables de entorno ....................................................................................................... 294
Solicitudes entrantes ................................................................................................................ 294Agregar el middleware a su aplicación (Django) ................................................................... 295Agregar el middleware a su aplicación (flask) ...................................................................... 296Agregar el middleware a su aplicación (Bottle) ..................................................................... 297Instrumentación manual del código de Python ..................................................................... 297Configuración de una estrategia de nomenclatura de segmentos ............................................ 297
Aplicación de parches a bibliotecas ........................................................................................... 298Seguimiento del contexto para el funcionamiento asíncrono ................................................... 300
AWS Clientes de SDK ............................................................................................................. 300Llamadas a HTTP salientes ...................................................................................................... 301Subsegmentos personalizados .................................................................................................. 302Anotaciones y metadatos ......................................................................................................... 304
Registro de anotaciones con el SDK de X-Ray para Python ................................................... 304Registro de metadatos con el SDK de X-Ray para Python ..................................................... 305Registro de identificadores de usuario con el SDK de X-Ray para Python ................................. 306
Instrumentación de aplicaciones sin servidor ............................................................................... 306Prerequisites .................................................................................................................. 307Paso 1: Crear un entorno ................................................................................................. 307Paso 2: Crear e implementar un entorno de Zappa .............................................................. 308Paso 3: Habilitar el seguimiento de X-Ray en API Gateway ................................................... 309Paso 4: Consultar el registro de seguimiento creado ............................................................ 309Paso 5: Eliminación ......................................................................................................... 310Pasos siguientes ............................................................................................................. 311
Uso de Ruby .................................................................................................................................. 312Requirements ......................................................................................................................... 313Configuración ......................................................................................................................... 313
Complementos del servicio ............................................................................................... 313Reglas de muestreo ........................................................................................................ 315Logging ......................................................................................................................... 317Configuración de la grabadora en código ............................................................................ 317Configuración de la grabadora con Rails ............................................................................ 318Variables de entorno ....................................................................................................... 318
Solicitudes entrantes ................................................................................................................ 319Uso del middleware de Rails ............................................................................................ 319Instrumentación manual del código .................................................................................... 320Configuración de una estrategia de nomenclatura de segmentos ............................................ 320
Aplicación de parches a bibliotecas ........................................................................................... 321AWS Clientes de SDK ............................................................................................................. 322Subsegmentos personalizados .................................................................................................. 323Anotaciones y metadatos ......................................................................................................... 323
Registro de anotaciones con el SDK de X-Ray para Ruby ..................................................... 324
viii
AWS X-Ray Guía para desarrolladores
Registro de metadatos con el SDK de X-Ray para Ruby ....................................................... 325Registro de ID de usuario con el SDK de X-Ray para Ruby ................................................... 325
Uso de .NET .................................................................................................................................. 327Requirements ......................................................................................................................... 328Agregar el X-Ray SDK for .NET a su aplicación ........................................................................... 328Configuración ......................................................................................................................... 328
Complementos ................................................................................................................ 329Reglas de muestreo ........................................................................................................ 330Registro (.NET) ............................................................................................................... 332Registro (.NET Core) ....................................................................................................... 332Variables de entorno ....................................................................................................... 333
Solicitudes entrantes ................................................................................................................ 333Instrumentación de las solicitudes entrantes (.NET) .............................................................. 334Instrumentación de las solicitudes entrantes (.NET Core) ...................................................... 335Configuración de una estrategia de nomenclatura de segmentos ............................................ 335
AWS Clientes de SDK ............................................................................................................. 336Llamadas a HTTP salientes ...................................................................................................... 338Consultas SQL ....................................................................................................................... 339
Seguimiento de consultas SQL con métodos síncronos y asíncronos ....................................... 339Recopilación de consultas SQL realizadas a SQL Server ...................................................... 340
Subsegmentos personalizados .................................................................................................. 341Anotaciones y metadatos ......................................................................................................... 342
Registro de anotaciones con el X-Ray SDK for .NET ............................................................ 343Registro de metadatos con el X-Ray SDK for .NET .............................................................. 343
Uso de la distribución de AWS paraOpenTelemetry .............................................................................. 345Etiquetado ...................................................................................................................................... 346
Restricciones de las etiquetas ................................................................................................... 347Administración de etiquetas en la consola de .............................................................................. 347
Agregar etiquetas a un nuevo grupo de (consola) ................................................................ 347Agregar etiquetas a una nueva regla de muestreo (consola) .................................................. 348Editar o eliminar etiquetas de un grupo (consola) ................................................................. 348Editar o eliminar etiquetas de una regla de muestreo (consola) .............................................. 349
Administración de etiquetas en la AWS CLI ................................................................................ 349Agregar etiquetas a un nuevo X-Ray grupo o regla de muestreo (CLI) ..................................... 349Agregar etiquetas a un recurso existente (CLI) .................................................................... 351Enumerar etiquetas en un recurso (CLI) ............................................................................. 351Eliminar etiquetas en un recurso (CLI) ............................................................................... 352
Controlar el acceso a X-Ray los recursos de en función de las etiquetas .......................................... 352Solución de problemas ..................................................................................................................... 353
X-Ray SDK for Java ................................................................................................................ 353X-Ray SDK for Node.js ............................................................................................................ 353El demonio de X-Ray .............................................................................................................. 354
Historial de revisión ......................................................................................................................... 355................................................................................................................................................. ccclvii
ix
AWS X-Ray Guía para desarrolladores
¿Qué es AWS X-Ray?AWS X-Ray es un servicio que recopila datos sobre las solicitudes que su aplicación atiende y proporcionaherramientas que puede utilizar para consultar, filtrar y obtener información sobre dichos datos paraidentificar problemas y oportunidades de optimización. En cada solicitud rastreada enviada a su aplicación,puede ver información detallada sobre la solicitud, la respuesta y también sobre las llamadas que suaplicación realiza a recursos, microservicios, bases de datos de AWS y API web de HTTP posteriores.
El SDK de X-Ray proporciona:
• Interceptadores para añadir a su código y controlar solicitudes HTTP entrantes• Controladores de cliente para instrumentar clientes AWS SDK que la aplicación utiliza para llamar a
otros AWS servicios de• Un cliente HTTP que se puede utilizar para instrumentar llamadas a servicios web HTTP internos y
externos
El SDK también admite la instrumentación de llamadas a bases de datos SQL, la instrumentaciónautomática de clientes AWS SDK y otras características.
En lugar de enviar los datos de rastreo directamente a X-Ray, el SDK envía documentos de segmentoJSON a un proceso del demonio que escucha el tráfico UDP. El demonio de X-Ray (p. 171) almacena
1
AWS X-Ray Guía para desarrolladores
en búfer segmentos en una cola y los carga a X-Ray en lotes. El demonio está disponible para Linux,Windows y macOS y se incluye en las plataformas AWS Elastic Beanstalk y AWS Lambda.
X-Ray utiliza datos de rastreo de los AWS recursos que alimentan sus aplicaciones en la nube paragenerar un gráfico de servicios detallado. El gráfico de servicios muestra el cliente, el servicio front-end ylos servicios back-end a los que llama el servicio front-end para procesar solicitudes y mantener los datos.Utilice el gráfico de servicios para identificar cuellos de botella, picos de latencia y otros problemas quepuede resolver a fin de mejorar el desempeño de las aplicaciones.
Consulte el tutorial de introducción (p. 8) para empezar a utilizar X-Ray en tan solo unos minutos conuna aplicación de ejemplo instrumentada. O siga leyendo (p. 3) para obtener información sobre loslenguajes, marcos de trabajo y servicios que funcionan con X-Ray.
2
AWS X-Ray Guía para desarrolladores
AWS X-RayCasos de uso y requisitosde
Puede utilizar el X-Ray SDK de y la integración de AWS servicios de para instrumentar solicitudes a susaplicaciones que se ejecutan localmente o en servicios AWS informáticos como Amazon EC2 ElasticBeanstalk, Amazon ECS y AWS Lambda.
Para instrumentar el código de su aplicación, utilice el SDK de X-Ray. El SDK registra datos sobre lassolicitudes entrantes y salientes y los envía al demonio de X-Ray, el cual retransmite los datos en lotes aX-Ray. Por ejemplo, cuando su aplicación llama a DynamoDB para recuperar información de un usuariode la tabla de DynamoDB, el SDK de X-Ray registra los datos de la solicitud de cliente y de la llamadaposterior a DynamoDB.
Otros AWS servicios de facilitan la instrumentación de los componentes de su aplicación al integrarse conX-Ray. La integración de servicios puede incluir rastrear encabezados a solicitudes entrantes, enviar datosde rastreo a X-Ray o ejecutar el demonio de X-Ray. Por ejemplo, AWS Lambda puede enviar los datos derastreo sobre las solicitudes a sus funciones de Lambda y ejecutar el demonio de X-Ray en los procesosde trabajo para facilitar el uso del SDK de X-Ray.
3
AWS X-Ray Guía para desarrolladoresLenguajes y marcos de trabajo admitidos
Muchos escenarios de instrumentación solo requieren cambios en la configuración. Por ejemplo, puedeinstrumentar todas las solicitudes HTTP entrantes y las llamadas posteriores a AWS los servicios de querealiza su aplicación Java. Para ello, añada el filtro del X-Ray SDK for Java a la configuración de servlety adopte el submódulo Instrumentor de AWS SDK for Java como una dependencia de compilación. Pararealizar una instrumentación avanzada, puede modificar el código de la aplicación para personalizar yanotar los datos que el SDK envía a X-Ray.
Secciones• Lenguajes y marcos de trabajo admitidos (p. 4)• Servicios compatibles AWS (p. 6)• Cambios en el código y la configuración (p. 7)
Lenguajes y marcos de trabajo admitidosAWS X-Ray proporciona herramientas e integración para admitir una variedad de lenguajes, marcos detrabajo y plataformas.
C#
En Windows Server, puede utilizar el X-Ray SDK for .NET para instrumentar las solicitudes entrantes, losclientes AWS del SDK, los clientes SQL y los clientes HTTP. En AWS Lambda puede utilizar la integraciónde Lambda en X-Ray para instrumentar las solicitudes entrantes.
Para obtener más información, consulte AWS X-Ray SDK para .NET (p. 327).
• .NET en Windows – Server: añada un controlador de (p. 334) mensajes a su configuración HTTP parainstrumentar las solicitudes entrantes.
• C# .NET Core en AWS Lambda – : habilite X-Ray en la configuración de la Lambda función parainstrumentar las solicitudes entrantes.
Go
En cualquier aplicación de Go, puede utilizar las SDK de X-Ray para Go clases de para instrumentar lassolicitudes entrantes, los clientes AWS del SDK, los clientes SQL y los clientes HTTP. La instrumentaciónautomática de solicitudes está disponible para las aplicaciones que utilizan controladores HTTP.
En AWS Lambda puede utilizar la integración de Lambda en X-Ray para instrumentar las solicitudesentrantes. Añada el SDK de X-Ray para Go a la función para disponer de una instrumentación completa.
Para obtener más información, consulte AWS X-RaySDK de para Go (p. 218).
• Aplicaciones web – Go: utilice el controlador SDK de X-Ray para Go (p. 224) HTTP para procesar lassolicitudes entrantes en sus rutas.
• En , AWS Lambda – habilite X-Ray en la configuración de la Lambda función de para instrumentar lassolicitudes entrantes. Añada SDK de X-Ray para Go para instrumentar clientes HTTP, SQL y AWS delSDK.
Java
En cualquier aplicación Java, puede utilizar las X-Ray SDK for Java clases de para instrumentar lassolicitudes entrantes, los clientes AWS del SDK, los clientes SQL y los clientes HTTP. La instrumentaciónautomática de solicitudes está disponible para los marcos de trabajo que admiten servlets de Java. Lainstrumentación automática del SDK está disponible mediante el submódulo Instrumentor.
En AWS Lambda puede utilizar la integración de Lambda en X-Ray para instrumentar las solicitudesentrantes. Añada el X-Ray SDK for Java a la función para disponer de una instrumentación completa.
4
AWS X-Ray Guía para desarrolladoresLenguajes y marcos de trabajo admitidos
Para obtener más información, consulte AWS X-Ray SDK para Java (p. 231).
• – Tomcat: añada un filtro (p. 251) de servlet al descriptor de implementación (web.xml) parainstrumentar las solicitudes entrantes.
• Spring Boot: – añada un filtro (p. 252) de servlet a su WebConfig clase para instrumentar lassolicitudes entrantes.
• Java en AWS Lambda – : habilite X-Ray en su Lambda función para instrumentar las solicitudesentrantes. Añada X-Ray SDK for Java para instrumentar clientes HTTP, SQL y AWS del SDK.
• Other – frameworks: añada un filtro de servlet si el marco admite servlets o cree manualmente unsegmento para cada solicitud entrante.
Node.js
En cualquier aplicación Node.js, puede utilizar las X-Ray SDK for Node.js clases de para instrumentar lassolicitudes entrantes, los clientes AWS del SDK, los clientes SQL y los clientes HTTP. La instrumentaciónautomática de solicitudes está disponible para las aplicaciones que utilizan los marcos de trabajo Express yRestify.
En AWS Lambda puede utilizar la integración de Lambda en X-Ray para instrumentar las solicitudesentrantes. Añada el X-Ray SDK for Node.js a la función para disponer de una instrumentación completa.
Para obtener más información, consulte AWS X-Ray SDK for Node.js (p. 270).
• Express o – Restify: utilice el X-Ray SDK for Node.js middleware (p. 276) para instrumentar lassolicitudes entrantes.
• Node.js en AWS Lambda – : habilite X-Ray en su Lambda función para instrumentar las solicitudesentrantes. Agregar el X-Ray SDK for Node.js para instrumentar clientes HTTP, SQL y AWS del SDK de
• Otros marcos de trabajo: cree – manualmente un segmento para cada solicitud entrante.
Python
En cualquier aplicación Python, puede utilizar las SDK de X-Ray para Python clases para instrumentar lassolicitudes entrantes, los clientes AWS del SDK, los clientes SQL y los clientes HTTP. La instrumentaciónautomática de solicitudes está disponible para las aplicaciones que utilizan los marcos de trabajo Django yFlask.
En AWS Lambda puede utilizar la integración de Lambda en X-Ray para instrumentar las solicitudesentrantes. Añada el SDK de X-Ray para Python a la función para disponer de una instrumentacióncompleta.
Para obtener más información, consulte AWS X-RaySDK de para Python (p. 287).
• Django o – Flask: utilice el SDK de X-Ray para Python middleware (p. 294) para instrumentar lassolicitudes entrantes.
• Python en AWS Lambda – : habilite X-Ray en la configuración de la Lambda función de parainstrumentar las solicitudes entrantes. Añada SDK de X-Ray para Python para instrumentar clientesHTTP, SQL y AWS del SDK.
• Otros marcos de trabajo: cree – manualmente un segmento para cada solicitud entrante.
Ruby
En cualquier aplicación Ruby, puede utilizar las SDK de X-Ray para Ruby clases de para instrumentar lassolicitudes entrantes, los clientes AWS del SDK, los clientes SQL y los clientes HTTP. La instrumentaciónautomática de recursos se puede realizar en aplicaciones que utilizan el marco de trabajo Rails.
5
AWS X-Ray Guía para desarrolladoresServicios compatibles AWS
• – Rails: añada la SDK de X-Ray para Ruby gema y el railtie a su archivo Gemfile y configure lagrabadora (p. 319) en un inicializador para instrumentar las solicitudes entrantes.
• Otros marcos de trabajo: cree – manualmente un segmento (p. 320) para cada solicitud entrante.
Si el SDK de X-Ray no está disponible para su lenguaje o plataforma, puede generar datos de rastreo deforma manual y enviarlos al demonio de X-Ray o directamente a la API de X-Ray (p. 99).
Servicios compatibles AWSVarios servicios de AWS proporcionan servicios de integración con X-Ray. Los serviciosintegrados (p. 188) ofrecen distintos niveles de integración, los cuales pueden incluir el muestreo y laincorporación de encabezados a las solicitudes entrantes, la ejecución del demonio de X-Ray y el envíoautomático de datos de rastreo a X-Ray.
• Instrumentación activa – Realiza un muestreo de las solicitudes entrantes y las instrumenta.• Instrumentación pasiva – Instrumenta solicitudes cuyo muestreo lo realizó otro servicio.• Rastreo de solicitudes – Agrega un encabezado de rastreo a todas las solicitudes entrantes y lo propaga.• – Tooling: ejecuta el X-Ray demonio de para recibir segmentos del X-Ray SDK.
Los siguientes servicios proporcionan la integración de X-Ray:
• AWS Lambda – Instrumentación activa y pasiva de solicitudes entrantes en todos los tiempos deejecución. AWS Lambda añade dos nodos al mapa de servicio, uno para el AWS Lambda servicioy otro para la función . Al habilitar la instrumentación, AWS Lambda también ejecuta el demoniode X-Ray en los tiempos de ejecución de Java y Node.js para usarlo con el SDK de X-Ray. Másinformación (p. 208).
• Amazon API Gateway – Instrumentación activa y pasiva. API Gateway utiliza reglas de muestreo paradeterminar qué solicitudes registrar y añade un nodo para la etapa de gateway a su mapa de servicio.Más información (p. 188).
• Elastic Load Balancing – Solicita realizar un rastreo de Application Load Balancers. El Application LoadBalancer agrega el ID de rastro al encabezado de la solicitud antes de enviarlo al grupo de destino. Másinformación (p. 203).
• AWS Elastic Beanstalk – Herramientas. Elastic Beanstalk incluye el X-Ray demonio de en las siguientesplataformas:• Configuraciones de Java SE – 2.3.0 y posteriores• Tomcat – 2.4.0 y configuraciones posteriores• Node.js – 3.2.0 y configuraciones posteriores• Windows – Server: todas las configuraciones distintas de Windows Server Core que se han lanzado
desde el 9th de diciembre de 2016.
Puede usar la consola de Elastic Beanstalk para indicar a Elastic Beanstalk que ejecute eldemonio en estas plataformas o utilizar la opción XRayEnabled en el espacio de nombresaws:elasticbeanstalk:xray. Más información (p. 202).
• Amazon EventBridge – Instrumentación pasiva. Si un servicio que publica eventos en EventBridge estáinstrumentado con el X-Ray SDK, los destinos de eventos recibirán el encabezado de rastreo y podránseguir propagando el ID de rastreo original. Más información (p. 203).
• Amazon Simple Notification Service – Instrumentación pasiva. Si un editor de Amazon SNS haceun rastreo de su cliente con el SDK de X-Ray, el suscriptor puede recuperar el encabezado derastreo y seguir propagando el rastreo original a partir del editor con el mismo ID de rastro. Másinformación (p. 209).
6
AWS X-Ray Guía para desarrolladoresCambios en el código y la configuración
• Amazon Simple Queue Service – Instrumentación pasiva. Si un servicio rastrea solicitudes utilizando elSDK de X-Ray, Amazon SQS podrá enviar el encabezado de rastreo y continuar propagando el rastrooriginal entre el remitente y el consumidor con un ID de rastro coherente. Más información (p. 214).
Cambios en el código y la configuraciónSe puede generar una gran cantidad de datos de rastreo sin realizar ningún tipo de cambio funcional enel código. El rastreo detallado de las llamadas front-end y las llamadas posteriores requieren cambiosmínimos únicamente en la compilación y en la configuración del tiempo de implementación.
Ejemplos de cambios en el código y la configuración
• AWS Configuración de recursos – de : cambie la configuración de AWS los recursos para instrumentarlas solicitudes a una Lambda función de . Cambia la configuración de la opción mediante la ejecución deldemonio de X-Ray en las instancias en su entorno de Elastic Beanstalk.
• Configuración de la – compilación: tome X-Ray SDK for Java submódulos como una dependencia detiempo de compilación para instrumentar todas las solicitudes posteriores a AWS los servicios de y a losrecursos de como Amazon DynamoDB tablas de , Amazon SQS colas de y Amazon S3 buckets de .
• Configuración de la – aplicación: para instrumentar las solicitudes HTTP entrantes, añada un filtro deservlet a la aplicación Java o utilice X-Ray SDK for Node.js como middleware en la aplicación Express.Cambie las reglas de muestreo y habilite los complementos para instrumentar los recursos de AmazonEC2, Amazon ECS y AWS Elastic Beanstalk que ejecuta la aplicación.
• Configuración de clase u objeto – Para instrumentar llamadas HTTP salientes en Java, importe la X-RaySDK for Java versión de HttpClientBuilder en lugar de la versión de Apache.org.
• Cambios – funcionales: añada un controlador de solicitudes a un cliente AWS del SDK para instrumentarlas llamadas que realiza a los AWS servicios de . Cree subsegmentos para agrupar las llamadasposteriores y añadir información de depuración a los segmentos que tengan anotaciones y metadatos.
7
AWS X-Ray Guía para desarrolladores
Introducción a AWS X-RayPara comenzar a utilizar AWS X-Ray, inicie una aplicación de ejemplo en Elastic Beanstalk que ya hayasido instrumentada (p. 231) para generar datos de rastreo. En unos minutos, puede iniciar la aplicaciónde ejemplo, generar tráfico, enviar segmentos a X-Ray y ver un gráfico de servicios y los rastros en laConsola de administración de AWS.
En este tutorial, se utiliza una aplicación Java de ejemplo (p. 137) para generar segmentos y enviarlosa X-Ray. La aplicación utiliza el marco de Spring para implementar una API web de formato JSON yAWS SDK for Java para mantener los datos en Amazon DynamoDB. Un filtro de servlet en la aplicacióninstrumenta todas las solicitudes entrantes que atiende la aplicación, y un controlador de solicitudes en elcliente AWS del SDK instrumenta las llamadas posteriores a DynamoDB.
Utiliza la consola de X-Ray para ver las conexiones entre cliente, el servidor y DynamoDB en un mapa deservicio. El mapa de servicio es una representación visual de los servicios que componen su aplicaciónweb y el cual se genera a partir de los datos de rastreo que genera al atender solicitudes.
8
AWS X-Ray Guía para desarrolladoresPrerequisites
Con el X-Ray SDK for Java, puede rastrear todos los AWS recursos principales y posteriores de laaplicación realizando dos cambios de configuración:
• Agregue el filtro de rastreo del X-Ray SDK for Java a la configuración del servlet en una claseWebConfig o en un archivo web.xml.
• Utilice los submódulos del X-Ray SDK for Java como dependencias de compilación en la configuraciónde compilación de Maven o Gradle.
También puede tener acceso al mapa de servicios sin procesar y a los datos de seguimiento utilizando laAWS CLI para llamar a la API de X-Ray. El mapa de servicio y los datos de rastreo son archivos JSON quepuede consultar para asegurarse de que la aplicación envíe datos o para corroborar campos específicoscomo parte de la automatización de pruebas.
Secciones• Prerequisites (p. 9)• Implementar en Elastic Beanstalk y generar datos de seguimiento (p. 10)• Consultar el mapa de servicios en la consola de X-Ray (p. 11)• Configuración de notificaciones de Amazon SNS (p. 13)• Explorar la aplicación de ejemplo (p. 15)• Opcional: política de privilegios mínimos (p. 18)• Eliminar recursos (p. 20)• Pasos siguientes (p. 20)
PrerequisitesEn este tutorial, se utiliza Elastic Beanstalk para crear y configurar los recursos que ejecutan la aplicaciónde ejemplo y el demonio de X-Ray. Si utiliza un usuario de IAM con permisos limitados, añada la políticade usuario administrada de Elastic Beanstalk para que dicho usuario pueda utilizar Elastic Beanstalk y la
9
AWS X-Ray Guía para desarrolladoresImplementar en Elastic Beanstalky generar datos de seguimiento
política administrada AWSXrayReadOnlyAccess para conceder permisos para leer el mapa de servicios ylos rastros en la consola de X-Ray.
Crear un entorno de Elastic Beanstalk para la aplicación de ejemplo. Si no ha utilizado Elastic Beanstalkpreviamente, al crear el entorno, también se creará un rol de servicio y un perfil de instancia para suaplicación. Debe existir una VPC predeterminada en la región en la que va a realizar la implementación oElastic Beanstalk producirá un error al implementar la aplicación de ejemplo.
Para crear un entorno de Elastic Beanstalk, realice los siguientes pasos:
1. Abra la consola de administración de Elastic Beanstalk con el enlacepreconfigurado https://console.aws.amazon.com/elasticbeanstalk/#/newApplication?applicationName=scorekeep&solutionStackName=Java
2. Seleccione Create application (Crear aplicación) para crear una aplicación con un entorno que ejecutela plataforma Java 8 SE.
3. Cuando el entorno esté listo, la consola lo redirigirá al entorno de tablero.4. Haga clic en el URL en la parte superior de la página para abrir el sitio.
Las instancias en su entorno necesitan permiso para enviar datos al servicio de AWS X-Ray. Además, laaplicación de ejemplo utiliza Amazon S3 y DynamoDB. Modifique el perfil de instancia predeterminado deElastic Beanstalk con el fin de incluir los permisos necesarios para utilizar estos servicios.
Para añadir permisos de X-Ray, Amazon S3 y DynamoDB a su entorno de Elastic Beanstalk
1. Abra el perfil de instancia de Elastic Beanstalk en la consola de IAM: aws-elasticbeanstalk-ec2-role.2. Seleccione Attach Policies (Asociar políticas).3. Asocie AWSXrayFullAccess , AmazonS3FullAccess y AmazonDynamoDBFullAccess al rol.
Note
Las políticas de acceso completo no son una práctica recomendada de uso general. Paraobtener instrucciones sobre cómo configurar una política de privilegios mínimos para reducirlos riesgos de seguridad, consulte Opcional: política de privilegios mínimos (p. 18).
Implementar en Elastic Beanstalk y generar datosde seguimiento
Implemente la aplicación de ejemplo en su entorno de Elastic Beanstalk. La aplicación de ejemplo utilizalos archivos de configuración de Elastic Beanstalk para configurar el uso de X-Ray en el entorno y crear laDynamoDB que usa de forma automática.
Para implementar el código fuente, realice los siguientes pasos:
1. Descargue la aplicación de ejemplo: eb-java-scorekeep-xray-gettingstarted-v1.3.zip2. Open the Elastic Beanstalk console.3. Navigate to the management console for your environment.4. Elija Upload and Deploy (Cargar e implementar).5. Cargue eb-java-scorekeep-xray-gettingstarted-v1.3.zip y elija después Deploy (Implementar).
La aplicación de ejemplo incluye una aplicación web front-end. Utilice la aplicación web para generar tráficoa la API y enviar los datos de rastreo a X-Ray.
10
AWS X-Ray Guía para desarrolladoresConsultar el mapa de servicios en la consola de X-Ray
Para generar datos de rastreo, realice los siguientes pasos:
1. En el entorno de tablero, haga clic en el URL para abrir la aplicación web.2. Elija Create (Crear) para crear un usuario y una sesión.3. Escriba un nombre de juego, establezca Rules en Tic Tac Toe y, a continuación, elija Create para
crear un juego.4. Seleccione Play (Jugar) para comenzar el juego.5. Elija una ficha para hacer un movimiento y cambiar el estado del juego.
Cada uno de estos pasos genera solicitudes HTTP a la API y llamadas posteriores a DynamoDB para leery escribir el usuario, la sesión, el juego, la movida y los datos de estado.
Consultar el mapa de servicios en la consola de X-Ray
Puede ver el mapa de servicios y los rastros que ha generado la aplicación de ejemplo en la consola de X-Ray.
Para utilizar la consola de X-Ray
1. Abra la página del mapa de serviciosX-Ray de la consola de .2. La consola muestra una representación del gráfico de servicios que X-Ray genera a partir de los datos
de rastreo que envía la aplicación.
El mapa de servicio muestra el cliente de la aplicación web, la API que se ejecuta en Elastic Beanstalk, elservicio de DynamoDB y cada tabla de DynamoDB que la aplicación utiliza. Cada solicitud que se envíaa la aplicación, hasta una cantidad máxima configurable de solicitudes por segundo, se rastrea hasta quellega a la API, genera solicitudes para los servicios posteriores y se completa.
11
AWS X-Ray Guía para desarrolladoresConsultar el mapa de servicios en la consola de X-Ray
Puede elegir cualquier nodo en el gráfico de servicios para ver los rastros de las solicitudes que generarontráfico hacia ese nodo. El nodo Amazon SNS está en rojo. Profundice para saber por qué.
Para encontrar la causa del error
1. Seleccione el nodo denominado SNS. El Service details panel (Panel Detalles de servicio) se abre a laderecha.
2. Elija View traces (Ver rastreos) para acceder a la pantalla Trace overview (Información general derastreo).
3. Seleccione el rastro en Trace list (Lista de rastros). Este rastro no tiene método ni URL porque seregistró durante el inicio y no en respuesta a una solicitud de entrada.
4. Seleccione el icono de estado rojo para abrir la página Exceptions (Excepciones) del subsegmento deSNS.
5. El SDK de X-Ray captura automáticamente las excepciones producidas por clientes del SDK de AWSinstrumentados y registra el seguimiento de la pila.
12
AWS X-Ray Guía para desarrolladoresConfiguración de notificaciones de Amazon SNS
La causa indica que la dirección de correo electrónico proporcionada en una llamada acreateSubscription realizada en la clase WebConfig no era válida. Solucionemos el problema.
Configuración de notificaciones de Amazon SNSScorekeep utiliza Amazon SNS para enviar notificaciones cuando los usuarios completan un juego.Cuando la aplicación se inicia, intenta crear una suscripción para una dirección de correo electrónicodefinida en una variable de entorno. Esa llamada está fallando y por eso el nodo de Amazon SNS delmapa de servicios está en rojo. Configure un correo electrónico de notificación en una variable de entornopara habilitar las notificaciones y cambiar el estado del mapa de servicios a verde.
Para configurar notificaciones de Amazon SNS para scorekeep
1. Open the Elastic Beanstalk console.2. Navigate to the management console for your environment.3. Choose Configuration.4. Elija Software Configuration (Configuración de software).5. En Environment Properties (Propiedades de entorno), sustituya el valor predeterminado por su
dirección de correo electrónico.
13
AWS X-Ray Guía para desarrolladoresConfiguración de notificaciones de Amazon SNS
Note
El valor predeterminado utiliza una AWS CloudFormationfunción de para recuperar unparámetro guardado en un archivo de configuración (un valor ficticio, en este caso).
6. Seleccione Apply.
Cuando se completa la actualización, Scorekeep se reinicia y crea una suscripción al tema de SNS.Compruebe su correo electrónico y confirme la suscripción para ver las actualizaciones cuando completeun juego.
14
AWS X-Ray Guía para desarrolladoresExplorar la aplicación de ejemplo
Explorar la aplicación de ejemploLa aplicación de ejemplo es una API web HTTP en Java que está configurada para utilizar el X-Ray SDKfor Java. Al implementar la aplicación Elastic Beanstalk, crea las tablas de DynamoDB, compila la API conGradle y configura el servidor proxy nginx para atender a la aplicación web de forma estática en la ruta deacceso raíz. Al mismo tiempo, Elastic Beanstalk enruta las solicitudes a las rutas que comienzan con /apia la API.
Para instrumentar las solicitudes de HTTP entrantes, la aplicación añade el TracingFilter queproporciona el SDK.
Example src/main/java/scorekeep/WebConfig.java: filtro de servlet
import javax.servlet.Filter;import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;...
@Configurationpublic class WebConfig {
@Bean public Filter TracingFilter() { return new AWSXRayServletFilter("Scorekeep"); }...
Este filtro envía datos de rastreo sobre todas las solicitudes entrantes que la aplicación atiende, incluidos elURL, el método, el estado de la respuesta, la hora de inicio y la hora de finalización de la solicitud.
15
AWS X-Ray Guía para desarrolladoresExplorar la aplicación de ejemplo
La aplicación también realiza llamadas posteriores a DynamoDB mediante AWS SDK for Java. Parainstrumentar estas llamadas, la aplicación simplemente usa los submódulos relacionados con el SDK deAWS como dependencias y el X-Ray SDK for Java instrumenta de forma automática todos los clientes delSDK de AWS.
La aplicación utiliza un Buildfile archivo para compilar el código fuente de la instancia con Gradle yun Procfile archivo para ejecutar el archivo ejecutable JAR que Gradle genera. La admisión de archivosBuildfile y Procfile es una característica de la plataforma Elastic Beanstalk Java SE.
Example Buildfile
build: gradle build
Example Procfile
web: java -Dserver.port=5000 -jar build/libs/scorekeep-api-1.0.0.jar
El archivo build.gradle descarga todos los submódulos del SDK de Maven durante la compilacióndeclarándolos como dependencias.
Example build.gradle: dependencias
...dependencies { compile("org.springframework.boot:spring-boot-starter-web") testCompile('org.springframework.boot:spring-boot-starter-test') compile('com.amazonaws:aws-java-sdk-dynamodb') compile("com.amazonaws:aws-xray-recorder-sdk-core") compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk") compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk-instrumentor") ...}dependencyManagement { imports { mavenBom("com.amazonaws:aws-java-sdk-bom:1.11.67") mavenBom("com.amazonaws:aws-xray-recorder-sdk-bom:2.4.0") }}
16
AWS X-Ray Guía para desarrolladoresExplorar la aplicación de ejemplo
El núcleo, el SDK de AWS y los submódulos Instrumentor del SDK de AWS son los únicos requisitos parainstrumentar de forma automática cualquier llamada posterior realizada con el SDK de AWS.
Para ejecutar el demonio de X-Ray, la aplicación utiliza otra característica de Elastic Beanstalk: losarchivos de configuración. El archivo de configuración indica a Elastic Beanstalk que ejecute el demonio yenvíe el log a petición.
Example .ebextensions/xray.config
option_settings: aws:elasticbeanstalk:xray: XRayEnabled: true
files: "/opt/elasticbeanstalk/tasks/taillogs.d/xray-daemon.conf" : mode: "000644" owner: root group: root content: | /var/log/xray/xray.log
El X-Ray SDK for Java proporciona una clase denominada AWSXRay que proporciona una grabadoraglobal, un TracingHandler que se puede utilizar para instrumentar el código. Puede configurar lagrabadora global para que personalice el AWSXRayServletFilter que crea los segmentos para lasllamadas HTTP entrantes. La muestra incluye un bloque estático en la clase WebConfig que configura lagrabadora global con complementos y reglas de muestreo.
Example src/main/java/scorekeep/WebConfig.java: grabadora
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.AWSXRayRecorderBuilder;import com.amazonaws.xray.plugins.EC2Plugin;import com.amazonaws.xray.plugins.ElasticBeanstalkPlugin;import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;
@Configurationpublic class WebConfig {... static { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()).withPlugin(new ElasticBeanstalkPlugin());
URL ruleFile = WebConfig.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build()); }}
En este ejemplo se utiliza el compilador para cargar las reglas de muestreo desde un archivo denominadosampling-rules.json. Las reglas de muestreo determinan la velocidad a la que el SDK registra lossegmentos de las solicitudes entrantes.
Example src/main/java/resources/sampling-rules.json
{ "version": 1, "rules": [ { "description": "Resource creation.", "service_name": "*",
17
AWS X-Ray Guía para desarrolladoresOpcional: política de privilegios mínimos
"http_method": "POST", "url_path": "/api/*", "fixed_target": 1, "rate": 1.0 }, { "description": "Session polling.", "service_name": "*", "http_method": "GET", "url_path": "/api/session/*", "fixed_target": 0, "rate": 0.05 }, { "description": "Game polling.", "service_name": "*", "http_method": "GET", "url_path": "/api/game/*/*", "fixed_target": 0, "rate": 0.05 }, { "description": "State polling.", "service_name": "*", "http_method": "GET", "url_path": "/api/state/*/*/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 }}
El archivo de reglas de muestreo define cuatro reglas de muestreo personalizadas y la reglapredeterminada. Para cada solicitud de entrada, el SDK evalúa las reglas personalizadas en el orden enque están definidas. El SDK aplica la primera regla que coincide con el método, la ruta y el nombre deservicio de la solicitud. Para Scorekeep, la primera regla captura todas las solicitudes POST (llamadas decreación de recursos) aplicando un objetivo fijo de una solicitud por segundo y una tasa del 1,0, es decir, el100 % de las solicitudes después de cumplir el objetivo fijo.
Las otras tres reglas personalizadas aplican una tasa del 5 % sin objetivo fijo a las lecturas de sesiones,juegos y estado (solicitudes GET). De este modo se reduce al mínimo el número de rastros de lasllamadas periódicas que el front-end realiza automáticamente cada pocos segundos para asegurarsede que el contenido está actualizado. Para el resto de solicitudes, el archivo define una velocidadpredeterminada de una solicitud por segundo y una tasa del 10 %.
La aplicación de ejemplo también muestra cómo usar funciones avanzadas, como la instrumentaciónmanual de clientes SDK, la creación de subsegmentos adicionales y llamadas HTTP salientes. Paraobtener más información, consulte AWS X-RayAplicación de muestra de (p. 137).
Opcional: política de privilegios mínimosAcaba de implementar este tutorial utilizando las políticas de seguridad AmazonS3FullAccess yAmazonDynamoDBFullAccess. El uso de una política de acceso completo no es la práctica recomendadaa largo plazo. Para mejorar la seguridad de lo que implementó, siga estos pasos para actualizar lospermisos. Para obtener más información sobre las prácticas recomendadas de seguridad en IAM laspolíticas de , consulte Identity and Access Management for AWS X-Ray.
18
AWS X-Ray Guía para desarrolladoresOpcional: política de privilegios mínimos
Para actualizar las políticas, primero identifique los ARN de sus recursos de Amazon S3 y DynamoDB. Acontinuación, utilice los ARN en dos políticas de IAM personalizadas. Por último, aplique esas políticas alperfil de instancia.
Para identificar el recurso de Amazon S3
1. Abra la página de recursos de la consola de AWS Config.2. En Resource type (Tipo de recurso), filtre por AWS S3 Bucket (Bucket de AWS S3) para buscar el
ARN del bucket de Amazon S3 que utiliza la aplicación.3. En Resource identifier (Identificador de recursos), elija el identificador que está asociado a
elasticbeanstalk.4. Registre su Amazon resource name (Nombre de recurso de Amazon) completo.5. Inserte el ARN en la siguiente política de IAM.
Example
{ "Version": "2012-10-17", "Statement": [ { "Sid": "ScorekeepS3", "Action": [ "s3:GetObject", "s3:PutObject" ], "Effect": "Allow", "Resource": "arn:aws:s3:::elasticbeanstalk-region-0987654321" } ]}
Para identificar el recurso de DynamoDB
1. Abra la página de recursos de la consola de AWS Config.2. En Resource type (Tipo de recurso), filtre por AWS DynamoDB Table (Tabla de DynamoDB) para
encontrar el ARN de las DynamoDB tablas que utiliza su aplicación.3. En Resource identifier (Identificador de recurso), elija el identificador asociado a una de las tablas
scorekeep.4. Registre su Amazon resource name (Nombre de recurso de Amazon) completo.5. Inserte el ARN en la siguiente política de IAM.
Example
{ "Version": "2012-10-17", "Statement": [ { "Sid": "ScorekeepDynamoDB", "Effect": "Allow", "Action": [ "dynamodb:PutItem", "dynamodb:UpdateItem", "dynamodb:DeleteItem", "dynamodb:GetItem" ], "Resource": "arn:aws:dynamodb:region:1234567890:table/scorekeep-*" }
19
AWS X-Ray Guía para desarrolladoresEliminar recursos
]}
Las tablas que crea la aplicación siguen una convención de nomenclatura coherente. Puede utilizar elformato de scorekeep-* para indicar todas las tablas que siguen esa convención.
Para cambiar la política de IAM
1. Abra el perfil de instancia de Elastic Beanstalk en la consola de IAM: aws-elasticbeanstalk-ec2-role.2. Elimine las políticas AmazonS3FullAccess y AmazonDynamoDBFullAccess del rol.3. Elija Attach policies (Asociar políticas) y, a continuación, Create policy (Crear política).4. Elija el JSON y péguelo en una de las políticas creadas anteriormente.5. Elija Review policy (Revisar política).6. En Name (Nombre), asigne un nombre.7. Elija Create Policy (Crear política).8. Asigne la política recién creada a aws-elasticbeanstalk-ec2-role.9. Repita este procedimiento para la segunda política creada anteriormente.
Eliminar recursosFinalice el entorno de Elastic Beanstalk para desactivar las instancias de Amazon EC2, las tablas deDynamoDB y otros recursos.
Para finalizar su entorno de Elastic Beanstalk, haga lo siguiente:
1. Open the Elastic Beanstalk console.2. Navigate to the management console for your environment.3. Elija Actions (Acciones).4. Elija Terminate Environment (Terminar entorno).5. Elija Terminate (Terminar).
Los datos de rastreo se eliminan automáticamente de X-Ray después de 30 days.
Pasos siguientesObtenga más información sobre X-Ray en el próximo capítulo, AWS X-RayConceptos de (p. 21).
Para instrumentar su propia aplicación, obtenga más información sobre el X-Ray SDK for Java o sobrealgunos SDK de X-Ray:
• X-Ray SDK for Java – AWS X-Ray SDK para Java (p. 231)• X-Ray SDK for Node.js – AWS X-Ray SDK for Node.js (p. 270)• X-Ray SDK for .NET – AWS X-Ray SDK para .NET (p. 327)
Para ejecutar el X-Ray demonio de localmente o en AWS, consulte AWS X-RayDemonio de (p. 171).
Para colaborar con la aplicación de ejemplo en GitHub, consulte eb-java-scorekeep.
20
AWS X-Ray Guía para desarrolladoresSegments
AWS X-RayConceptos deAWS X-Ray recibe datos de servicios en forma de segmentos. A continuación, X-Ray agrupa lossegmentos que tienen una solicitud común en rastros. X-Ray procesa los rastros para generar un gráficode servicio que proporciona una representación visual de la aplicación.
Conceptos• Segments (p. 21)• Subsegments (p. 22)• Gráfico de servicios (p. 24)• Traces (p. 25)• Sampling (p. 26)• Encabezado de seguimiento (p. 26)• Expresiones de filtro (p. 27)• Groups (p. 27)• Anotaciones y metadatos (p. 27)• Errores y excepciones (p. 28)
SegmentsLos recursos informáticos en los que se ejecuta la lógica de su aplicación envían datos del trabajo enforma de segmentos. Un segmento incluye el nombre del recurso, detalles de la solicitud y detalles deltrabajo realizado. Por ejemplo, cuando una solicitud HTTP llega a la aplicación, puede registrar datossobre:
• El host – nombre de host, alias o dirección IP• La solicitud – método, dirección del cliente, ruta, agente de usuario• La respuesta – estado, contenido• El trabajo realizado – hora de inicio y finalización, subsegmentos• Problemas que se producen – errores y excepciones (p. 28), incluida la captura automática de pilas
de excepciones.
21
AWS X-Ray Guía para desarrolladoresSubsegments
El X-Ray SDK recopila información de los encabezados de solicitud y respuesta, el código de la aplicacióny los metadatos sobre los AWS recursos en los que se ejecuta. Puede elegir los datos que se recopilaránmodificando la configuración o el código de la aplicación para instrumentar las solicitudes entrantes, lassolicitudes posteriores y los clientes AWS del SDK.
Solicitudes reenviadas
Si un balanceador de carga u otro intermediario reenvía una solicitud a la aplicación, X-Ray tomala dirección IP del cliente del encabezado X-Forwarded-For de la solicitud, en lugar de hacerlode la dirección IP de origen del paquete IP. La dirección IP del cliente que se registra para unasolicitud reenviada puede falsificarse, por lo que no se debe confiar en ella.
Puede utilizar el SDK de X-Ray para registrar información adicional como, por ejemplo, anotaciones ymetadatos (p. 27). Para obtener más información sobre la estructura y la información que se registraen los segmentos y subsegmentos, consulte AWS X-RayDocumentos de segmentos de (p. 123). Losdocumentos de segmento pueden tener un tamaño de hasta 64 kB.
SubsegmentsUn segmento puede desglosar los datos del trabajo realizado en subsegmentos. Los subsegmentsproporcionan información y detalles más precisos sobre los intervalos de las llamadas posteriores que laaplicación realizó para cumplir la solicitud original. Un subsegmento puede contener detalles adicionalessobre una llamada a un AWS servicio de , una API HTTP externa o una base de datos SQL. Puedeincluso definir subsegmentos arbitrarios para instrumentar funciones específicas o líneas de código en suaplicación.
22
AWS X-Ray Guía para desarrolladoresSubsegments
En el caso de los servicios que no envían sus propios segmentos, como Amazon DynamoDB, X-Ray utilizasubsegmentos para generar segmentos inferidos y nodos posteriores en el mapa de servicio. Esto lepermite ver todas sus dependencias posteriores, incluso si no soportan el rastreo o son externas.
Los subsegmentos representan la vista de su aplicación de una llamada posterior como cliente. Si elservicio posterior también está instrumentado, el segmento que envía sustituye al segmento inferidogenerado desde el subsegmento del cliente principal. El nodo en el gráfico de servicio utiliza siempreinformación desde el segmento del servicio, si está disponible, mientras que el límite entre los dos nodosutiliza el subsegmento del servicio ascendente.
Por ejemplo, si llama a DynamoDB con un cliente AWS del SDK instrumentado, el X-Ray SDK registra unsubsegmento para esa llamada. DynamoDB no envía un segmento, por lo que el segmento inferido enel rastro, el DynamoDB nodo en el gráfico de servicio y el límite entre el servicio y DynamoDB contieneninformación del subsegmento.
Si llama a otro servicio instrumentado con una aplicación instrumentada, el servicio posterior envía supropio segmento para registrar su vista de la misma llamada que el servicio ascendente registró en unsubsegmento. En el gráfico de servicio, los nodos de ambos servicios contienen información de tiempoy error de los segmentos de dichos servicios, mientras que el límite entre ellos contiene información delsubsegmento del servicio ascendente.
23
AWS X-Ray Guía para desarrolladoresGráfico de servicios
Ambos puntos de vista son útiles, ya que el servicio posterior registra precisamente cuándo comenzó yfinalizó el trabajo en la solicitud y el servicio ascendente registra la latencia de ida y vuelta, incluido eltiempo que la solicitud ha pasado viajando entre los dos servicios.
Gráfico de serviciosX-Ray utiliza los datos que su aplicación envía para generar un gráfico de servicio. Cada AWS recursoque envía datos a X-Ray aparece como un servicio en el gráfico. Los límites conectan los serviciosque trabajan en equipo para atender solicitudes. Los límites conectan a los clientes con la aplicación, yconectan la aplicación con los servicios y recursos posteriores que esta utiliza.
Nombre de servicios
El elemento name de un segmento debe coincidir con el nombre de dominio o el nombre lógicodel servicio que genera el segmento. Sin embargo, no es algo impuesto. Cualquier aplicación quetenga permiso para PutTraceSegments puede enviar segmentos con cualquier nombre.
Un gráfico de servicios es un documento JSON que contiene información acerca de los servicios yrecursos que componen la aplicación. La consola de X-Ray utiliza el gráfico de servicios para generar unavisualización o un mapa de servicios.
En las aplicaciones distribuidas, X-Ray combina nodos de todos los servicios que procesan solicitudes conel mismo ID de rastro en un único gráfico de servicios. El primer servicio al que llega la solicitud añade unencabezado de rastro (p. 26) que se propaga entre el front-end y servicios que a los llama.
Por ejemplo, Scorekeep (p. 137) ejecuta una API web que llama a un microservicio (una función deAWS Lambda) para generar un nombre aleatorio usando una biblioteca Node.js. El X-Ray SDK for Javagenera el ID de rastro y lo incluye en las llamadas a Lambda. Lambda envía datos de rastreo y transfiere
24
AWS X-Ray Guía para desarrolladoresTraces
el ID de rastro a la función. El X-Ray SDK for Node.js también utiliza el ID de rastro para enviar datos. Enconsecuencia, el mapa de servicios muestra los nodos de la API, el servicio Lambda y la función Lambdacomo nodos independientes pero conectados.
Los datos de gráfico de servicio se conservan para 30 días.
TracesEl ID de rastro muestra la ruta que recorre una solicitud en la aplicación. Un rastro recopila todos lossegmentos que genera una solicitud. Esta solicitud suele ser una solicitud HTTP GET o POST que viajaa través de un balanceador de carga, llega al código de la aplicación y genera llamadas posteriores aotros AWS servicios o APIs web externas. El primer servicio compatible con el que interactúa la solicitudHTTP le añade un encabezado de ID de rastro, que continúa propagándose para registrar la latencia, ladisposición y otros datos que requiere la solicitud.
25
AWS X-Ray Guía para desarrolladoresSampling
Los datos de gráfico de servicio se conservan para 30 days.
SamplingPara garantizar un rastreo eficaz y proporcionar una muestra representativa de las solicitudes que suaplicación atiende, el SDK de X-Ray aplica un algoritmo de muestreo para determinar qué solicitudes serastrearán. De forma predeterminada, el SDK de X-Ray registra la primera solicitud de cada segundo y uncinco por ciento de todas las solicitudes adicionales.
Para evitar incurrir en cargos por servicio al empezar, la tasa de muestreo predeterminada esconservadora. Puede configurar X-Ray para modificar la regla de muestreo predeterminada y configurarreglas adicionales que aplican el muestreo en función de las propiedades del servicio o solicitud.
Por ejemplo, es posible que desee deshabilitar las solicitudes de muestreo y rastreo completo para lasllamadas que modifican el estado o tratar con cuentas de usuario o transacciones. Para llamadas de sololectura de alto volumen, como sondeo en segundo plano, comprobaciones de estado o mantenimientode conexión, puede muestrear con un bajo índice y seguirá obteniendo datos suficientes para ver losproblemas que surjan.
Para obtener más información, consulte Configuración de reglas de muestreo en la consola de X-Ray (p. 76).
Encabezado de seguimientoTodas las solicitudes se rastrean hasta alcanzar un mínimo configurable, después de lo cual se rastreaun porcentaje de solicitudes para evitar un costo innecesario. La decisión de muestreo y el ID de rastro seañaden a las solicitudes HTTP en los encabezados de rastreo denominados X-Amzn-Trace-Id. El primerservicio integrado con X-Ray, al que llega la solicitud añade un identificador de rastreo, que es leído por elSDK de X-Ray, e incluido en la respuesta.
Example Encabezado de rastreo con ID de rastro raíz y decisión de muestreo
X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793;Sampled=1
Seguridad del encabezado de rastreo
Un encabezado de rastro se puede originar a partir del SDK de X-Ray, un servicio de AWS, opor solicitud del cliente. Su aplicación puede eliminar el encabezado X-Amzn-Trace-Id en lassolicitudes entrantes para evitar los problemas causados por usuarios que agregan ID de rastro odecisiones de muestreo a sus solicitudes.
El encabezado de rastreo también pueden contener un ID de segmento primario si la solicitud se originó apartir de una aplicación instrumentada. Por ejemplo, si su aplicación llama a una API web HTTP posteriorcon un cliente HTTP instrumentado, el SDK de X-Ray añade el ID del segmento de la solicitud originalal encabezado de rastreo de la solicitud posterior. Una aplicación instrumentada que atiende la solicitudposterior puede registrar el ID del segmento primario para conectar ambas solicitudes.
Example Encabezado de rastreo con ID de rastro raíz, ID de segmento primario y decisión demuestreo
X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793;Parent=53995c3f42cd8ad8;Sampled=1
26
AWS X-Ray Guía para desarrolladoresExpresiones de filtro
Expresiones de filtroAunque se haya realizado un muestreo, una aplicación genera grandes cantidades de datos. La consolade AWS X-Ray ofrece una vista fácil de navegar del gráfico de servicio. Allí se muestra información sobreel estado y el rendimiento con la cual se puede identificar problemas y posibilidades de optimización en suaplicación. Cuando se realiza un rastreo avanzado, puede explorar en profundidad en busca de solicitudesindividuales, o bien utilizar expresiones de filtro para encontrar rastros relacionados con rutas específicas ousuarios específicos.
GroupsComo complemento de las expresiones de filtro, X-Ray también admite la característica de grupos.Mediante una expresión de filtro, puede definir los criterios para aceptar los rastros en el grupo.
Puede llamar al grupo por nombre o por nombre de recurso de Amazon (ARN) para generar su propiográfico de servicios, resúmenes de rastros y métricas de Amazon CloudWatch. Una vez que se crea ungrupo, los rastros de entrada se comparan con la expresión de filtro del grupo a medida que se almacenanen el servicio X-Ray. Las métricas para el número de rastros que coinciden con cada criterio se publican enCloudWatch cada minuto.
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 quecombina la expresión nueva con la anterior. Para evitarlo, elimine el grupo actual y cree uno nuevo.
Note
Los grupos se facturan por el número de rastros recuperados que coinciden con la expresión defiltro. Para obtener más información, consulte Precios de AWS X-Ray.
Para obtener más información acerca de los grupos, consulte Configuración de grupos de en la consola X-Ray de (p. 92).
Anotaciones y metadatosCuando instrumenta su aplicación, el SDK de X-Ray registra información acerca de las solicitudesentrantes y de salida, los recursos de AWS utilizados y la aplicación en sí. Puede añadir más informaciónal documento de segmento, por ejemplo anotaciones y metadatos. Las anotaciones y los metadatos seagregan en el nivel de seguimiento y se pueden añadir a cualquier segmento o subsegmento.
Las anotaciones son pares de clave-valor que se indexan para usarlos en expresiones de filtro (p. 64).Utilice anotaciones para registrar los datos que desee utilizar para agrupar rastros en la consola o cuandollame a la API de GetTraceSummaries.
27
AWS X-Ray Guía para desarrolladoresErrores y excepciones
X-Ray indexa hasta 50 anotaciones por rastro.
Los metadatos son pares de clave-valor con valores de cualquier tipo, por ejemplo objetos y listas, peroque no se indexan. Utilice los metadatos para registrar los datos que desee almacenar en el rastro, peroque no vaya a usar para buscar rastros.
Puede ver anotaciones y metadatos en los detalles de segmento o subsegmento, en la consola de X-Ray.
Errores y excepcionesX-Ray rastrea los errores que se producen en su código de aplicación y los errores que devuelven losservicios posteriores. Los errores se clasifican como se indica a continuación.
• Error – errores del cliente (errores de la serie 400)• Fault – errores del servidor (errores de la serie 500)• Throttle – errores de limitación controlada (429 Demasiadas solicitudes)
Cuando se produce una excepción, mientras la aplicación está sirviendo una solicitud instrumentada, elSDK de X-Ray registra detalles sobre la excepción, incluido el rastreo de pila, si está disponible. Puede verexcepciones en detalles de segmento (p. 60) en la consola de X-Ray.
28
AWS X-Ray Guía para desarrolladoresProtección de los datos
Seguridad en AWS X-RayLa seguridad en la nube de AWS es la mayor prioridad. Como cliente de AWS, se beneficiará de unaarquitectura de red y un centro de datos diseñados para satisfacer los requisitos de seguridad de lasorganizaciones más exigentes.
La seguridad es una responsabilidad compartida entre AWS y usted. El modelo de responsabilidadcompartida la describe como seguridad de la nube y seguridad en la nube:
• Seguridad de la nube – AWS es responsable de proteger la infraestructura que ejecuta servicios deAWS en la nube de AWS. AWS también proporciona servicios que puede utilizar de forma segura.Auditores externos prueban y verifican periódicamente la eficacia de nuestra seguridad en el marcode los programas de conformidad de AWS. Para obtener más información acerca de los programasde conformidad que se aplican a X-Ray, consulte Servicios de AWS en el ámbito del programa deconformidad.
• Seguridad en la nube – su responsabilidad viene determinada por el servicio de AWS que utilice. Ustedtambién es responsable de otros factores incluida la confidencialidad de los datos, los requisitos de laempresa y la legislación y los reglamentos aplicables.
Esta documentación lo ayudará a comprender cómo aplicar el modelo de responsabilidad compartidacuando se utiliza X-Ray. En los siguientes temas, se le mostrará cómo configurar X-Ray para satisfacer losobjetivos de seguridad y conformidad. También aprenderá a utilizar otros AWS servicios de que puedenayudarle a monitorizar y proteger sus X-Ray recursos de .
Topics
• Protección de datos en AWS X-Ray (p. 29)• Administración de identidad y acceso en AWS X-Ray (p. 30)• Validación de la conformidad en AWS X-Ray (p. 49)• Resiliencia de AWS X-Ray (p. 50)• Seguridad de la infraestructura en AWS X-Ray (p. 50)
Protección de datos en AWS X-RayAWS X-Ray siempre cifra los registros de seguimiento y los datos en reposo relacionados. Cuandonecesite auditar y deshabilitar las claves de cifrado por motivos internos o de conformidad, puedeconfigurar X-Ray para que utilice una clave maestra de cliente (CMK) de AWS Key Management Service(AWS KMS) a la hora de cifrar los datos.
X-Ray dispone de una CMK administrada por AWS llamada aws/xray. Utilice esta clave únicamentecuando desee auditar el uso de claves en AWS CloudTrail y no la propia clave. Cuando necesiteadministrar el acceso a la clave o configurar la rotación de claves, puede crear una CMK administrada porel cliente.
Si cambia la configuración de cifrado, X-Ray tardará algún tiempo en generar y propagar las claves dedatos. Mientras se procesa la nueva clave, X-Ray puede cifrar los datos con una combinación de laconfiguración nueva y antigua. Si se modifica la configuración de cifrado, los datos existentes no volverán acifrarse.
29
AWS X-Ray Guía para desarrolladoresAdministración de identidades y accesos
Note
AWS KMS genera costos cuando X-Ray utiliza una CMK para cifrar o descifrar los datos derastreo.
• Cifrado – predeterminado: gratis.• AWS CMK administrada por – : paga por el uso de claves.• CMK administrada por el – cliente: paga por el uso y el almacenamiento de claves.
Consulte Precios de AWS Key Management Service para obtener más información.
Note
X-Ray Las notificaciones de conocimientos de envían eventos a Amazon EventBridge, queactualmente no admite CMKs administradas por el cliente. Para obtener más información,consulte Protección de datos en Amazon EventBridge.
Debe tener acceso de nivel de usuario a una CMK administrada por el cliente para configurar X-Ray parautilizarlo y, a continuación, consultar los rastros cifrados. Para obtener más información, consulte Permisosde usuario para cifrado (p. 39).
Si desea configurar X-Ray para que utilice una CMK con el cifrado
1. Abra la consola de X-Ray.2. Seleccione Encryption (Cifrado).3. Seleccione Use a customer master key (Usar una clave maestra de cliente).4. Elija una clave en el menú desplegable:
• – aws/xray: utilice la CMK AWS administrada por .• key alias (alias de – clave) utilice una CMK administrada por el cliente en su cuenta.• Manually enter a key ARN (Escribir manualmente un ARN de – clave): utilice una CMK administrada
por el cliente en otra cuenta. En el campo que aparece, escriba el nombre de recurso de Amazon(ARN) completo.
Note
X-Ray no admite CMK asimétricas.5. Seleccione Apply.
Si X-Ray no puede obtener acceso a la clave de cifrado, deja de almacenar los datos. Esto puede ocurrir siel usuario pierde acceso a la CMK o si se deshabilita una clave que actualmente está en uso. Cuando estosucede, X-Ray muestra una notificación en la barra de navegación.
Para configurar las opciones de cifrado con la API de X-Ray, consulte Configuring Configuración demuestreo, grupos y cifrado de con la AWS X-Ray API de (p. 116).
Administración de identidad y acceso en AWS X-Ray
AWS Identity and Access Management (IAM) es un servicio de AWS que ayuda a un administrador acontrolar de forma segura el acceso a los recursos de AWS. Los administradores de IAM controlan quién
30
AWS X-Ray Guía para desarrolladoresPúblico
puede ser autenticado (iniciar sesión) y estar autorizado (tener permisos) para utilizar los recursos de X-Ray. IAM es un servicio de AWS que se puede utilizar sin costo adicional.
Temas• Público (p. 31)• Autenticación con identidades (p. 31)• Administración de acceso mediante políticas (p. 33)• Cómo funciona AWS X-Ray con IAM (p. 35)• AWS X-RayEjemplos de políticas de basadas en identidades (p. 40)• Solución de problemas de identidad y acceso en AWS X-Ray (p. 47)
PúblicoLa forma en la que utilice AWS Identity and Access Management (IAM) varía en función del trabajo querealice en X-Ray.
Usuario de servicio: si utiliza el servicio X-Ray para realizar su trabajo, su administrador le proporciona lascredenciales y los permisos que necesita. A medida que utilice más características de X-Ray para realizarsu trabajo, es posible que necesite permisos adicionales. Entender cómo se administra el acceso puedeayudarle a solicitar los permisos correctos a su administrador. Si no puede acceder a una característica enX-Ray, consulte Solución de problemas de identidad y acceso en AWS X-Ray (p. 47).
Administrador de servicio: si está a cargo de los recursos de X-Ray en su empresa, probablemente tengaacceso completo a X-Ray. Su trabajo consiste en determinar qué a características y recursos de X-Raydeben acceder sus empleados. A continuación, debe enviar solicitudes a su administrador de IAM paracambiar los permisos de los usuarios de su servicio. Revise la información de esta página para conocer losconceptos básicos de IAM. Para obtener más información sobre cómo su empresa puede utilizar IAM conX-Ray, consulte Cómo funciona AWS X-Ray con IAM (p. 35).
Administrator de IAM: si es un administrador de IAM, es posible que quiera conocer información sobrecómo escribir políticas para administrar el acceso a X-Ray. Para ver ejemplos de políticas basadas en laidentidad de X-Ray que puede utilizar en IAM, consulte AWS X-RayEjemplos de políticas de basadas enidentidades (p. 40).
Autenticación con identidadesLa autenticación es la manera de iniciar sesión en AWS mediante credenciales de identidad. Para obtenermás información acerca de cómo iniciar sesión con la Consola de administración de AWS, consulte Iniciarsesión en la Consola de administración de AWS como usuario de IAM usuario o usuario raíz en la Guía delusuario de IAM.
Debe estar autenticado (haber iniciado sesión en AWS) como Usuario de la cuenta raíz de AWS, usuariode IAM o asumiendo un rol de IAM. También puede utilizar la autenticación de inicio de sesión únicode la empresa o incluso iniciar sesión con Google o Facebook. En estos casos, su administrador habráconfigurado previamente la federación de identidad mediante roles de IAM. Cuando obtiene acceso a AWSmediante credenciales de otra empresa, asume un rol indirectamente.
Para iniciar sesión directamente en la Consola de administración de AWS, use la contraseña con sudirección de correo electrónico usuario raíz o el nombre de usuario de IAM. Puede obtener acceso aAWS mediante programación utilizando sus claves de acceso de usuario usuario raíz o de IAM. AWSproporciona SDK y herramientas de línea de comandos para firmar criptográficamente su solicitud consus credenciales. Si no utiliza las herramientas de AWS, debe firmar usted mismo la solicitud. Para ello,utilice Signature Version 4, un protocolo para autenticar solicitudes de API de entrada. Para obtener másinformación sobre las solicitudes de autenticación, consulte Proceso de firma de Signature Version 4 en laAWS General Reference.
31
AWS X-Ray Guía para desarrolladoresAutenticación con identidades
Independientemente del método de autenticación que utilice, es posible que también deba proporcionarinformación de seguridad adicional. Por ejemplo, AWS le recomienda el uso de la autenticación multifactor(MFA) para aumentar la seguridad de su cuenta. Para obtener más información, consulte Uso de Multi-Factor Authentication (MFA) en AWS en la Guía del usuario de IAM.
Usuario raíz de la cuenta de AWSCuando se crea por primera vez una cuenta de AWS, se comienza con una única identidad de inicio desesión que tiene acceso completo a todos los servicios y recursos de AWS de la cuenta. Esta identidadrecibe el nombre de AWS de la cuenta de usuario raíz y se obtiene acceso a ella iniciando sesión con ladirección de correo electrónico y la contraseña que utilizó para crear la cuenta. Le recomendamos queno utilice usuario raíz en sus tareas cotidianas, ni siquiera en las tareas administrativas. En lugar de ello,es mejor ceñirse a la práctica recomendada de utilizar exclusivamente usuario raíz para crear el primerusuario de IAM. A continuación, guarde las credenciales de usuario raíz en un lugar seguro y utilícelasúnicamente para algunas tareas de administración de cuentas y servicios.
Usuarios y grupos de IAMUn usuario de IAM es una entidad de la cuenta de AWS que dispone de permisos específicos para unasola persona o aplicación. Un usuario de IAM puede tener credenciales a largo plazo, como un nombrede usuario y una contraseña o un conjunto de claves de acceso. Para obtener más información acerca decómo generar claves de acceso, consulte Administración de las claves de acceso de los usuarios de IAMen la Guía del usuario de IAM. Al generar claves de acceso para un usuario de IAM, asegúrese de ver yguardar de forma segura el par de claves. No puede recuperar la clave de acceso secreta en el futuro. Ensu lugar, debe generar un nuevo par de claves de acceso.
Un grupo de IAM es una identidad que especifica un conjunto de usuarios de IAM. No puede iniciar sesióncomo grupo. Puede usar los grupos para especificar permisos para varios usuarios a la vez. Los gruposfacilitan la administración de los permisos de grandes conjuntos de usuarios. Por ejemplo, podría tener ungrupo cuyo nombre fuese Administradores de IAM y conceder permisos a dicho grupo para administrar losrecursos de IAM.
Los usuarios son diferentes de los roles. Un usuario se asocia exclusivamente a una persona o aplicación,pero la intención es que cualquier usuario pueda asumir un rol que necesite. Los usuarios tienencredenciales permanentes a largo plazo y los roles proporcionan credenciales temporales. Para obtenermás información, consulte Cuándo crear un usuario de IAM (en lugar de un rol) en la Guía del usuario deIAM.
Roles de IAMUn rol de IAM es una entidad de la cuenta de AWS que dispone de permisos específicos. Es similar a unusuario de IAM, pero no está asociado a una determinada persona. Puede asumir temporalmente un rolde IAM en la Consola de administración de AWS cambiando de roles. Puede asumir un rol llamando auna operación de la AWS CLI o de la API de AWS, o utilizando una URL personalizada. Si necesita másinformación sobre los métodos de uso de los roles, consulte Uso de roles de IAM en la Guía del usuario deIAM.
Los roles de IAM con credenciales temporales son útiles en las siguientes situaciones:
• Permisos de usuario temporales de IAM: un usuario de IAM puede asumir un rol de IAM para recibirtemporalmente permisos distintos que le permitan realizar una tarea concreta.
• Acceso de usuario federado: En lugar de crear un usuario de IAM, puede utilizar identidades existentesde AWS Directory Service, del directorio de usuarios de la empresa o de un proveedor de identidadesweb. A estas identidades se les llama usuarios federados. AWS asigna una función a un usuariofederado cuando se solicita acceso a través de un proveedor de identidad. Para obtener másinformación acerca de los usuarios federados, consulte Usuarios federados y roles en la Guía delusuario de IAM.
32
AWS X-Ray Guía para desarrolladoresAdministración de acceso mediante políticas
• Acceso entre cuentas: puede utilizar un rol de IAM para permitir que alguien (una entidad principal deconfianza) de otra cuenta obtenga acceso a los recursos de su cuenta. Los roles son la forma principalde conceder acceso entre cuentas. Sin embargo, con algunos servicios de AWS, puede asociar unapolítica directamente a un recurso (en lugar de utilizar un rol como proxy). Para obtener informaciónacerca de la diferencia entre los roles y las políticas basadas en recursos para el acceso entre cuentas,consulte Cómo los roles de IAM difieren de las políticas basadas en recursos en la Guía del usuario deIAM.
• Acceso entre servicios: Some AWS services use features in other AWS services. For example, when youmake a call in a service, it's common for that service to run applications in Amazon EC2 or store objectsin Amazon S3. A service might do this using the calling principal's permissions, using a service role, orusing a service-linked role.• Permisos principales: When you use an IAM user or role to perform actions in AWS, you are
considered a principal. Policies grant permissions to a principal. When you use some services, youmight perform an action that then triggers another action in a different service. In this case, you musthave permissions to perform both actions. To see whether an action requires additional dependentactions in a policy, see Actions, Resources, and Condition Keys for AWS X-Ray in the ServiceAuthorization Reference.
• Rol de servicio: Un rol de servicio es un rol de IAM que adopta un servicio para realizar acciones ensu nombre. Los roles de servicio ofrecen acceso solo dentro de su cuenta y no se pueden utilizarpara otorgar acceso a servicios en otras cuentas. Un administrador de IAM puede crear, modificar yeliminar un rol de servicio desde IAM. Para obtener más información, consulte Creación de un rol paradelegar permisos a un servicio de AWS en la Guía del usuario de IAM.
• Role vinculado al servicio: A service-linked role is a type of service role that is linked to an AWSservice. The service can assume the role to perform an action on your behalf. Service-linked rolesappear in your IAM account and are owned by the service. An IAM administrator can view, but not editthe permissions for service-linked roles.
• Aplicaciones que se ejecutan en Amazon EC2: Puede utilizar un rol de IAM para administrarcredenciales temporales para las aplicaciones que se ejecutan en una instancia EC2 y realizansolicitudes de la AWS CLI o la API de AWS. Es preferible hacerlo de este modo a almacenar claves deacceso en la instancia EC2. Para asignar un rol de AWS a una instancia EC2 y ponerla a disposición detodas las aplicaciones, cree un perfil de instancia asociado a la misma. Un perfil de instancia contiene elrol y permite a los programas que se ejecutan en la instancia EC2 obtener credenciales temporales. Paraobtener más información, consulte Uso de un rol de IAM para conceder permisos a aplicaciones que seejecutan en instancias Amazon EC2 en la Guía del usuario de IAM.
Para obtener información acerca del uso de los roles de IAM o usuarios de IAM, consulte Cuándo crear unrol de IAM (en vez de un usuario) en la Guía del usuario de IAM.
Administración de acceso mediante políticasPara controlar el acceso en AWS, se crean políticas y se asocian a identidades de IAM o recursos deAWS. Una política es un objeto de AWS que, cuando se asocia a una identidad o un recurso, define suspermisos. Puede iniciar sesión como usuario usuario raíz o IAM o puede asumir un rol de IAM. Cuandorealiza una solicitud, AWS evalúa las políticas relacionadas basadas en identidades o en recursos. Lospermisos en las políticas determinan si la solicitud se permite o se deniega. Las mayoría de las políticas sealmacenan en AWS como documentos JSON. Para obtener más información acerca de la estructura y elcontenido de los documentos de política JSON, consulte Información general de las políticas de JSON enla Guía del usuario de IAM.
Administrators can use AWS JSON policies to specify who has access to what. That is, which principal canperform actions on what resources, and under what conditions.
Cada entidad de IAM (usuario o rol) comienza sin permisos. En otras palabras, de forma predeterminada,los usuarios no pueden hacer nada, ni siquiera cambiar sus propias contraseñas. Para concederpermiso a un usuario para hacer algo, el administrador debe asociarle una política de permisos. O bien
33
AWS X-Ray Guía para desarrolladoresAdministración de acceso mediante políticas
el administrador puede añadir al usuario a un grupo que tenga los permisos necesarios. Cuando eladministrador concede permisos a un grupo, todos los usuarios de ese grupo obtienen los permisos.
Las políticas de IAM definen permisos para una acción independientemente del método que se utilicepara realizar la operación. Por ejemplo, suponga que dispone de una política que permite la accióniam:GetRole. Un usuario con dicha política puede obtener información del usuario de la Consola deadministración de AWS, la AWS CLI o la API de AWS.
Políticas basadas en identidadIdentity-based policies are JSON permissions policy documents that you can attach to an identity, such asan IAM user, group of users, or role. These policies control what actions users and roles can perform, onwhich resources, and under what conditions. To learn how to create an identity-based policy, see CreatingIAM policies in the Guía del usuario de IAM.
Las políticas basadas en identidad pueden clasificarse además como políticas insertadas o políticasadministradas. Las políticas insertadas se integran directamente en un único usuario, grupo o rol. Laspolíticas administradas son políticas independientes que puede asociar a varios usuarios, grupos y rolesde su cuenta de AWS. Las políticas administradas incluyen las políticas administradas por AWS y laspolíticas administradas por el cliente. Para obtener más información acerca de cómo elegir una políticaadministrada o una política insertada, consulte Elegir entre políticas administradas y políticas insertadas enla Guía del usuario de IAM.
Políticas basadas en recursosResource-based policies are JSON policy documents that you attach to a resource. Examples of resource-based policies are IAM role trust policies and Amazon S3 bucket policies. In services that support resource-based policies, service administrators can use them to control access to a specific resource. For theresource where the policy is attached, the policy defines what actions a specified principal can perform onthat resource and under what conditions. You must specify a principal in a resource-based policy. Principalscan include accounts, users, roles, federated users, or AWS services.
Las políticas basadas en recursos son políticas insertadas que se encuentran en ese servicio. No puedeutilizar políticas administradas por AWS de IAM en una política basada en recursos.
Listas de control de acceso (ACL)Access control lists (ACLs) control which principals (account members, users, or roles) have permissions toaccess a resource. ACLs are similar to resource-based policies, although they do not use the JSON policydocument format.
Amazon S3, AWS WAF y Amazon VPC son ejemplos de servicios compatibles con las ACL. Para obtenermás información sobre las ACL, consulte Información general de las listas de control de acceso (ACL) en laGuía para desarrolladores de Amazon Simple Storage Service.
Otros tipos de políticasAWS admite otros tipos de políticas menos frecuentes. Estos tipos de políticas pueden establecer elmáximo de permisos que los tipos de políticas más frecuentes le otorgan.
• Límites de permisos: un límite de permisos es una característica avanzada que le permite definir lospermisos máximos que una política basada en identidad puede conceder a una entidad de IAM (usuarioo rol de IAM). Puede establecer un límite de permisos para una identidad. Los permisos resultantes sonla intersección de las políticas basadas en identidades de la entidad y los límites de sus permisos. Laspolíticas basadas en recursos que especifiquen el usuario o rol en el campo Principal no estaránrestringidas por el límite de permisos. Una denegación explícita en cualquiera de estas políticas anulará
34
AWS X-Ray Guía para desarrolladoresCómo funciona AWS X-Ray con IAM
el permiso. Para obtener más información acerca de los límites de permisos, consulte see Límites depermisos para las entidades de IAM en la Guía del usuario de IAM.
• Políticas de control de servicios (SCP): las SCP son políticas de JSON que especifican los permisosmáximos para una organización o unidad organizativa (OU) en AWS Organizations. AWS Organizationses un servicio que le permite agrupar y administrar de forma centralizada varias cuentas de AWSque posee su negocio. Si habilita todas las funciones en una organización, entonces podrá aplicarpolíticas de control de servicio (SCP) a una o todas sus cuentas. Una SCP limita los permisos para lasentidades de las cuentas de miembros, incluido cada Usuario de la cuenta raíz de AWS. Para obtenermás información acerca de Organizaciones y las SCP, consulte Funcionamiento de las SCP en la Guíadel usuario de AWS Organizations.
• Políticas de sesión: las políticas de sesión son políticas avanzadas que se pasan como parámetrocuando se crea una sesión temporal mediante programación para un rol o un usuario federado. Lospermisos de la sesión resultantes son la intersección de las políticas basadas en identidades del rol y laspolíticas de la sesión. Los permisos también pueden proceder de una política basada en recursos. Unadenegación explícita en cualquiera de estas políticas anulará el permiso. Para obtener más información,consulte Políticas de sesión en la Guía del usuario de IAM.
Varios tipos de políticasCuando se aplican varios tipos de políticas a una solicitud, los permisos resultantes son más complicadosde entender. Para obtener información acerca de cómo AWS determina si permitir una solicitud cuandohay varios tipos de políticas implicados, consulte Lógica de evaluación de políticas en la Guía del usuariode IAM.
Cómo funciona AWS X-Ray con IAMAntes de utilizar IAM para administrar el acceso a X-Ray, debe saber qué características de IAM estándisponibles para su uso con X-Ray. Para obtener una perspectiva general de cómo X-Ray y otros serviciosde AWS funcionan con IAM, consulte Servicios de AWS que funcionan con IAM en la Guía del usuario deIAM.
Puede utilizar AWS Identity and Access Management (IAM) para conceder X-Ray permisos a los usuariosy recursos informáticos de su cuenta. IAM controla el acceso al X-Ray servicio en el nivel de API paraaplicar los permisos de manera uniforme, independientemente del cliente (consola, AWS SDK, AWS CLI)que empleen los usuarios.
Para utilizar la consola de X-Ray (p. 51) para ver mapas de servicios y segmentos, solo necesitapermisos de lectura. Para habilitar el acceso a la consola, añada la AWSXrayReadOnlyAccess políticaadministrada (p. 44) al usuario de IAM.
Para desarrollo local y pruebas (p. 38), cree un usuario de IAM con permisos de lectura y escritura.Genere claves de acceso para el usuario y guárdelas en la ubicación estándar del AWS SDK. Puedeutilizar estas credenciales con el X-Ray demonio de , la AWS CLIy el AWS SDK de .
Para implementar su aplicación instrumentada en AWS (p. 39), cree un rol de IAM con permisos deescritura y asígnelo a los recursos que ejecutan la aplicación. AWSXRayDaemonWriteAccess incluyepermiso para cargar registros de seguimiento y algunos permisos de lectura, así como para admitir el usode reglas de (p. 76)muestreo.
Las políticas de lectura y escritura no incluyen permiso para configurar la configuración de clave decifrado (p. 29) y reglas de muestreo. Utilice AWSXrayFullAccess para obtener acceso a estasconfiguraciones o añadir API de configuración (p. 116) en una política personalizada. Para el cifrado yel descifrado con una clave administrada por el cliente que cree, también necesita permiso para utilizar laclave (p. 39).
Temas
35
AWS X-Ray Guía para desarrolladoresCómo funciona AWS X-Ray con IAM
• X-RayPolíticas de basadas en identidades (p. 36)• X-RayPolíticas de basadas en recursos (p. 38)• Autorización basada en etiquetas de X-Ray (p. 38)• Ejecutar la aplicación de forma local (p. 38)• Ejecutar la aplicación en AWS (p. 39)• Permisos de usuario para cifrado (p. 39)
X-RayPolíticas de basadas en identidadesCon las políticas basadas en identidad de IAM, puede especificar las acciones permitidas o denegadas ylos recursos además de las condiciones en las que se permiten o deniegan las acciones. X-Ray admiteacciones, recursos y claves de condiciones específicos. Para obtener más información acerca de loselementos que utiliza en una política de JSON, consulte Referencia de los elementos de las políticas deJSON de IAM en la Guía del usuario de IAM.
Actions
Administrators can use AWS JSON policies to specify who has access to what. That is, which principal canperform actions on what resources, and under what conditions.
El elemento Action de una política JSON describe las acciones que puede utilizar para permitir o denegarel acceso en una política. Las acciones de la política generalmente tienen el mismo nombre que laoperación de API de AWS asociada. Hay algunas excepciones, como acciones de solo permiso que notienen una operación de API coincidente. También hay algunas operaciones que requieren varias accionesen una política. Estas acciones adicionales se denominan acciones dependientes.
Incluya acciones en una política para conceder permisos para realizar la operación asociada.
Las acciones de políticas de X-Ray incluyen el siguiente prefijo antes de la acción: xray:. Por ejemplo,para conceder a alguien permiso para recuperar detalles de los recursos de grupo con la operación de laAPI X-Ray de GetGroup, incluya la acción xray:GetGroup en su política. Las instrucciones de políticadeben incluir un elemento Action o NotAction. X-Ray define su propio conjunto de acciones, quedescriben las tareas que se pueden realizar con este servicio.
Para especificar varias acciones en una única instrucción, sepárelas con comas del siguiente modo:
"Action": [ "xray:action1", "xray:action2"
Puede utilizar caracteres comodín para especificar varias acciones (*). Por ejemplo, para especificar todaslas acciones que comiencen con la palabra Get, incluya la siguiente acción:
"Action": "xray:Get*"
Para ver una lista de acciones de X-Ray, consulte Acciones definidas por AWS X-Ray en la Guía delusuario de IAM.
Resources
Administrators can use AWS JSON policies to specify who has access to what. That is, which principal canperform actions on what resources, and under what conditions.
El elemento Resource de la política JSON especifica el objeto u objetos a los que se aplica la acción.Las instrucciones deben contener un elemento Resource o NotResource. Una práctica recomendada
36
AWS X-Ray Guía para desarrolladoresCómo funciona AWS X-Ray con IAM
consiste en especificar un recurso utilizando su nombre de recurso de Amazon (ARN). Puede hacerlo paraacciones que admitan un tipo de recurso específico, conocido como permisos de nivel de recurso.
Para las acciones que no admiten permisos de nivel de recurso, como las operaciones de descripción,utilice un carácter comodín (*) para indicar que la instrucción se aplica a todos los recursos.
"Resource": "*"
Puede controlar el acceso a los recursos a través de una política de IAM. Para las acciones que admitenpermisos de nivel de recursos, se usa un nombre de recurso de Amazon (ARN) para identificar el recursoal que se aplica la política.
Es posible utilizar todas las acciones de X-Ray en una política de IAM para conceder o denegar permisoa los usuarios para utilizar esa acción. Sin embargo, no todas las acciones de X-Ray admiten permisos denivel de recursos, que le permiten especificar los recursos en los que se puede realizar una acción.
Para las acciones que no admiten permisos de nivel de recursos, debe utilizar "*" como recurso.
Las siguientes acciones de X-Ray admiten permisos de nivel de recursos:
• CreateGroup
• GetGroup
• UpdateGroup
• DeleteGroup
• CreateSamplingRule
• UpdateSamplingRule
• DeleteSamplingRule
A continuación, se muestra un ejemplo de una política de permisos basada en identidad para una acciónCreateGroup: El ejemplo muestra el uso de un ARN relacionado con el nombre de grupo local-users con el ID único como elemento comodín. El ID único se genera cuando se crea el grupo y, por lotanto, no puede predecirse en la política con antelación. Cuando se utiliza GetGroup, UpdateGroup oDeleteGroup, puede definir esto como un elemento comodín o el ARN exacto, incluido el ID.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "xray:CreateGroup" ], "Resource": [ "arn:aws:xray:eu-west-1:123456789012:group/local-users/*" ] } ]}
A continuación, se muestra un ejemplo de una política de permisos basada en identidad para una acciónCreateSamplingRule:
{ "Version": "2012-10-17", "Statement": [
37
AWS X-Ray Guía para desarrolladoresCómo funciona AWS X-Ray con IAM
{ "Effect": "Allow", "Action": [ "xray:CreateSamplingRule" ], "Resource": [ "arn:aws:xray:eu-west-1:123456789012:sampling-rule/base-scorekeep" ] } ]}
Note
El ARN de una regla de muestreo se define por su nombre. A diferencia de los ARN de grupo, lasreglas de muestreo no tienen un ID generado de manera inequívoca.
Para ver una lista de los tipos de recursos de X-Ray y sus ARN, consulte Recursos definidos por AWSX-Ray en la Guía del usuario de IAM. Para obtener información acerca de con qué acciones puedeespecificar los ARN de cada recurso, consulte Acciones definidas por AWS X-Ray.
Claves de condición
X-Ray no proporciona ninguna clave de condición específica del servicio, pero sí admite el uso de algunasclaves de condición globales. Para ver todas las claves de condición globales de AWS, consulte Claves decontexto de condición globales de AWS en la Guía del usuario de IAM.
Examples
Para ver ejemplos de políticas de X-Ray basadas en identidades, consulte AWS X-RayEjemplos depolíticas de basadas en identidades (p. 40).
X-RayPolíticas de basadas en recursosX-Ray no admite las políticas basadas en recursos, pero sí admite las políticas de nivel de recursos.
Autorización basada en etiquetas de X-RayPuede asociar etiquetas a X-Ray grupos de o reglas de muestreo, o pasar etiquetas en una solicitud a X-Ray. Para controlar el acceso en función de etiquetas, debe proporcionar información de las etiquetas en elelemento de condición de una política utilizando las claves de condición xray:ResourceTag/key-name,aws:RequestTag/key-name o aws:TagKeys. Para obtener más información acerca del etiquetado derecursos de X-Ray, consulte Etiquetado de reglas y grupos X-Ray de muestreo (p. 346).
Para ver un ejemplo de política basada en identidades para limitar el acceso a un recurso en función delas etiquetas de dicho recurso, consulte Administración del acceso a X-Ray grupos y reglas de muestreobasadas en etiquetas (p. 42).
Ejecutar la aplicación de forma localSu aplicación instrumentada envía datos de rastreo al daemon de X-Ray. El daemon almacena en búferdocumentos de segmento y los carga en lotes en el servicio X-Ray. El daemon necesita permisos deescritura para cargar los datos de rastreo y telemetría en el servicio X-Ray.
Cuando ejecute el daemon localmente (p. 177), almacene la clave secreta y la clave de acceso deusuario de IAM en un archivo denominado credentials, en una carpeta con el nombre .aws de sucarpeta de usuario.
38
AWS X-Ray Guía para desarrolladoresCómo funciona AWS X-Ray con IAM
Example ~/.aws/credentials
[default]aws_access_key_id=AKIAIOSFODNN7EXAMPLEaws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Si ya ha configurado las credenciales para utilizarlas con el AWS SDK o la AWS CLI, el demonio puedeutilizarlas. En caso de que haya varios perfiles disponibles, el daemon utilizará el perfil predeterminado.
Ejecutar la aplicación en AWSCuando ejecute su aplicación en AWS, utilice un rol para conceder permisos a la instancia Amazon EC2 oa la función Lambda que ejecute el daemon.
• Amazon Elastic Compute Cloud (Amazon EC2) – Cree un rol de IAM y asócielo a la instancia EC2 comoperfil de instancia.
• Amazon Elastic Container Service (Amazon ECS): – crear un rol de IAM y asociarlo a instancias decontenedor como rol de IAM de instancia de contenedor.
• AWS Elastic Beanstalk (Elastic Beanstalk) – Elastic Beanstalk incluye X-Ray permisos en su perfilde instancia predeterminado. Puede usar el perfil de instancia predeterminado o añadir permisos deescritura a un perfil de instancia personalizado.
• AWS Lambda (Lambda) – Añadir permisos de escritura al rol de ejecución de la función.
Para crear un rol para su uso con X-Ray
1. Abra la consola de IAM.2. Elija Roles.3. Elija Create New Role.4. En Role Name (Nombre del rol), escriba xray-application. Elija Next Step (Paso siguiente).5. En Role Type (Tipo de rol), elija Amazon EC2.6. Adjunte políticas administradas para que la aplicación tenga acceso a los servicios de AWS.
• AWSXRayDaemonWriteAccess – Le concede permiso al demonio de X-Ray para cargar datos derastreo.
• AmazonS3ReadOnlyAccess (Amazon EC2solo ): – concede a la instancia permiso para descargar elX-Ray demonio de desde Amazon S3.
Si la aplicación utiliza el SDK de AWS para acceder a otros servicios, añada políticas que otorguenacceso a dichos servicios.
7. Elija Next Step (Paso siguiente).8. Elija Create Role (Crear rol).
Permisos de usuario para cifradoX-Ray cifra todos los datos de rastro y de forma predeterminada y puede configurarlo para que use unaclave que usted administre (p. 29). Si elige una clave maestra del cliente administrada por el cliente deAWS Key Management Service, tiene que asegurarse de que la política de acceso a la clave le concedapermisos a X-Ray para utilizarla para cifrar. Otros usuarios de su cuenta también tienen que obteneracceso a la clave para ver los datos de rastreo cifrados en la consola de X-Ray.
Para una CMK administrada por el cliente, configure su clave con una política de acceso que permita lassiguientes acciones:
39
AWS X-Ray Guía para desarrolladoresEjemplos de políticas basadas en identidades
• El usuario que configura la clave en X-Ray tiene permisos para llamar a kms:CreateGrant ykms:DescribeKey.
• Los usuarios que pueden tener acceso a los datos de rastreo cifrados tienen permiso para llamar akms:Decrypt.
Cuando se añade un usuario al grupo Key users (Usuarios clave) en la sección de configuración de clavede la consola de IAM, tienen permisos para ambas operaciones. El permiso solo se tiene que establecer enla política de claves, por tanto no necesita ningún permiso de AWS KMS en sus usuarios, grupos o rolesde IAM. Consulte Uso de políticas de claves en la Guía para desarrolladores de AWS KMS.
Para el cifrado predeterminado o si elige la CMK administrada de AWS (aws/xray), el permiso se basa enquién tiene acceso a las API de X-Ray. Cualquier persona con acceso a PutEncryptionConfig, incluidoen AWSXrayFullAccess, puede cambiar la configuración de cifrado. Para evitar que un usuario cambie laclave de cifrado, no le conceda permiso para utilizar PutEncryptionConfig.
AWS X-RayEjemplos de políticas de basadas enidentidadesDe forma predeterminada, los usuarios y roles de IAM no tienen permiso para crear, ver ni modificarrecursos de X-Ray. Tampoco pueden realizar tareas mediante la Consola de administración de AWS, laAWS CLI, o la API de AWS. Un administrador de IAM debe crear políticas de IAM que concedan permisosa los usuarios y a los roles para realizar operaciones de la API concretas en los recursos especificadosque necesiten. El administrador debe adjuntar esas políticas a los usuarios o grupos de IAM que necesitenesos permisos.
Para obtener más información acerca de cómo crear una política basada en identidad de IAM con estosdocumentos de políticas de JSON de ejemplo, consulte Creación de políticas en la pestaña JSON en laGuía del usuario de IAM.
Temas• Prácticas recomendadas relativas a políticas (p. 40)• Uso de la consola de X-Ray (p. 41)• Permitir a los usuarios consultar sus propios permisos (p. 41)• Administración del acceso a X-Ray grupos y reglas de muestreo basadas en etiquetas (p. 42)• IAM Políticas administradas por para X-Ray (p. 44)• Especificación de un recurso en una política de IAM (p. 46)
Prácticas recomendadas relativas a políticasLas políticas basadas en identidad son muy eficaces. Determinan si alguien puede crear, acceder oeliminar los recursos de X-Ray de su cuenta. Estas acciones pueden generar costes adicionales para sucuenta de AWS. Siga estas directrices y recomendaciones al crear o editar políticas basadas en identidad:
• Introducción sobre el uso de políticas administradas de AWS: para comenzar a utilizar X-Rayrápidamente, utilice las políticas administradas de AWS para proporcionar a los empleados los permisosnecesarios. Estas políticas ya están disponibles en su cuenta y las mantiene y actualiza AWS. Paraobtener más información, consulte Introducción al uso de permisos con políticas administradas de AWSen la Guía del usuario de IAM.
• Conceder privilegios mínimos – Al crear políticas personalizadas, conceda solo los permisos necesariospara llevar a cabo una tarea. Comience con un conjunto mínimo de permisos y conceda permisosadicionales según sea necesario. Por lo general, es más seguro que comenzar con permisos que son
40
AWS X-Ray Guía para desarrolladoresEjemplos de políticas basadas en identidades
demasiado tolerantes e intentar hacerlos más severos más adelante. Para obtener más información,consulte la sección Otorgar privilegios mínimos en la Guía del usuario de IAM.
• Habilitar MFA para operaciones confidenciales – Para mayor seguridad, obligue a los usuarios deIAM a que utilicen la autenticación multifactor (MFA) para acceder a recursos u operaciones de APIconfidenciales. Para obtener más información, consulte Uso de la autenticación multifactor (MFA) enAWS en la Guía del usuario de IAM.
• Utilizar condiciones de política para mayor seguridad – En la medida en que sea práctico, defina lascondiciones en las que sus políticas basadas en identidad permitan el acceso a un recurso. Por ejemplo,puede escribir condiciones para especificar un rango de direcciones IP permitidas desde el que debeproceder una solicitud. También puede escribir condiciones para permitir solicitudes solo en un intervalode hora o fecha especificado o para solicitar el uso de SSL o MFA. Para obtener más información,consulteElementos de la política de JSON de IAM: condición en la Guía del usuario de IAM.
Uso de la consola de X-RayPara acceder a la consola de AWS X-Ray, debe tener un conjunto mínimo de permisos. Estos permisosdeben permitirle registrar y consultar los detalles sobre los recursos de X-Ray en su cuenta de AWS. Sicrea una política basada en identidad que sea más restrictiva que el mínimo de permisos necesarios, laconsola no funcionará del modo esperado para las entidades (usuarios o roles de IAM) que tengan esapolítica.
Para asegurarse de que esas entidades puedan seguir usando la consola de X-Ray, asocie también lapolítica administrada de AWS siguiente a las entidades. Para obtener más información, consulte Adición depermisos a un usuario en la Guía del usuario de IAM:
AWSXrayReadOnlyAccess
No es necesario que conceda permisos mínimos para la consola a los usuarios que solo realizan llamadasa la AWS CLI o a la API de AWS. En su lugar, permite acceso únicamente a las acciones que coincidancon la operación de API que intenta realizar.
Permitir a los usuarios consultar sus propios permisosEn este ejemplo, se muestra cómo podría crear una política que permita a los usuarios de IAM ver laspolíticas administradas e insertadas que se asocian a la identidad de sus usuarios. Esta política incluyepermisos para llevar a cabo esta acción en la consola o mediante programación con la AWS CLI o la APIde AWS.
{ "Version": "2012-10-17", "Statement": [ { "Sid": "ViewOwnUserInfo", "Effect": "Allow", "Action": [ "iam:GetUserPolicy", "iam:ListGroupsForUser", "iam:ListAttachedUserPolicies", "iam:ListUserPolicies", "iam:GetUser" ], "Resource": ["arn:aws:iam::*:user/${aws:username}"] }, { "Sid": "NavigateInConsole", "Effect": "Allow",
41
AWS X-Ray Guía para desarrolladoresEjemplos de políticas basadas en identidades
"Action": [ "iam:GetGroupPolicy", "iam:GetPolicyVersion", "iam:GetPolicy", "iam:ListAttachedGroupPolicies", "iam:ListGroupPolicies", "iam:ListPolicyVersions", "iam:ListPolicies", "iam:ListUsers" ], "Resource": "*" } ]}
Administración del acceso a X-Ray grupos y reglas de muestreobasadas en etiquetasPuede utilizar condiciones en su política basada en identidad para controlar el acceso a X-Ray grupos yreglas de muestreo basadas en etiquetas. La siguiente política de ejemplo se podría utilizar para denegara un rol de IAM usuario de los permisos para crear, eliminar o actualizar grupos de con las etiquetasstage:prod o stage:preprod. Para obtener más información acerca del etiquetado de reglas y gruposX-Ray de muestreo, consulte Etiquetado de reglas y grupos X-Ray de muestreo (p. 346).
Para denegar a un usuario el acceso para crear, actualizar o eliminar un grupo con una etiquetastage:prod o stage:preprod, asigne al usuario un rol con una política similar a la siguiente.
{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowAllXRay", "Effect": "Allow", "Action": "xray:*", "Resource": "*" }, { "Sid": "DenyCreateGroupWithStage", "Effect": "Deny", "Action": [ "xray:CreateGroup" ], "Resource": "*", "Condition": { "StringEquals": { "aws:RequestTag/stage": [ "preprod", "prod" ] } } }, { "Sid": "DenyUpdateGroupWithStage", "Effect": "Deny", "Action": [ "xray:UpdateGroup", "xray:DeleteGroup" ], "Resource": "*", "Condition": { "StringEquals": {
42
AWS X-Ray Guía para desarrolladoresEjemplos de políticas basadas en identidades
"aws:ResourceTag/stage": [ "preprod", "prod" ] } } } ]}
Para denegar la creación de una regla de muestreo, utilice aws:RequestTag para indicar etiquetas queno se pueden pasar como parte de una solicitud de creación. Para denegar la actualización o eliminaciónde una regla de muestreo, utilice aws:ResourceTag para denegar acciones en función de las etiquetasde esos recursos.
{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowAllXRay", "Effect": "Allow", "Action": "xray:*", "Resource": "*" }, { "Sid": "DenyCreateSamplingRuleWithStage", "Effect": "Deny", "Action": "xray:CreateSamplingRule", "Resource": "*", "Condition": { "StringEquals": { "aws:RequestTag/stage": [ "preprod", "prod" ] } } }, { "Sid": "DenyUpdateSamplingRuleWithStage", "Effect": "Deny", "Action": [ "xray:UpdateSamplingRule", "xray:DeleteSamplingRule" ], "Resource": "*", "Condition": { "StringEquals": { "aws:ResourceTag/stage": [ "preprod", "prod" ] } } } ]}
Puede asociar estas políticas (o combinarlas en una única política y, a continuación, asociar la política)a los IAM usuarios de su cuenta. Para que el usuario pueda realizar cambios en un grupo o una reglade muestreo, el grupo o la regla de muestreo no deben estar etiquetados como stage=prepod ostage=prod. La clave de la etiqueta de condición Stage coincide con los nombres de las claves decondición Stage y stage porque no distinguen entre mayúsculas y minúsculas. Para obtener más
43
AWS X-Ray Guía para desarrolladoresEjemplos de políticas basadas en identidades
información sobre el bloque de condición, consulte Elementos de la política de IAM JSON de : Condition enla Guía del usuario de IAM .
Un usuario con un rol que tenga asociada la siguiente política no puede añadir la etiqueta role:admin alos recursos y no puede eliminar etiquetas de un recurso que tenga role:admin asociado.
{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowAllXRay", "Effect": "Allow", "Action": "xray:*", "Resource": "*" }, { "Sid": "DenyRequestTagAdmin", "Effect": "Deny", "Action": "xray:TagResource", "Resource": "*", "Condition": { "StringEquals": { "aws:RequestTag/role": "admin" } } }, { "Sid": "DenyResourceTagAdmin", "Effect": "Deny", "Action": "xray:UntagResource", "Resource": "*", "Condition": { "StringEquals": { "aws:ResourceTag/role": "admin" } } } ]}
IAM Políticas administradas por para X-RayA fin de facilitar la concesión de permisos, IAM admite políticas administradas en cada servicio. Un serviciopuede actualizar estas políticas administradas con nuevos permisos al lanzar nuevas API. AWS X-Rayproporciona políticas administradas de solo lectura, solo escritura y casos de uso de administrador.
• AWSXrayReadOnlyAccess – Permisos de lectura para utilizar la X-Ray consola AWS CLIde , la o elAWS SDK de para obtener datos de rastreo y mapas de servicios de la X-Ray API de . Incluye permisopara ver reglas de muestreo.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "xray:GetSamplingRules", "xray:GetSamplingTargets", "xray:GetSamplingStatisticSummaries", "xray:BatchGetTraces", "xray:GetServiceGraph", "xray:GetTraceGraph",
44
AWS X-Ray Guía para desarrolladoresEjemplos de políticas basadas en identidades
"xray:GetTraceSummaries", "xray:GetGroups", "xray:GetGroup", "xray:GetTimeSeriesServiceStatistics", "xray:GetInsightSummaries", "xray:GetInsight", "xray:GetInsightEvents", "xray:GetInsightImpactGraph" ], "Resource": [ "*" ] } ]}
• AWSXRayDaemonWriteAccess – Describe cómo escribir permisos para utilizar el X-Ray demonio de ,la AWS CLIo el AWS SDK de para cargar documentos de segmento y telemetría en la X-Ray API de .Incluye permisos de lectura para obtener reglas de muestreo (p. 76) y notificar los resultados demuestreo.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "xray:PutTraceSegments", "xray:PutTelemetryRecords", "xray:GetSamplingRules", "xray:GetSamplingTargets", "xray:GetSamplingStatisticSummaries" ], "Resource": [ "*" ] } ]}
• AWSXrayFullAccess – Permiso para utilizar todas las X-Ray APIs , incluidos los permisos de lectura,los permisos de escritura y el permiso para configurar los ajustes de las claves de cifrado y las reglas demuestreo.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "xray:*" ], "Resource": [ "*" ] } ]}
Para añadir una política administrada a un usuario, un grupo o un rol de IAM
1. Abra la consola de IAM.
45
AWS X-Ray Guía para desarrolladoresEjemplos de políticas basadas en identidades
2. Abra el rol asociado a su perfil de instancia, al usuario de IAM o al grupo de usuarios de IAM.3. En Permissions (Permisos), asocia la política administrada.
Especificación de un recurso en una política de IAMPuede controlar el acceso a los recursos a través de una política de IAM. Para las acciones que admitenpermisos de nivel de recursos, se usa un nombre de recurso de Amazon (ARN) para identificar el recursoal que se aplica la política.
Es posible utilizar todas las acciones de X-Ray en una política de IAM para conceder o denegar permisoa los usuarios para utilizar esa acción. Sin embargo, no todas las acciones de X-Ray admiten permisos denivel de recursos, que le permiten especificar los recursos en los que se puede realizar una acción.
Para las acciones que no admiten permisos de nivel de recursos, debe utilizar "*" como recurso.
Las siguientes acciones de X-Ray admiten permisos de nivel de recursos:
• CreateGroup
• GetGroup
• UpdateGroup
• DeleteGroup
• CreateSamplingRule
• UpdateSamplingRule
• DeleteSamplingRule
A continuación, se muestra un ejemplo de una política de permisos basada en identidad para una acciónCreateGroup: El ejemplo muestra el uso de un ARN relacionado con el nombre de grupo local-users con el ID único como elemento comodín. El ID único se genera cuando se crea el grupo y, por lotanto, no puede predecirse en la política con antelación. Cuando se utiliza GetGroup, UpdateGroup oDeleteGroup, puede definir esto como un elemento comodín o el ARN exacto, incluido el ID.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "xray:CreateGroup" ], "Resource": [ "arn:aws:xray:eu-west-1:123456789012:group/local-users/*" ] } ]}
A continuación, se muestra un ejemplo de una política de permisos basada en identidad para una acciónCreateSamplingRule:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "xray:CreateSamplingRule"
46
AWS X-Ray Guía para desarrolladoresSolución de problemas
], "Resource": [ "arn:aws:xray:eu-west-1:123456789012:sampling-rule/base-scorekeep" ] } ]}
Note
El ARN de una regla de muestreo se define por su nombre. A diferencia de los ARN de grupo, lasreglas de muestreo no tienen un ID generado de manera inequívoca.
Solución de problemas de identidad y acceso en AWSX-RayUtilice la información siguiente para diagnosticar y solucionar los problemas comunes que puedan surgircuando trabaje con X-Ray e IAM.
Temas• No tengo autorización para realizar una acción en X-Ray (p. 47)• No tengo autorización para realizar la acción iam:PassRole (p. 47)• Quiero ver mis claves de acceso (p. 48)• Soy administrador y deseo permitir que otros obtengan acceso a X-Ray (p. 48)• Quiero permitir a personas externas a mi cuenta de AWS el acceso a mis recursos de X-Ray (p. 48)
No tengo autorización para realizar una acción en X-RaySi la Consola de administración de AWS le indica que no está autorizado para llevar a cabo una acción,debe ponerse en contacto con su administrador para recibir ayuda. Su administrador es la persona que lefacilitó su nombre de usuario y contraseña.
En el siguiente ejemplo, el error se produce cuando el usuario mateojackson de IAM intentautilizar la consola para ver detalles sobre una regla de muestreo, pero no tiene permisosxray:GetSamplingRules.
User: arn:aws:iam::123456789012:user/mateojackson is not authorized to perform: xray:GetSamplingRules on resource: arn:${Partition}:xray:${Region}:${Account}:sampling-rule/${SamplingRuleName}
En este caso, Mateo pide a su administrador que actualice sus políticas de forma que pueda obteneracceso al recurso de regla de muestreo mediante la acción xray:GetSamplingRules.
No tengo autorización para realizar la acción iam:PassRoleSi recibe un error que indica que no está autorizado para llevar a cabo la acción iam:PassRole, debeponerse en contacto con su administrador para recibir ayuda. Su administrador es la persona que le facilitósu nombre de usuario y contraseña. Pida a la persona que actualice sus políticas de forma que puedatransferir un rol a X-Ray.
Algunos servicios de AWS le permiten transferir un rol existente a dicho servicio en lugar de crear un nuevorol de servicio o uno vinculado al servicio. Para ello, debe tener permisos para transferir el rol al servicio.
En el siguiente ejemplo, el error se produce cuando un usuario de IAM denominado marymajor intentautilizar la consola para realizar una acción en X-Ray. Sin embargo, la acción requiere que el servicio
47
AWS X-Ray Guía para desarrolladoresSolución de problemas
cuente con permisos otorgados por un rol de servicio. Mary no tiene permisos para transferir el rol alservicio.
User: arn:aws:iam::123456789012:user/marymajor is not authorized to perform: iam:PassRole
En este caso, Mary pide a su administrador que actualice sus políticas para que pueda realizar la accióniam:PassRole.
Quiero ver mis claves de accesoDespués de crear sus claves de acceso de usuario de IAM, puede ver su ID de clave de acceso encualquier momento. Sin embargo, no puede volver a ver su clave de acceso secreta. Si pierde la clave deacceso secreta, debe crear un nuevo par de claves de acceso.
Las claves de acceso se componen de dos partes: un ID de clave de acceso (por ejemplo,AKIAIOSFODNN7EXAMPLE) y una clave de acceso secreta (por ejemplo, wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY). El ID de clave de acceso y la clave de acceso secreta se utilizan juntos, como unnombre de usuario y contraseña, para autenticar sus solicitudes. Administre sus claves de acceso con elmismo nivel de seguridad que para el nombre de usuario y la contraseña.
Important
No proporcione las claves de acceso a terceras personas, ni siquiera para que le ayuden a buscarel ID de usuario canónico. Si lo hace, podría conceder a otra persona acceso permanente a sucuenta.
Cuando cree un par de claves de acceso, se le pide que guarde el ID de clave de acceso y la clave deacceso secreta en un lugar seguro. La clave de acceso secreta solo está disponible en el momento de sucreación. Si pierde la clave de acceso secreta, debe añadir nuevas claves de acceso a su usuario de IAM.Puede tener un máximo de dos claves de acceso. Si ya cuenta con dos, debe eliminar un par de clavesantes de crear uno nuevo. Para ver las instrucciones, consulte Administración de las claves de acceso enla Guía del usuario de IAM.
Soy administrador y deseo permitir que otros obtengan acceso aX-RayPara permitir que otros obtengan acceso a X-Ray, debe crear una entidad de IAM (usuario o rol) parala persona o aplicación que necesita acceso. Esta persona utilizará las credenciales de la entidad paraobtener acceso a AWS. A continuación, debe asociar una política a la entidad que le conceda los permisoscorrectos en X-Ray.
Para comenzar de inmediato, consulte Creación del primer grupo y usuario delegado de IAM en la Guía delusuario de IAM.
Quiero permitir a personas externas a mi cuenta de AWS elacceso a mis recursos de X-RayPuede crear un rol que los usuarios de otras cuentas o las personas externas a la organización puedanutilizar para acceder a sus recursos. Puede especificar una persona de confianza para que asuma el rol.En el caso de los servicios que admitan las políticas basadas en recursos o las listas de control de acceso(ACL), puede utilizar dichas políticas para conceder a las personas acceso a sus recursos.
Para obtener más información, consulte lo siguiente:
• Para obtener información acerca de si X-Ray admite estas características, consulte Cómo funciona AWSX-Ray con IAM (p. 35).
48
AWS X-Ray Guía para desarrolladoresRegistro y monitorización
• Para aprender cómo proporcionar acceso a sus recursos en cuentas de AWS de su propiedad, consulteProporcionar acceso a un usuario de IAM a otra cuenta de AWS de la que es propietario en la Guía delusuario de IAM.
• Para obtener información acerca de cómo ofrecer acceso a sus recursos a cuentas de AWS de terceros,consulte Proporcionar acceso a las cuentas de AWS propiedad de terceros en la Guía del usuario deIAM.
• Para obtener información acerca de cómo ofrecer acceso a la identidad federada, consulte Proporcionaracceso a usuarios autenticados externamente (identidad federada) en la Guía del usuario de IAM.
• Para obtener información acerca de la diferencia entre utilizar los roles y las políticas basadas enrecursos para el acceso entre cuentas, consulte Cómo los roles de IAM difieren de las políticas basadasen recursos en la Guía del usuario de IAM.
Registro y monitoreo en AWS X-RayLa monitorización es una parte importante del mantenimiento de la fiabilidad, la disponibilidad y elrendimiento de sus soluciones de AWS. Debe recopilar datos de monitorización de todas las partes desu solución de AWS para que pueda depurar más fácilmente un error multipunto si se produce. AWSproporciona varias herramientas para monitorizar sus recursos de X-Ray y responder a posibles incidentes:
Registros de AWS CloudTrail
AWS X-Ray se integra con AWS CloudTrail para registrar las acciones de la API realizadas porun usuario, un rol o un servicio de AWS en X-Ray. Puede utilizar CloudTrail para monitorizar lassolicitudes de la API de X-Ray en tiempo real y almacenar los registros en Amazon S3, AmazonCloudWatch Logs y Amazon CloudWatch Events. Para obtener más información, consulte Registro dellamadas a X-Ray la API de con AWS CloudTrail (p. 191).
Seguimiento de AWS Config
AWS X-Ray se integra con AWS Config para registrar cambios de configuración realizados en losrecursos de cifrado de X-Ray. Puede utilizar AWS Config para realizar un inventario de recursos decifrado de X-Ray, auditar el historial de configuración de X-Ray y enviar notificaciones basadas enlos cambios de recursos. Para obtener más información, consulte Seguimiento de los cambios en laconfiguración de cifrado de X-Ray con AWS Config (p. 199).
Monitorización de Amazon CloudWatch
Puede utilizar X-Ray SDK for Java para publicar las métricas de Amazon CloudWatch sin muestrearde sus segmentos de X-Ray recopilados. Estas métricas se derivan de la hora de inicio y finalizacióndel segmento, y los marcadores de estado limitado, fallo y error. Utilice estas métricas de seguimientopara exponer los reintentos y los problemas de dependencia con los subsegmentos. Para obtener másinformación, consulte AWS X-Ray Métricas de para X-Ray SDK for Java (p. 264).
Validación de la conformidad en AWS X-RayHay auditores externos que evalúan la seguridad y la conformidad de AWS X-Ray en distintos programasde conformidad de AWS. Esto incluye SOC, PCI, HIPAA y otros.
Para obtener una lista de los servicios de AWS en el ámbito de programas de conformidad específicos,consulte Servicios de AWS en el ámbito del programa de conformidad. Para obtener información general,consulte Programas de conformidad de AWS.
Puede descargar los informes de auditoría de terceros utilizando AWS Artifact. Para obtener másinformación, consulte Descarga de informes en AWS artefacto.
49
AWS X-Ray Guía para desarrolladoresResiliencia
Su responsabilidad en el ámbito de la conformidad al usar X-Ray viene determinada por la confidencialidadde los datos, los objetivos de conformidad de su empresa y las leyes y regulaciones aplicables. AWSproporciona los siguientes recursos para ayudarlo con los requisitos de conformidad:
• Guías de inicio rápido de seguridad y conformidad – estas guías de implementación tratanconsideraciones sobre arquitectura y ofrecen pasos para implementar los entornos de referenciacentrados en la seguridad y la conformidad en AWS.
• Documento técnico sobre arquitectura para seguridad y conformidad de HIPAA – este documentotécnico describe cómo las empresas pueden utilizar AWS para crear aplicaciones conformes con HIPAA.
• AWS Recursos de conformidad – Este conjunto de manuales y guías podría aplicarse a su sector yubicación.
• AWS Config – este servicio de AWS evalúa en qué medida las configuraciones de los recursos cumplenlas prácticas internas, las directrices del sector y las normativas.
• AWS Security Hub – Este servicio de AWS ofrece una vista integral de su estado de seguridad enAWS que le ayuda a comprobar la conformidad con las normas del sector de seguridad y las prácticasrecomendadas.
Resiliencia de AWS X-RayLa infraestructura global de AWS está conformada por regiones y zonas de disponibilidad de AWS. Lasregiones de AWS proporcionan varias zonas de disponibilidad físicamente independientes y aisladasque se encuentran conectadas mediante redes con un alto nivel de rendimiento y redundancia, ademásde baja latencia. Con las zonas de disponibilidad, puede diseñar y utilizar aplicaciones y bases de datosque realizan una conmutación por error automática entre zonas de disponibilidad sin interrupciones. Laszonas de disponibilidad tienen una mayor disponibilidad, tolerancia a errores y escalabilidad que lasinfraestructuras tradicionales de centros de datos únicos o múltiples.
Para obtener más información sobre zonas de disponibilidad y las regiones de AWS, consulteInfraestructura global de AWS.
Seguridad de la infraestructura en AWS X-RayAl tratarse de un servicio administrado, AWS X-Ray está protegido por los procedimientos de seguridadde red globales de AWS que se describen en el documento técnico Amazon Web Services: Informacióngeneral sobre procesos de seguridad.
Puede utilizar llamadas a la API publicadas en AWS para obtener acceso a X-Ray a través de la red.Los clientes deben ser compatibles con Transport Layer Security (TLS) 1.0 o una versión posterior.Le recomendamos TLS 1.2 o una versión posterior. Los clientes también deben ser compatibles conconjuntos de cifrado con confidencialidad directa total (PFS) tales como Ephemeral Diffie-Hellman (DHE)o Elliptic Curve Ephemeral Diffie-Hellman (ECDHE). La mayoría de los sistemas modernos como Java 7 yposteriores son compatibles con estos modos.
Además, las solicitudes deben estar firmadas mediante un ID de clave de acceso y una clave de accesosecreta que esté asociada a una entidad principal de IAM. También puede utilizar AWS Security TokenService (AWS STS) para generar credenciales de seguridad temporales para firmar solicitudes.
50
AWS X-Ray Guía para desarrolladoresConsulta del mapa de servicio
AWS X-RayConsola deCon la consola de AWS X-Ray, puede ver los mapas de servicios y los rastros de las solicitudes que susaplicaciones atienden.
El mapa de servicio de la consola es una representación visual del gráfico de servicios de JSON que X-Ray genera a partir de los datos de rastreo 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 posterioresque representan los servicios web y los recursos utilizados por una aplicación mientras procesa unasolicitud.
Puede utilizar filtros para ver un mapa de servicio o los rastros de una solicitud específica, un servicio, unaconexión entre dos servicios (un límite) o solicitudes que satisfagan una condición. X-Ray proporciona unlenguaje de expresión de filtro para filtrar solicitudes, servicios y límites en función de los datos presentesen los encabezados de la solicitud, el estado de la respuesta y los campos indexados en los segmentosoriginales.
Consulta del mapa de servicioUtilice el mapa de servicio 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.
Para ver el mapa de servicio, realice los siguientes pasos:
1. Abra la página del mapa de servicios de la consola de X-Ray.
51
AWS X-Ray Guía para desarrolladoresConsulta del mapa de servicio
2. Seleccione un nodo de servicio para ver sus solicitudes o un límite entre dos nodos para ver lassolicitudes que pasaron por esa conexión.
3. Utilice el histograma (p. 75) para filtrar los rastros por duración y seleccione los códigos de estadocuyos rastros desee ver. Elija después View traces (Ver rastros) para abrir la lista de rastros con laexpresión de filtro aplicada.
El mapa de servicio indica el estado de cada nodo mediante el uso de colores en función de la proporciónde llamadas correctas y errores o fallos:
52
AWS X-Ray Guía para desarrolladoresConsulta del mapa de servicio
• 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)
En el centro de cada nodo, la consola muestra el tiempo medio de respuesta y el número de rastreos quese envían por minuto durante el intervalo de tiempo seleccionado.
Si el mapa de servicio es grande, la consola utiliza de manera predeterminada una vista reducida. Utilicelos controles que aparecen en pantalla o el ratón para ampliar y reducir la imagen o para moverla por lapantalla.
53
AWS X-Ray Guía para desarrolladoresVer el mapa de servicio por grupo
Controls
• – Ampliar o reducir. También puede utilizar la rueda del ratón para ampliar o reducir la
imagen.•
– Desplácese por el mapa de servicio. Haga clic y arrastre para desplazarse con el ratón.•
– Encuadre el nodo o límite seleccionado en el centro del mapa.
Ver el mapa de servicio por grupoMediante una expresión de filtro, puede definir los criterios para aceptar los registros de seguimiento enun grupo. Siga los pasos que se indican a continuación para mostrar ese grupo específico en el mapa deservicio.
Para ver el mapa de servicio de un grupo
1. Abra la página del mapa de servicios de la consola de X-Ray.2. Elija un nombre de grupo en el menú desplegable situado a la izquierda de la barra de búsqueda.
54
AWS X-Ray Guía para desarrolladoresCambio de la presentación del nodo
Cambio de la presentación del nodoUtilice las siguientes opciones para cambiar la forma en que se presenta el mapa de servicio. Puedeactivar los iconos de servicio para seguir mejor la secuencia de servicios y puede cambiar los pesos de losnodos para representar mejor el tráfico o el estado.
Para cambiar la presentación del nodo
1. Abra la página del mapa de servicio de la consola de X-Ray o un mapa de seguimiento individual.
Las opciones del nodo se encuentran en la parte inferior derecha del mapa.2. Elija una presentación para su nodo.
Service Icons enabled
Service Icons (Iconos de – servicio): cuando está habilitado, muestra un icono para el AWSservicio de que el nodo ha dado respuesta, en lugar del resumen de actividad predeterminado.
55
AWS X-Ray Guía para desarrolladoresCambio de la presentación del nodo
Node weight by None
– None: cambio de tamaño de nodo; todos los nodos tienen el mismo peso.
Node weight by Health
– Estado: el tamaño del nodo se calcula por el número total de solicitudes afectadas. Lassolicitudes afectadas incluyen fault error, y throttle. Por ejemplo, un nodo con unamuestra de 1000 solicitudes en el que el 10 % (100 solicitudes) están afectadas tendrá un tamañomayor que un nodo con una muestra de 100 solicitudes en el que el 50 % (50 solicitudes) estánafectadas.
Node weight by Traffic
– Traffic: el tamaño del nodo se calcula por el número total de solicitudes muestreadas. Porejemplo, un nodo con 1000 solicitudes muestreadas tendrá un tamaño mayor que uno con100 solicitudes muestreadas.
56
AWS X-Ray Guía para desarrolladoresConsulta de registros de seguimiento
Consulta de registros de seguimientoUtilice la lista de rastros de la consola de X-Ray para encontrar rastros por URL, código de respuesta uotros datos a partir del resumen de rastros.
Para utilizar la lista de rastros
1. Abra la Información general del registro de seguimiento en la consola de X-Ray.
2. Elija una URL para filtrar la lista de rastros.3. Elija un ID de rastro para ver la escala de tiempo de un rastro.
57
AWS X-Ray Guía para desarrolladoresConsulta de registros de seguimiento
La vista Timeline (Escala de tiempo) muestra una jerarquía de segmentos y subsegmentos. La primeraentrada de la lista es el segmento, que representa todos los datos registrados por el servicio para unamisma solicitud.
Debajo del segmento aparecen los subsegmentos. En este ejemplo se muestran los subsegmentosregistrados por los clientes de Amazon DynamoDB instrumentados, así como un subsegmentopersonalizado.
El X-Ray SDK registra subsegmentos automáticamente cuando se utiliza un AWS SDK, HTTP ocliente SQL instrumentado para realizar llamadas a recursos externos. También puede indicar al SDKque registre los subsegmentos personalizados de cualquier bloque de código o de funciones. Lossubsegmentos adicionales que se registran mientras hay un subsegmento abierto se convierten enelementos secundarios del subsegmento personalizado.
En la vista Timeline (Escala de tiempo), también puede acceder a los datos de registros de seguimientosin procesar que la consola utiliza para generar la escala. Elija Raw data (Datos sin formato) para ver eldocumento JSON que contiene los segmentos y subsegmentos que componen el rastro.
58
AWS X-Ray Guía para desarrolladoresConsulta del mapa de seguimiento
Consulta del mapa de seguimientoUtilice el mapa de seguimiento para asignar visualmente la ruta integral de una sola solicitud.
Para ver un mapa de seguimiento
1. Abra la Información general del registro de seguimiento en la consola de X-Ray.2. Elija una URL para filtrar la lista de rastros.3. Elija un ID de rastro para ver la escala de tiempo de un rastro. El mapa de seguimiento se muestra
encima del rastro de línea de tiempo.
59
AWS X-Ray Guía para desarrolladoresConsulta de detalles de segmentos
Consulta de detalles de segmentosEn la escala de tiempo del rastro, elija el nombre de un segmento para ver sus detalles. En Overview(Información general) se muestra información acerca de la solicitud y la respuesta.
La pestaña Resources (Recursos) de un segmento muestra información sobre los recursos de AWS quese utilizan para ejecutar la aplicación y el SDK de X-Ray. Utilice el complemento de Amazon EC2, AWSElastic Beanstalk o Amazon ECS del SDK para registrar información sobre los recursos específica de losservicios.
60
AWS X-Ray Guía para desarrolladoresConsulta de detalles de subsegmentos
En las pestañas restantes (Annotations (Anotaciones), Metadata (Metadatos) y Exceptions (Excepciones)),se muestran las anotaciones, los metadatos y las excepciones registrados en el segmento. Lasexcepciones se capturan automáticamente cuando una solicitud instrumentada las inicia. Las anotacionesy los metadatos contienen información adicional que se registra utilizando los métodos proporcionados porel SDK.
Consulta de detalles de subsegmentosEn la escala de tiempo del rastro, elija el nombre de un segmento para ver sus detalles. Para lossubsegmentos generados con clientes instrumentados, la pestaña Overview (Información general)
61
AWS X-Ray Guía para desarrolladoresConsulta de detalles de subsegmentos
contiene información acerca de la solicitud y la respuesta desde el punto de vista de la aplicación. En esteejemplo se muestra un subsegmento procedente de una llamada instrumentada a DynamoDB.
La pestaña Resources (Recursos) de un subsegmento muestra detalles sobre la tabla de DynamoDB, laoperación a la que se ha llamado y el ID de la solicitud.
En los subsegmentos personalizados, la pestaña Overview (Información general) muestra el nombredel subsegmento, que se puede establecer de modo que especifique el área de código o la función queregistra.
62
AWS X-Ray Guía para desarrolladoresConsulta de detalles de subsegmentos
Utilice subsegmentos personalizados para organizar en grupos los subsegmentos de los clientesinstrumentados. También puede registrar en subsegmentos los metadatos y las anotaciones, que puedenresultarle útiles para depurar funciones.
63
AWS X-Ray Guía para desarrolladoresExpresiones de filtro
En este ejemplo, la aplicación registra el estado de cada objeto Game en el que guarda DynamoDB. Lohace pasando el objeto al método putMetadata en el subsegmento. El SDK de X-Ray serializa el objetoen JSON y se lo añade al documento de segmento.
Uso de expresiones de filtro para buscar registrosde seguimiento en la consola
Al elegir un periodo de tiempo de registros de seguimiento para ver en la consola de X-Ray, puede obtenermás resultados que los que la consola puede mostrar. En la esquina superior derecha, la consola muestrael número de registros de seguimiento que analiza y si hay más registros de seguimiento disponibles.
Para filtrar los resultados a tan solo los registros de seguimiento que desea encontrar a través de unaexpresión de filtro.
Temas• Detalles de expresión de filtro (p. 64)• Uso de expresiones de filtro con grupos (p. 65)• Sintaxis de expresiones de filtro (p. 65)• Palabras clave booleanas (p. 66)• Palabras clave numéricas (p. 67)• Palabras clave de cadenas (p. 68)• Palabras clave complejas (p. 69)• id Función (p. 71)
Detalles de expresión de filtroCuando elige un nodo en el mapa de servicio (p. 51), la consola construye una expresión de filtro enfunción del nombre de servicio del nodo y los tipos de errores presentes en función de su selección. Paraencontrar registros de seguimiento que muestren problemas de rendimiento o relacionados con solicitudesespecíficas, puede ajustar la expresión proporcionada por la consola, o bien crear la suya propia. Siañade anotaciones con el SDK de X-Ray, también puede filtrar en función de la presencia de una clave deanotación o el valor de una clave.
Note
Si elige un intervalo de tiempo relativo en el mapa de servicio y elige un nodo, la consola convierteel intervalo de tiempo a una hora absoluta de inicio y finalización. Para asegurarse de que losregistros de seguimiento del nodo aparezcan en los resultados de búsqueda y evitar los tiemposde examen cuando el nodo no estaba activo, el intervalo de tiempo solo incluye las horas alas 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 aanalizar.
Si sigue habiendo más resultados disponibles de los que la consola puede mostrar, la consola muestracuá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ó. Paraasegurarse de ver todos los registros de seguimiento coincidentes representados en los resultados, filtreaú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 delintervalo de tiempo y va hacia atrás. Si hay un gran número de registros de seguimiento, pero pocos
64
AWS X-Ray Guía para desarrolladoresUso de expresiones de filtro con grupos
resultados, la consola divide el intervalo de tiempo en porciones y las analiza en paralelo. La barra deprogreso muestra las partes del intervalo de tiempo que se han analizado.
Uso de expresiones de filtro con gruposLos grupos son una colección de registros de seguimiento que se definen mediante una expresión de filtro.Puede utilizar grupos para generar gráficos de servicios adicionales y suministrar métricas de AmazonCloudWatch.
Los grupos se identifican por su nombre o un nombre de recurso de Amazon (ARN) y contienen unaexpresión de filtro. El servicio compara los registros de seguimiento de entrada con la expresión y losalmacena en consecuencia.
Puede crear y modificar grupos mediante el menú desplegable situado a la izquierda de la barra debúsqueda de expresiones de filtro.
Note
Si el servicio encuentra un error al evaluar un grupo, ese grupo deja de estar incluido en elprocesamiento 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 de en la consola X-Ray de (p. 92).
Sintaxis de expresiones de filtroLas expresiones de filtro pueden incluir una palabra clave, un operador único o binario y un valor para lacomparación.
keyword operator value
Cada tipo de palabra clave tiene sus propios operadores. Por ejemplo, responsetime es una palabraclave 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
65
AWS X-Ray Guía para desarrolladoresPalabras clave booleanas
Puede combinar varias expresiones en una expresión compuesta utilizando los operadores AND u OR.
Example – Solicitudes con duración total de –58 segundos
duration >= 5 AND duration <= 8
Solo se detectan problemas con las palabras clave y los operadores sencillos en el nivel de registro deseguimiento. 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 clavecomplejas (p. 69) service() y edge(). Estas palabras clave permiten aplicar un filtro de expresióna todos los nodos posteriores, a un único nodo posterior o a un límite entre dos nodos. Para obtener unmayor nivel de detalle, puede filtrar los servicios y los bordes con la función id() (p. 71).
Palabras clave booleanasLos valores de palabra clave booleana son true o false. Utilícelas para encontrar registros de seguimientoque 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 ofalse.
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
66
AWS X-Ray Guía para desarrolladoresPalabras clave numéricas
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 nombredel servicio es "registros de seguimiento"
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éricasUtilice palabras clave numéricas para buscar solicitudes con un tiempo de respuesta, duración o estado derespuesta 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 derespuesta.
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 , donde la duración total fue de –58 segundos
duration >= 5 AND duration <= 8
67
AWS X-Ray Guía para desarrolladoresPalabras clave de cadenas
Example – Solicitudes que se completaron sin errores en menos de 3 segundos, incluidas todaslas 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 cadenasUtilice palabras clave de cadena para encontrar registros de seguimiento con texto específico en losencabezados de solicitud o ID de usuario específicos.
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 rastro.• 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 en cualquier segmento incluido en el rastro.• resource.arn – Valor del campo ARN de recurso en cualquier segmento incluido en el rastro.
Los operadores de cadena permiten encontrar valores iguales a un texto determinado o que contienendicho 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 específica.
Example – filtro http.url
http.url CONTAINS "/api/game/"
Para probar si un registro de seguimiento incluye un campo, independientemente de su valor, compruebesi la cadena está vacía.
68
AWS X-Ray Guía para desarrolladoresPalabras clave complejas
Example – filtro user
Encuentre todos los registros de seguimiento con ID de usuario.
user CONTAINS ""
Example – Seleccione los registros de seguimiento con una causa raíz de error que incluyan elservicio denominado "Auth"
rootcause.fault.service { name = "Auth" }
Example – Seleccione los registros de seguimiento con una causa raíz de tiempo de respuestacuyo ú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 últimaexcepción tenga el mensaje "access denied for account_id: 1234567890"
rootcause.fault.exception { last and message = "Access Denied for account_id: 1234567890"
Palabras clave complejasUtilice palabras clave complejas para buscar solicitudes basadas en nombre del servicio, nombre de bordeo valor de anotación. Para servicios y límites, puede especificar una expresión de filtro adicional que seaplica al servicio o al límite. Para anotaciones, puede filtrar por el valor de una anotación con una claveespecífica, utilizando operadores booleanos, numéricos o de cadena.
Palabras clave complejas
• annotation.key – Valor de una anotación con el campo key. El valor de una anotación puede serun valor booleano, numérico o de cadena, por lo que puede utilizar cualquiera de los operadores decomparación de esos tipos. No se puede utilizar esta palabra clave en combinación con la palabra claveservice o edge.
• 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 estaconexión.
• group.name / group.arn – El valor de la expresión de filtro de un grupo, al que se hace referenciapor nombre de grupo o ARN de grupo.
• json – objeto de causa raíz JSON. Consulte Obtener datos de AWS X-Ray (p. 106) para ver los pasospara crear entidades JSON mediante programación.
• service(name) {filter} – Servicio con nombre name. Las llaves opcionales pueden contener unaexpresión de filtro que se aplica a los segmentos creados por el servicio.
Utilice la palabra clave service para encontrar los registros de seguimiento de las solicitudes que seencuentran en un nodo determinado de su mapa de servicios.
Los operadores de palabras clave complejos encuentran segmentos en los que se ha establecido o no seha establecido la clave especificada.
Operadores de palabras clave complejos
• – none: la expresión es verdadera si se establece la palabra clave. Si la palabra clave es de tipobooleano, se evaluará en el valor booleano.
69
AWS X-Ray Guía para desarrolladoresPalabras clave complejas
• ! – La expresión es verdadera si no se establece la palabra clave. Si la palabra clave es de tipobooleano, se evaluará en el 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 estaconexión.
• annotation.key – Valor de una anotación con el campo key. El valor de una anotación puede serun valor booleano, numérico o de cadena, por lo que puede utilizar cualquiera de los operadores decomparación de esos tipos. No se puede utilizar esta palabra clave en combinación con la palabra claveservice o edge.
• json – objeto de causa raíz JSON. Consulte Obtener datos de AWS X-Ray (p. 106) para ver los pasospara crear entidades JSON mediante programación.
Utilice la palabra clave service para encontrar los registros de seguimiento de las solicitudes que seencuentran en un nodo determinado de su mapa de servicios.
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 deservicios.
Example – filtro service
Solicitudes que provocan un error en cualquier ubicación de su mapa de servicios.
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 queresultó 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 unlí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 serviciodenominado api.example.com.
http.url BEGINSWITH "http://api.example.com/" AND http.url CONTAINS "/v2/" AND !service("api.example.com")
Example – Filtro de tiempo de respuesta y servicio de
Busque los registros de seguimiento en los que http url esté establecido y en los que el tiempo derespuesta sea superior a 2 segundos.
70
AWS X-Ray Guía para desarrolladoresid Función
http.url AND responseTime > 2
Para anotaciones, puede llamar a todos los registros de seguimiento donde annotation.key se hayaestablecido 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 – Se establece la anotación
Solicitudes con una anotación denominada age set.
annotation.age
Example – La anotación no está establecida
Solicitudes sin una anotación denominada age set.
!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 – Grupo de con usuario de
Las solicitudes en las que los rastros cumplen el filtro de high_response_time grupo (por ejemplo,responseTime > 3) y el usuario se denomina 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" } ] } ] }]
id FunciónCuando se proporciona un nombre de servicio a las palabras clave service o edge, se obtienenresultados de todos los nodos que tienen ese nombre. Si desea filtrar de manera más precisa, puedeutilizar la función id para especificar un tipo de servicio, además de un nombre, para diferenciar los nodoscon el mismo nombre.
id(name: "service-name", type:"service::type")
71
AWS X-Ray Guía para desarrolladoresid Función
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, la aplicación de ejemplo Scorekeep (p. 137) incluye una función de AWS Lambdadenominada random-name. Esta función crea dos nodos en el mapa de servicios, uno para invocar a lafunción y otro para el servicio de Lambda.
Los dos nodos tienen el mismo nombre pero son de diferente tipo. Un filtro service estándar permiteencontrar 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 delservicio.
Example – filtro service con la función id
Solicitudes que incluyen un error en un servicio denominado random-name de tipoAWS::Lambda::Function.
72
AWS X-Ray Guía para desarrolladoresVinculación en profundidad
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
Solicitudes que incluyen un error en un servicio de tipo AWS::Lambda::Function.
service(id(type: "AWS::Lambda::Function")) { error }
Vinculación en profundidadPuede usar rutas y consultas para establecer un vínculo en profundidad en rastros específicos, o bien usarvistas filtradas y el mapa de servicio.
Páginas de la consola
• Página principal: xray/home#/welcome• Introducción: xray/home#/getting-started• Mapa de servicios: xray/home#/service-map• Rastros: xray/home#/traces
RastrosPuede generar enlaces a las vistas de escala de tiempo, sin procesar y mapa de los rastros individuales.
Rastro de línea de tiempo: xray/home#/traces/trace-id
Datos de rastreo sin procesar: xray/home#/traces/trace-id/raw
Example – Datos de rastreo sin procesar
https://console.aws.amazon.com/xray/home#/traces/1-57f5498f-d91047849216d0f2ea3b6442/raw
Expresiones de filtroEnlazan 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
73
AWS X-Ray Guía para desarrolladoresIntervalo de tiempo
Para obtener más información sobre las expresiones de filtro, consulte Uso de expresiones de filtro parabuscar registros de seguimiento en la consola (p. 64).
Intervalo de tiempoEspecifique un intervalo de tiempo o una hora de inicio y una hora de finalización en formato ISO8601. Losrangos de tiempo se indican en UTC y su duración máxima es de 6 hours.
Intervalo tiempo: xray/home#/page?timeRange=range-in-minutes
Example – Mapa de servicio de la última hora
https://console.aws.amazon.com/xray/home#/service-map?timeRange=PT1H
Hora de inicio y hora de 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=2018-9-01T16:00:00~2018-9-01T22:00:00
Example – Intervalo de tiempo con una precisión de minutos
https://console.aws.amazon.com/xray/home#/traces?timeRange=2018-9-01T16:00~2018-9-01T22:00
RegiónEspecifique una región de AWS a la que enlazar las páginas en esa región. De lo contrario, la consola leredirige a la última región que ha visitado.
Región: xray/home?region=region#/page
Example – Mapa de servicios en EE. UU. Oeste (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 hash ylas consultas específicas de X-Ray van después del nombre de página.
Example – Mapa de servicios de última hora en EE. UU. Oeste (Oregón) (us-west-2)
https://console.aws.amazon.com/xray/home?region=us-west-2#/service-map?timeRange=PT1H
En combinaciónExample – Registros de seguimiento recientes con 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
74
AWS X-Ray Guía para desarrolladoresHistogramas
Salida
• Página: Rastros• Intervalo de tiempo: Últimos 15 minutos• Filtro: duración>= 5 Y duración <= 8
Usar histogramas de latencia en la consola de X-Ray
Al seleccionar un nodo o un límite en un mapa de servicios (p. 51) de AWS X-Ray, la consola de X-Raymuestra un histograma de distribución de latencias.
LatenciaLa latencia es el tiempo que transcurre entre el momento de iniciar una solicitud y el momento decompletarla. Los histogramas muestran una distribución de las latencias. Muestran la duración en el eje x yel 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ástiempo.
Interpretación de los detalles del servicioLos histogramas de servicio y los histogramas de límites constituyen una representación visual de latenciadesde 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 queatiende el servicio. Las latencias son las que registra el servicio y no incluyen ninguna latencia de redentre el servicio y el solicitante.
• Elija un límite haciendo clic en la línea o en la punta de flecha del límite entre dos servicios. X-Raymuestra un histograma de las solicitudes del solicitante atendidas por el servicio posterior. Las latenciasson las que ha registrado el solicitante e incluyen la latencia de la conexión de red entre los dosservicios.
Para interpretar el panel de histograma Service details, puede buscar los valores que más difieran de lamayoría de valores del histograma. Estos valores atípicos pueden aparecer como picos o puntas en elhistograma 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 deseeiniciar la selección y arrastre de izquierda a derecha para resaltar el intervalo de latencias que quiera incluiren el filtro de rastros.
75
AWS X-Ray Guía para desarrolladoresMuestreo
Una vez seleccionado el intervalo, puede elegir Zoom (Zoom) para ver solo esa parte del histograma yretocar la selección.
Una vez establecido el enfoque en el área que desea, elija View traces (Ver rastros).
Configuración de reglas de muestreo en la consolade X-Ray
Puede utilizar la consola de AWS X-Ray para configurar reglas de muestreo para sus servicios. El SDK deX-Ray y los servicios de AWS que admiten el rastreo activo (p. 6) con la configuración de muestreo utilizanreglas de muestreo para determinar las solicitudes que se van a registrar.
Temas
76
AWS X-Ray Guía para desarrolladoresConfiguración de reglas de muestreo
• Configuración de reglas de muestreo (p. 77)• Personalización de reglas de muestreo (p. 77)• Opciones de reglas de muestreo (p. 78)• Ejemplos de reglas de muestreo (p. 79)• Configuración del servicio para utilizar reglas de muestreo (p. 79)• Visualización de resultados de muestreo (p. 80)• Pasos siguientes (p. 80)
Configuración de reglas de muestreoPuede configurar el muestreo para los siguientes casos de uso:
• API Gateway El punto de entrada – API Gateway admite el muestreo y el rastreo activo. Para habilitarel rastreo activo en una etapa de la API, consulte Amazon API Gateway Compatibilidad de seguimientoactivo de para AWS X-Ray (p. 188).
• AWS AppSync – AWS AppSync admite el muestreo y el rastreo activo. Para habilitar el rastreo activo enAWS AppSync las solicitudes, consulte Rastreo con AWS X-Ray.
• Instrument X-Ray SDK on compute – platforms: cuando se utilizan plataformas de computación comoAmazon EC2 Amazon ECS, o AWS Elastic Beanstalk, se admite el muestreo cuando la aplicación se hainstrumentado con el X-Ray último SDK.
Personalización de reglas de muestreoAl personalizar las reglas de muestreo, puede controlar la cantidad de datos que va a registrar y modificarel comportamiento de muestreo sobre la marcha sin modificar o volver a implementar su código. Las reglasde muestreo indican al SDK de X-Ray cuántas solicitudes se van a registrar para un conjunto de criterios.De forma predeterminada, el SDK de X-Ray registra la primera solicitud de cada segundo y un cinco porciento de todas las solicitudes adicionales. Una petición por segundo es el depósito. Esto garantiza quese registre al menos un registro de seguimiento cada segundo mientras el servicio atienda solicitudes. Elcinco por ciento es el porcentaje al que se muestrean las solicitudes adicionales más allá del tamaño deldepósito.
Puede configurar el SDK de X-Ray para leer reglas de muestreo desde un documento JSON que incluyacon su código. Sin embargo, cuando ejecute varias instancias de su servicio, cada instancia realizael muestreo de manera independiente. Esto hace que el porcentaje total de solicitudes muestreadasaumente, ya que los depósitos de todas las instancias se suman de forma efectiva. Además, paraactualizar 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 (p. 79) para leer reglasdesde el servicio de X-Ray, puede evitar ambos problemas. El servicio administra el depósito de cada reglay asigna cuotas a cada instancia de su servicio para distribuir el depósito de manera uniforme, en funcióndel número de instancias que se ejecuten. El límite del depósito se calcula de acuerdo con las reglas quehaya establecido. Y, dado que las reglas están configuradas en el servicio, puede administrar las reglas sinrealizar implementaciones adicionales.
Para configurar las reglas de muestreo en la consola de X-Ray
1. Abra la consola de X-Ray.2. Seleccione Sampling (Muestreo).3. Para crear una regla, elija Create sampling rule (Crear regla de muestreo).
Para editar una regla, elija el nombre de una regla.
77
AWS X-Ray Guía para desarrolladoresOpciones de reglas de muestreo
Para eliminar una regla, elija una regla y utilice el menú Actions (Acciones) para eliminarla.
Opciones de reglas de muestreoLas siguientes opciones están disponibles para cada regla. En los valores de cadena se pueden usarcaracteres comodín para buscar coincidencias de un solo carácter (?) o cero o más caracteres (*).
Opciones de reglas de muestreo
• Rule name (Nombre de regla) (cadena) un nombre – único para la regla.• Priority (Prioridad) (entero comprendido entre 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 laprimera regla coincidente.
• Reservoir (Depósito) (entero no negativo): número – fijo de solicitudes coincidentes que se van ainstrumentar por segundo, antes de aplicar el porcentaje fijo. Los servicios no utilizan directamente eldepósito, sino que se aplica a todos los servicios que usan la regla en su conjunto.
• Rate (Porcentaje) (número entre 0 y 100) – El porcentaje de solicitudes coincidentes que se van ainstrumentar, después de que se agote el depósito. El porcentaje puede ser un valor entero o de tipofloat.
• Service name (Nombre de servicio) (cadena) – el nombre del servicio instrumentado, tal como apareceen el mapa de servicio.• X-Ray – SDK: el nombre del servicio que configura en la grabadora.• Amazon API Gateway – api-name/stage.
• Service type (Tipo de servicio) (cadena): tipo de – servicio tal y como aparece en el mapa de servicio.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 Amazon EC2 instancia (complemento).• AWS::ECS::Container – Un Amazon ECS contenedor de (complemento).• AWS::APIGateway::Stage – Una Amazon API Gateway etapa de .• AWS::AppSync::GraphQLAPI – Una solicitud AWS AppSync de API.
• Host (Host) (cadena): el nombre de – host del encabezado de host HTTP.• HTTP method (Método HTTP) (cadena): – método de la solicitud HTTP.• URL path (Ruta URL) (cadena) – la ruta URL de la solicitud.
• X-Ray – SDK: la parte de la ruta de la URL de la solicitud HTTP.• Amazon API Gateway – No se admite.
• Resource ARN (ARN de recurso) (cadena) el – ARN del AWS recurso que ejecuta el servicio.• X-Ray SDK – de : no compatible. El SDK solo puede utilizar reglas con Resource ARN (ARN de
recurso) configurado en *.• Amazon API Gateway – El ARN de la etapa.
• (Opcional) Atributos (clave y valor) Atributos de – segmento que se conocen cuando se toma la decisiónde muestreo.• X-Ray SDK – de : no compatible. El SDK omite las reglas que especifican atributos.• Amazon API Gateway – Encabezados de la solicitud HTTP original.
78
AWS X-Ray Guía para desarrolladoresEjemplos de reglas de muestreo
Ejemplos de reglas de muestreoExample – 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 aplicaa las solicitudes que no coinciden con cualquier otra regla.
• Reservoir (Depósito) – 0• Tasa – 0.005 (0,5 por ciento)
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• Priority (Prioridad – 1• Reservoir (Depósito) – 1• Rate (Tasa) – 1• Nombre del servicio – Scorekeep• Service type (Tipo de servicio – *• Host (Host) – *• HTTP method (Método HTTP – PUT• Ruta de la URL – /history/*• ARN de recurso – *
Example – Porcentaje mínimo superior para POST
• Nombre de la regla – POST minimum• Priority (Prioridad – 100• Reservoir (Depósito) – 10• Rate (Tasa) – 0.10• Nombre del servicio – *• Service type (Tipo de servicio – *• Anfitrión – *• HTTP method (Método HTTP – POST• Ruta de la URL – *• ARN de recurso – *
Configuración del servicio para utilizar reglas demuestreoEl SDK de X-Ray requiere configuración adicional para utilizar reglas de muestreo que configura en laconsola. Consulte el tema de configuración para su lenguaje para obtener más información sobre cómoconfigurar una estrategia de muestreo.
• Java: – Reglas de muestreo (p. 244)
79
AWS X-Ray Guía para desarrolladoresVisualización de resultados de muestreo
• Go – Reglas de muestreo (p. 221)• Node.js – Reglas de muestreo (p. 273)• Python – Reglas de muestreo (p. 291)• Ruby – Reglas de muestreo (p. 315)• .NET – Reglas de muestreo (p. 330)
Para API Gateway, consulte Amazon API Gateway Compatibilidad de seguimiento activo de para AWS X-Ray (p. 188).
Visualización de resultados de muestreoLa página X-RayMuestreo de la consola muestra información detallada sobre cómo utilizan los servicioscada regla de muestreo.
La columna Trend (Tendencia) muestra cómo se ha utilizado la regla en los últimos minutos. Cadacolumna muestra las estadísticas para una ventana de 10 segundos.
Estadísticas de muestreo
• Total matched – rule: el número de solicitudes que coincide con esta regla. Este número no incluyesolicitudes que podrían haber coincidido con esta regla, pero coincidieron primero con una regla deprioridad más alta.
• Total – sampled: el número de solicitudes registradas.• Sampled with fixed – rate: el número de solicitudes muestreadas aplicando el porcentaje fijo de la regla.• Sampled with reservoir – limit: el número de solicitudes muestreadas mediante una cuota asignada por
X-Ray.• Borrowed from – reservoir: el número de solicitudes muestreadas tomando prestadas del depósito. La
primera vez que un servicio hace coincidir una solicitud con una regla, aún no le ha asignado una cuot X-Ray. Sin embargo, si el depósito es al menos 1, el servicio toma prestado un rastreo por segundo hastaque 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 lasreglas de muestreo los servicios, consulte Uso de reglas de muestreo con la API de X-Ray (p. 121).
Pasos siguientesPuede usar la API de X-Ray para administrar reglas de muestreo. Con la API, puede crear y actualizar lasreglas mediante programación de forma programada o en respuesta a alarmas o notificaciones. ConsulteConfiguring Configuración de muestreo, grupos y cifrado de con la AWS X-Ray API de (p. 116) paraobtener instrucciones y ejemplos de reglas adicionales.
El SDK de X-Ray y los servicios de AWS también utilizan la API de X-Ray para leer reglas de muestreo,notificar resultados de muestreo y obtener objetivos de muestreo. Los servicios deben realizar unseguimiento de la frecuencia con la que se aplica cada regla, evaluar las reglas en función de la prioridad ytomar prestado del depósito cuando una solicitud coincide con una regla para la que X-Ray no ha asignadoaún una cuota al servicio. Para obtener más información acerca de cómo utiliza un servicio la API paramuestreo, consulte Uso de reglas de muestreo con la API de X-Ray (p. 121).
Cuando el SDK de X-Ray llama a las API de muestreo, utiliza el demonio de X-Ray como proxy. Si yautiliza el puerto de TCP 2000, puede configurar el demonio para ejecutar el proxy en un puerto diferente.Para obtener más información, consulte Configuración del demonio de AWS X-Ray (p. 174).
80
AWS X-Ray Guía para desarrolladoresInsights
Uso de conocimientos en la AWS X-Ray consola deAWS X-Ray analiza continuamente los datos de rastreo de su cuenta para identificar problemasemergentes en sus aplicaciones. Cuando las tasas de errores superan el rango esperado, crea unconocimiento que registra el incidente y realiza un seguimiento de su impacto hasta que se resuelve.Puede utilizar conocimientos de para identificar el impacto del usuario para problemas en curso o paraanalizar problemas transitorios que se produjeron en el pasado.
La X-Ray consola también identifica nodos con incidentes continuos en el mapa de servicio. Para ver unresumen de la información, elija el nodo afectado.
X-Ray crea un conocimiento cuando detecta una anomalía en uno o varios nodos del mapa de servicio. Elservicio utiliza el modelado estadístico para predecir las tasas de errores previstas de los servicios de ensu aplicación. En el ejemplo anterior, la anomalía es un aumento de los errores de AWS Elastic Beanstalk.El Elastic Beanstalk servidor ha experimentado varios tiempos de espera de llamadas a la API, provocandouna anomalía en los nodos posteriores.
Habilitar la información en la X-Ray consola deLa información debe estar habilitada para cada grupo con el que desee utilizar características deinformación. Puede habilitar la información desde la página Groups (Grupos)
1. Abra la consola de X-Ray.2. Seleccionar un grupo existente o crear uno nuevo eligiendo Create groupy, a continuación, seleccione
Enable Insights. Para obtener más información acerca de la configuración de grupos en la X-Rayconsola de , consulte Configuración de grupos de en la consola X-Ray de (p. 92).
3. En el panel de navegación de la izquierda, elija Insights y, a continuación, elija la información quedesea ver.
81
AWS X-Ray Guía para desarrolladoresHabilitar notificaciones de conocimientos
Note
X-Ray utiliza las APIs GetInsightSummaries, GetInsight, GetInsightEvents yGetInsightImpactGraph para recuperar datos de conocimientos de . Para ver información,utilice la política administrada de IAM AWSXrayReadOnlyAccess o añada la siguiente políticapersonalizada a su rol de IAM:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "xray:GetInsightSummaries", "xray:GetInsight", "xray:GetInsightEvents", "xray:GetInsightImpactGraph" ], "Resource": [ "*" ] } ] }
Para obtener más información, consulte Cómo funciona AWS X-Ray con IAM (p. 35).
Habilitar notificaciones de conocimientosCon las notificaciones de conocimientos, se crea una notificación para cada evento de conocimiento,como, por ejemplo, cuando se crea un conocimiento, cambia significativamente o se cierra. Los clientespueden recibir estas notificaciones a través de Amazon EventBridge eventos de y utilizar reglascondicionales para realizar acciones como notificaciones de SNS, invocación de Lambda, publicación demensajes en una cola de SQS o cualquiera de los destinos EventBridge que admite . Las notificacionesde Insights se emiten en la medida de lo posible, pero no se garantizan. Para obtener más informaciónacerca de los destinos, consulte Destinos de https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-targets.htmlAmazon EventBridge.
Puede habilitar las notificaciones de conocimientos para cualquier grupo de conocimientos habilitadodesde la página Groups (Grupos).
Para habilitar las notificaciones para un X-Ray grupo de
1. Abra la consola de X-Ray.2. Seleccionar un grupo existente o crear uno nuevo eligiendo Create group, asegúrese de que Enable
Insights (Habilitar Insights) esté seleccionado y, a continuación, seleccione Enable Notifications(Habilitar notificaciones). Para obtener más información acerca de la configuración de grupos en la X-Ray consola de , consulte Configuración de grupos de en la consola X-Ray de (p. 92).
Para configurar reglas Amazon EventBridge condicionales
1. Abra la consola de Amazon EventBridge.2. Vaya a Rules en la barra de navegación izquierda y elija Create rule.3. Proporcione un nombre y una descripción para la regla.
82
AWS X-Ray Guía para desarrolladoresInformación general de Insight
4. Elija Event patterny, a continuación, elija Custom pattern. Proporcione un patrón que contenga"source": [ "aws.xray" ] y "detail-type": [ "AWS X-Ray Insight Update" ]. Acontinuación se muestran algunos ejemplos de posibles patrones.• Patrón de eventos para que coincida con todos los eventos entrantes de X-Ray la información de :
{"source": [ "aws.xray" ],"detail-type": [ "AWS X-Ray Insight Update" ]}
• Patrón de eventos para que coincida con un state y un categoryespecificados:
{"source": [ "aws.xray" ],"detail-type": [ "AWS X-Ray Insight Update" ],"detail": { "State": [ "ACTIVE" ], "Category": [ "FAULT" ] }}
5. Seleccione y configure los destinos que desea invocar cuando un evento coincida con esta regla.6. (Opcional) Proporcione etiquetas para identificar y seleccionar más fácilmente esta regla.7. Elija Create.
Note
X-Ray Las notificaciones de conocimientos de envían eventos a Amazon EventBridge, queactualmente no admite CMKs administradas por el cliente. Para obtener más información,consulte Protección de datos en AWS X-Ray (p. 29).
Información general de InsightLa página de información general de un conocimiento intenta responder a tres preguntas clave:
• ¿Cuál es el problema subyacente?• ¿Cuál es la causa raíz?• ¿Cuál es el impacto en el cliente?
La sección Servicios anómalos muestra una línea temporal para cada servicio que ilustra el cambio enlas tasas de errores durante el incidente. La escala de tiempo muestra el número de rastros con erroressuperpuestos en una banda sólida que indica el número esperado de errores en función de la cantidad detráfico registrado. La duración del conocimiento se visualiza en la ventana Incident (Incidente). La ventanadel incidente comienza cuando X-Ray observa que la métrica se vuelve anómala y persiste mientras lainformación está activa.
En el siguiente ejemplo se muestra un aumento de errores que han provocado un incidente:
83
AWS X-Ray Guía para desarrolladoresInformación general de Insight
La sección Root cause (Causa raíz) muestra un mapa de servicio centrado en el servicio de causa raíz yla ruta afectada. Puede ocultar los nodos no afectados seleccionando el icono de ojo en la parte superiorderecha del Root cause map (Mapa de causa raíz). El servicio de causa raíz es el nodo posterior máslejano en el que X-Ray ha identificado una anomalía. Puede representar un servicio que ha instrumentadoo un servicio externo al que el servicio ha llamado con un cliente instrumentado. Por ejemplo, si llama aAmazon DynamoDB con un cliente AWS del SDK instrumentado, un aumento de errores de DynamoDB dalugar a un conocimiento con DynamoDB como causa raíz.
Para profundizar más en la causa raíz, seleccione View root cause details en el gráfico de causa raíz.Puede utilizar la página Analytics (Análisis) para investigar la causa raíz y los mensajes relacionados. Paraobtener más información, consulte Interacción con la consola de AWS X-Ray Analytics (p. 87).
Los errores que continúan subiendo en el mapa pueden afectar a varios nodos y provocar variasanomalías. Si un error se transfiere de vuelta al usuario que ha realizado la solicitud, el resultado esun error del cliente. Se trata de un error en el nodo raíz del mapa de servicio. El gráfico de impactoproporciona una escala de tiempo de la experiencia del cliente para todo el grupo. Esta experiencia secalcula en función de porcentajes de los siguientes estados: Error, Error, Throttle y Okay.
84
AWS X-Ray Guía para desarrolladoresRevisar el progreso de un conocimiento
Este ejemplo muestra un aumento de registros de seguimiento con un error en el nodo raíz durante elmomento de un incidente. Los incidentes en los servicios posteriores no siempre corresponden a unaumento de los errores del cliente.
Elección de Analyze insight abre la consola de X-Ray Analytics en una ventana donde puede profundizaren el conjunto de rastros que causan la información. Para obtener más información, consulte Interaccióncon la consola de AWS X-Ray Analytics (p. 87).
Revisar el progreso de un conocimientoX-Ray vuelve a evaluar los conocimientos de forma periódica hasta que se resuelven y registra cadacambio intermedio notable como un evento. Puede revisar los eventos de incidentes en la línea temporalde impacto en la página Inspect (Inspeccionar). De forma predeterminada, la escala de tiempo muestra elservicio más afectado hasta que elija un servicio diferente.
Para ver un mapa de servicios y gráficos de un evento, elíjalo en la escala de tiempo de impacto. El mapade servicio muestra los servicios de su aplicación que se ven afectados por el incidente. En Impact analysis(Análisis de impacto), los gráficos muestran líneas temporales de errores para el nodo seleccionado y paralos clientes del grupo.
85
AWS X-Ray Guía para desarrolladoresRevisar el progreso de un conocimiento
Para examinar en mayor profundidad los rastros implicados en un incidente, elija Analyze event (Analizarevento) en la página Inspect (Inspeccionar). Puede utilizar la página Analytics (Análisis) para refinar la listade rastros e identificar a los usuarios afectados. Para obtener más información, consulte Interacción con laconsola de AWS X-Ray Analytics (p. 87).
86
AWS X-Ray Guía para desarrolladoresAnalytics
Interacción con la consola de AWS X-Ray AnalyticsLa consola de AWS X-Ray Analytics es una herramienta interactiva para interpretar rápidamente los datosde rastreo con el fin de conocer el rendimiento de la aplicación y sus servicios subyacentes. La consolale permite explorar, analizar y visualizar los registros de seguimiento a través de gráficos de tiempo derespuesta y series temporales.
Al realizar selecciones en la consola de Analytics, la consola crea filtros para reflejar el subconjuntoseleccionado de registros de seguimiento. Puede acotar el conjunto de datos con filtros cada vez másdetallados haciendo clic en los gráficos y los paneles de métricas y campos asociados al conjunto deregistros de seguimiento actual.
Temas• Características de la consola (p. 87)• Distribución del tiempo de respuesta (p. 89)• Actividad de series temporales (p. 90)• Ejemplos de flujo de trabajo (p. 90)• Observar errores en el gráfico de servicio (p. 90)• Identificar los picos de tiempo de respuesta (p. 91)• Consultar todos los registros de seguimiento marcados con un código de estado (p. 91)• Consultar todos los elementos de un subgrupo y asociados a un usuario (p. 92)• Comparar dos conjuntos de registros de seguimiento con criterios diferentes (p. 92)• Identificar un registro de seguimiento de su interés y ver sus detalles (p. 92)
Características de la consolaLa consola de X-Ray Analytics utiliza las siguientes características principales para agrupar, filtrar,comparar y cuantificar los datos de rastreo.
Características
Característica Descripción
Grupos El grupo seleccionado inicial es Default. Paracambiar el grupo recuperado, seleccione ungrupo diferente en el menú que se encuentraa la derecha de la barra de búsqueda principalde expresiones de filtro. Para obtener másinformación sobre los grupos, consulte Uso deexpresiones de filtro con grupos.
Retrieved traces (Registros de seguimientorecuperados)
De forma predeterminada, la consola de Analyticsgenera gráficos basados en todos los registrosde seguimiento del grupo seleccionado. Losregistros de seguimiento recuperados representantodos los registros de seguimiento del conjuntode trabajo. Puede ver el número de registrosde seguimiento en este icono. Las expresionesde filtro que se aplican a la barra de búsquedaprincipal acotan y actualizan los registros deseguimiento recuperados.
87
AWS X-Ray Guía para desarrolladoresCaracterísticas de la consola
Característica Descripción
Show in charts/Hide from charts (Mostrar y ocultarde gráficos)
Un control de alternancia para comparar elgrupo activo con los registros de seguimientorecuperados. Para comparar los datos relativos algrupo con los filtros activos, elija Show in charts(Mostrar en gráficos). Para eliminar esta vista delos gráficos, elija Hide from charts (Ocultar degráficos).
Filtered trace set A (Conjunto de registros deseguimiento filtrados A)
Mediante las interacciones con los gráficos ylas tablas, aplique filtros para crear los criteriospara Filtered trace set A (Conjunto de registrosde seguimiento A filtrados). Cuando se aplicanlos filtros, se calcula el número de registros deseguimiento aplicables y el porcentaje de registrosde seguimiento del total recuperado dentro de esteicono. Los filtros se rellenan como etiquetas dentrodel icono Filtered trace set A (Conjunto de registrosde seguimiento A filtrados) y también se puedeneliminar del icono.
Refine (Acotar) Esta función actualiza el conjunto de registrosde seguimiento recuperados en función delos filtros aplicados al conjunto de registros deseguimiento A. Al reajustar el conjunto de registrosde seguimiento recuperado se actualiza el conjuntode trabajo de todos los registros de seguimientorecuperados en función de los filtros del conjuntode registros de seguimiento A. El conjunto detrabajo de registros de seguimiento recuperados esun subconjunto muestreado de todos los registrosde seguimiento del grupo.
Filtered trace set B (Conjunto de registros deseguimiento filtrados B)
Cuando se crea Filtered trace set B (Conjunto deregistros de seguimiento B filtrados) es un copiade Filtered trace set A (Conjunto de registros deseguimiento A filtrados). Para comparar los dosconjuntos de registros de seguimiento, seleccionenuevas opciones de filtro que se apliquen alconjunto de registros de seguimiento A, mientras elconjunto de registros de seguimiento A permanecefijo. Cuando se aplican los filtros, se calcula elnúmero de registros de seguimiento aplicables yel porcentaje de registros de seguimiento del totalrecuperado en este icono. Los filtros se rellenancomo etiquetas dentro del icono Filtered trace set B(Conjunto de registros de seguimiento B) y tambiénse pueden eliminar del icono.
88
AWS X-Ray Guía para desarrolladoresDistribución del tiempo de respuesta
Característica Descripción
Response Time Root Cause Entity Paths (Rutas deentidad de causa raíz de tiempo de respuesta)
Una tabla de rutas de entidad registradas. X-Raydetermina qué ruta del registro de seguimiento esla causa más probable del tiempo de respuesta.El formato indica una jerarquía de entidadesdetectadas, que termina en una causa raíz detiempo de respuesta. Utilice estas filas para filtrarerrores de tiempo de respuesta recurrentes. Paraobtener más información sobre cómo personalizarun filtro de causa raíz y obtener los datos a travésde la API, consulte Recuperación y reajuste deanálisis de causa raíz.
Delta (�) Una columna que se agrega a las tablas demétricas cuando los conjuntos de registros deseguimiento A y B están activos. La columna Deltacalcula la diferencia porcentual de los registrosde seguimiento entre el conjunto de registrosde seguimiento A y el conjunto de registros deseguimiento B.
Distribución del tiempo de respuestaLa consola de X-Ray Analytics genera dos gráficos principales que le ayudan a visualizar los registrosde seguimiento: Response Time Distribution (Distribución del tiempo de respuesta) y Time Series Activity(Actividad de series temporales). En esta sección y las siguientes se proporcionan ejemplos de cada uno yse 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 deseries temporales utiliza la misma combinación de colores):
• All traces in the group (Todos los registros de seguimiento del grupo): gris• Retrieved traces (Registros de seguimiento recuperados): naranja• Filtered trace set A (Conjunto de registros de seguimiento filtrados A): verde• Filtered trace set B (Conjunto de registros de seguimiento 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 seguimientocon un tiempo de respuesta determinado. Haga clic y arrastre para realizar selecciones en la distribucióndel tiempo de respuesta. De esta forma, se selecciona y se crea un filtro del conjunto de registros deseguimiento de trabajo llamado responseTime para todos los registros de seguimiento de un tiempo derespuesta específico.
89
AWS X-Ray Guía para desarrolladoresActividad de series temporales
Actividad de series temporalesEl gráfico de actividad de series temporales muestra el número de registros de seguimiento en un periodode tiempo determinado. Los indicadores de color reflejan los colores del gráfico de líneas de la distribucióndel tiempo de respuesta. Cuanto más oscuro y opaco es el bloque de color de las series de actividad, másregistros 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 estaforma, se selecciona y se crea un filtro llamado timerange en el conjunto de registros de seguimiento detrabajo para todos los registros de seguimiento en un periodo de tiempo específico.
Ejemplos de flujo de trabajoLos siguientes ejemplos muestran casos de uso comunes de la consola de X-Ray Analytics. Cada ejemplomuestra una función clave de la experiencia de la consola. En su conjunto, los ejemplos siguen un flujode trabajo de solución de problemas básico. Los pasos describen cómo detectar primero los nodos enmal estado y, a continuación, cómo interactuar con la consola de Analytics para generar automáticamenteconsultas comparativas. Una vez que haya reducido el alcance a través de las consultas, verá los detallesde los registros de seguimiento de interés para determinar qué está dañando el estado del servicio.
Observar errores en el gráfico de servicioEl mapa de servicio indica el estado de cada nodo coloreándolo en función de la proporción entre lasllamadas correctas y los errores. Cuando vea un porcentaje en rojo en el nodo, eso indica un error. Utilicela consola de X-Ray Analytics para investigar el problema.
Para obtener más información acerca de cómo leer el mapa de servicio, consulte Consulta del mapa deservicio.
90
AWS X-Ray Guía para desarrolladoresIdentificar los picos de tiempo de respuesta
Identificar los picos de tiempo de respuestaMediante la distribución del tiempo de respuesta, puede observar los picos de tiempo de respuesta. Alseleccionar el pico en el tiempo de respuesta, las tablas que se encuentran debajo de los gráficos seactualizará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 delas líneas gráficas. Ahora puede arrastrar ese elemento resaltado a la izquierda o a la derecha por ladistribución para actualizar su selección y filtro.
Consultar todos los registros de seguimientomarcados con un código de estadoPuede analizar los registros de seguimiento dentro del pico seleccionado mediante las tablas de métricasque 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 losregistros de seguimiento de código de estado 500. Esto crea una etiqueta de filtro en el icono del conjuntode registros de seguimiento llamado http.status.
91
AWS X-Ray Guía para desarrolladoresConsultar todos los elementos de unsubgrupo y asociados a un usuario
Consultar todos los elementos de un subgrupo yasociados a un usuarioExamine el conjunto de errores en función del usuario, URL, causa raíz del tiempo de respuesta u otrosatributos predefinidos. Por ejemplo, para filtrar más el conjunto de registros de seguimiento con un códigode estado 500, seleccione una fila de la tabla USERS. Se obtienen dos etiquetas de filtro en el icono delconjunto de registros de seguimiento: http.status, tal y como se designó anteriormente, y user.
Comparar dos conjuntos de registros de seguimientocon criterios diferentesCompare 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 tiempode respuesta. A continuación, seleccione Compare (Comparar). Inicialmente, esto crea una copia de losfiltros del conjunto de registros de seguimiento A.
Para continuar, defina un nuevo conjunto de filtros que se aplique al conjunto de registros de seguimientoB. Este segundo conjunto se representa mediante una línea verde. En el siguiente ejemplo se muestrandiferentes líneas en función de la combinación de colores azul y verde.
Identificar un registro de seguimiento de su interés yver sus detallesCuando reduzca el alcance mediante los filtros de la consola, la lista de registros de seguimiento dedebajo de las tablas de métricas le resultará más útil. La tabla de lista de registros de seguimiento combinainformació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 registrode seguimiento y ver su escala de tiempo y sus datos sin procesar.
Configuración de grupos de en la consola X-Ray deLos grupos son una colección de registros de seguimiento que se definen mediante una expresión de filtro.Puede utilizar grupos para generar gráficos de servicios adicionales y suministrar métricas de AmazonCloudWatch Puede utilizar la AWS X-Ray consola de o la X-Ray API para crear y administrar grupospara sus servicios. En este tema se describe cómo crear y administrar grupos de mediante la X-Rayconsola de . Para obtener información sobre cómo administrar grupos mediante la X-Ray API de , consulteGroups (p. 120).
92
AWS X-Ray Guía para desarrolladoresCrear un grupo en la X-Ray consola de
Puede crear grupos de rastros para mapas de servicio, rastros o análisis. Al crear un grupo, el grupo pasaa estar disponible como filtro en el menú desplegable del grupo en las tres páginas: Service map, Traces y Analytics.
Los grupos se identifican por su nombre o un nombre de recurso de Amazon (ARN) y contienen unaexpresión de filtro. El servicio compara los registros de seguimiento de entrada con la expresión y losalmacena en consecuencia. Para obtener más información acerca de cómo crear una expresión de filtro,consulte Uso de expresiones de filtro para buscar registros de seguimiento en la consola (p. 64).
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 quecombina la expresión nueva con la anterior. Para evitar esto, elimine un grupo de actual y cree uno nuevo.
Note
Los grupos se facturan por el número de rastros recuperados que coinciden con la expresión defiltro. Para obtener más información, consulte Precios de AWS X-Ray.
Temas• Crear un grupo en la X-Ray consola de (p. 93)• Aplicar un grupo (p. 94)• Editar un grupo (p. 95)• Clonar un grupo (p. 96)• Eliminar un grupo (p. 97)• Ver métricas de grupo de en Amazon CloudWatch (p. 97)
Crear un grupo en la X-Ray consola de1. Inicie sesión en Consola de administración de AWS y abra la consola de X-Ray en https://
console.aws.amazon.com/xray/home.2. Abra la página Create group (Crear grupo) desde la página Groups (Grupos) en el panel de
navegación izquierdo o desde el menú de grupo en una de las siguientes páginas: Service map (Mapade servicio), Traces (Rastros) y Analytics (Análisis).
3. En la página Create group (Crear grupo), escriba un nombre para el grupo. El nombre de un grupopuede tener un máximo de 32 caracteres y contener caracteres alfanuméricos y guiones. Los nombresde grupo distinguen entre mayúsculas y minúsculas.
4. Escriba una expresión de filtro. Para obtener más información acerca de cómo crear una expresión defiltro, consulte Uso de expresiones de filtro para buscar registros de seguimiento en la consola (p. 64).
93
AWS X-Ray Guía para desarrolladoresAplicar un grupo
En el siguiente ejemplo, el grupo de filtra los registros de seguimiento de errores del servicio deapi.example.com. y solicita al servicio de en el que el tiempo de respuesta fue mayor o igual acinco segundos.
fault = true AND http.url CONTAINS "example/game" AND responsetime >= 5
5. En Insights, habilite o deshabilite el acceso a Insights para el grupo. Para obtener más informaciónacerca de los conocimientos, consulte Uso de conocimientos en la AWS X-Ray consola de (p. 81).
6. En Tags (Etiquetas), escriba una clave de etiqueta y, opcionalmente, un valor de etiqueta. Alañadir una etiqueta, aparece una nueva línea para que introduzca otra. Las claves de las etiquetasdeben ser únicas. Para eliminar una etiqueta, elija X al final de la fila de la etiqueta. Para obtenermás información acerca de las etiquetas de , consulte Etiquetado de reglas y grupos X-Ray demuestreo (p. 346).
7. Elija Create group.
Aplicar un grupo1. Inicie sesión en Consola de administración de AWS y abra la consola de X-Ray en https://
console.aws.amazon.com/xray/home.2. Abra una de las siguientes páginas desde el panel de navegación:
• Mapa de servicios• Rastros• Análisis
3. Haga lo siguiente, en cualquier orden.
a. En el menú del grupo, elija el grupo que ha creado en the section called “Crear un grupo en la X-Ray consola de” (p. 93). Los datos que se muestran en la página cambian para que coincidancon la expresión de filtro establecida en el grupo.
b. También puede elegir el periodo de tiempo para el que desea ver los datos. El valorpredeterminado es Last 5 minutes (Últimos 5 minutos) en la pestaña Relative (Relativo).
94
AWS X-Ray Guía para desarrolladoresEditar un grupo
Para establecer un intervalo de fecha y hora específico, elija Custom (UTC) (Personalizado(UTC)). Las horas especificadas en esta pestaña están en formato 24-hour. Por ejemplo, 18:00 hes 18:00. El intervalo de tiempo personalizado puede ser de seis horas como máximo.
Editar un grupo1. Inicie sesión en Consola de administración de AWS y abra la consola de X-Ray en https://
console.aws.amazon.com/xray/home.2. Realice una de las siguientes acciones para abrir la página Edit group (Editar grupo).
a. En la página Groups (Grupos), elija el nombre de un grupo para editarlo.
95
AWS X-Ray Guía para desarrolladoresClonar un grupo
b. En el menú del grupo de una de las siguientes páginas, apunte a un grupo y, a continuación, elijaEdit (Editar).
• Mapa de servicios• Rastros• Análisis
3. Aunque no puede cambiar el nombre de un grupo, puede actualizar la expresión de filtro. Para obtenermás información acerca de cómo crear una expresión de filtro, consulte Uso de expresiones de filtropara buscar registros de seguimiento en la consola (p. 64). En el siguiente ejemplo, el grupo de filtralos registros de seguimiento de errores del servicio de api.example.com, donde la dirección URLde la solicitud contiene y example/gameel tiempo de respuesta de las solicitudes fue mayor o igual acinco segundos.
fault = true AND http.url CONTAINS "example/game" AND responsetime >= 5
4. En Insights (Información), habilite o deshabilite las notificaciones de información y de información parael grupo. Para obtener más información acerca de los conocimientos, consulte Uso de conocimientosen la AWS X-Ray consola de (p. 81).
5. En Tags (Etiquetas), edite las claves y los valores de las etiquetas. Las claves de las etiquetas debenser únicas. Los valores de etiqueta son opcionales; puede eliminar valores, si lo desea. Para eliminaruna etiqueta, elija X al final de la fila de la etiqueta. Para obtener más información acerca de lasetiquetas de , consulte Etiquetado de reglas y grupos X-Ray de muestreo (p. 346).
6. Cuando haya terminado de actualizar la expresión de filtro, elija Update group (Actualizar grupo).
Clonar un grupoLa clonación de un grupo crea un nuevo grupo que tiene la expresión de filtro y las etiquetas de un grupoexistente. Al clonar un grupo, el nuevo grupo tiene el mismo nombre que el grupo desde el que se clona,con -clone anexado al nombre.
1. Inicie sesión en Consola de administración de AWS y abra la consola de X-Ray en https://console.aws.amazon.com/xray/home.
2. En la página Groups (Grupos), seleccione un grupo seleccionando su casilla de verificación. Solopuede seleccionar un grupo a la vez.
3. En el menú Actions (Acciones), elija Clone group (Clonar grupo).
96
AWS X-Ray Guía para desarrolladoresEliminar un grupo
4. En la página Create group (Crear grupo), el nombre del grupo es group-name-clone. Si lo desea,escriba un nuevo nombre para el grupo. El nombre de un grupo puede tener un máximo de 32caracteres y contener caracteres alfanuméricos y guiones. Los nombres de grupo distinguen entremayúsculas y minúsculas.
5. Puede mantener la expresión de filtro del grupo existente o, si lo desea, introducir una nuevaexpresió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 para buscar registros de seguimiento en la consola (p. 64).En el siguiente ejemplo, el grupo de filtra los registros de seguimiento de errores del servicioapi.example.com. y solicitan al servicio en el que el tiempo de respuesta fue mayor o igual a cincosegundos.
service("api.example.com") { fault = true OR responsetime >= 5 }
6. En Tags (Etiquetas), edite las claves y los valores de las etiquetas, si es necesario. Las claves delas etiquetas deben ser únicas. Los valores de etiqueta son opcionales; puede eliminar valores si lodesea. Para eliminar una etiqueta, elija X al final de la fila de la etiqueta. Para obtener más informaciónacerca de las etiquetas de , consulte Etiquetado de reglas y grupos X-Ray de muestreo (p. 346).
7. Elija Create group.
Eliminar un grupoSiga los pasos de esta sección para eliminar un grupo en la X-Ray consola de . No se puede eliminar elgrupo Default (Predeterminado).
1. Inicie sesión en Consola de administración de AWS y abra la consola de X-Ray en https://console.aws.amazon.com/xray/home.
2. Para eliminar un grupo de la página Edit group (Editar grupo), haga lo siguiente.
a. En la página Groups (Grupos), elija un nombre de grupo para editarlo.b. Elija Eliminar.c. Cuando se le pida confirmación, elija Delete.
3. Para eliminar un grupo del menú Actions (Acciones), haga lo siguiente.
a. En la página Groups (Grupos), seleccione un grupo seleccionando su casilla de verificación. Solopuede seleccionar un grupo a la vez.
b. En el menú Actions (Acciones), elija Delete group (Eliminar grupo).
c. Cuando se le pida confirmación, elija Delete (Eliminar).
Ver métricas de grupo de en Amazon CloudWatchUna vez creado un grupo, los registros de seguimiento entrantes se comparan con la expresión de filtrodel grupo a medida que se almacenan en el X-Ray servicio . Las métricas para el número de rastros quecoinciden con cada criterio se publican en Amazon CloudWatch cada minuto. Al elegir View metric (Vermétrica) en la página Edit group (Editar grupo) se abre la CloudWatch consola de en la página Metric
97
AWS X-Ray Guía para desarrolladoresVer métricas de grupo de en Amazon CloudWatch
(Métrica). Para obtener más información acerca de cómo utilizar CloudWatch las métricas de , consulteUso de Amazon CloudWatch métricas de en la Amazon CloudWatch Guía del usuario de .
1. Inicie sesión en Consola de administración de AWS y abra la consola de X-Ray en https://console.aws.amazon.com/xray/home.
2. Realice una de las siguientes acciones para abrir la página Edit group (Editar grupo).
a. En la página Groups (Grupos), elija un grupo para editarlo.b. En el menú del grupo de una de las siguientes páginas, apunte a un grupo y, a continuación, elija
Edit (Editar).
• Mapa de servicios• Rastros• Análisis
3. En la página Edit group (Editar grupo), elija View metric (Ver métrica).
Se abre CloudWatch la página Metrics (Métricas) de la consola de en una nueva pestaña.
98
AWS X-Ray Guía para desarrolladoresTutorial
AWS X-RayAPI deLa X-Ray API de proporciona acceso a todas las X-Ray funcionalidades a través del AWS SDK, la AWSCommand Line Interfaceo directamente a través de HTTPS. La Referencia de la X-Ray API de documentalos parámetros de entrada de cada acción de la API, así como los campos y los tipos de datos quedevuelven.
Puede utilizar el AWS SDK para desarrollar programas que utilicen la X-Ray API de . La consola y X-Rayel X-Ray demonio de utilizan el AWS SDK para comunicarse con X-Ray. El AWS SDK para cada lenguajetiene un documento de referencia para clases y métodos que se asignan a acciones y tipos de X-Ray APIde .
AWS Referencias del SDK de
• Java – AWS SDK for Java• JavaScript – AWS SDK for JavaScript• .NET – AWS SDK para .NET• Ruby – AWS SDK parar Ruby• – SDK de GoAWS para Go• PHP – AWS SDK para PHP• Python – AWS SDK for Python (Boto)
es una herramienta AWS Command Line Interface de línea de comandos que utiliza para llamar SDK forPython a APIs de .AWS La primera vez que se aprende una AWS API, la AWS CLI proporciona una formasencilla de explorar los parámetros disponibles y ver la salida del servicio en formato JSON o de texto.
Consulte la Referencia de comandos de la AWS CLI para obtener más información sobre los subcomandosde aws xray.
Temas• Uso de la AWS X-Ray API de con la AWS CLI de (p. 99)• Envío de datos de seguimiento a AWS X-Ray (p. 102)• Obtención de datos de AWS X-Ray (p. 106)• Configuring Configuración de muestreo, grupos y cifrado de con la AWS X-Ray API de (p. 116)• Uso de reglas de muestreo con la API de X-Ray (p. 121)• AWS X-RayDocumentos de segmentos de (p. 123)
Uso de la AWS X-Ray API de con la AWS CLI deLa AWS CLI permite a acceder al X-Ray servicio directamente y utilizar las mismas APIs que utiliza la X-Ray consola para recuperar el gráfico de servicios y los datos de rastreo sin procesar. La aplicación deejemplo incluye scripts que muestran cómo utilizar estas APIs con la AWS CLI de .
PrerequisitesEste tutorial utiliza la aplicación de ejemplo Scorekeep e incluye scripts para generar datos de rastreo y unmapa de servicio. Siga las instrucciones en el tutorial de introducción (p. 8) para iniciar la aplicación.
Este tutorial utiliza la AWS CLI para mostrar el uso básico de la API de X-Ray. La AWS CLI de , disponiblepara Windows, Linux y OS-X, proporciona acceso de línea de comandos a las APIs públicas de todos losAWS servicios de .
99
AWS X-Ray Guía para desarrolladoresGenerar datos de seguimiento
Note
Debe verificar que la AWS CLI esté configurada en la misma región en la que se creó la aplicaciónde ejemplo Scorekeep.
Los scripts incluidos para probar la aplicación de ejemplo utiliza cURL para enviar tráfico a la API y jq paraanalizar la salida. Puede descargar el jq ejecutable de desde stedolan.github.io y el curl ejecutable dedesde https://curl.haxx.se/download.html. La mayoría de las instalaciones en Linux y OS X instalacionesincluyen cURL.
Generar datos de seguimientoLa aplicación web sigue funcionando para generar tráfico a la API cada pocos segundos mientras que lainstalación está en curso, pero solo genera un tipo de solicitud. Utilice el script test-api.sh para ejecutarescenarios 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. Open the Elastic Beanstalk console.2. Navigate to the management console for your environment.3. Copie la URL del entorno del encabezado de la página.4. Abra el script bin/test-api.sh y reemplace el valor de la API con el URL del entorno.
#!/bin/bashAPI=scorekeep.9hbtbm23t2.us-west-2.elasticbeanstalk.com/api
5. Ejecute el script para generar tráfico a la API.
~/debugger-tutorial$ ./bin/test-api.shCreating users,session,game,configuring game,playing game,ending game,game complete.{"id":"MTBP8BAS","session":"HUF6IT64","name":"tic-tac-toe-test","users":["QFF3HBGM","KL6JR98D"],"rules":"102","startTime":1476314241,"endTime":1476314245,"states":["JQVLEOM2","D67QLPIC","VF9BM9NC","OEAA6GK9","2A705O73","1U2LFTLJ","HUKIDD70","BAN1C8FI","G3UDJTUF","AB70HVEV"],"moves":["BS8F8LQ","4MTTSPKP","463OETES","SVEBCL3N","N7CQ1GHP","O84ONEPD","EG4BPROQ","V4BLIDJ3","9RL3NPMV"]}
Uso de la API de X-Ray.La AWS CLI de proporciona comandos para todas las acciones de la API de que X-Ray proporciona,incluidos GetServiceGraph y GetTraceSummaries. Consulte la Referencia de la API de AWS X-Raypara 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{
100
AWS X-Ray Guía para desarrolladoresUso de la API de X-Ray.
"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)
101
AWS X-Ray Guía para desarrolladoresCleanup
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 }...
CleanupFinalice el entorno de Elastic Beanstalk para desactivar las instancias de Amazon EC2, las tablas deDynamoDB y otros recursos.
Para finalizar su entorno de Elastic Beanstalk, haga lo siguiente:
1. Open the Elastic Beanstalk console.2. Navigate to the management console for your environment.3. Elija Actions (Acciones).4. Elija Terminate Environment (Terminar entorno).5. Elija Terminate (Terminar).
Los datos de rastreo se eliminan automáticamente de X-Ray después de 30 days.
Envío de datos de seguimiento a AWS X-RayPuede enviar datos de rastreo a X-Ray en forma de documentos de segmento. Un documento desegmento es una cadena con formato JSON que contiene información sobre el trabajo que su aplicaciónrealiza en respuesta a una solicitud. La aplicación puede registrar en segmentos los datos sobre el trabajo
102
AWS X-Ray Guía para desarrolladoresEnvío de datos
que realiza o bien registrar en subsegmentos los datos sobre el trabajo que utiliza servicios y recursosposteriores.
Los segmentos contienen información sobre el trabajo que realiza su aplicación. Un segmento, comomínimo, registra el tiempo empleado en una tarea, un nombre y dos ID. El ID de rastro permite controlarla 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 secomplete 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 (p. 104) o a través deldemonio de X-Ray (p. 105).
La mayoría de las aplicaciones llaman a otros servicios u obtienen acceso a los recursos con AWS SDK.Registre información acerca de las llamadas posteriores en subsegmentos. X-Ray utiliza subsegmentospara identificar los servicios posteriores que no envían segmentos y crean entradas para segmentos en elgrá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 posteriorespara realizar solicitudes de larga ejecución o para evitar superar el tamaño máximo del documento desegmentos (64 kB).
Example Subsegment
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 ysubsegmentos, consulte AWS X-RayDocumentos de segmentos de (p. 123).
103
AWS X-Ray Guía para desarrolladoresGeneración de identificadores de seguimiento
Secciones• Generación de identificadores de seguimiento (p. 104)• Uso de PutTraceSegments (p. 104)• Envío de documentos de segmento al demonio de X-Ray (p. 105)
Generación de identificadores de seguimientoPara enviar datos a X-Ray, tiene que generar un ID de rastreo único para cada solicitud. Los ID de rastreodeben cumplir los siguientes requisitos.
Formato de ID de rastro
Un trace_id consta de tres números separados por guiones. Por ejemplo, 1-58406520-a006649127e371903a2de979. Esto incluye:
• El número de versión, es decir, 1.• La hora en que se realizó la solicitud original, la fecha en Unix, en 8 dígitos hexadecimales.
Por ejemplo, el 1 de diciembre de 2016 a las 10:00 a. m. PST en formato de tiempo Unix es1480615200 segundos o 58406520 en formato hexadecimal.
• Un identificador 96 bits del rastro, único a nivel global en 24 dígitos hexadecimales.
Puede escribir un script para generar ID de rastreo para pruebas. A continuación se incluyen dos ejemplos.
Python
import timeimport osimport binascii
START_TIME = time.time()HEX=hex(int(START_TIME))[2:]TRACE_ID="1-{}-{}".format(HEX, binascii.hexlify(os.urandom(12)))
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 muestra de Scorekeep para scripts que crean ID de rastreo y envían segmentosal demonio de X-Ray.
• Python: – xray_start.py• Bash – xray_start.sh
Uso de PutTraceSegmentsPuede cargar documentos de segmento con la API de PutTraceSegments. La API tiene un únicopará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 desegmento directamente a X-Ray.
104
AWS X-Ray Guía para desarrolladoresEnvío de documentos de segmento al demonio de 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": []}
Note
El procesador de comandos de Windows y Windows PowerShell tienen requisitos diferentes paraañadir comillas o comillas con caracteres de escape en cadenas JSON. Consulte Entrecomilladode cadenas 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 delID 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 demonio de X-RayEn lugar de enviar documentos de segmento a la API de X-Ray, puede enviar segmentos y subsegmentosal demonio de X-Ray, que se encargará de almacenarlos en búfer y cargarlos a la API de X-Ray enlotes. El X-Ray SDK envía documentos de segmento al demonio de para evitar realizar llamadas a AWSdirectamente.
Note
Consulte Ejecución del demonio de X-Ray localmente (p. 177) para obtener instrucciones sobrecómo ejecutar el demonio.
Envíe el segmento en formato JSON a través del puerto UDP 2000, anteponiéndole el encabezado deldemonio, {"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 elencabezado 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
105
AWS X-Ray Guía para desarrolladoresObtención de datos
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 demonio (p. 174) para comprobar que se ha enviado el segmento a X-Ray.
2017-07-07T01:57:24Z [Debug] processor: sending partial batch2017-07-07T01:57:24Z [Debug] processor: segment batch size: 1. capacity: 502017-07-07T01:57:24Z [Info] Successfully sent batch of 1 segments (0.020 seconds)
Obtención de datos de AWS X-RayAWS X-Ray procesa los datos de rastreo que usted le envía para generar registros de seguimientocompletos, resúmenes de registros de seguimiento y gráficos de servicios en JSON. Puede recuperar losdatos generados directamente desde la API de con la AWS CLI de .
Secciones• Recuperación del gráfico de servicios (p. 106)• Recuperación del gráfico de servicios por grupo (p. 111)• Recuperación de registros de seguimiento (p. 111)• Recuperación y ajuste de las causas raíz de Analytics (p. 114)
Recuperación del gráfico de serviciosPuede utilizar la API de GetServiceGraph para recuperar el gráfico de servicios de JSON. La APIrequiere una hora de inicio y de finalización, que se puede calcular a partir de un terminal de Linux con elcomando date.
$ date +%s1499394617
date +%s imprime una fecha en cuestión de segundos. Utilice este número como hora de finalización yré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 EC2, una tabla de DynamoDB y un tema de Amazon SNS.
Example Salida de GetServiceGraph
{ "Services": [ { "ReferenceId": 0, "Name": "xray-sample.elasticbeanstalk.com", "Names": [
106
AWS X-Ray Guía para desarrolladoresRecuperación del gráfico de servicios
"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": {
107
AWS X-Ray Guía para desarrolladoresRecuperación del gráfico de servicios
"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 }
108
AWS X-Ray Guía para desarrolladoresRecuperación del gráfico de servicios
], "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 } ],
109
AWS X-Ray Guía para desarrolladoresRecuperación del gráfico de servicios
"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 } ] } ]
110
AWS X-Ray Guía para desarrolladoresRecuperación del gráfico de servicios por grupo
}
Recuperación del gráfico de servicios por grupoPara obtener un gráfico de servicios en función del contenido de un grupo, incluya un groupName ogroupARN. En el ejemplo siguiente, se muestra una llamada a un gráfico de servicios para un grupodenominado 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 seguimientoPuede utilizar la API de GetTraceSummaries para obtener una lista de resúmenes de registros deseguimiento. Estos resúmenes incluyen información que puede utilizar para identificar los registros deseguimiento que desee descargar en su totalidad, y que incluyen anotaciones, información de solicitud yrespuesta e identificadores.
Existen dos indicadores TimeRangeType disponibles al llamar aws xray get-trace-summaries:
• TraceId – la GetTraceSummaries búsqueda predeterminada utiliza el tiempo TraceID y devuelve losregistros de seguimiento iniciados dentro del [start_time, end_time) rango calculado. Este rangode marcas de tiempo se calcula en función de la codificación de la marca de tiempo en TraceId o sepuede definir de forma manual.
• Hora del – evento: para buscar eventos a medida que se producen a lo largo del tiempo, AWS X-Raypermite buscar rastros con marcas de tiempo de eventos. El tiempo de evento devuelve registros deseguimiento activos durante el intervalo [start_time, end_time), independientemente del cuándose inició el seguimiento.
Utilice el comando aws xray get-trace-summaries para obtener una lista de resúmenes de registrosde seguimiento. Los siguientes comandos le permiten obtener una lista de resúmenes de registros deseguimiento 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,
111
AWS X-Ray Guía para desarrolladoresRecuperación de registros de seguimiento
"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 registro de seguimiento del resultado para recuperar un registro de seguimiento completocon la API de BatchGetTraces.
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,
112
AWS X-Ray Guía para desarrolladoresRecuperación de registros de seguimiento
\"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\",
113
AWS X-Ray Guía para desarrolladoresRecuperación y ajuste de las causas raíz de Analytics
\"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 detodos los documentos de segmento recibidos que tienen el mismo ID de registro de seguimiento. Estosdocumentos no representan los datos tal y como la aplicación se los envió a X-Ray, En cambio, representalos documentos procesados generados por los servicios de X-Ray. X-Ray crea el documento de rastreocompleto compilando los documentos de segmento que envía la aplicación y eliminando los datos que nose ajustan al esquema de documentos de segmento (p. 123).
X-Ray también crea segmentos inferidos para las llamadas posteriores a los servicios que no envían lossegmentos propiamente dichos. Por ejemplo, si llama a DynamoDB con un cliente instrumentado, el SDKde X-Ray registra un subsegmento con detalles sobre la llamada desde su punto de vista. No obstante,DynamoDB no envía el segmento correspondiente. X-Ray utiliza la información del subsegmento paracrear un segmento inferido para representar el recurso de DynamoDB en el mapa de servicios y lo añadeal documento de rastreo.
Para obtener varios registros de seguimiento desde la API, se necesita una lista de ID de registros deseguimiento, que se puede extraer de la salida de get-trace-summaries con una consulta de la AWSCLI. Redirija la lista a la entrada de batch-get-traces para obtener registros de seguimiento completospara un periodo de tiempo 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 AnalyticsAl generar un resumen de registros de seguimiento con la API GetTraceSummaries. se pueden reutilizarlos resúmenes de rastros parciales en formato JSON para crear una expresión de filtro más precisa enfunción de las causas raíz. Consulte los ejemplos que aparecen a continuación para ver el procedimientode ajuste.
Example Ejemplo de salida de GetTraceSummaries: sección de causa raíz de tiempo derespuesta
{ "Services": [ { "Name": "GetWeatherData", "Names": ["GetWeatherData"], "AccountId": 123456789012, "Type": null, "Inferred": false, "EntityPath": [
114
AWS X-Ray Guía para desarrolladoresRecuperación y ajuste de las causas raíz de Analytics
{ "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 filtor para las entidades decausa raíz coincidentes. Para cada campo presente en el JSON, todas las coincidencias candidatas debenser exactas o no se devolverá el registro de seguimiento. Los campos eliminados se convierten en valorescomodí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 (p. 64) para obtener más información sobre cómoejecutar consultas con expresiones de filtro.
115
AWS X-Ray Guía para desarrolladoresConfiguración
Example Ejemplo de filtro JSON
rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]
Configuring Configuración de muestreo, grupos ycifrado de con la AWS X-Ray API de
AWS X-Ray dispone de varias API para configurar las reglas de muestreo (p. 76), las reglas de grupos y laconfiguración de cifrado (p. 29).
Secciones• Configuración de cifrado (p. 116)• Reglas de muestreo (p. 117)• Groups (p. 120)
Configuración de cifradoUtilice PutEncryptionConfig para especificar la clave maestra del cliente (CMK) de AWS KeyManagement Service (AWS KMS) que se va a utilizar para el cifrado.
Note
X-Ray no admite CMK 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 unnombre de recurso de Amazon (ARN).
Utilice GetEncryptionConfig para obtener la configuración actual. Cuando X-Ray termina de aplicar laconfiguració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 CMK y utilizar el cifrado predeterminado, establezca el tipo de cifrado en NONE.
116
AWS X-Ray Guía para desarrolladoresReglas de muestreo
$ aws xray put-encryption-config --type NONE{ "EncryptionConfig": { "Status": "UPDATING", "Type": "NONE" }}
Reglas de muestreoPuede administrar las reglas ??? (p. 76) de muestreo de su cuenta con la X-Ray API de . Para obtenermás información sobre cómo añadir y administrar etiquetas, consulte Etiquetado de reglas y grupos X-Rayde muestreo (p. 346).
Obtener todas las reglas de muestreo con GetSamplingRules.
$ aws xray get-sampling-rules{ "SamplingRuleRecords": [ { "SamplingRule": { "RuleName": "Default", "RuleARN": "arn:aws:xray:us-east-2:123456789012:sampling-rule/Default", "ResourceARN": "*", "Priority": 10000, "FixedRate": 0.05, "ReservoirSize": 1, "ServiceName": "*", "ServiceType": "*", "Host": "*", "HTTPMethod": "*", "URLPath": "*", "Version": 1, "Attributes": {} }, "CreatedAt": 0.0, "ModifiedAt": 1529959993.0 } ]}
La regla predeterminada se aplica a todas las solicitudes que no coinciden con otra regla. Es la regla conprioridad más baja y no se puede eliminar. Sin embargo, puede cambiar el porcentaje y el tamaño dedepósito con UpdateSamplingRule.
Example Entrada de la API para UpdateSamplingRule – 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 predeterminadaa uno por ciento sin depósito. Las etiquetas son opcionales. Si decide agregar etiquetas, se requiere unaclave de etiqueta y los valores de etiqueta son opcionales. Para eliminar etiquetas existentes de una reglade muestreo, utilice UntagResource
117
AWS X-Ray Guía para desarrolladoresReglas de muestreo
$ 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 CreateSamplingRule. Al crear una regla, la mayoría delos campos de la regla son obligatorios. En el siguiente ejemplo se crean dos reglas. Esta primera reglaestablece un porcentaje de base para la aplicación de ejemplo Scorekeep. Empareja todas las solicitudesservidas por la API que no coinciden con una regla de prioridad superior.
Example Entrada de la API para UpdateSamplingRule – 9000-base-scorekeep.json
{ "SamplingRule": { "RuleName": "base-scorekeep", "ResourceARN": "*", "Priority": 9000, "FixedRate": 0.1, "ReservoirSize": 5, "ServiceName": "Scorekeep", "ServiceType": "*", "Host": "*", "HTTPMethod": "*", "URLPath": "*", "Version": 1 }}
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 lassolicitudes GET realizadas por el cliente cada pocos segundos para comprobar si hay cambios en elestado del juego.
Example Entrada de la API para UpdateSamplingRule – 5000-polling-scorekeep.json
{ "SamplingRule": { "RuleName": "polling-scorekeep", "ResourceARN": "*", "Priority": 5000, "FixedRate": 0.003, "ReservoirSize": 0,
118
AWS X-Ray Guía para desarrolladoresReglas de muestreo
"ServiceName": "Scorekeep", "ServiceType": "*", "Host": "*", "HTTPMethod": "GET", "URLPath": "/api/state/*", "Version": 1 }}
Las etiquetas son opcionales. Si decide agregar etiquetas, se requiere una clave de etiqueta y los valoresde 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 DeleteSamplingRule.
$ aws xray delete-sampling-rule --rule-name polling-scorekeep{
119
AWS X-Ray Guía para desarrolladoresGroups
"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 }}
GroupsPuede utilizar la API de X-Ray para administrar los grupos de su cuenta. Los grupos son una colecciónde registros de seguimiento que se definen mediante una expresión de filtro. Puede utilizar grupos paragenerar gráficos de servicios adicionales y suministrar métricas de Amazon CloudWatch. ConsulteObtención de datos de AWS X-Ray (p. 106) para obtener más información sobre cómo trabajar congráficos de servicios y métricas a través de la X-Ray API de . Para obtener más información acercade los grupos, consulte Configuración de grupos de en la consola X-Ray de (p. 92). Para obtener másinformación sobre cómo añadir y administrar etiquetas, consulte Etiquetado de reglas y grupos X-Ray demuestreo (p. 346).
Cree un grupo con CreateGroup. Las etiquetas son opcionales. Si decide agregar etiquetas, se requiereuna clave de etiqueta y 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 para obtener todos los grupos existente GetGroups.
$ aws xray get-groups{ "Groups": [ { "GroupName": "TestGroup", "GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID", "FilterExpression": "service(\"example.com\") {fault OR error}" }, { "GroupName": "TestGroup2", "GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup2/UniqueID", "FilterExpression": "responsetime > 2" } ],
120
AWS X-Ray Guía para desarrolladoresMuestreo
"NextToken": "tokenstring"}
Actualice un grupo con UpdateGroup. Las etiquetas son opcionales. Si decide agregar etiquetas, serequiere una clave de etiqueta y los valores de etiqueta son opcionales. Para eliminar etiquetas existentesde un grupo, utilice UntagResource.
$ aws xray update-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID" --filter-expression "service(\"example.com\") {fault OR error}" --tags [{"Key": "Stage","Value": "Prod"},{"Key": "Department","Value": "QA"}]{ "GroupName": "TestGroup", "GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID", "FilterExpression": "service(\"example.com\") {fault OR error}"}
Utilice para eliminar un grup DeleteGroup.
$ aws xray delete-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID" { }
Uso de reglas de muestreo con la API de X-RayEl SDK AWS X-Ray utiliza la API de X-Ray para obtener reglas de muestreo, notificar resultados demuestreo y obtener las cuotas. Puede utilizar estas API para entender mejor cómo funcionan las reglas demuestreo o para implementar muestras en un lenguaje que el SDK de X-Ray no admita.
Comience por obtener todas las reglas de muestreo con GetSamplingRules.
$ aws xray get-sampling-rules{ "SamplingRuleRecords": [ { "SamplingRule": { "RuleName": "Default", "RuleARN": "arn:aws:xray:us-east-1::sampling-rule/Default", "ResourceARN": "*", "Priority": 10000, "FixedRate": 0.01, "ReservoirSize": 0, "ServiceName": "*", "ServiceType": "*", "Host": "*", "HTTPMethod": "*", "URLPath": "*", "Version": 1, "Attributes": {} }, "CreatedAt": 0.0, "ModifiedAt": 1530558121.0 }, { "SamplingRule": { "RuleName": "base-scorekeep", "RuleARN": "arn:aws:xray:us-east-1::sampling-rule/base-scorekeep",
121
AWS X-Ray Guía para desarrolladoresMuestreo
"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 demuestreo (p. 117) 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 reglacoincida, utilice el porcentaje fijo y el tamaño de depósito para tomar una decisión de muestreo. Registresolicitudes muestreadas y pase por alto (para fines de rastreo) las solicitudes sin muestrear. Deje deevaluar 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 antesde aplicar el porcentaje fijo. El depósito se aplica en todos los servicios acumulativamente, por lo queno se puede utilizar directamente. Sin embargo, si es distinto de cero, podrá tomar prestado un rastreopor segundo desde el depósito hasta que X-Ray asigne una cuota. Antes de recibir una cuota, registre laprimera solicitud cada segundo y aplique el porcentaje fijo a las solicitudes adicionales. El porcentaje fijo esun número decimal entre 0 y 1,00 (100 %).
El siguiente ejemplo muestra una llamada a GetSamplingTargets con información detallada sobre lasdecisiones 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,
122
AWS X-Ray Guía para desarrolladoresDocumentos de segmentos
"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 esteejemplo, el servicio ha tomado prestados 10 rastros desde el depósito en 10 segundos y ha aplicado elporcentaje fijo del 10 por ciento a las otras 100 solicitudes, lo que se traduce en un total de 20 solicitudesmuestreadas. La cuota es buena durante cinco minutos (que se indica mediante el tiempo de vida) o hastaque se asigna una nueva cuota. X-Ray también podría asignar un intervalo de informes más largo que elpredeterminado, aunque no aquí.
Note
La respuesta de X-Ray podría no incluir una cuota la primera vez que llama. Continue tomandoprestado del depósito hasta que se les asigne una cuota.
Los otros dos campos de la respuesta podrían indicar problemas con la entrada. CompruebeLastRuleModification respecto a la última vez que llamó a GetSamplingRules. Si es más reciente,obtenga una nueva copia de las reglas. UnprocessedStatistics puede incluir errores que indicanque una regla se ha eliminado, que el documento de estadísticas en la entrada era demasiado antiguo oerrores de permisos.
AWS X-RayDocumentos de segmentos deUn segmento de rastreo es una representación JSON de una solicitud que atiende su aplicación. Unsegmento de rastreo registra información sobre la solicitud original, información sobre el trabajo que laaplicación realiza localmente y subsegmentos con información sobre las llamadas posteriores que laaplicación realiza a AWS recursos, APIs HTTP y bases de datos SQL.
Un documento de segmento transmite información sobre un segmento a X-Ray. Un documento desegmento puede tener un tamaño de hasta 64 kB y contener un segmento completo con subsegmentos,
123
AWS X-Ray Guía para desarrolladoresCampos de segmentos
un fragmento de un segmento que indique que una solicitud está en curso o un único subsegmento quese envía por separado. Puede enviar documentos de segmento directamente a X-Ray mediante la API dePutTraceSegments.
X-Ray compila y procesa los documentos de segmento para generar resúmenes de rastros yrastros completos que admiten consultas a los que puede obtener acceso mediante las API deGetTraceSummaries y BatchGetTraces, respectivamente. Además de los segmentos y subsegmentosque envía a X-Ray, el servicio utiliza la información de los subsegmentos para generar segmentosinferidos, que se añaden al rastro completo. Los segmentos inferidos representan servicios y recursosposteriores en el mapa de servicio.
X-Ray proporciona un esquema JSON para los documentos de segmento. Puede descargar el esquemaaquí: xray-segmentdocument-schema-v1.0.0. Los campos y objetos incluidos en el esquema se describencon más detalle en las secciones siguientes.
X-Ray indexa un subconjunto de los campos de segmento para su uso con expresiones defiltro. Por ejemplo, si establece el campo user de un segmento en un identificador único, puedebuscar los segmentos asociados a usuarios específicos en la consola X-Ray o mediante la APIGetTraceSummaries. Para obtener más información, consulte Uso de expresiones de filtro para buscarregistros de seguimiento en la consola (p. 64).
Cuando instrumente su aplicación con el SDK de X-Ray, el SDK generará automáticamente losdocumentos de segmento. En lugar de enviar documentos directamente a X-Ray, el SDK los transmite através de un puerto UDP local al demonio de X-Ray (p. 171). Para obtener más información, consulteEnvío de documentos de segmento al demonio de X-Ray (p. 105).
Secciones• Campos de segmentos (p. 124)• Subsegments (p. 126)• Datos de solicitudes HTTP (p. 129)• Annotations (p. 131)• Metadata (p. 131)• AWS Datos de recursos de (p. 132)• Errores y excepciones (p. 134)• Consultas SQL (p. 135)
Campos de segmentosUn 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.Note
Los valores deben ser cadenas (de hasta 250 caracteres), a menos que se indique lo contrario.
124
AWS X-Ray Guía para desarrolladoresCampos de segmentos
Campos de segmentos obligatorios
• name: nombre lógico del servicio que gestiona la solicitud (hasta 200 caracteres). Por ejemplo, elnombre 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: identificador de 64 bits para el segmento, único entre otros segmentos del mismo rastro, en16 dígitos hexadecimales.
• trace_id: un identificador único que se conecta a todos los segmentos y subsegmentos procedentesde una única solicitud de cliente.
Formato de ID de rastro
Un trace_id consta de tres números separados por guiones. Por ejemplo, 1-58406520-a006649127e371903a2de979. Esto incluye:• El número de versión, es decir, 1.• La hora en que se realizó la solicitud original, la fecha en Unix, en 8 dígitos hexadecimales.
Por ejemplo, el 1 de diciembre de 2016 a las 10:00 a. m. PST en formato de tiempo Unix es1480615200 segundos o 58406520 en formato hexadecimal.
• Un identificador 96 bits del rastro, único a nivel global en 24 dígitos hexadecimales.Seguridad de ID de rastro
Los ID de rastro se pueden ver en los encabezados de respuesta (p. 26). Genere ID de rastrocon algoritmo aleatorio seguro para garantizar que los atacantes no puedan calcular futuros IDde 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 puntoflotante en tiempo Unix. Por ejemplo, 1480615200.010 o 1.480615200010E9. Use tantos decimalescomo 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 registrarque se inició un segmento pero que no se completó. Envíe un segmento en curso cuando su aplicaciónreciba una solicitud que llevará tiempo atender, para rastrear la recepción de la solicitud. Cuando larespuesta se envía, envíe el segmento completo para sobrescribir el segmento en curso. Envíe solo unsegmento completo o uno o cero segmentos en curso por solicitud.
Nombre de servicios
El elemento name de un segmento debe coincidir con el nombre de dominio o el nombre lógicodel servicio que genera el segmento. Sin embargo, no es algo impuesto. Cualquier aplicación quetenga permiso para PutTraceSegments 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 al usuario que envió la solicitud.• origin – El tipo de AWS recurso que ejecuta la aplicación.
Valores admitidos• AWS::EC2::Instance – Una Amazon EC2 instancia .• AWS::ECS::Container – Un Amazon ECS contenedor de .
125
AWS X-Ray Guía para desarrolladoresSubsegments
• AWS::ElasticBeanstalk::Environment – Un Elastic Beanstalk entorno de .
Si hay varios valores que sean aplicables a su aplicación, utilice el que sea más específico. Por ejemplo,supongamos que un entorno de Docker multicontenedor en Elastic Beanstalk ejecuta su aplicación en uncontenedor 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 elementoprincipal de los otros dos recursos.
• parent_id – Un ID de subsegmento que especifica si la solicitud se originó desde una aplicacióninstrumentada. El SDK de X-Ray añade el ID del subsegmento principal al encabezado de rastreo (p. 26)para las llamadas HTTP posteriores. En el caso de subsegmentos anidados, un subsegmento puedetener un segmento o un subsegmento como padre.
• http – http (p. 129) : objetos con información sobre la solicitud HTTP original.• aws – aws (p. 132) : objeto con información sobre el AWS recurso en el que la aplicación atiende la
solicitud.• errorLos campos de throttle fault causeerror– , (p. 134), y que indican que se ha producido
un error y que incluyen información sobre la excepción que ha provocado el error.• annotations – annotations (p. 131) Objeto con pares clave-valor que desea X-Ray indexar para
búsquedas.• metadata – metadata (p. 131) : objeto con los datos adicionales que desea almacenar en el
segmento.• subsegments – : matriz de subsegment (p. 126) objetos .
SubsegmentsPuede crear subsegmentos para registrar las llamadas a AWS los servicios y recursos que realice conel AWS SDK, las llamadas a APIs web HTTP internas o externas o las consultas de base de datosSQL. 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 personalizadoque registre los metadatos de una llamada a una función interna puede contener otros subsegmentospersonalizados y subsegmentos para llamadas posteriores.
Un subsegmento registra una llamada posterior desde el punto de vista del servicio que llama. X-Rayutiliza subsegmentos para identificar los servicios posteriores que no envían segmentos y crean entradaspara 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 posteriorespara realizar solicitudes de larga ejecución o para evitar superar el tamaño máximo del documento desegmentos.
Example Segmento con un subsegmento incrustado
Un subsegmento independiente tiene un type de subsegment y un parent_id que identifica elsegmento 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",
126
AWS X-Ray Guía para desarrolladoresSubsegments
"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 serastreen 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 queidentifica 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 },
127
AWS X-Ray Guía para desarrolladoresSubsegments
"response" : { "status" : 200, "content_length" : 861 } }}
Cuando se complete la solicitud, cierre el segmento reenviándolo con un end_time. El segmentocompleto sobrescribe el segmento en curso.
También puede enviar subsegmentos por separado para solicitudes realizadas que activen flujos detrabajo asíncronos. Por ejemplo, una API web puede devolver una respuesta OK 200 inmediatamenteantes de iniciar el trabajo que el usuario ha solicitado. Puede enviar un segmento completo a X-Ray encuanto se envíe la respuesta, seguido de subsegmentos para el trabajo realizado más adelante. Al igualque con los segmentos, también puede enviar un fragmento de un subsegmento para registrar que elsubsegmento se ha iniciado y, a continuación, sobrescribirlo con un subsegmento completo una vez quese haya completado la llamada posterior.
Los siguientes campos son obligatorios o necesarios en determinadas circunstancias para lossubsegmentos.
Note
Los valores son cadenas (de hasta 250 caracteres), a menos que se indique lo contrario.
Campos de subsegmentos obligatorios
• id – Un identificador 64-bit para el subsegmento, único entre los segmentos del mismo rastro, en 16dígitos hexadecimales.
• name – El nombre lógico del subsegmento. En el caso de las llamadas posteriores, asigne un nombre alsubsegmento detrás del recurso o servicio llamado. Para los subsegmentos personalizados, asigne elnombre 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 depunto flotante en tiempo Unix, con una precisión de milisegundos. Por ejemplo, 1480615200.010 o1.480615200010E9.
• end_time – : número que representa el momento en que se cerró el subsegmento. Por ejemplo,1480615200.090 o 1.480615200090E9. Especifique un end_time valor de o in_progress.
• in_progress – : booleano que se establece true en en lugar de especificar un end_time pararegistrar que se inicia un subsegmento, pero que no se ha completado. Envíe solo un subsegmentocompleto 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 delsubsegmento se realiza por separado.
Formato de ID de rastro
Un trace_id consta de tres números separados por guiones. Por ejemplo, 1-58406520-a006649127e371903a2de979. Esto incluye:• El número de versión, es decir, 1.• La hora en que se realizó la solicitud original, la fecha en Unix, en 8 dígitos hexadecimales.
Por ejemplo, el 1 de diciembre de 2016 a las 10:00 a. m. PST en formato de tiempo Unix es1480615200 segundos o 58406520 en formato hexadecimal.
• Un identificador 96 bits del rastro, único a nivel global en 24 dígitos hexadecimales.• parent_id – ID de segmento 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 puedetener un segmento o un subsegmento como padre.
• type – subsegment. Solo es necesario si el envío del subsegmento se realiza por separado.
128
AWS X-Ray Guía para desarrolladoresDatos de solicitudes HTTP
Los siguientes campos son opcionales para los subsegmentos.
Campos de subsegmentos opcionales
• namespace – aws para llamadas al SDK de AWS; remote para otras llamadas posteriores.• http – http (p. 129) : objeto con información sobre una llamada HTTP saliente.• aws – aws (p. 132) : objeto con información sobre el AWS recurso posterior al que llamó la aplicación.• errorLos campos de throttle fault causeerror– , (p. 134), y que indican que se ha producido
un error y que incluyen información sobre la excepción que ha provocado el error.• annotations – annotations (p. 131) Objeto con pares clave-valor que desea X-Ray indexar para
búsquedas.• metadata – metadata (p. 131) con los datos adicionales que desea almacenar en el segmento.• subsegments – : matriz de subsegment (p. 126) objetos .• precursor_ids – : matriz de IDs subsegmentos que identifica los subsegmentos con el mismo
segmento principal que completó antes de este subsegmento.
Datos de solicitudes HTTPUtilice 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 yrespuesta HTTP.
http
Todos los campos son opcionales.
• request – Información sobre una solicitud.• method – El método de solicitud. Por ejemplo, GET.• url – La URL completa de la solicitud, compilada a partir del protocolo, el nombre de host y la ruta de
la solicitud.• user_agent – La cadena del 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) valor booleano que indica que el client_ip se ha leído
desde un X-Forwarded-For encabezado y no es de confianza, ya que podría haberse falsificado.• traced – (solo subsegmentos) booleano que indica que la llamada posterior es para otro servicio
rastreado. Si este campo está establecido en true, X-Ray considera que el rastro se debe dividirhasta que el servicio posterior cargue el segmento con un parent_id que coincida con el id delsubsegmento que contiene este bloque.
• response – Información sobre una respuesta.• status – : número que indica el estado HTTP de la respuesta.• content_length – : número que indica la longitud del cuerpo de la respuesta en bytes.
Cuando instrumenta una llamada a una API web posterior, registre un subsegmento con informaciónacerca de la solicitud HTTP y la respuesta. X-Ray utiliza el subsegmento para generar un segmentoinferido de la API remota.
Example Segmento para las llamadas HTTP atendidas por una aplicación en ejecución enAmazon EC2
{
129
AWS X-Ray Guía para desarrolladoresDatos de solicitudes HTTP
"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.4.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-5880168b-fd5153bb58284b67678aa78c", "start_time": 1484786387.131, "end_time": 1484786387.501, "parent_id": "004f72be19cddc2a", "http": { "request": { "method": "GET", "url": "https://names.example.com/" },
130
AWS X-Ray Guía para desarrolladoresAnnotations
"response": { "content_length": -1, "status": 200 } }, "inferred": true}
AnnotationsLos 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éricoso booleanos (pero no objetos ni matrices). X-Ray indexa hasta 50 anotaciones por rastreo.
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.4.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, perono otros símbolos ni espacios en blanco.
MetadataLos segmentos y subsegmentos pueden incluir un objeto metadata que contenga uno o varios camposcon valores de cualquier tipo, incluidos objetos y matrices. X-Ray no indexa los metadatos y los valorespueden tener cualquier tamaño, siempre que el documento del segmento no supere el tamaño máximo
131
AWS X-Ray Guía para desarrolladoresAWS Datos de recursos de
(64 kB). Puede ver los metadatos en el documento del segmento completo devuelto por la API deBatchGetTraces. Las claves de campo (debug en el siguiente ejemplo) empezando por AWS. estánreservadas 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" ] } } ]}
AWS Datos de recursos dePara 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 enun entorno Docker multicontenedor en Elastic Beanstalk podría tener información sobre la instanciaAmazon EC2, el contenedor de Amazon ECS que se ejecuta en la instancia y el propio entorno de ElasticBeanstalk.
aws (Segmentos)
Todos los campos son opcionales.
• account_id – Si la aplicación envía segmentos a otra AWS cuenta, registre el ID de la cuenta queejecuta la aplicación.
• ecs – Información sobre un Amazon ECS contenedor de .• container – El ID del contenedor que ejecuta la aplicación.
• ec2 – Información sobre una instancia EC2• instance_id – El ID de instancia de la instancia EC2
132
AWS X-Ray Guía para desarrolladoresAWS Datos de recursos de
• availability_zone – La zona de disponibilidad en la que se ejecuta la instancia.
Example AWS Bloque de 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" }, "xray": { "sdk": "2.4.0 for Java" }}
• elastic_beanstalk – Información sobre un Elastic Beanstalk entorno. Puede encontrar estainformación en un archivo denominado /var/elasticbeanstalk/xray/environment.conf en lasplataformas 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 atiende la solicitud.• deployment_id – : número que indica el ID de la última implementación correcta en la instancia que
atiende la solicitud.
Para los subsegmentos, registre información sobre los AWS servicios y recursos a los que obtiene accesosu aplicación. X-Ray utiliza esta información para crear segmentos inferidos que representan los serviciosposteriores en su mapa de servicio.
aws (Subsegmentos)
Todos los campos son opcionales.
• operation – El nombre de la acción de la API invocada frente a un AWS servicio o recurso de .• account_id – Si su aplicación obtiene acceso a recursos de otra cuenta de o envía segmentos a otra
cuenta de , registre el ID de la cuenta de propietaria del AWS recurso al que su aplicación accedió.• region – Si el recurso se encuentra en una región diferente de la aplicación, registre la región. Por
ejemplo, us-west-2.• request_id – Identificador único de la solicitud.• queue_url – Para las operaciones en una Amazon SQS cola de , la URL de la cola.• table_name – Para las operaciones en una DynamoDB tabla, el nombre de la tabla.
Example Subsegmento para una llamada a DynamoDB para guardar un elemento
{ "id": "24756640c0d0978a", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "DynamoDB", "namespace": "aws", "http": { "response": { "content_length": 60,
133
AWS X-Ray Guía para desarrolladoresErrores y excepciones
"status": 200 } }, "aws": { "table_name": "scorekeep-user", "operation": "UpdateItem", "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG", }}
Errores y excepcionesCuando se produzca un error, puede registrar información sobre el error y las excepciones que segeneran. Registre los errores en los segmentos cuando la aplicación devuelva un error al usuario, y en lossubsegmentos 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 ManyRequests de una llamada posterior podría hacer que la aplicación devolviera un error 500 InternalServer 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 larespuesta fue 4XX Client Error).
• throttle – booleano que indica que se ha restringido una solicitud (el código de estado de larespuesta fue 429 Too Many Requests).
• fault – booleano que indica que se ha producido un error del servidor (el código de estado de larespuesta 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 cuando se produjo la excepción.• paths – La matriz de rutas a las bibliotecas o módulos en uso cuando se produjo la excepción.• exceptions – La matriz de objetos de excepción.
Incluya información detallada sobre el error en uno o varios objetos exception.
exception
Todos los campos son opcionales excepto id.
• id – Un identificador 64-bit para la excepción, único entre los segmentos del mismo rastro, en 16 dígitoshexadecimales.
• 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 omiten en stack.• skipped – : entero que indica el número de excepciones que se han omitido entre esta excepción y su
excepción secundaria, es decir, la excepción que ha causado.
134
AWS X-Ray Guía para desarrolladoresConsultas SQL
• cause – ID de excepción del elemento principal de la excepción, es decir, la excepción que provocó estaexcepció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 del archivo.• label – El nombre de la función o método.
Consultas SQLPuede 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 cadenasde conexión de URL, registre la cadena de conexión, sin incluir las contraseñas.
• url – Para una conexión de base de datos que utiliza una cadena de conexión de URL, registre la URL,sin incluir las contraseñas.
• sanitized_query – La consulta de base de datos, con los valores proporcionados por el usuarioeliminados o sustituidos por 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 el número de versión del controlador del motor de base de datos que
utiliza su aplicación.• user – El nombre de usuario de la base de datos.• preparation – call si la consulta utilizaba un PreparedCall; statement si la consulta utilizaba unPreparedStatement.
Example Subsegmento con una consulta SQL
{ "id": "3fd8634e78ca9560", "start_time": 1484872218.696, "end_time": 1484872218.697, "name": "[email protected]", "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=?;" }
135
AWS X-Ray Guía para desarrolladoresConsultas SQL
}
136
AWS X-Ray Guía para desarrolladores
AWS X-RayAplicación de muestra deLa aplicación AWS X-Ray eb-java-scorekeep de ejemplo, disponible en GitHub, muestra el uso del AWSX-Ray SDK para instrumentar llamadas HTTP entrantes, clientes DynamoDB del SDK y clientes HTTP.La aplicación de ejemplo usa características de AWS Elastic Beanstalk para crear tablas de DynamoDB,compilar códigos Java en la instancia y ejecutar el demonio de X-Ray sin necesidad de realizar unaconfiguración adicional.
El ejemplo es una versión instrumentada del proyecto Scorekeep en AWSLabs. Incluye una aplicaciónweb front-end, la API que realiza la llamada y las tablas de DynamoDB que usa para almacenar los datos.Todos los componentes se alojan en un entorno de Elastic Beanstalk para garantizar portabilidad y unaimplementación sencilla.
La instrumentación básica con (p. 250)filtros, complementos (p. 242)y clientes AWS del SDK (p. 254)instrumentados se muestra en la xray-gettingstarted ramificación del proyecto. Estaes la ramificación que se implementa en el tutorial Introducción (p. 8). Dado que esta rama solo incluyelos aspectos básicos, puede diferenciarla rápidamente de la ramificación master para comprenderrápidamente los aspectos básicos.
137
AWS X-Ray Guía para desarrolladores
La aplicación de ejemplo muestra una instrumentación básica en estos archivos:
• Filtro de solicitudes HTTP – WebConfig.java• AWS Instrumentación de clientes de SDK – build.gradle
La ramificación xray de la aplicación añade el uso de HTTPClient (p. 255), Anotaciones (p. 260),consultas SQL (p. 257), subsegmentos personalizados (p. 258), una función de AWSLambda (p. 208) instrumentada, así como scripts y código de inicialización instrumentado (p. 162). Estemapa de servicio muestra la ramificación xray que se ejecuta sin una base de datos SQL conectada:
138
AWS X-Ray Guía para desarrolladores
Para permitir el inicio de sesión del usuario y el uso de AWS SDK for JavaScript en el explorador, laramificación xray-cognito añade Amazon Cognito para permitir la autenticación y autorización delusuario. Con credenciales recuperadas desde Amazon Cognito, la aplicación web también envía datos derastreo a X-Ray para registrar la información de la solicitud desde el punto de vista del cliente. El cliente delnavegador aparece como su propio nodo en el mapa de servicio y registra información adicional, incluida laURL de la página que el usuario está visualizando y el ID de usuario.
Por último, la ramificación xray-worker añade una función Lambda de Python instrumentada que seejecuta de forma independiente, procesando los elementos de una cola de Amazon SQS. Scorekeepañade un elemento a la cola cada vez que termina un juego. El trabajo de Lambda, que activa Eventos de
139
AWS X-Ray Guía para desarrolladores
CloudWatch, extrae elementos de la cola cada pocos minutos y los procesa para almacenar los registrosde juego en Amazon S3 para su análisis.
Con todas las características habilitadas, el mapa de servicio de Scorekeep tiene este aspecto:
140
AWS X-Ray Guía para desarrolladoresIntroducción (CLI)
Para obtener instrucciones sobre cómo utilizar la aplicación de ejemplo con X-Ray, consulte el tutorialde introducción (p. 8). Además del uso básico del X-Ray SDK for Java que se detalla en este tutorial, elejemplo también muestra cómo utilizar las siguientes características.
Características avanzadas• Introducción a AWS X-Ray a través de la AWS CLI (p. 141)• Instrumentación manual de clientes AWS del SDK (p. 152)• Creación de subsegmentos adicionales (p. 153)• Registro de anotaciones, metadatos e identificadores de usuario (p. 153)• Instrumentación de llamadas a HTTP salientes (p. 154)• Instrumentación de llamadas a una base de datos PostgreSQL (p. 155)• Instrumentación de funciones AWS Lambda (p. 157)• Instrumentación de aplicaciones de Amazon ECS (p. 161)• Instrumentación de código de inicio (p. 162)• Instrumentación de scripts (p. 163)• Instrumentación de un cliente de aplicación web (p. 165)• Uso de clientes instrumentados en subprocesos de trabajo (p. 168)• Vinculación en profundidad a la consola de X-Ray (p. 170)
Introducción a AWS X-Ray a través de la AWS CLIEn este tutorial se muestra cómo utilizar la AWS CLI para implementar la aplicación de muestra Scorekeepcon una plantilla AWS CloudFormation y, a continuación, generar y recuperar datos de rastreo. La AWSCLI se utiliza para acceder al servicio de X-Ray directamente y utilizar las mismas API que la consola de X-Ray usa para recuperar los gráficos de servicios y los datos de rastreo sin procesar.
Para obtener acceso a los datos de rastreo y al mapa de servicios sin procesar, utilice la AWS CLI parallamar a la API de X-Ray. El mapa de servicios y los datos de rastreo están en formato JSON. Después,puede consultar los datos de rastreo para asegurarse de que la aplicación envíe datos o para corroborarcampos específicos, como parte de la automatización de pruebas.
Este tutorial tarda aproximadamente 30 minutos en completarse. Aunque proporcionamos enlaces paraobtener más información sobre varios temas relacionados, no es necesario salir de esta página paracompletar el tutorial. Le sugerimos que abra y revise los scripts en un editor de texto o en el repositorio deGitHub a medida que avanza. Los scripts muestran casos de uso de la AWS CLI y cómo administrar losdatos que devuelven las llamadas a la API.
Temas• Prerequisites (p. 142)• Crear la instancia Amazon EC2 (p. 142)• Instale la CLI de AWS (p. 143)• Implementar Scorekeep (p. 144)• Generar datos de seguimiento (p. 146)• Obtener datos (p. 147)• Configurar las notificaciones de Amazon SNS (p. 151)• Eliminar recursos (p. 152)• Pasos siguientes (p. 152)
141
AWS X-Ray Guía para desarrolladoresPrerequisites
PrerequisitesLas secciones siguientes describen los conocimientos que debe tener y los permisos a los que debe teneracceso para seguir este tutorial.
Línea de comandos
El tutorial utiliza una instancia Amazon Elastic Compute Cloud (Amazon EC2) de Ubuntu Server 18.04LTS, incluida en la capa gratuita de AWS. La instancia de Ubuntu proporciona un terminal. Para seguir losprocedimientos de este tutorial, necesitará un shell o un terminal de línea de comando para ejecutar loscomandos. Los comandos se muestran en listados precedidos por un símbolo de comando ($).
$ this is a commandthis is output
También debe estar familiarizado con el uso de vi en el terminal. Hay muchas fuentes de información envi donde puede aprender los comandos básicos, por ejemplo, una hoja de referencia de Vim.
Permisos de usuario
Al trabajar en una instancia Amazon EC2, se recomienda utilizar un rol de perfil de instancia paraobtener credenciales. Esto le permite delegar permisos para realizar solicitudes de API sin distribuir suscredenciales de AWS. Creará un rol de AWS Identity and Access Management (IAM) que especifique lospermisos que desea conceder a las aplicaciones que se ejecuten en su instancia Amazon EC2.
Realice los pasos siguientes para preparar un rol y asociarlo a la instancia Amazon EC2 durante lacreación.
Para crear un rol Scorekeep
1. Inicie sesión en la Consola de administración de AWS y abra la consola de IAM en https://console.aws.amazon.com/iam/.
2. Elija Roles y después Create Role (Crear rol).3. En Casos de uso comunes, elija EC2, y, a continuación, elija Siguiente: Permisos.4. Elija AdministradorAccess y, a continuación, Siguiente: Etiquetas.5. Elija Siguiente: Revisar, asigne el nombre scorekeep-ubuntu y, a continuación, elija Crear un rol.
Crear la instancia Amazon EC2Para demostrar cómo configurar la aplicación de ejemplo mediante la AWS CLI, primero debe implementaruna instancia Amazon EC2 limpia a través de la consola. El resto del tutorial requiere esta instancia.
Para crear una instancia Amazon EC2 de Ubuntu
1. Inicie sesión en la Consola de administración de AWS y abra la consola de Amazon EC2 en https://console.aws.amazon.com/ec2/.
2. Compruebe que se encuentra en la región de AWS donde desea crear la instancia.3. Elija Launch Instance. Utilice la característica de búsqueda para filtrar por Ubuntu y, a continuación,
elija Ubuntu Server 18.04 LTS. Se incluye en la capa gratuita de AWS.4. En la parte superior del asistente de lanzamiento, elija 3. Configure Instance. A continuación, asigne el
rol scorekeep-ubuntu que creó en los requisitos previos de los permisos al campo Rol de IAM .5. En la parte superior del asistente de lanzamiento, elija 5. Añada etiquetas y, a continuación, elija Add
tag (Añadir etiqueta). Después, haga lo siguiente:
142
AWS X-Ray Guía para desarrolladoresInstale la CLI de AWS
• En Key (Clave), escriba Name.• En Value (Valor), escriba scorekeep-ubuntu.
6. En la parte superior del asistente de lanzamiento, elija 6. Página Configure Security Group. Cambie elNombre del grupo de seguridad a scorekeep-ubuntu.
7. (Opcional) En Origen, elija Mi IP. Las restricción del acceso a la instancia es una prácticarecomendada de seguridad.
8. Elija Review and Launch (Revisar y lanzar) y, a continuación, elija Launch (Lanzar).9. Elija Crear un nuevo par de claves y asigne a este el nombre scorekeep-ubuntu-key.10. Elija Descargar par de claves y, a continuación, elija Lanzar instancias.
Esta instancia tarda menos de cinco minutos en lanzarse y puede conectarse poco después.
Para conectarse a una instancia Amazon EC2 de Ubuntu
1. Inicie sesión en la Consola de administración de AWS y abra la consola de Amazon EC2 en https://console.aws.amazon.com/ec2/.
2. Compruebe que está en la región de AWS donde se creó la instancia.3. Elija Instances.4. En la lista de instancias, seleccione scorekeep-ubuntu.5. Para obtener instrucciones sobre los métodos de conexión, elija Conectarse.
Instale la CLI de AWSUna vez conectado a la instancia, debe instalar la AWS CLI. Los comandos de la AWS CLI se utilizanen los pasos siguientes para crear recursos, implementar la aplicación instrumentada y extraer datos derastreo de la aplicación implementada.
Para configurar la AWS CLI y realizar llamadas, necesita un ID de clave de acceso de AWS y una clavede acceso secreta de AWS. Al trabajar en una instancia Amazon EC2, utilice el rol asociado a la instanciapara obtener estas credenciales. No utilice sus claves personales.
Para obtener información detallada y escenarios sobre perfiles de instancia en Amazon EC2, consulteRoles de IAM para Amazon EC2 y Uso de credenciales temporales con AWS recursos de .
Para instalar y configurar la AWS CLI
Ejecute los comandos siguientes para descargar la AWS CLI y, a continuación, descomprímala e instálela.
$ sudo apt update$ sudo apt install python3-pip $ pip3 install awscli --upgrade --user$ sudo apt install awscli$ aws --versionaws-cli/1.18.63 Python/3.6.9 Linux/4.15.0-1065-aws botocore/1.16.13
Ejecute los comandos siguientes para obtener las credenciales del rol de instancia Amazon EC2 y asignarlas credenciales para su uso.
También debe elegir una región para especificarla en la tabla Puntos de enlace regionales. Esto esnecesario. Determina la región en la que se crearán los recursos subsiguientes y a la que apuntan losscripts.
143
AWS X-Ray Guía para desarrolladoresImplementar Scorekeep
$ curl http://169.254.169.254/latest/meta-data/iam/security-credentials/scorekeep-ubuntu{ "Code" : "Success", "LastUpdated" : "2020-04-29T01:03:10Z", "Type" : "AWS-HMAC", "AccessKeyId" : "ASIAIOSFODNN7EXAMPLE", "SecretAccessKey" : "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY", "Token" : "TokenString", "Expiration" : "2020-04-29T07:38:23Z"}$ export AWS_ACCESS_KEY_ID=ASIAIOSFODNN7EXAMPLE$ export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY$ export AWS_SESSION_TOKEN=TokenString$ export AWS_DEFAULT_REGION=Region
Note
Si se desconecta de la instancia Amazon EC2 antes de finalizar el tutorial, tendrá que repetirestos comandos de exportación para restablecer las credenciales y la región.
Implementar ScorekeepEl entorno y la aplicación ya están listos para implementar Scorekeep. Esta aplicación Java deejemplo (p. 137) genera segmentos y los envía a X-Ray.
La aplicación utiliza el marco de Spring para implementar una API web de formato JSON y AWS SDKfor Java para mantener los datos en DynamoDB. Un filtro de servlet en la aplicación instrumenta todaslas solicitudes entrantes que atiende la aplicación. Un controlador de solicitudes del cliente de AWS SDKinstrumenta las llamadas posteriores a DynamoDB.
El paquete contiene varios scripts de shell numerados, lo que agiliza la creación de los recursos. Tambiénincluye una plantilla de AWS CloudFormation. Para obtener más información sobre AWS CloudFormation,consulte ¿Qué es AWS CloudFormation?
Para descargar e implementar Scorekeep
Ejecute los comandos siguientes para instalar y configurar git y ejecute git clone para clonarel repositorio de Scorekeep en su servidor Ubuntu. Scorekeep tiene distintas ramificacionespara los diferentes proyectos de introducción. Para este tutorial, ejecute git checkout xray-gettingstarted.
$ git config --global user.name "Name"$ git config --global user.email "[email protected]"$ git clone https://github.com/aws-samples/eb-java-scorekeep.git$ cd eb-java-scorekeepeb-java-scorekeep$ git checkout xray-gettingstarted
Ejecute los scripts de implementación del proyecto para crear un bucket de Amazon S3 e implementar laaplicación. Siga leyendo información sobre los scripts mientras el proyecto se implementa.
eb-java-scorekeep$ ./1-create-bucket.shmake_bucket: beanstalk-artifacts-8174xmplbb388b50eb-java-scorekeep$ ./2-deploy.shSuccessfully packaged artifacts and wrote output template to file out.yml.Execute the following command to deploy the packaged templateaws cloudformation deploy --template-file /home/ubuntu/eb-java-scorekeep/out.yml --stack-name scorekeep
144
AWS X-Ray Guía para desarrolladoresImplementar Scorekeep
Waiting for changeset to be created..Waiting for stack create/update to completeSuccessfully created/updated stack - scorekeep
El script 1-create-bucket.sh crea un bucket con la convención de nomenclatura beanstalk-artifacts-$BUCKET_ID, donde $BUCKET_ID es un ID generado de forma aleatoria.
El script 2-deploy.sh crea una pila de AWS CloudFormation que contiene un entorno de AWS ElasticBeanstalk. Utiliza la AWS CLI para cargar el código fuente en Amazon S3 e implementar una plantilla quedefine los recursos de la pila.
Note
La creación de todos los artefactos de la pila tarda unos 10 minutos. Puede que tenga que pulsarIntro para solicitar el mensaje de confirmación final.
Example eb-java-scorekeep/2-deploy.sh
#!/bin/bashset -eo pipefailARTIFACT_BUCKET=$(cat bucket-name.txt)git archive --format=zip HEAD > package.zipaws cloudformation package --template-file template.yml --s3-bucket $ARTIFACT_BUCKET --output-template-file out.ymlaws cloudformation deploy --template-file out.yml --stack-name scorekeep --capabilities CAPABILITY_NAMED_IAM
El archivo template.yml crea un entorno de Elastic Beanstalk con los permisos requeridos, tablas deAmazon DynamoDB y otros recursos que utiliza la aplicación de ejemplo.
Example eb-java-scorekeep/template.yml
AWSTemplateFormatVersion: 2010-09-09Description: An AWS Elastic application that uses DynamoDB.Parameters: emailAddress: Type: String Default: UPDATEMEResources: application: Type: AWS::ElasticBeanstalk::Application Properties: ApplicationName: Scorekeep Description: RESTful web API in Java with Spring that provides an HTTP interface for creating and managing game sessions and users. version: Type: AWS::ElasticBeanstalk::ApplicationVersion Properties: ApplicationName: !Ref application SourceBundle: ./package.zip environment: Type: AWS::ElasticBeanstalk::Environment Properties: ApplicationName: !Ref application EnvironmentName: BETA OptionSettings: - Namespace: aws:elasticbeanstalk:application:environment OptionName: AWS_REGION Value: !Ref AWS::Region ...
145
AWS X-Ray Guía para desarrolladoresGenerar datos de seguimiento
Una vez finalizada la implementación, ejecute 3-open-website.sh para obtener la URL del sitio.
eb-java-scorekeep$ ./3-open-website.shhttp://awseb-e-b-AWSEBLoa-SR79XMPLF2H8-586716793.us-west-2.elb.amazonaws.com
Abra el sitio web en un navegador para ver la aplicación web y comenzar a generar datos de rastreo.
Generar datos de seguimientoTambién puede utilizar el script test-api.sh incluido en el paquete para ejecutar escenarios integrales ygenerar datos de rastreo diversos mientras prueba la API.
Para usar el script test-api.sh
1. Instale la biblioteca jq. El script test-api.sh utiliza jq para analizar los datos JSON que devuelvenlas llamadas a la API.
$ sudo apt install jq
2. Utilice la AWS CLI para obtener el valor CNAMEdel entorno. Utilice la EnvironmentName BETA pararealizar consultas. Este es el nombre que se definió en la plantilla de AWS CloudFormation.
$ aws elasticbeanstalk describe-environments --environment-names BETA{ "Environments": [ { "EnvironmentName": "BETA", "EnvironmentId": "e-fn2pvynnue", "ApplicationName": "Scorekeep", "VersionLabel": "scorekeep-version-1jd6hjta4qjzl", "SolutionStackName": "64bit Amazon Linux 2018.03 v2.10.4 running Java 8", "PlatformArn": "arn:aws:elasticbeanstalk:us-west-2::platform/Java 8 running on 64bit Amazon Linux/2.10.4", "EndpointURL": "awseb-e-f-AWSEBLoa-1UJJGXA6MKWMN-1234567.us-west-2.elb.amazonaws.com", "CNAME": "BETA.eba-example.us-west-2.elasticbeanstalk.com", ...}
3. Abra el script /bin/test-api.sh y reemplace el valor de la API con el URL del entorno.
eb-java-scorekeep$ vi bin/test-api.sh #!/bin/bashAPI=scorekeep-ubuntu.9hbtbm23t2.us-west-2.elasticbeanstalk.com/api
4. Ejecute el script para generar tráfico a la API.
eb-java-scorekeep$ ./bin/test-api.shCreating users,session,game,configuring game,playing game,ending game,game complete.{"id":"MTBP8BAS","session":"HUF6IT64","name":"tic-tac-toe-test","users":["QFF3HBGM","KL6JR98D"],"rules":"102","startTime":1476314241,"endTime":1476314245,"states":["JQVLEOM2","D67QLPIC","VF9BM9NC","OEAA6GK9","2A705O73","1U2LFTLJ","HUKIDD70","BAN1C8FI","G3UDJTUF","AB70HVEV"],"moves":["BS8F8LQ","4MTTSPKP","463OETES","SVEBCL3N","N7CQ1GHP","O84ONEPD","EG4BPROQ","V4BLIDJ3","9RL3NPMV"]}
146
AWS X-Ray Guía para desarrolladoresObtener datos
Obtener datosPuede utilizar la API de GetServiceGraph para recuperar el gráfico de servicios de JSON. La APIrequiere una hora de inicio y una hora de finalización. Puede calcularlas desde un terminal Linux con elcomando date.
$ date +%s1499394617
date +%s imprime una fecha en cuestión de segundos. Utilice este número como hora de finalización yreste el tiempo que corresponda para crear 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 ejemplo siguiente, se muestra un gráfico de servicio con cuatro nodos, que incluye un nodo cliente,una instancia EC2, una tabla de DynamoDB y un tema de Amazon Simple Notification Service (AmazonSNS).
Gráfico de servicios sin formato
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,
147
AWS X-Ray Guía para desarrolladoresObtener datos
"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 } ] }, {
148
AWS X-Ray Guía para desarrolladoresObtener datos
"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,
149
AWS X-Ray Guía para desarrolladoresObtener datos
"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,
150
AWS X-Ray Guía para desarrolladoresConfigurar las notificaciones de Amazon SNS
"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 } ] } ]}
Configurar las notificaciones de Amazon SNSScorekeep utiliza Amazon SNS para enviar notificaciones cuando los usuarios completan unjuego. Cuando la aplicación se inicia, intenta crear una suscripción para una dirección de correoelectrónico definida en una variable de entorno. Esa llamada está fallando, lo que provoca el recuentoErrorStatistics en los datos sin procesar.
Para obtener más información sobre cómo aparece en la consola de , consulte Ver el mapa de servicio enla X-Ray consola de .
El siguiente comando establece el valor de la NOTIFICATION_EMAIL variable en el entorno BETA [email protected].
$ aws elasticbeanstalk update-environment --environment-name BETA --option-settings Namespace=aws:elasticbeanstalk:application:environment,OptionName=NOTIFICATION_EMAIL,[email protected]{ "EnvironmentName": "BETA", "EnvironmentId": "e-iarzmpigxz", "ApplicationName": "Scorekeep", "VersionLabel": "scorekeep-version-1rrbj5e9c31yc", "SolutionStackName": "64bit Amazon Linux 2018.03 v2.10.7 running Java 8", ...
151
AWS X-Ray Guía para desarrolladoresEliminar recursos
}
Cuando se completa la actualización, Scorekeep se reinicia y crea una suscripción al tema de AmazonSNS. Compruebe su correo electrónico y confirme la suscripción para ver las actualizaciones cuandocomplete un juego.
Eliminar recursosEjecute el script 6-cleanup.sh para eliminar el bucket que creó y retirar la pila de AWS CloudFormation.Se le pedirá que confirme con yes o no. Después de confirmar, puede salir de la línea de comandos,terminar la instancia Amazon EC2 y eliminar el rol de IAM.
Para terminar una instancia Amazon EC2 (consola)
1. Inicie sesión en la Consola de administración de AWS y abra la consola de Amazon EC2 en https://console.aws.amazon.com/ec2/.
2. Compruebe que se encuentra en la región donde se creó la instancia.3. Elija Instances.4. En la lista de instancias, seleccione scorekeep-ubuntu.5. Elija Actions (Acciones).6. En la lista, elija Estado de instancia y, a continuación, elija Terminar.7. Para confirmar, elija Sí, terminar.
Para eliminar el rol de IAM (consola)
1. Inicie sesión en la Consola de administración de AWS y abra la consola de IAM en https://console.aws.amazon.com/iam/.
2. Elija Roles. Busque scorekeep-ubuntu y selecciónelo.3. Elija Eliminar el rol y, a continuación, Sí, eliminar.
Pasos siguientesEncontrará más información sobre X-Ray en AWS X-RayConceptos de (p. 21).
Para instrumentar su propia aplicación, obtener más información sobre el X-Ray SDK for Java o sobrealguno de los SDK de X-Ray restantes, consulte lo siguiente:
• AWS X-Ray SDK para Java (p. 231)• AWS X-Ray SDK for Node.js (p. 270)• AWS X-Ray SDK para .NET (p. 327)
Para ejecutar el X-Ray demonio de localmente o en AWS, consulte AWS X-RayDemonio de (p. 171).
Para colaborar con la aplicación de ejemplo en GitHub, consulte eb-java-scorekeep.
Instrumentación manual de clientes AWS del SDKEl instrumenta X-Ray SDK for Java automáticamente todos los clientes AWS del SDK cuando se incluye elsubmódulo Instrumentor del AWS SDK en las dependencias (p. 233)de compilación.
152
AWS X-Ray Guía para desarrolladoresSubsegmentos personalizados
Puede deshabilitar la instrumentación de clientes automática eliminando el submódulo Instrumentor.Esto le permite instrumentar algunos clientes manualmente a la vez que se pasan otros por alto, o utilizardiferentes controladores de rastreo en clientes distintos.
Para ilustrar la compatibilidad con la instrumentación de clientes AWS SDK específicos, la aplicación pasaun controlador de rastreo a AmazonDynamoDBClientBuilder como controlador de solicitudes en elusuario, el juego y el modelo de sesión. Esta modificación del código indica al SDK que instrumente todaslas llamadas a DynamoDB con esos clientes.
Example src/main/java/scorekeep/SessionModel.java – Instrumentación manual delcliente AWS del SDK
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.handlers.TracingHandler;
public class SessionModel { private AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard() .withRegion(Constants.REGION) .withRequestHandlers(new TracingHandler(AWSXRay.getGlobalRecorder())) .build(); private DynamoDBMapper mapper = new DynamoDBMapper(client);
Si elimina el submódulo Instrumentor del AWS SDK de las dependencias del proyecto, solo aparecerán losclientes AWS del SDK instrumentados manualmente en el mapa de servicio.
Creación de subsegmentos adicionalesEn la clase de modelo del usuario, la aplicación crea de forma manual subsegmentos para agrupar todaslas llamadas posteriores que se realizaron dentro de la función saveUser y agrega metadatos.
Example src/main/java/scorekeep/UserModel.java: subsegmentos personalizados
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.entities.Subsegment;... public void saveUser(User user) { // Wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("## UserModel.saveUser"); try { mapper.save(user); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } }
Registro de anotaciones, metadatos eidentificadores de usuario
En la clase de modelo de juego, la aplicación registra objetos Game en un bloque de metadatos (p. 262)cada vez que se guarda un juego en DynamoDB. De forma independiente, la aplicación registra losidentificadores de juego en anotaciones (p. 261) para su uso con expresiones de filtro (p. 64).
153
AWS X-Ray Guía para desarrolladoresClientes de HTTP
Example src/main/java/scorekeep/GameModel.java: anotaciones y metadatos
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.entities.Segment;import com.amazonaws.xray.entities.Subsegment;... public void saveGame(Game game) throws SessionNotFoundException { // wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame"); try { // check session String sessionId = game.getSession(); if (sessionModel.loadSession(sessionId) == null ) { throw new SessionNotFoundException(sessionId); } Segment segment = AWSXRay.getCurrentSegment(); subsegment.putMetadata("resources", "game", game); segment.putAnnotation("gameid", game.getId()); mapper.save(game); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } }
En el controlador de movimiento, la aplicación registra los identificadores de usuario (p. 263) consetUser. Los identificadores de usuario se registran en un campo aparte en segmentos y se indexan parasu uso con la búsqueda.
Example src/main/java/scorekeep/MoveController.java: ID de usuario
import com.amazonaws.xray.AWSXRay;... @RequestMapping(value="/{userId}", method=RequestMethod.POST) public Move newMove(@PathVariable String sessionId, @PathVariable String gameId, @PathVariable String userId, @RequestBody String move) throws SessionNotFoundException, GameNotFoundException, StateNotFoundException, RulesException { AWSXRay.getCurrentSegment().setUser(userId); return moveFactory.newMove(sessionId, gameId, userId, move); }
Instrumentación de llamadas a HTTP salientesLa clase del generador del usuario muestra cómo la aplicación usa la versión de HTTPClientBuilderdel X-Ray SDK for Java para instrumentar las llamadas HTTP salientes.
Example src/main/java/scorekeep/UserFactory.java: instrumentación de HTTPClient
import com.amazonaws.xray.proxies.apache.http.HttpClientBuilder;
public String randomName() throws IOException { CloseableHttpClient httpclient = HttpClientBuilder.create().build(); HttpGet httpGet = new HttpGet("http://uinames.com/api/"); CloseableHttpResponse response = httpclient.execute(httpGet); try { HttpEntity entity = response.getEntity();
154
AWS X-Ray Guía para desarrolladoresClientes de SQL
InputStream inputStream = entity.getContent(); ObjectMapper mapper = new ObjectMapper(); Map<String, String> jsonMap = mapper.readValue(inputStream, Map.class); String name = jsonMap.get("name"); EntityUtils.consume(entity); return name; } finally { response.close(); } }
Si actualmente utiliza org.apache.http.impl.client.HttpClientBuilder, puedesimplemente intercambiar la instrucción de importación para esa clase por una paracom.amazonaws.xray.proxies.apache.http.HttpClientBuilder.
Instrumentación de llamadas a una base de datosPostgreSQL
El archivo application-pgsql.properties añade el interceptor de rastreo de PostgreSQL de X-Rayal origen de datos creado en RdsWebConfig.java.
Example application-pgsql.properties: instrumentación de una base de datosPostgreSQL
spring.datasource.continue-on-error=truespring.jpa.show-sql=falsespring.jpa.hibernate.ddl-auto=create-dropspring.datasource.jdbc-interceptors=com.amazonaws.xray.sql.postgres.TracingInterceptorspring.jpa.database-platform=org.hibernate.dialect.PostgreSQL94Dialect
Note
Consulte Configuración de bases de datos con Elastic Beanstalk en la Guía para desarrolladoresde AWS Elastic Beanstalk para obtener más información acerca de cómo añadir una base dedatos de PostgreSQL al entorno de aplicaciones.
La página de demostración de X-Ray en la ramificación xray incluye una demostración que utiliza elorigen de datos instrumentado para generar rastros que muestran información sobre las consultas SQLque se generan. Vaya a la ruta /#/xray de la aplicación en ejecución o elija Powered by AWS X-Ray enla barra de navegación para ver la página de demostración.
155
AWS X-Ray Guía para desarrolladoresClientes de SQL
156
AWS X-Ray Guía para desarrolladoresAWS LambdaFunciones de
Elija Trace SQL queries (Rastrear consultas SQL) para simular las sesiones de juego y almacenar losresultados en la base de datos asociada. A continuación, elija View traces in X-Ray (AWSVer rastros en X-Ray) para ver una lista filtrada de rastros que pasan por la /api/history ruta de la API.
Elija uno de los rastros de la lista para ver la escala de tiempo, incluida la consulta SQL.
Instrumentación de funciones AWS LambdaScorekeep utiliza dos funciones de AWS Lambda. La primera es una función de Node.js de la ramificaciónlambda que genera nombres aleatorios para nuevos usuarios. Cuando un usuario crea una sesión sinintroducir ningún nombre, la aplicación llama a una función denominada random-name con el AWS SDKfor Java. El X-Ray SDK for Java registra información sobre la llamada a Lambda en un subsegmento,como cualquier otra llamada realizada con un cliente AWS del SDK instrumentado.
Note
La ejecución de la función random-name Lambda requiere la creación de recursos adicionalesfuera del entorno de Elastic Beanstalk. Consulte el archivo readme para obtener más informacióne instrucciones: AWS Lambda Integration.
La segunda función, scorekeep-worker, es una función de Python que se ejecuta de formaindependiente de la API de Scorekeep. Cuando un juego termina, la API escribe el ID de sesión y elID de juego en una cola de SQS. La función de trabajo lee los elementos de la cola y llama a la APIde Scorekeep para construir registros completos de cada sesión de juego para su almacenamiento enAmazon S3.
Scorekeep incluye plantillas y scripts de AWS CloudFormation para crear ambas funciones. Dado quenecesita agrupar el SDK de X-Ray con el código de la función, las plantillas crean las funciones sinningún tipo de código. Al implementar Scorekeep, un archivo de configuración incluido en la carpeta.ebextensions crea un paquete de origen que incluye el SDK y actualiza el código de la función y laconfiguración con el AWS Command Line Interface.
Funciones• Nombre aleatorio (p. 158)• Worker (p. 159)
157
AWS X-Ray Guía para desarrolladoresNombre aleatorio
Nombre aleatorioScorekeep llama a la función de nombre aleatorio cuando un usuario comienza una sesión de juego sininiciar sesión o especificar un nombre de usuario. Cuando Lambda procesa la llamada a random-name,lee el encabezado de rastreo (p. 26), que contiene el ID de rastreo y la decisión de muestreo escrita por elX-Ray SDK for Java.
Para cada solicitud de muestreo, Lambda ejecuta el demonio de X-Ray y escribe dos segmentos. El primersegmento registra información sobre la llamada a Lambda que invoca la función. Este segmento contienela misma información que el subsegmento registrado por Scorekeep, pero desde el punto de vista deLambda. El segundo segmento representa el trabajo que hace la función.
Lambda pasa el segmento de la función al SDK de X-Ray a través del contexto de la función. Cuandoinstrumenta una función Lambda, no utiliza el SDK para crear un segmento para las solicitudesentrantes (p. 276). Lambda proporciona el segmento y se usa el SDK para instrumentar los clientes yescribir subsegmentos.
La función random-name se implementa en Node.js. Utiliza el SDK para JavaScript en Node.js para enviarnotificaciones con Amazon SNSy el X-Ray SDK for Node.js para instrumentar el cliente del AWS SDK.Para escribir anotaciones, la función crea un subsegmento personalizado con AWSXRay.captureFunc yescribe anotaciones en la función instrumentada. En Lambda, no puede escribir anotaciones directamenteen el segmento de la función, únicamente en un subsegmento que cree.
Example function/index.js: función Lambda random-name
var AWSXRay = require('aws-xray-sdk-core');var AWS = AWSXRay.captureAWS(require('aws-sdk'));
158
AWS X-Ray Guía para desarrolladoresWorker
AWS.config.update({region: process.env.AWS_REGION});var Chance = require('chance');
var myFunction = function(event, context, callback) { var sns = new AWS.SNS(); var chance = new Chance(); var userid = event.userid; var name = chance.first();
AWSXRay.captureFunc('annotations', function(subsegment){ subsegment.addAnnotation('Name', name); subsegment.addAnnotation('UserID', event.userid); });
// Notify var params = { Message: 'Created randon name "' + name + '"" for user "' + userid + '".', Subject: 'New user: ' + name, TopicArn: process.env.TOPIC_ARN }; sns.publish(params, function(err, data) { if (err) { console.log(err, err.stack); callback(err); } else { console.log(data); callback(null, {"name": name}); } });};
exports.handler = myFunction;
Esta función se crea automáticamente al implementar la aplicación de ejemplo en Elastic Beanstalk.La ramificación xray incluye un script para crear una función de Lambda en blanco. Los archivos deconfiguración de la .ebextensions carpeta crean el paquete de la función con npm install durante laimplementación y, a continuación, actualizan la Lambda función con la AWS CLI de .
WorkerLa función de trabajo instrumentada se proporciona en su propia ramificación, xray-worker, ya que nose puede ejecutar a menos que antes cree la función de trabajo y los recursos relacionados. Consulte elarchivo readme de la ramificación para obtener instrucciones.
La función se activa por un evento de Amazon CloudWatch Events empaquetado cada 5 minutos. Cuandose ejecuta, la función extrae un elemento de una cola de Amazon SQS que administra Scorekeep. Cadamensaje contiene información sobre un juego terminado.
El trabajo extrae los documentos y el registro del juego de otras tablas a las que hace referencia el registrode juego. Por ejemplo, el registro del juego en DynamoDB incluye una lista de los movimientos que se hanrealizado durante el juego. La lista no contiene los movimientos en sí, sino los ID de los movimientos queestán almacenados en una tabla distinta.
Las sesiones y los estados también se almacenan como referencias. Esto impide que las entradas dela tabla de juego sean demasiado grandes, pero requiere llamadas adicionales para obtener toda lainformación sobre el juego. El trabajo anula las referencias a todas estas entradas y construye un registrocompleto del juego como un único documento en Amazon S3. Cuando desea realizar el análisis de losdatos, puede ejecutar consultas en él directamente en Amazon S3 con Amazon Athena sin ejecutarmigraciones de datos que realizan muchas lecturas para obtener los datos de DynamoDB.
159
AWS X-Ray Guía para desarrolladoresWorker
La función de trabajo tiene habilitado el rastreo activo en su configuración en AWS Lambda. A diferenciade la función de nombre aleatorio, el trabajo no recibe una solicitud de una aplicación instrumentada, por loque AWS Lambda no recibe un encabezado de rastreo. Con el rastreo activo, Lambda crea el ID de rastreoy toma decisiones de muestreo.
El SDK de X-Ray para Python es tan solo unas líneas situadas en la parte superior de la función queimporta el SDK y ejecuta su función patch_all para aplicar parches en los clientes AWS SDK for Python(Boto) y HTTP que utiliza para llamar a Amazon SQS y Amazon S3. Cuando el trabajo llama a la API deScorekeep, el SDK añade el encabezado de rastreo (p. 26) a la solicitud para rastrear llamadas a través dela API.
Example _lambda/scorekeep-worker/scorekeep-worker.py: función Lambda del procesode trabajo
import osimport boto3import jsonimport requestsimport timefrom aws_xray_sdk.core import xray_recorderfrom aws_xray_sdk.core import patch_all
patch_all()
160
AWS X-Ray Guía para desarrolladoresAmazon ECS
queue_url = os.environ['WORKER_QUEUE']
def lambda_handler(event, context): # Create SQS client sqs = boto3.client('sqs') s3client = boto3.client('s3')
# Receive message from SQS queue response = sqs.receive_message( QueueUrl=queue_url, AttributeNames=[ 'SentTimestamp' ], MaxNumberOfMessages=1, MessageAttributeNames=[ 'All' ], VisibilityTimeout=0, WaitTimeSeconds=0 ) ...
Instrumentación de aplicaciones de Amazon ECSEn la ramificación xray-ecs, la aplicación de ejemplo Scorekeep muestra cómo instrumentar unaaplicación que se ejecuta en Amazon Elastic Container Service (Amazon ECS). La ramificaciónproporciona scripts y archivos de configuración para crear, cargar y ejecutar imágenes de Docker en unentorno Multicontainer Docker en AWS Elastic Beanstalk.
El proyecto incluye tres Dockerfiles que definen las imágenes de contenedor para los componentes de laAPI, el frontend y el demonio de X-Ray.
• /Dockerfile: la API de Scorekeep.• /scorekeep-frontend/Dockerfile: el cliente de la aplicación web Angular y el proxy nginx que
dirige el tráfico entrante.• /xray-daemon/Dockerfile: el demonio de X-Ray.
El Dockerfile del demonio de X-Ray crea una imagen basada en Amazon Linux que ejecuta el demonio deX-Ray. Descargue la imagen de ejemplo completa de Docker Hub.
Example Dockerfile: Amazon Linux
FROM amazonlinuxRUN yum install -y unzipRUN curl -o daemon.zip https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-linux-3.x.zipRUN unzip daemon.zip && cp xray /usr/bin/xrayENTRYPOINT ["/usr/bin/xray", "-t", "0.0.0.0:2000", "-b", "0.0.0.0:2000"]EXPOSE 2000/udpEXPOSE 2000/tcp
El archivo Make situado en el mismo directorio define los comandos para compilar la imagen, cargarla enAmazon ECR y ejecutarla localmente (p. 178).
Para ejecutar los contenedores en Amazon ECS, la ramificación incluye un script para generar un archivoDockerrun.aws.json, que se puede implementar en un entorno Multicontainer Docker en Elastic
161
AWS X-Ray Guía para desarrolladoresCódigo de inicio
Beanstalk. La plantilla utilizada por el script muestra cómo escribir una definición de tarea que configura laconexión de red entre los contenedores en Amazon ECS (p. 184).
Note
Dockerrun.aws.json es la versión de Elastic Beanstalk de un archivo de definición de tarea deAmazon ECS. Si no desea utilizar Elastic Beanstalk para crear el clúster de Amazon ECS, puedemodificar el archivo Dockerrun.aws.json para que se ejecute directamente en Amazon ECSeliminando la clave AWSEBDockerrunVersion del archivo.
Consulte el archivo README de la ramificación para obtener instrucciones sobre cómo implementarScorekeep en Amazon ECS.
Instrumentación de código de inicioEl X-Ray SDK for Java crea automáticamente segmentos para solicitudes entrantes. Siempre quehaya una solicitud en el ámbito, puede utilizar clientes instrumentados y registrar subsegmentos sinproblema. Sin embargo, si intenta utilizar un cliente instrumentado en código de inicio, obtendrá unaSegmentNotFoundException.
El código de inicio se ejecuta fuera del flujo de solicitud/respuesta estándar de una aplicación web, por loque necesita crear segmentos manualmente para instrumentarlo. Scorekeep muestra la instrumentación decódigo de inicio en sus archivos WebConfig. Scorekeep llama a una base de datos SQL y Amazon SNSdurante el startup.
162
AWS X-Ray Guía para desarrolladoresScripts
La clase WebConfig predeterminada crea una suscripción de Amazon SNS para notificaciones. Paraproporcionar un segmento para que el SDK de X-Ray escriba cuando se utiliza el cliente de Amazon SNS,Scorekeep llama a beginSegment y endSegment en la grabadora global.
Example src/main/java/scorekeep/WebConfig.java – Cliente AWS del SDKinstrumentado en código de inicio
AWSXRay.beginSegment("Scorekeep-init");if ( System.getenv("NOTIFICATION_EMAIL") != null ){ try { Sns.createSubscription(); } catch (Exception e ) { logger.warn("Failed to create subscription for email "+ System.getenv("NOTIFICATION_EMAIL")); }}AWSXRay.endSegment();
En RdsWebConfig, que Scorekeep utiliza cuando hay una base de datos de Amazon RDS conectada,la configuración también crea un segmento para el cliente SQL que utiliza Hibernate cuando aplica elesquema de base de datos durante el startup.
Example src/main/java/scorekeep/RdsWebConfig.java: cliente de base de datos SQLinstrumentado en el código de inicio
@PostConstructpublic void schemaExport() { EntityManagerFactoryImpl entityManagerFactoryImpl = (EntityManagerFactoryImpl) localContainerEntityManagerFactoryBean.getNativeEntityManagerFactory(); SessionFactoryImplementor sessionFactoryImplementor = entityManagerFactoryImpl.getSessionFactory(); StandardServiceRegistry standardServiceRegistry = sessionFactoryImplementor.getSessionFactoryOptions().getServiceRegistry(); MetadataSources metadataSources = new MetadataSources(new BootstrapServiceRegistryBuilder().build()); metadataSources.addAnnotatedClass(GameHistory.class); MetadataImplementor metadataImplementor = (MetadataImplementor) metadataSources.buildMetadata(standardServiceRegistry); SchemaExport schemaExport = new SchemaExport(standardServiceRegistry, metadataImplementor);
AWSXRay.beginSegment("Scorekeep-init"); schemaExport.create(true, true); AWSXRay.endSegment();}
SchemaExport se ejecuta de forma automática y utiliza un cliente SQL. Dado que el cliente estáinstrumentado, Scorekeep debe anular la implementación predeterminada y proporcionar un segmentopara que lo utilice el SDK cuando se llama al cliente.
Instrumentación de scriptsTambién puede instrumentar código que no forme parte de su aplicación. Cuando el demonio de X-Rayse está ejecutando, transmitirá los segmentos que reciba a X-Ray, incluso si no los ha generado el SDKde X-Ray. Scorekeep utiliza sus propios scripts para instrumentar la compilación que compila la aplicacióndurante la implementación.
Example bin/build.sh: script de compilación instrumentado
SEGMENT=$(python bin/xray_start.py)
163
AWS X-Ray Guía para desarrolladoresScripts
gradle build --quiet --stacktrace &> /var/log/gradle.log; GRADLE_RETURN=$?if (( GRADLE_RETURN != 0 )); then echo "Gradle failed with exit status $GRADLE_RETURN" >&2 python bin/xray_error.py "$SEGMENT" "$(cat /var/log/gradle.log)" exit 1fipython bin/xray_success.py "$SEGMENT"
xray_start.py, xray_error.py y xray_success.py son scripts de Python sencillos que construyenobjetos de segmento, los convierten a documentos JSON y los envían al demonio sobre UDP. Si lacompilación Gradle falla, puede encontrar el mensaje de error haciendo clic en el nodo scorekeep-build enel mapa de servicio de la consola de X-Ray.
164
AWS X-Ray Guía para desarrolladoresCliente
Instrumentación de un cliente de aplicación webEn la ramificación xray-cognito, Scorekeep utiliza Amazon Cognito para permitir que los usuarios creenuna cuenta e inicien sesión con ella para recuperar su información de usuario desde un grupo de usuariosde Amazon Cognito. Cuando un usuario inicia sesión, Scorekeep utiliza un grupo de identidad de AmazonCognito para obtener credenciales de AWS temporales para su uso con el AWS SDK for JavaScript.
El grupo de identidades está configurado para permitir a los usuarios que han iniciado sesión escribir datosde rastreos en AWS X-Ray. La aplicación web utiliza estas credenciales para registrar el ID del usuario queha iniciado sesión, la ruta del navegador y la vista del cliente de llamadas a la API Scorekeep.
La mayor parte del trabajo se realiza en una clase de servicio denominada xray. Este clase de servicioofrece métodos para generar los identificadores requeridos, crear segmentos en curso, finalizar segmentosy enviar documentos de segmento a la API de X-Ray.
Example public/xray.js: registrar y cargar segmentos
...
165
AWS X-Ray Guía para desarrolladoresCliente
service.beginSegment = function() { var segment = {}; var traceId = '1-' + service.getHexTime() + '-' + service.getHexId(24);
var id = service.getHexId(16); var startTime = service.getEpochTime();
segment.trace_id = traceId; segment.id = id; segment.start_time = startTime; segment.name = 'Scorekeep-client'; segment.in_progress = true; segment.user = sessionStorage['userid']; segment.http = { request: { url: window.location.href } };
var documents = []; documents[0] = JSON.stringify(segment); service.putDocuments(documents); return segment; }
service.endSegment = function(segment) { var endTime = service.getEpochTime(); segment.end_time = endTime; segment.in_progress = false; var documents = []; documents[0] = JSON.stringify(segment); service.putDocuments(documents); }
service.putDocuments = function(documents) { var xray = new AWS.XRay(); var params = { TraceSegmentDocuments: documents }; xray.putTraceSegments(params, function(err, data) { if (err) { console.log(err, err.stack); } else { console.log(data); } }) }
Estos métodos se llaman en el encabezado y funciones transformResponse en los servicios derecursos que la aplicación web utiliza para llamar a la API de Scorekeep. Para incluir el segmento decliente en el mismo rastreo que el segmento que genera la API, la aplicación web debe incluir el ID derastreo y el ID de segmento en un encabezado de seguimiento (p. 26) (X-Amzn-Trace-Id) que el SDKde X-Ray puede leer. Cuando la aplicación Java instrumentada recibe una solicitud con este encabezado,el X-Ray SDK for Java utiliza el mismo ID de rastreo y hace que el segmento del cliente de la aplicaciónweb sea el principal de su segmento.
Example public/app/services.js – Registro de segmentos para llamadas de recursosangulares y escritura de encabezados de rastreo
var module = angular.module('scorekeep');module.factory('SessionService', function($resource, api, XRay) { return $resource(api + 'session/:id', { id: '@_id' }, { segment: {},
166
AWS X-Ray Guía para desarrolladoresCliente
get: { method: 'GET', headers: { 'X-Amzn-Trace-Id': function(config) { segment = XRay.beginSegment(); return XRay.getTraceHeader(segment); } }, transformResponse: function(data) { XRay.endSegment(segment); return angular.fromJson(data); }, },...
El mapa de servicio resultante incluye un nodo para el cliente de la aplicación web.
Los rastreos que incluyen segmentos desde la aplicación web muestran la dirección URL que el usuario veen el navegador (rutas que empiezan por /#/). Sin la instrumentación de cliente, solo obtiene la direcciónURL del recurso de la API que la aplicación web llama (rutas que empiezan por /api/).
167
AWS X-Ray Guía para desarrolladoresSubprocesos de trabajo
Uso de clientes instrumentados en subprocesos detrabajo
Scorekeep utiliza un subproceso de empleado para publicar una notificación en Amazon SNS cuando unusuario gana un juego. La publicación de la notificación tarda más tiempo que el resto de las operacionesde solicitud combinadas y no afecta al cliente o al usuario. Por lo tanto, la realización de la tarea de formaasíncrona es una buena manera de mejorar el tiempo de respuesta.
Sin embargo, el X-Ray SDK for Java no sabe qué segmento estaba activo cuando se creó el subproceso.Por tanto, cuando se intenta utilizar el cliente AWS SDK for Java instrumentado dentro del subproceso,lanza una SegmentNotFoundException, bloqueando el subproceso.
Example Web-1.error.log
Exception in thread "Thread-2" com.amazonaws.xray.exceptions.SegmentNotFoundException: Failed to begin subsegment named 'AmazonSNS': segment cannot be found. at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method) at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:62) at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)...
Para solucionar este problema, la aplicación utiliza GetTraceEntity para obtener una referencia alsegmento en el subproceso principal y Entity.run() para ejecutar de forma segura el código delsubproceso de trabajo con acceso al contexto del segmento.
Example src/main/java/scorekeep/MoveFactory.java: – pasa el contexto de rastreo a unsubproceso de trabajo
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.AWSXRayRecorder;import com.amazonaws.xray.entities.Entity;import com.amazonaws.xray.entities.Segment;import com.amazonaws.xray.entities.Subsegment;... Entity segment = recorder.getTraceEntity();
168
AWS X-Ray Guía para desarrolladoresSubprocesos de trabajo
Thread comm = new Thread() { public void run() { segment.run(() -> { Subsegment subsegment = AWSXRay.beginSubsegment("## Send notification"); Sns.sendNotification("Scorekeep game completed", "Winner: " + userId); AWSXRay.endSubsegment(); } }
Dado que la solicitud ya se ha resuelto antes de la llamada a Amazon SNS, la aplicación crea unsubsegmento independiente para el subproceso. Esto impide que el SDK de X-Ray cierre el segmentoantes de que registre la respuesta desde Amazon SNS. Si no hay ningún subsegmento abierto cuandoScorekeep resuelve la solicitud, se podría perder la respuesta de Amazon SNS.
Consulte Transmisión de contexto de segmento entre subprocesos en una aplicaciónmultiproceso (p. 266) para obtener más información acerca de los subprocesos múltiples.
169
AWS X-Ray Guía para desarrolladoresVinculación en profundidad
Vinculación en profundidad a la consola de X-RayLas páginas de sesión y juego de la aplicación web Scorekeep utilizan la vinculación profunda para enlazara listas de seguimiento filtradas y mapas de servicio.
Example public/game.html: enlaces profundos
<div id="xray-link"> <p><a href="https://console.aws.amazon.com/xray/home#/traces?filter=http.url%20CONTAINS%20%22{{ gameid }}%22&timeRange=PT1H" target="blank">View traces for this game</a></p> <p><a href="https://console.aws.amazon.com/xray/home#/service-map&timeRange=PT1H" target="blank">View service map</a></p></div>
Consulte Vinculación en profundidad (p. 73) para obtener más información sobre cómo construir enlacesprofundos.
170
AWS X-Ray Guía para desarrolladoresDescargar el demonio
AWS X-RayDemonio deEl demonio de AWS X-Ray es una aplicación de software que escucha tráfico en el puerto UDP 2000,recopila datos sin procesar en segmentos y los retransmite a la API de AWS X-Ray. El demonio funcionaen combinación con los SDK de AWS X-Ray y debe mantenerse en ejecución para que los datos queenvíen los SDK puedan llegar al servicio de X-Ray.
Note
El demonio de X-Ray es un proyecto de código abierto. Puede seguir el proyecto, enviarproblemas y solicitudes de extracción en GitHub: github.com/aws/aws-xray-daemon
En AWS Lambda y AWS Elastic Beanstalk, utilice la integración de esos servicios con X-Ray para ejecutarel demonio. Lambda ejecuta el demonio automáticamente cada vez que se invoca una función para unasolicitud de muestreo. En Elastic Beanstalk, utilice la opción de configuración XRayEnabled (p. 180)para ejecutar el demonio en las instancias de su entorno.
Para ejecutar el X-Ray demonio de localmente, en las instalaciones o en otros AWS servicios de ,descárguelo, ejecútelo (p. 173)y, a continuación, asígnele permiso (p. 173) para cargar documentos desegmento en X-Ray.
Descargar el demonioPuede descargar el demonio de desde Amazon S3, Docker Hub o Amazon ECR y, a continuación,ejecutarlo localmente o instalarlo en una Amazon EC2 instancia durante el lanzamiento.
Amazon S3
Instaladores y ejecutables del demonio de X-Ray
• Linux (ejecutable): aws-xray-daemon-linux-3.x.zip (sig)• Linux (instalador RPM): aws-xray-daemon-3.x.rpm• Linux (instalador DEB): aws-xray-daemon-3.x.deb• Linux (ARM64, ejecutable) – aws-xray-daemon-linux-arm64-3.x.zip ([EMPTY])• Linux (ARM64, instalador de RPM) – aws-xray-daemon-arm64-3.x.rpm• Linux (ARM64, instalador DEB) – aws-xray-daemon-arm64-3.x.deb• OS X (ejecutable): aws-xray-daemon-macos-3.x.zip (sig)• Windows (ejecutable): aws-xray-daemon-windows-process-3.x.zip (sig)• Windows (servicio) : aws-xray-daemon-windows-service-3.x.zip (sig)
Estos enlaces siempre apuntan a la última versión del demonio. Para descargar una versiónespecífica, sustituya 3.x por el número de versión. Por ejemplo, 2.1.0.
X-RayLos recursos de se replican en buckets de las regiones admitidas. Para utilizar el bucket máscercano a usted o a sus recursos de AWS, sustituya la región de los enlaces anteriores por su región.
Amazon ECR
A partir de la versión 3.2.0 de , el demonio de se encuentra en Amazon ECR . Antes de extraer unaimagen, debe autenticar su cliente de Docker en el registro Amazon ECR público de .
171
AWS X-Ray Guía para desarrolladoresVerificación de la firma del archivo de demonio
Ejecute el siguiente comando para autenticarse en el registro de ECR público mediante get-login-password (AWS CLI):
aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws
Extraiga la última etiqueta de la versión publicada ejecutando el siguiente comando:
docker pull public.ecr.aws/xray/aws-xray-daemon:latest
Las versiones anteriores o alfa se pueden descargar reemplazando latest por alpha o un númerode versión específico. No se recomienda utilizar una imagen de demonio con una etiqueta alfa en unentorno de producción.
Docker Hub
El demonio de se encuentra en Docker Hub. Para descargar la última versión publicada, ejecute elsiguiente comando:
docker pull amazon/aws-xray-daemon:latest
Las versiones anteriores del demonio de se pueden lanzar reemplazando por latest la versióndeseada.
Verificación de la firma del archivo de demonioSe incluyen los archivos signature de GPG de los recursos de demonio comprimidos en archivos ZIP. Laclave pública es: aws-xray.gpg.
Puede utilizar la clave pública para verificar que el archivo ZIP del demonio es original y no se hamodificado. En primer lugar, importe la clave pública con GnuPG.
Para importar la clave pública
1. Descargue la clave pública.2. Importe la clave pública en su llavero.
$ gpg --import aws-xray.gpggpg: /Users/me/.gnupg/trustdb.gpg: trustdb createdgpg: key 7BFE036BFE6157D3: public key "AWS X-Ray <[email protected]>" importedgpg: Total number processed: 1gpg: imported: 1
Utilice la clave importada para verificar la firma del archivo ZIP del demonio.
Para verificar la firma de un archivo
1. Descargue el archivo y el archivo de firma.2. Ejecute gpg --verify para verificar la firma.
$ gpg --verify aws-xray-daemon-linux-3.0.0.zip.sig aws-xray-daemon-linux-3.0.0.zipgpg: Signature made Wed 19 Apr 2017 05:06:31 AM UTC using RSA key ID FE6157D3
172
AWS X-Ray Guía para desarrolladoresEjecutar el demonio
gpg: Good signature from "AWS X-Ray <[email protected]>"gpg: WARNING: This key is not certified with a trusted signature!gpg: There is no indication that the signature belongs to the owner.Primary key fingerprint: EA6D 9271 FBF3 6990 277F 4B87 7BFE 036B FE61 57D3
Tenga en cuenta la advertencia sobre confianza. Una clave solo es de confianza si la ha firmado usted oalguien en quien confíe. Esto no significa que la firma no sea válida, solo que no han verificado la clavepública.
Ejecutar el demonioEjecute el demonio localmente desde la línea de comandos. Utilice la opción -o para ejecutarlo en modolocal y -n para configurar la región.
~/Downloads$ ./xray -o -n us-east-2
Si desea obtener instrucciones específicas para cada plataforma, consulte estos temas:
• Linux (local) – Ejecución del demonio de X-Ray en Linux (p. 177)• Windows (local) – Ejecución del demonio de X-Ray en Windows (p. 179)• Elastic Beanstalk – Ejecución del demonio de X-Ray en AWS Elastic Beanstalk (p. 180)• Amazon EC2 – Ejecución del demonio de X-Ray en Amazon EC2 (p. 183)• Amazon ECS – Ejecución del demonio de X-Ray en Amazon ECS (p. 184)
Puede personalizar aún más el comportamiento del demonio utilizando las opciones de la línea decomandos o un archivo de configuración. Para obtener más información, consulte Configuración deldemonio de AWS X-Ray (p. 174).
Concesión de permiso al demonio para el envío dedatos a X-Ray
El X-Ray demonio utiliza el AWS SDK para cargar datos de rastreo en X-Rayy necesita AWS credencialescon permiso para hacerlo.
En Amazon EC2, el demonio utiliza el rol del perfil de instancia de la instancia de manera automática.Guarde localmente las claves de acceso en un archivo denominado credentials, que debe estar en lacarpeta .aws de su directorio de usuarios.
Example ~/.aws/credentials
[default]aws_access_key_id = AKIAIOSFODNN7EXAMPLEaws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Si especifica las credenciales en más de una ubicación (archivo de credenciales, perfil de instancia ovariables de entorno), la cadena de proveedores del SDK determina qué credenciales se utilizan. Paraobtener más información acerca de cómo proporcionar credenciales al SDK, consulte Especificación decredenciales en la Guía para desarrolladores del AWS SDK de para Go.
173
AWS X-Ray Guía para desarrolladoresX-RayRegistros del demonio de
El rol o usuario de IAM al cual pertenecen las credenciales del demonio deben tener el permiso de escribirdatos en el servicio de forma automática.
• Para utilizar el demonio en Amazon EC2, cree un nuevo rol del perfil de instancia o agregue una políticaadministrada a un rol existente.
• Para utilizar el demonio en Elastic Beanstalk, añada la política administrada al rol predeterminado delperfil de instancia de Elastic Beanstalk.
• Para ejecutar el demonio a nivel local, cree un usuario de IAM y guarde las claves de acceso en sucomputadora.
Para obtener más información, consulte Administración de identidad y acceso en AWS X-Ray (p. 30).
X-RayRegistros del demonio deEl demonio muestra información sobre la configuración y los segmentos actuales y luego la envía a AWSX-Ray.
2016-11-24T06:07:06Z [Info] Initializing AWS X-Ray daemon 2.1.02016-11-24T06:07:06Z [Info] Using memory limit of 49 MB2016-11-24T06:07:06Z [Info] 313 segment buffers allocated2016-11-24T06:07:08Z [Info] Successfully sent batch of 1 segments (0.123 seconds)2016-11-24T06:07:09Z [Info] Successfully sent batch of 1 segments (0.006 seconds)
De forma predeterminada, el daemon envía los logs a STDOUT. Si ejecuta el demonio en segundo plano,utilice la opción de línea de comandos --log-file o un archivo de configuración para establecer la rutadel archivo de log. También puede definir el nivel de log y deshabilitar la rotación de logs. Para obtenerinstrucciones, consulte Configuración del demonio de AWS X-Ray (p. 174).
En Elastic Beanstalk, la plataforma establece la ubicación de los logs del demonio. Para obtener másinformación, consulte Ejecución del demonio de X-Ray en AWS Elastic Beanstalk (p. 180).
Configuración del demonio de AWS X-RayPuede utilizar las opciones de la línea de comandos o un archivo de configuración para personalizarel comportamiento del demonio de X-Ray. La mayoría de las opciones están disponibles con ambosmétodos, pero algunas solo están disponibles en los archivos de configuración y otras solo en la línea decomandos.
Para empezar, la única opción que debe conocer es -n o --region, que se utiliza para establecer laregión que el demonio utiliza para enviar los datos de rastreo a X-Ray.
~/xray-daemon$ ./xray -n us-east-2
Si no ejecuta el demonio en Amazon EC2, sino localmente, puede agregar la opción -o para omitir lacomprobación de las credenciales del perfil de instancia, de modo que el demonio esté listo con mayorrapidez.
~/xray-daemon$ ./xray -o -n us-east-2
El resto de las opciones de la línea de comandos le permiten configurar el registro, escuchar en otropuerto, limitar la cantidad de memoria que puede utilizar el demonio o asumir un rol para enviar datos derastreo a otra cuenta.
174
AWS X-Ray Guía para desarrolladoresVariables de entorno admitidas
Puede pasar un archivo de configuración al demonio para tener acceso a las opciones avanzadas deconfiguración y realizar tareas como limitar el número de llamadas simultáneas a X-Ray, deshabilitar larotación de logs, y enviar tráfico a un proxy.
Secciones• Variables de entorno admitidas (p. 175)• Uso de las opciones de la línea de comandos (p. 175)• Uso de un archivo de configuración (p. 176)
Variables de entorno admitidasEl demonio de X-Ray admite las siguientes variables de entorno:
• AWS_REGION – Especifica la AWS región del punto de enlace de X-Ray servicio de .• HTTPS_PROXY – Especifica una dirección de proxy para que el demonio de cargue segmentos a través
de . Se pueden utilizar un nombre de dominio DNS o una dirección IP y los números de puerto queutilizan los servidores proxy.
Uso de las opciones de la línea de comandosPase estas opciones al demonio cuando lo ejecute localmente o con un script de datos de usuario.
Opciones de la línea de comandos
• -b, --bind – : escucha documentos de segmento en otro puerto UDP.
--bind "127.0.0.1:3000"
Valor predeterminado – 2000.• -t, --bind-tcp – : escucha las llamadas al X-Ray servicio en un puerto TCP diferente.
-bind-tcp "127.0.0.1:3000"
Valor predeterminado – 2000.• -c, --config – Carga un archivo de configuración que se obtiene a partir de la ruta específica.
--config "/home/ec2-user/xray-daemon.yaml"
• -f, --log-file – Envía los logs a la ruta específica del archivo.
--log-file "/var/log/xray-daemon.log"
• -l, --log-level – Muestra el nivel de log, desde el más detallado al menos detallado: dev, debug,info, warn, error, prod.
--log-level warn
Valor predeterminado – prod• -m, --buffer-memory – : permite cambiar la cantidad de memoria en MB que pueden utilizar los
búferes (mínimo 3).
175
AWS X-Ray Guía para desarrolladoresUso de un archivo de configuración
--buffer-memory 50
Predeterminado – 1% de memoria disponible• -o, --local-mode – No comprueba los metadatos de la instancia EC2.• -r, --role-arn – Asume el rol de IAM especificado para cargar segmentos a una cuenta diferente.
--role-arn "arn:aws:iam::123456789012:role/xray-cross-account"
• -a, Nombre de recurso de --resource-arn – Amazon (ARN) del AWS recurso que ejecuta el demoniode .
• -p, --proxy-address – Carga de segmentos en AWS X-Ray a través de un proxy. Debe especificarseel protocolo del servidor proxy.
--proxy-address "http://192.0.2.0:3000"
• -n, : --region – envía segmentos al X-Ray servicio de una región específica.• -v, --version – Muestra la versión del AWS X-Ray demonio.• -h, --help – Muestra la pantalla de ayuda.
Uso de un archivo de configuraciónTambién puede utilizar un archivo con formato YAML para configurar el demonio. Transfiera el archivo deconfiguración al demonio mediante la opción -c.
~$ ./xray -c ~/xray-daemon.yaml
Configuración de las opciones de archivo
• TotalBufferSizeMB – Tamaño máximo del búfer en MB (mínimo 3). Elija 0 para utilizar 1% dememoria del host.
• Concurrency – Número máximo de llamadas simultáneas a AWS X-Ray para cargar documentos desegmento.
• Region – Envíe segmentos al AWS X-Ray servicio de en una región específica.• Socket – Configura el enlace del demonio.
• UDPAddress – Cambia el puerto sobre el cual el demonio escucha tráfico.• TCPAddress – Escuche las llamadas al X-Ray servicio (p. 121) en otro puerto TCP.
• Logging – Configura el comportamiento de registro.• LogRotation – Establézcalo en false para deshabilitar la rotación de registros.• LogLevel – Cambie el nivel de registro, de más detallado a menos: dev, debug, info, warn, error,prod (predeterminado).
• LogPath – Envía los logs a la ruta específica del archivo.• LocalMode – Se configura en true para omitir la comprobación de los metadatos de la instancia EC2.• ResourceARN – Nombre de recurso de Amazon (ARN) del AWS recurso que ejecuta el demonio.• RoleARN – Asume el rol de IAM especificado para cargar segmentos a una cuenta diferente.• ProxyAddress – Cargue segmentos en AWS X-Ray a través de un proxy.• Endpoint – Cambie el punto de enlace de X-Ray servicio al que el demonio envía documentos de
segmento.
176
AWS X-Ray Guía para desarrolladoresEjecución del demonio localmente
• NoVerifySSL – Deshabilite la verificación del certificado TLS.• Version – Versión del formato del archivo de configuración del demonio. La versión del formato de
archivo es un campo obligatorio.
Example Xray-daemon.yaml
Este archivo de configuración cambia el puerto de escucha del demonio a 3000, desactiva lascomprobaciones de metadatos de instancias, establece el rol que se usará para cargar segmentos ycambia las opciones de región y registro.
Socket: UDPAddress: "127.0.0.1:3000" TCPAddress: "127.0.0.1:3000"Region: "us-west-2"Logging: LogLevel: "warn" LogPath: "/var/log/xray-daemon.log"LocalMode: trueRoleARN: "arn:aws:iam::123456789012:role/xray-cross-account"Version: 2
Ejecución del demonio de X-Ray localmentePuede ejecutar el demonio de AWS X-Ray localmente en Linux, MacOS, Windows o en un contenedor deDocker. Ejecute el demonio para transmitir los datos de seguimiento a X-Ray durante el desarrollo y laspruebas de una aplicación instrumentada. Descargue y extraiga el demonio mediante las instrucciones queencontrará aquí (p. 171).
Cuando se ejecuta localmente, el demonio puede leer las credenciales desde un archivo de credencialesdel AWS SDK (.aws/credentials en su directorio de usuarios) o desde variables de entorno. Paraobtener más información, consulte Concesión de permiso al demonio para el envío de datos a X-Ray (p. 173).
El demonio escucha los datos UDP en el puerto 2000. Puede cambiar el puerto y otras opciones medianteun archivo de configuración y distintas opciones de línea de comandos. Para obtener más información,consulte Configuración del demonio de AWS X-Ray (p. 174).
Ejecución del demonio de X-Ray en LinuxPuede ejecutar el demonio ejecutable desde la línea de comandos. Utilice la opción -o para ejecutarlo enmodo local y -n para configurar la región.
~/xray-daemon$ ./xray -o -n us-east-2
Para ejecutar el demonio en segundo plano, use &.
~/xray-daemon$ ./xray -o -n us-east-2 &
Finalice un proceso de demonio que se ejecuta en segundo plano con pkill.
~$ pkill xray
177
AWS X-Ray Guía para desarrolladoresEjecución del demonio de X-Ray en un contenedor Docker
Ejecución del demonio de X-Ray en un contenedorDockerPara ejecutar el demonio localmente en un contenedor de Docker, guarde el texto siguiente en un archivodenominado Dockerfile. Descargue la imagen de ejemplo completa de Docker Hub.
Example Dockerfile: Amazon Linux
FROM amazonlinuxRUN yum install -y unzipRUN curl -o daemon.zip https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-linux-3.x.zipRUN unzip daemon.zip && cp xray /usr/bin/xrayENTRYPOINT ["/usr/bin/xray", "-t", "0.0.0.0:2000", "-b", "0.0.0.0:2000"]EXPOSE 2000/udpEXPOSE 2000/tcp
Compile la imagen del contenedor con docker build.
~/xray-daemon$ docker build -t xray-daemon .
Ejecute la imagen en un contenedor con docker run.
~/xray-daemon$ docker run \ --attach STDOUT \ -v ~/.aws/:/root/.aws/:ro \ --net=host \ -e AWS_REGION=us-east-2 \ --name xray-daemon \ -p 2000:2000/udp \ xray-daemon -o
Este comando utiliza las siguientes opciones:
• --attach STDOUT – Ver la salida del demonio en el terminal.• -v ~/.aws/:/root/.aws/:ro – Conceda al contenedor acceso de solo lectura al .aws directorio
para que pueda leer sus credenciales del AWS SDK.• AWS_REGION=us-east-2 – Establezca la variable de AWS_REGION entorno para indicar al demonio de
la región que debe utilizar.• --net=host – Conecte el contenedor a la host red. Los contenedores de la red host pueden
comunicarse entre sí sin publicar puertos.• -p 2000:2000/udp – Asigne el puerto UDP 2000 de su equipo al mismo puerto del contenedor. Esto
no es necesario para que se comuniquen los contenedores de la misma red, pero sí permite enviarsegmentos al demonio desde la línea de comandos (p. 105) o desde una aplicación que no se ejecutaen Docker.
• --name xray-daemon – Asigne un nombre al contenedor xray-daemon en lugar de generar unnombre aleatorio.
• -o (después del nombre de la imagen): – añada la -o opción al punto de entrada que ejecuta el demoniodentro del contenedor. Esta opción indica al demonio que se ejecute en modo local para impedirle queintente leer los metadatos de la instancia Amazon EC2.
Para detener el demonio, utilice docker stop. Si realiza cambios en el archivo Dockerfile y crea unaimagen nueva, debe eliminar el contenedor existente para poder crear otra con el mismo nombre. Utilicedocker rm para eliminar el contenedor.
178
AWS X-Ray Guía para desarrolladoresEjecución del demonio de X-Ray en Windows
$ docker stop xray-daemon$ docker rm xray-daemon
La aplicación de ejemplo Scorekeep muestra cómo utilizar el demonio de X-Ray en un contenedor deDocker. Para obtener más información, consulte Instrumentación de aplicaciones de Amazon ECS (p. 161).
Ejecución del demonio de X-Ray en WindowsPuede ejecutar el demonio ejecutable desde la línea de comandos. Utilice la opción -o para ejecutarlo enmodo local y -n para configurar la región.
> .\xray_windows.exe -o -n us-east-2
Utilice un script en PowerShell para crear y ejecutar un servicio para el demonio.
Example PowerShell script: Windows
if ( Get-Service "AWSXRayDaemon" -ErrorAction SilentlyContinue ){ sc.exe stop AWSXRayDaemon sc.exe delete AWSXRayDaemon}if ( Get-Item -path aws-xray-daemon -ErrorAction SilentlyContinue ) { Remove-Item -Recurse -Force aws-xray-daemon}
$currentLocation = Get-Location$zipFileName = "aws-xray-daemon-windows-service-3.x.zip"$zipPath = "$currentLocation\$zipFileName"$destPath = "$currentLocation\aws-xray-daemon"$daemonPath = "$destPath\xray.exe"$daemonLogPath = "C:\inetpub\wwwroot\xray-daemon.log"$url = "https://s3.dualstack.us-west-2.amazonaws.com/aws-xray-assets.us-west-2/xray-daemon/aws-xray-daemon-windows-service-3.x.zip"
Invoke-WebRequest -Uri $url -OutFile $zipPathAdd-Type -Assembly "System.IO.Compression.Filesystem"[io.compression.zipfile]::ExtractToDirectory($zipPath, $destPath)
sc.exe create AWSXRayDaemon binPath= "$daemonPath -f $daemonLogPath"sc.exe start AWSXRayDaemon
Ejecución del demonio de X-Ray en OS XPuede ejecutar el demonio ejecutable desde la línea de comandos. Utilice la opción -o para ejecutarlo enmodo local y -n para configurar la región.
~/xray-daemon$ ./xray_mac -o -n us-east-2
Para ejecutar el demonio en segundo plano, use &.
~/xray-daemon$ ./xray_mac -o -n us-east-2 &
Utilice nohup para evitar que el demonio finalice cuando se cierre la terminal.
~/xray-daemon$ nohup ./xray_mac &
179
AWS X-Ray Guía para desarrolladoresEn Elastic Beanstalk
Ejecución del demonio de X-Ray en AWS ElasticBeanstalk
Para retransmitir los datos de rastreo desde su aplicación a AWS X-Ray, puede ejecutar el demoniode X-Ray en las instancias Elastic Beanstalk de su entorno de Amazon EC2. Para obtener una lista deplataformas compatibles, consulte Configuración de AWS X-Ray la depuración en la Guía para AWSElastic Beanstalk desarrolladores de .
Note
El demonio utiliza el perfil de instancia del entorno para obtener permiso. Para obtenerinstrucciones sobre cómo añadir permisos al perfil de instancia de Elastic Beanstalk, consulteConcesión de permiso al demonio para el envío de datos a X-Ray (p. 173).
Elastic BeanstalkLas plataformas de proporcionan una opción de configuración que puede establecer paraejecutar el demonio de forma automática. Puede habilitar el demonio en un archivo de configuración en elcódigo fuente o mediante la opción disponible en la consola de Elastic Beanstalk. Cuando habilita la opciónde configuración, el demonio se instala en la instancia y se ejecuta como servicio.
Es posible que la versión incluida en las plataformas de Elastic Beanstalk no sea la versión más reciente.Consulte Plataformas compatibles para ver qué versión del demonio está disponible para la configuraciónde la plataforma que utiliza.
Elastic Beanstalk no proporciona el demonio de X-Ray en la plataforma Multicontainer Docker (AmazonECS). En la aplicación de ejemplo Scorekeep puede verse cómo se utiliza el demonio de X-Ray enAmazon ECS con Elastic Beanstalk. Para obtener más información, consulte Instrumentación deaplicaciones de Amazon ECS (p. 161).
Uso de la integración de Elastic Beanstalk en X-Raypara ejecutar el demonio de X-RayUtilice la consola para activar la integración de X-Ray o configúrela en el código fuente de la aplicación conun archivo de configuración.
Para habilitar el demonio de X-Ray en la consola Elastic Beanstalk, realice los siguientes pasos:
1. Open the Elastic Beanstalk console.2. Navigate to the management console for your environment.3. Choose Configuration.4. Elija Software Settings (Configuración de software).5. En X-Ray daemon, elija Enabled.6. Seleccione Apply.
Puede incluir un archivo de configuración en el código fuente para que la configuración sea portátil entreentornos.
Example .ebextensions/xray-daemon.config
option_settings: aws:elasticbeanstalk:xray: XRayEnabled: true
Elastic Beanstalk le transfiere un archivo de configuración al demonio y envía los logs a una ubicaciónestándar.
180
AWS X-Ray Guía para desarrolladoresDescarga y ejecución del demoniode X-Ray manualmente (avanzado)
En plataformas Windows Server
• Archivo de configuración – C:\Program Files\Amazon\XRay\cfg.yaml• Registros – c:\Program Files\Amazon\XRay\logs\xray-service.log
En plataformas Linux
• Archivo de configuración – /etc/amazon/xray/cfg.yaml• Registros – /var/log/xray/xray.log
Elastic Beanstalk proporciona herramientas para extraer registros de instancias de la Consola deadministración de AWS o de la línea de comandos. Puede indicar a Elastic Beanstalk que incluya losregistros del demonio de X-Ray añadiendo una tarea con un archivo de configuración.
Example .ebextensions/xray-logs.config - Linux
files: "/opt/elasticbeanstalk/tasks/taillogs.d/xray-daemon.conf" : mode: "000644" owner: root group: root content: | /var/log/xray/xray.log
Example .ebextensions/xray-logs.config: Windows Server
files: "c:/Program Files/Amazon/ElasticBeanstalk/config/taillogs.d/xray-daemon.conf" : mode: "000644" owner: root group: root content: | c:\Progam Files\Amazon\XRay\logs\xray-service.log
Consulte Visualización de registros desde las Elastic Beanstalk Amazon EC2 instancias del entorno en laGuía AWS Elastic Beanstalk para desarrolladores de para obtener más información.
Descarga y ejecución del demonio de X-Raymanualmente (avanzado)Si el demonio de X-Ray no está disponible para la configuración de la plataforma, puede descargarlodesde Amazon S3 y ejecutarlo con un archivo de configuración.
Utilice un archivo de configuración de Elastic Beanstalk para descargar y ejecutar el demonio.
Example .ebextensions/xray.config - Linux
commands: 01-stop-tracing: command: yum remove -y xray ignoreErrors: true 02-copy-tracing: command: curl https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-3.x.rpm -o /home/ec2-user/xray.rpm 03-start-tracing:
181
AWS X-Ray Guía para desarrolladoresDescarga y ejecución del demoniode X-Ray manualmente (avanzado)
command: yum install -y /home/ec2-user/xray.rpm
files: "/opt/elasticbeanstalk/tasks/taillogs.d/xray-daemon.conf" : mode: "000644" owner: root group: root content: | /var/log/xray/xray.log "/etc/amazon/xray/cfg.yaml" : mode: "000644" owner: root group: root content: | Logging: LogLevel: "debug" Version: 2
Example .ebextensions/xray.config: Windows Server
container_commands: 01-execute-config-script: command: Powershell.exe -ExecutionPolicy Bypass -File c:\\temp\\installDaemon.ps1 waitAfterCompletion: 0 files: "c:/temp/installDaemon.ps1": content: | if ( Get-Service "AWSXRayDaemon" -ErrorAction SilentlyContinue ) { sc.exe stop AWSXRayDaemon sc.exe delete AWSXRayDaemon }
$targetLocation = "C:\Program Files\Amazon\XRay" if ((Test-Path $targetLocation) -eq 0) { mkdir $targetLocation }
$zipFileName = "aws-xray-daemon-windows-service-3.x.zip" $zipPath = "$targetLocation\$zipFileName" $destPath = "$targetLocation\aws-xray-daemon" if ((Test-Path $destPath) -eq 1) { Remove-Item -Recurse -Force $destPath }
$daemonPath = "$destPath\xray.exe" $daemonLogPath = "$targetLocation\xray-daemon.log" $url = "https://s3.dualstack.us-west-2.amazonaws.com/aws-xray-assets.us-west-2/xray-daemon/aws-xray-daemon-windows-service-3.x.zip"
Invoke-WebRequest -Uri $url -OutFile $zipPath Add-Type -Assembly "System.IO.Compression.Filesystem" [io.compression.zipfile]::ExtractToDirectory($zipPath, $destPath)
New-Service -Name "AWSXRayDaemon" -StartupType Automatic -BinaryPathName "`"$daemonPath`" -f `"$daemonLogPath`"" sc.exe start AWSXRayDaemon encoding: plain "c:/Program Files/Amazon/ElasticBeanstalk/config/taillogs.d/xray-daemon.conf" : mode: "000644" owner: root group: root content: | C:\Program Files\Amazon\XRay\xray-daemon.log
182
AWS X-Ray Guía para desarrolladoresEn Amazon EC2
Estos ejemplos también añaden el archivo de registro del demonio a la tarea de registros de finalizaciónde Elastic Beanstalk para incluirlo cuando se soliciten registros con la consola o la interfaz de línea decomandos de Elastic Beanstalk (CLI de EB).
Ejecución del demonio de X-Ray en Amazon EC2Puede ejecutar el demonio de X-Ray en los siguientes sistemas operativos en Amazon EC2:
• Amazon Linux• Ubuntu• Windows Server (2012 R2 y posteriores)
Utilice un perfil de instancia para conceder permiso al demonio para cargar datos de rastreo a X-Ray.Para obtener más información, consulte Concesión de permiso al demonio para el envío de datos a X-Ray (p. 173).
Utilice un script de datos de usuario para ejecutar el demonio de manera automática cuando inicie lainstancia.
Example Script de datos de usuario: Linux
#!/bin/bashcurl https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-3.x.rpm -o /home/ec2-user/xray.rpmyum install -y /home/ec2-user/xray.rpm
Example Script de datos de usuario: Windows Server
<powershell>if ( Get-Service "AWSXRayDaemon" -ErrorAction SilentlyContinue ) { sc.exe stop AWSXRayDaemon sc.exe delete AWSXRayDaemon}
$targetLocation = "C:\Program Files\Amazon\XRay"if ((Test-Path $targetLocation) -eq 0) { mkdir $targetLocation}
$zipFileName = "aws-xray-daemon-windows-service-3.x.zip"$zipPath = "$targetLocation\$zipFileName"$destPath = "$targetLocation\aws-xray-daemon"if ((Test-Path $destPath) -eq 1) { Remove-Item -Recurse -Force $destPath}
$daemonPath = "$destPath\xray.exe"$daemonLogPath = "$targetLocation\xray-daemon.log"$url = "https://s3.dualstack.us-west-2.amazonaws.com/aws-xray-assets.us-west-2/xray-daemon/aws-xray-daemon-windows-service-3.x.zip"
Invoke-WebRequest -Uri $url -OutFile $zipPathAdd-Type -Assembly "System.IO.Compression.Filesystem"[io.compression.zipfile]::ExtractToDirectory($zipPath, $destPath)
New-Service -Name "AWSXRayDaemon" -StartupType Automatic -BinaryPathName "`"$daemonPath`" -f `"$daemonLogPath`""sc.exe start AWSXRayDaemon
183
AWS X-Ray Guía para desarrolladoresEn Amazon ECS
</powershell>
Ejecución del demonio de X-Ray en Amazon ECSEn Amazon ECS, cree una imagen de Docker que ejecute el demonio de X-Ray, súbala al repositoriode imágenes de Docker y luego impleméntela en su clúster de Amazon ECS. Puede utilizar mapeosde puertos y la configuración del modo de red en el archivo de definición de tareas para permitir que laaplicación se comunique con el contenedor del demonio.
Uso de la imagen de Docker oficial de laX-Ray proporciona una imagen del contenedor de Docker que puede implementar junto con la aplicación.
$ docker pull amazon/aws-xray-daemon
Example Definición de tarea
{ "name": "xray-daemon", "image": "amazon/aws-xray-daemon", "cpu": 32, "memoryReservation": 256, "portMappings" : [ { "hostPort": 0, "containerPort": 2000, "protocol": "udp" } ] }
Creación y compilación de una imagen de DockerSi desea realizar una configuración personalizada, es posible que tenga que definir su propia imagen deDocker.
Note
En la aplicación de ejemplo Scorekeep puede verse cómo se utiliza el demonio de X-Ray enAmazon ECS. Para obtener más información, consulte Instrumentación de aplicaciones deAmazon ECS (p. 161).
Añada políticas administradas al rol de tarea para conceder permiso al demonio para cargar datos derastreo en X-Ray. Para obtener más información, consulte Concesión de permiso al demonio para el envíode datos a X-Ray (p. 173).
Utilice uno de los siguientes Dockerfiles para crear una imagen que ejecute el demonio.
Example Dockerfile: Amazon Linux
FROM amazonlinuxRUN yum install -y unzipRUN curl -o daemon.zip https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-linux-3.x.zipRUN unzip daemon.zip && cp xray /usr/bin/xray
184
AWS X-Ray Guía para desarrolladoresCreación y compilación de una imagen de Docker
ENTRYPOINT ["/usr/bin/xray", "-t", "0.0.0.0:2000", "-b", "0.0.0.0:2000"]EXPOSE 2000/udpEXPOSE 2000/tcp
Note
Las marcas -t y -b son necesarias para especificar una dirección de enlace que escuche elbucle invertido de un entorno con varios contenedores.
Example Dockerfile – Ubuntu
Para los derivados de Debian, tendrá que instalar certificados de una autoridad de certificación (CA) paraevitar problemas al descargar el instalador.
FROM ubuntu:16.04RUN apt-get update && apt-get install -y --force-yes --no-install-recommends apt-transport-https curl ca-certificates wget && apt-get clean && apt-get autoremove && rm -rf /var/lib/apt/lists/*RUN wget https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-3.x.debRUN dpkg -i aws-xray-daemon-3.x.debENTRYPOINT ["/usr/bin/xray", "--bind=0.0.0.0:2000", "--bind-tcp=0.0.0.0:2000"]EXPOSE 2000/udpEXPOSE 2000/tcp
En la definición de tarea, la configuración depende del modo de red que se utilice. El modo de red puentees la opción predeterminada y se puede utilizar en la VPC predeterminada. En una red en modo puente,establezca la variable de entorno AWS_XRAY_DAEMON_ADDRESS para indicar al SDK de X-Ray a quépuerto del contenedor se ha de hacer referencia y establezca el puerto de host. Por ejemplo, podríapublicar el puerto UDP 2000 y crear un enlace desde el contenedor de la aplicación hasta el contenedordel demonio.
Example Definición de tarea
{ "name": "xray-daemon", "image": "123456789012.dkr.ecr.us-east-2.amazonaws.com/xray-daemon", "cpu": 32, "memoryReservation": 256, "portMappings" : [ { "hostPort": 0, "containerPort": 2000, "protocol": "udp" } ] }, { "name": "scorekeep-api", "image": "123456789012.dkr.ecr.us-east-2.amazonaws.com/scorekeep-api", "cpu": 192, "memoryReservation": 512, "environment": [ { "name" : "AWS_REGION", "value" : "us-east-2" }, { "name" : "NOTIFICATION_TOPIC", "value" : "arn:aws:sns:us-east-2:123456789012:scorekeep-notifications" }, { "name" : "AWS_XRAY_DAEMON_ADDRESS", "value" : "xray-daemon:2000" } ], "portMappings" : [ { "hostPort": 5000,
185
AWS X-Ray Guía para desarrolladoresConfiguración de las opciones de línea decomandos en la consola de Amazon ECS
"containerPort": 5000 } ], "links": [ "xray-daemon" ] }
Si ejecuta el clúster en la subred privada de una VPC, puede utilizar el modo de red awsvpc paraasociar una interfaz de red elástica (ENI) a los contenedores. De este modo, puede evitar utilizarenlaces. Omita el puerto de host en los mapeos de puertos, el enlace y la variable de entornoAWS_XRAY_DAEMON_ADDRESS.
Example Definición de tarea de VPC
{ "family": "scorekeep", "networkMode":"awsvpc", "containerDefinitions": [ { "name": "xray-daemon", "image": "123456789012.dkr.ecr.us-east-2.amazonaws.com/xray-daemon", "cpu": 32, "memoryReservation": 256, "portMappings" : [ { "containerPort": 2000, "protocol": "udp" } ] }, { "name": "scorekeep-api", "image": "123456789012.dkr.ecr.us-east-2.amazonaws.com/scorekeep-api", "cpu": 192, "memoryReservation": 512, "environment": [ { "name" : "AWS_REGION", "value" : "us-east-2" }, { "name" : "NOTIFICATION_TOPIC", "value" : "arn:aws:sns:us-east-2:123456789012:scorekeep-notifications" } ], "portMappings" : [ { "containerPort": 5000 } ] } ]}
Configuración de las opciones de línea de comandosen la consola de Amazon ECSLas opciones de línea de comandos anulan cualquier valor que presente algún conflicto del archivo deconfiguración de la imagen. Las opciones de línea de comandos se suelen utilizar para pruebas locales,pero también se pueden utilizar para mayor comodidad al establecer variables de entorno o con el fin decontrolar el proceso de inicio.
Al añadir opciones de línea de comandos, se actualiza el CMD de Docker que se pasa al contenedor. Paraobtener más información, consulte Docker run reference.
186
AWS X-Ray Guía para desarrolladoresConfiguración de las opciones de línea decomandos en la consola de Amazon ECS
Para establecer una opción de línea de comandos
1. Abra la consola de Amazon ECS en https://console.aws.amazon.com/ecs/.2. En la barra de navegación, seleccione la región que contiene la definición de tarea.3. En el panel de navegación, elija Task Definitions.4. En la página Task Definitions, seleccione la casilla situada a la izquierda de la definición de tarea que
revisar y seleccione Create new revision.5. En la página Create new revision of Task Definition (Crear nueva revisión de definición de tarea),
seleccione el contenedor.6. En la sección ENVIRONMENT (ENTORNO), añada al campo Command (Comando) la lista de
opciones de línea de comandos separadas por comas.7. Elija Update (Actualizar).8. Verifique la información y seleccione Create.
En el ejemplo siguiente se muestra cómo escribir una opción de línea de comandos separada por comaspara la opción RoleARN. La opción RoleARN asume el rol de IAM especificado para cargar segmentos enuna cuenta diferente.
Example
--role-arn, arn:aws:iam::123456789012:role/xray-cross-account
Para obtener más información sobre las opciones de línea de comandos disponibles en X-Ray, consulteConfiguración del AWS X-Ray (p. 174)demonio de .
187
AWS X-Ray Guía para desarrolladoresAPI Gateway
Integración de AWS X-Ray con otrosservicios de AWS
Otros AWS servicios de proporcionan integración con AWS X-Ray añadiendo un encabezado de rastreo alas solicitudes, ejecutando el X-Ray demonio de o tomando decisiones de muestreo y cargando datos derastreo en X-Ray.
Note
Los SDK de X-Ray incluyen complementos para llevar a cabo una integración adicional conlos servicios de AWS. Por ejemplo, puede utilizar el complemento X-Ray del SDK de ElasticBeanstalk para Java para agregar información acerca del entorno de Elastic Beanstalk queejecuta su aplicación, incluidos el nombre e ID del entorno.
Temas• Amazon API Gateway Compatibilidad de seguimiento activo de para AWS X-Ray (p. 188)• Amazon EC2 y AWS App Mesh (p. 189)• AWS AppSync y AWS X-Ray (p. 191)• Registro de llamadas a X-Ray la API de con AWS CloudTrail (p. 191)• Monitoreo de puntos de enlace y API con CloudWatch (p. 193)• Seguimiento de los cambios en la configuración de cifrado de X-Ray con AWS Config (p. 199)• Amazon Elastic Compute Cloud y AWS X-Ray (p. 202)• AWS Elastic Beanstalk y AWS X-Ray (p. 202)• Elastic Load Balancing y AWS X-Ray (p. 203)• Amazon EventBridge y AWS X-Ray (p. 203)• AWS Lambda y AWS X-Ray (p. 208)• Amazon SNS y AWS X-Ray (p. 209)• AWS Step Functions y AWS X-Ray (p. 213)• Amazon SQS y AWS X-Ray (p. 214)• Amazon S3 y AWS X-Ray (p. 216)
Amazon API Gateway Compatibilidad deseguimiento activo de para AWS X-Ray
Puede utilizar X-Ray para realizar un seguimiento y analizar las solicitudes de los usuarios a medida queavanzan a través de las API de Amazon API Gateway hasta los servicios subyacentes. API Gatewaypermite el rastreo de X-Ray en todos los tipos de puntos de enlace de API Gateway: regionales,optimizados para bordes y privados. Puede utilizar X-Ray con Amazon API Gateway en todas las AWSregiones donde X-Ray está disponible. Para obtener más información, consulte Rastro de la ejecución deAPI de API Gateway con AWS X-Ray en la Guía para desarrolladores de Amazon API Gateway.
Note
X-Ray solo admite el rastreo de para APIs REST a través de API Gateway.
Amazon API Gateway proporciona compatibilidad de rastreo activo (p. 6) para AWS X-Ray. Habilite elrastreo activo en sus etapas de la API para realizar el muestreo de solicitudes entrantes y enviar rastros aX-Ray.
188
AWS X-Ray Guía para desarrolladoresApp Mesh
Para habilitar el rastreo activo en una etapa de la API
1. Abra la consola de API Gateway en https://console.aws.amazon.com/apigateway/.2. Elegir una API.3. Elegir una etapa.4. En la pestaña Logs/Tracing (Registros/rastreo), elija Enable Tracing X-Ray(Habilitar rastreo).5. Seleccione Resources (Recursos) en el panel de navegación del lado izquierdo.6. Para volver a implementar la API con la nueva configuración, elija Actions (Acciones), Deploy API
(Implementar API).
API Gateway utiliza reglas de muestreo que define en la consola de X-Ray para determinar qué solicitudesregistrar. Puede crear reglas que solo se aplican a las API o que se aplican únicamente a las solicitudesque contienen determinados encabezados. API Gateway registra los encabezados en atributos enel segmento, junto con detalles acerca de la fase y solicitud. Para obtener más información, consulteConfiguración de reglas de muestreo en la consola de X-Ray (p. 76).
Para todas las solicitudes entrantes, API Gateway añade un encabezado de rastreo (p. 26) a solicitudesHTTP entrantes que no tienen uno.
X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793
Formato de ID de rastro
Un trace_id consta de tres números separados por guiones. Por ejemplo, 1-58406520-a006649127e371903a2de979. Esto incluye:
• El número de versión, es decir, 1.• La hora en que se realizó la solicitud original, la fecha en Unix, en 8 dígitos hexadecimales.
Por ejemplo, el 1 de diciembre de 2016 a las 10:00 a. m. PST en formato de tiempo Unix es1480615200 segundos o 58406520 en formato hexadecimal.
• Un identificador 96 bits del rastro, único a nivel global en 24 dígitos hexadecimales.
Si el rastreo activo está deshabilitado, la fase sigue registrando un segmento si la solicitud procedede un servicio que ha muestreado la solicitud e iniciado un rastreo. Por ejemplo, una aplicación webinstrumentada puede llamar a una API API Gateway con un cliente HTTP. Cuando instrumente uncliente HTTP con el SDK X-Ray, agrega un encabezado de rastreo a la solicitud saliente que contiene ladecisión de muestreo. API Gateway lee el encabezado de rastreo y crea un segmento para las solicitudesmuestreadas.
Si utiliza API Gateway para generar un SDK de Java para la API, puede instrumentar el cliente delSDK añadiendo un controlador de solicitudes con el compilador de clientes, de la misma forma queinstrumentaría manualmente un cliente del AWS SDK. Para obtener instrucciones, consulte Seguimientode llamadas al AWS SDK con la X-Ray SDK for Java (p. 254).
Amazon EC2 y AWS App MeshAWS X-Ray se integra con AWS App Mesh para administrar proxies de Envoy en microservicios. AppMesh proporciona una versión de Envoy que se puede configurar para que envíe datos de seguimientoal demonio de X-Ray que se ejecuta en un contenedor de la misma tarea o pod. X-Ray permite utilizar elseguimiento con los siguientes servicios de App Mesh compatibles:
• Amazon Elastic Container Service (Amazon ECS)
189
AWS X-Ray Guía para desarrolladoresApp Mesh
• Amazon Elastic Kubernetes Service (Amazon EKS)• Amazon Elastic Compute Cloud (Amazon EC2)
Utilice las siguientes instrucciones para aprender a habilitar el X-Ray rastreo de a través de App Mesh.
Para configurar el proxy de Envoy para enviar datos a X-Ray, establezca lavariableENABLE_ENVOY_XRAY_TRACING de entorno en su definición de contenedor.
Example Definición del contenedor de Envoy para Amazon ECS
{ "name": "envoy", "image": "840364872350.dkr.ecr.us-west-2.amazonaws.com/aws-appmesh-envoy:v1.15.1.0-prod", "essential": true, "environment": [ { "name": "APPMESH_VIRTUAL_NODE_NAME", "value": "mesh/myMesh/virtualNode/myNode" }, { "name": "ENABLE_ENVOY_XRAY_TRACING", "value": "1" } ], "healthCheck": { "command": [ "CMD-SHELL", "curl -s http://localhost:9901/server_info | cut -d' ' -f3 | grep -q live" ],
190
AWS X-Ray Guía para desarrolladoresAWS AppSync
"startPeriod": 10, "interval": 5, "timeout": 2, "retries": 3 }
Note
Para obtener más información sobre las direcciones de región de Envoy disponibles, consulteImagen de Envoy en la Guía del usuario de AWS App Mesh.
Para obtener más información sobre la ejecución del demonio de X-Ray en un contenedor, consulteEjecución del demonio de X-Ray en Amazon ECS (p. 184). Para ver una aplicación de ejemplo quecontiene una malla de servicios, un microservicio, un proxy de Envoy y un demonio de X-Ray, implementeel ejemplo colorapp del repositorio de GitHub de ejemplos de App Mesh.
Más información
• Introducción a AWS App Mesh• Introducción a AWS App Mesh y Amazon ECS
AWS AppSync y AWS X-RayPuede habilitar y rastrear solicitudes para AWS AppSync. Para obtener más información, consulteSeguimiento con AWS X-Ray para obtener instrucciones.
Cuando el X-Ray rastreo de está habilitado para una API de AWS AppSync, se crea automáticamente unrolAWS vinculado al servicio Identity and Access Management en su cuenta con los permisos adecuados.Esto permite a AWS AppSync enviar registros de seguimiento a X-Ray de forma segura.
Registro de llamadas a X-Ray la API de con AWSCloudTrail
AWS X-Ray se integra con AWS CloudTrail para registrar las acciones de la API realizadas por un usuario,un rol o un servicio de AWS en X-Ray. Puede utilizar CloudTrail para monitorizar las solicitudes a la APIde X-Ray en tiempo real y almacenar registros en Amazon S3, Amazon CloudWatch Logs y AmazonCloudWatch Events. X-Ray admite el registro de las siguientes acciones como eventos en archivos deregistro de CloudTrail:
Acciones de la API admitidas
• PutEncryptionConfig
• GetEncryptionConfig
• CreateGroup
• UpdateGroup
• DeleteGroup
• GetGroup
• GetGroups
• GetInsight
• GetInsightEvents
• GetInsightImpactGraph
191
AWS X-Ray Guía para desarrolladoresCloudTrail
• GetInsightSummaries
Para crear un registro de seguimiento
1. Abra la página Trails (Registros de seguimiento) de la consola de CloudTrail.2. Elija Create trail.3. Escriba un nombre de registro de seguimiento y elija los tipos de eventos que desea registrar.
• Eventos de – administración: registre acciones de la API que crean, leen, actualizan o eliminanAWS recursos de . Se registran las llamadas a todas las acciones de la API admitidas en todos losservicios de AWS.
• Eventos de datos – Registre acciones de la API que se dirijan a recursos específicos, como lecturasde Amazon S3 objetos o invocaciones de AWS Lambda funciones. Elija qué buckets y funcionesdesea monitorear.
4. Elija un bucket de Amazon S3; y la configuración de cifrado.5. Seleccione Create (Crear).
CloudTrail registra las llamadas a la API de los tipos seleccionados en archivos de registro de Amazon S3.Un log de CloudTrail es una matriz desordenada de eventos con formato JSON. En cada llamada que serealiza a una acción de la API admitida, CloudTrail registra información sobre la solicitud y la entidad quela hizo. Los eventos de log incluyen el nombre de la acción, los parámetros y la respuesta de X-Ray, asícomo los datos del solicitante.
Example X-RayEntrada de log de GetEncryptionConfig en
{ "eventVersion"=>"1.05", "userIdentity"=>{ "type"=>"AssumedRole", "principalId"=>"AROAJVHBZWD3DN6CI2MHM:MyName", "arn"=>"arn:aws:sts::123456789012:assumed-role/MyRole/MyName", "accountId"=>"123456789012", "accessKeyId"=>"AKIAIOSFODNN7EXAMPLE", "sessionContext"=>{ "attributes"=>{ "mfaAuthenticated"=>"false", "creationDate"=>"2018-9-01T00:24:36Z" }, "sessionIssuer"=>{ "type"=>"Role", "principalId"=>"AROAJVHBZWD3DN6CI2MHM", "arn"=>"arn:aws:iam::123456789012:role/MyRole", "accountId"=>"123456789012", "userName"=>"MyRole" } } }, "eventTime"=>"2018-9-01T00:24:36Z", "eventSource"=>"xray.amazonaws.com", "eventName"=>"GetEncryptionConfig", "awsRegion"=>"us-east-2", "sourceIPAddress"=>"33.255.33.255", "userAgent"=>"aws-sdk-ruby2/2.11.19 ruby/2.3.1 x86_64-linux", "requestParameters"=>nil, "responseElements"=>nil, "requestID"=>"3fda699a-32e7-4c20-37af-edc2be5acbdb", "eventID"=>"039c3d45-6baa-11e3-2f3e-e5a036343c9f", "eventType"=>"AwsApiCall", "recipientAccountId"=>"123456789012"
192
AWS X-Ray Guía para desarrolladoresCloudWatch
}
El elemento userIdentity contiene información sobre la persona que generó la solicitud. La información deidentidad del usuario le ayuda a determinar lo siguiente:
• Si la solicitud se realizó con las credenciales raíz o del usuario de IAM.• Si la solicitud se realizó con credenciales de seguridad temporales de un rol o fue un usuario federado.• Si la solicitud la realizó otro servicio de AWS.
Si desea recibir una notificación cuando haya un nuevo archivo de registro disponible, configure CloudTrailpara que publique notificaciones de Amazon SNS. Para obtener más información, consulte ConfiguringAmazon SNS Notifications for CloudTrail.
También puede añadir archivos de registro de X-Ray varias regiones de AWS y varias cuentas de AWSen un solo bucket de Amazon S3. Para obtener más información, consulte Recibir archivos de registro deCloudTrail de varias regiones y Recibir archivos de registro de CloudTrail de varias cuentas.
Monitoreo de puntos de enlace y API conCloudWatch
AWS X-Ray se integra con Amazon CloudWatch para que sea compatible con CloudWatch ServiceLens yCloudWatch Synthetics en al monitorizar el estado de sus aplicaciones. Al correlacionar las métricas, losregistros y los seguimientos, ServiceLens proporciona una visión integral de sus servicios a fin de ayudarlea detallar rápidamente los cuellos de botella de rendimiento e identificar a los usuarios afectados. Paraobtener más información acerca de ServiceLens, consulte Uso de ServiceLens para monitorizar el estadode sus aplicaciones.
ServiceLens se integra con CloudWatch Synthetics, un servicio totalmente gestionado que le permitemonitorizar sus puntos de enlace y API de afuera hacia adentro. Synthetics utiliza canaries modulares yligeros que se ejecutan 24 horas al día, una vez por minuto. Canaries son scripts configurables que siguenlas mismas rutas y realizan las mismas acciones que un cliente. Esto permite la visión de interacciónindirecta de las experiencias de los clientes y la disponibilidad del servicio desde su punto de vista.
Puede personalizar los canaries para comprobar la disponibilidad, la latencia, las transacciones los enlacesrotos o inactivos, las finalizaciones de tareas paso a paso, los errores de carga de la página, la latenciade carga de los recursos de la interfaz de usuario, los flujos de asistente complejos o el resto de flujos detrabajo en su aplicación.
Para empezar a utilizar Synthetics, habilite X-Ray para las API, los puntos de enlace y las aplicacionesweb, por ejemplo, las API que se ejecutan en API Gateway (p. 188). Después. cree un canary y observeel nodo de Synthetics en su gráfico de servicio. Para obtener más información acerca de la configuraciónde las pruebas de Synthetics, consulte Uso de Synthetics para crear y administrar canaries.
Temas• Depuración de canaries de CloudWatch synthetics mediante X-Ray (p. 193)
Depuración de canaries de CloudWatch syntheticsmediante X-RayCloudWatch Synthetics es un servicio completamente administrado que le permite monitorizar sus API ypuntos de enlace mediante canaries con scripts que se ejecutan 24 horas al día, una vez por minuto.
193
AWS X-Ray Guía para desarrolladoresCloudWatchSynthetics de
Puede personalizar las scripts de un canary para comprobar si hay cambios en:
• Disponibilidad• Latency (Latencia)• Transacciones• Vínculos rotos o inactivos• Finalizaciones de tareas paso a paso• Errores de carga de páginas• Latencias de carga para activos de la interfaz de usuario• Flujos complejos del asistente• Flujos de compras en la aplicación
Los canaries siguen las mismas rutas y realizan las mismas acciones y comportamientos que sus clientesy verifican de forma continua la experiencia del cliente.
Para obtener más información acerca de la configuración de las pruebas de Synthetics, consulte Uso deSynthetics para crear y administrar canaries.
Los siguientes ejemplos muestran ejemplos comunes de casos de uso para los problemas de depuraciónque plantean los canaries de Synthetics. Cada ejemplo muestra una estrategia clave para la depuraciónmediante el mapa de servicios o la consola de X-Ray Analytics.
Para obtener más información acerca de cómo leer e interactuar con el mapa de servicios, consulte Ver elmapa de servicio.
Para obtener más información acerca de cómo leer e interactuar con la consola de X-Ray Analytics,consulte Interacción con la consola AWS X-Rayde Analytics.
Temas• Consultar canaries con un informe de errores mayor en el mapa de servicios (p. 195)
194
AWS X-Ray Guía para desarrolladoresCloudWatchSynthetics de
• Uso de mapas de seguimiento para registros de seguimiento individuales para consultar cada solicitudcon detalle (p. 195)
• Determinar la causa raíz de los errores continuos en los servicios ascendentes ydescendentes (p. 196)
• Identificar los cuellos de botella y las tendencias de rendimiento (p. 197)• Comparar las tasas de error y de latencia antes y después de los cambios (p. 197)• Determinar la cobertura de canary necesaria para todas las API y URL (p. 198)• Utilizar los grupos para centrarse en las pruebas de synthetics (p. 198)
Consultar canaries con un informe de errores mayor en el mapade serviciosPara ver qué canaries tienen un aumento de errores, fallos, tasas de limitación controlada o tiemposde respuesta lentos en su mapa de X-Ray servicios, puede resaltar los nodos del cliente de canaryde Synthetics mediante el Client::Synthetic filtro (p. 64). Al hacer clic en un nodo se muestra ladistribución del tiempo de respuesta de toda la solicitud. Al hacer clic en un borde entre dos nodos semuestran detalles sobre las solicitudes que pasaron por esa conexión. También puede ver nodos inferidos"remotos" para servicios posteriores relacionados en su mapa de servicio.
Al hacer clic en el nodo Synthetics, hay un botón View in Synthetics (Ver en Synthetics) en el panel lateralque le redirige a la consola de Synthetics donde puede comprobar los detalles del valor controlado.
Uso de mapas de seguimiento para registros de seguimientoindividuales para consultar cada solicitud con detallePara determinar qué servicio produce la mayor latencia o que causa un error, invoque el mapa deseguimiento al seleccionar el rastreo en el mapa de servicios. Los mapas de rastreo individuales muestranla ruta integral de una sola solicitud. Utilice esto para comprender los servicios invocados y visualizar losservicios ascendentes y descendentes.
195
AWS X-Ray Guía para desarrolladoresCloudWatchSynthetics de
Determinar la causa raíz de los errores continuos en los serviciosascendentes y descendentesUna vez que reciba una CloudWatch alarma de errores en un valor controlado de Synthetics, utiliceel modelado estadístico en los datos de rastreo en X-Ray para determinar la causa raíz probable delproblema en la consola de X-Ray Analytics. En la consola de Analytics, la tabla Response Time RootCause (Causa raíz del tiempo de respuesta) muestra las rutas de entidades registradas. X-Ray determinaque ruta en su rastreo tiene más probabilidades de ser la causa del tiempo de respuesta. El formato indicauna jerarquía de entidades detectadas, que termina en una causa raíz de tiempo de respuesta.
El siguiente ejemplo muestra que la prueba de Synthetics para la API “XXX” que se ejecuta en APIGateway está fallando debido a una excepción de capacidad de rendimiento de la Amazon DynamoDBtabla.
196
AWS X-Ray Guía para desarrolladoresCloudWatchSynthetics de
Identificar los cuellos de botella y las tendencias de rendimientoPuede ver las tendencias del rendimiento de su punto de enlace a lo largo del tiempo mediante el tráficocontinuo de sus canaries de Synthetics para rellenar un mapa de rastreo durante un período de tiempo.
Comparar las tasas de error y de latencia antes y después de loscambiosSeñale el momento en el que se produjo un cambio para correlacionar ese cambio a un aumento de losproblemas captados por los canaries. Utilice la consola de X-Ray Analytics para definir los intervalos detiempo anteriores y posteriores como conjuntos de seguimiento, creando una diferenciación visual en ladistribución del tiempo de respuesta.
197
AWS X-Ray Guía para desarrolladoresCloudWatchSynthetics de
Determinar la cobertura de canary necesaria para todas las API yURLUtilice X-Ray Analytics para comparar la experiencia de los canaries con los usuarios. La interfaz deusuario a continuación muestra una línea de tendencia azul para los canaries y una línea verde para losusuarios. También puede identificar las dos URL de tres que no tienen pruebas de canary.
Utilizar los grupos para centrarse en las pruebas de syntheticsPuede crear un X-Ray grupo de mediante una expresión de filtro para centrarse en un determinadoconjunto de flujos de trabajo, como, por ejemplo, una prueba de Synthetics para la aplicación “www” que seejecuta en AWS Elastic Beanstalk. Utilice las palabras clave complejas (p. 69) service() y edge() parafiltrar por servicios y bordes.
Example Expresión de filtro de grupo
"edge(id(name: "www", type: "client::Synthetics"), id(name: "www", type: "AWS::ElasticBeanstalk::Environment"))"
198
AWS X-Ray Guía para desarrolladoresAWS Config
Seguimiento de los cambios en la configuración decifrado de X-Ray con AWS Config
AWS X-Ray se integra con AWS Config para registrar cambios de configuración realizados en los recursosde cifrado de X-Ray. Puede utilizar AWS Config para realizar un inventario de recursos de cifrado de X-Ray, auditar el historial de configuración de X-Ray y enviar notificaciones basadas en los cambios derecursos.
AWS Config admite el registro de los siguientes cambios de recursos de cifrado de X-Ray como eventos:
• Cambios de configuración: cambiar o añadir una clave de cifrado o volver a la configuración de cifradode X-Ray predeterminada.
Utilice las siguientes instrucciones para obtener información sobre cómo crear una conexión básica entreX-Ray y AWS Config.
199
AWS X-Ray Guía para desarrolladoresCreación de un desencadenador de funciones Lambda
Creación de un desencadenador de funcionesLambdaDebe tener el ARN de una función de AWS Lambda personalizada antes de poder generar una reglade AWS Config personalizada. Siga estas instrucciones para crear una función básica con Node.js quedevuelve un valor conforme o no conforme de vuelta a AWS Config en función del estado del recursoXrayEncryptionConfig.
Para crear una función de Lambda con un disparador de cambio AWS::XrayEncryptionConfig
1. Abra la consola de Lambda. Elija Create function.2. Elija Blueprints (Proyectos) y, a continuación, filtre la biblioteca de proyectos para el proyecto config-
rule-change-triggered. Haga clic en el nombre del proyecto o bien elija Configure (Configurar) paracontinuar.
3. Defina los siguientes campos para configurar el proyecto:
• En Name (Nombre), escriba un nombre.• Para Role (Rol), elija Create new role from template(s) (Crear un rol nuevo a partir de las plantillas).• Para Role name (Nombre del rol), escriba un nombre.• Para Policy templates (Plantillas de política), elija AWS Config Rules permissions (Permisos de
reglas de AWS Config).4. Elija Create function (Crear función) para crear y visualizar su función en la consola de AWS Lambda.5. Edite el código de la función para reemplazar AWS::EC2::Instance por
AWS::XrayEncryptionConfig. También puede actualizar el campo de descripción para reflejareste cambio.
Código predeterminado
if (configurationItem.resourceType !== 'AWS::EC2::Instance') { return 'NOT_APPLICABLE'; } else if (ruleParameters.desiredInstanceType === configurationItem.configuration.instanceType) { return 'COMPLIANT'; } return 'NON_COMPLIANT';
Código actualizado
if (configurationItem.resourceType !== 'AWS::XRay::EncryptionConfig') { return 'NOT_APPLICABLE'; } else if (ruleParameters.desiredInstanceType === configurationItem.configuration.instanceType) { return 'COMPLIANT'; } return 'NON_COMPLIANT';
6. Añada lo siguiente a su rol de ejecución en IAM para acceso a X-Ray. Estos permisos permitenacceso de solo lectura a sus recursos de X-Ray. Si no se proporciona acceso a los recursosapropiados se producirá un mensaje de fuera de ámbito desde AWS Config cuando se evalúa lafunción de Lambda asociada a la regla.
{ "Sid": "Stmt1529350291539", "Action": [ "xray:GetEncryptionConfig" ],
200
AWS X-Ray Guía para desarrolladoresCreación de una regla de AWS
Config personalizada para X-Ray
"Effect": "Allow", "Resource": "*" }
Creación de una regla de AWS Config personalizadapara X-RayCuando se crea la función de Lambda, anote el ARN de la función y vaya a la consola de AWS Config paracrear la regla personalizada.
Para crear una regla de AWS Config para X-Ray
1. Abra la página Rules (Reglas) de la consola de AWS Config.2. Elija Add rule (Añadir una regla) y, a continuación, elija Add custom rule (Añadir una regla
personalizada).3. En AWS Lambda Function ARN (ARN de la función de AWS Lambda), inserte el ARN asociado a la
función de Lambda que desea utilizar.4. Elija el tipo de disparador que desea establecer:
• Cambios de configuración: AWS Config dispara la evaluación cuando cambia la configuración de unrecurso que coincida con el ámbito de regla. La evaluación se realiza después de que AWS Configenvía una notificación sobre un cambio de elementos de configuración.
• Periódica: AWS Config ejecuta las evaluaciones de la regla con la frecuencia que se elija (porejemplo, cada 24 horas).
5. Para Resource type (Tipo de recurso), elija EncryptionConfig en la sección X-Ray.6. Elija Save (Guardar).
La consola de AWS Config comienza a evaluar la conformidad de la regla de forma inmediata. Laevaluación puede tardar varios minutos en completarse.
Ahora que esta regla es compatible, AWS Config puede empezar a compilar un historial de auditoría. AWSConfig registra los cambios de recursos en forma de escala de tiempo. Para cada cambio en la escala detiempo de eventos, AWS Config genera una tabla en formato de/a para mostrar lo que ha cambiado en larepresentación JSON de la clave de cifrado. Los dos cambios de campo asociados a EncryptionConfig sonConfiguration.type y Configuration.keyID.
Resultados de ejemploA continuación, se muestra un ejemplo de una escala de tiempo de AWS Config que muestra los cambiosrealizados en fechas y horas concretas.
A continuación, se muestra un ejemplo de una entrada de cambio de AWS Config. El formato de/a ilustra loque ha cambiado. En este ejemplo se muestra que la configuración de cifrado de X-Ray predeterminada secambió a una clave de cifrado definida.
201
AWS X-Ray Guía para desarrolladoresNotificaciones de Amazon SNS
Notificaciones de Amazon SNSPara recibir una notificación de los cambios de configuración, establezca que AWS Config publique lasnotificaciones de Amazon SNS. Para obtener más información, consulte Monitorización de cambios derecursos de AWS Config por correo electrónico.
Amazon Elastic Compute Cloud y AWS X-RayPuede instalar y ejecutar el demonio de X-Ray en una instancia Amazon EC2 con un script de datos deusuario. Consulte Ejecución del demonio de X-Ray en Amazon EC2 (p. 183) para obtener instrucciones.
Utilice un perfil de instancia para conceder permiso al demonio para cargar datos de rastreo a X-Ray.Para obtener más información, consulte Concesión de permiso al demonio para el envío de datos a X-Ray (p. 173).
AWS Elastic Beanstalk y AWS X-RayLas plataformas AWS Elastic Beanstalk incluyen el demonio de X-Ray. Puede ejecutar el demonio (p. 180)mediante la configuración de una opción en la consola de Elastic Beanstalk o con un archivo deconfiguración.
En la plataforma Java SE, puede utilizar un archivo Buildfile para compilar la aplicación con Maven oGradle en la instancia. El X-Ray SDK for Java y el AWS SDK for Java están disponibles en Maven, paraque pueda implementar únicamente su código de aplicación y compilar la aplicación en la instancia sintener que agrupar y cargar todas sus dependencias.
Puede utilizar las propiedades de entorno de Elastic Beanstalk para configurar el SDK X-Ray. El métodoque Elastic Beanstalk utiliza para transferir las propiedades del entorno a su aplicación varía en funciónde la plataforma. Use las variables de entorno del X-Ray SDK o las propiedades del sistema según suplataforma.
• Plataforma Node.js: utilice variables de entorno (p. 275)• Plataforma Java SE: utilice variables de entorno (p. 250)• Plataforma Tomcat: utilice propiedades del sistema (p. 250)
Para obtener información, consulte la sección Configuración de la depuración en AWS X-Ray en la Guíapara desarrolladores de AWS Elastic Beanstalk.
202
AWS X-Ray Guía para desarrolladoresElastic Load Balancing
Elastic Load Balancing y AWS X-RayLos balanceadores de carga de aplicación de Elastic Load Balancing añaden un ID de rastro a lassolicitudes HTTP entrantes en un encabezado denominado X-Amzn-Trace-Id.
X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793
Formato de ID de rastro
Un trace_id consta de tres números separados por guiones. Por ejemplo, 1-58406520-a006649127e371903a2de979. Esto incluye:
• El número de versión, es decir, 1.• La hora en que se realizó la solicitud original, la fecha en Unix, en 8 dígitos hexadecimales.
Por ejemplo, el 1 de diciembre de 2016 a las 10:00 a. m. PST en formato de tiempo Unix es1480615200 segundos o 58406520 en formato hexadecimal.
• Un identificador 96 bits del rastro, único a nivel global en 24 dígitos hexadecimales.
Los balanceadores de carga no envían datos a X-Ray y no aparecen como nodo en su mapa de servicio.
Para obtener más información, consulte la sección Rastreo de solicitudes en el balanceador de carga deaplicaciones en la Guía para desarrolladores de Elastic Load Balancing.
Amazon EventBridge y AWS X-RayAWS X-Ray se integra con Amazon EventBridge para rastrear los eventos que se pasan a través deEventBridge. Si un servicio que está instrumentado con el X-Ray SDK envía eventos a EventBridge,el contexto de rastreo se propaga a los destinos de eventos posteriores dentro del encabezado de (p. 26)rastreo. El X-Ray SDK recoge automáticamente el encabezado de rastreo y lo aplica a cualquierinstrumentación posterior. Esta continuidad permite a los usuarios rastrear, analizar y depurar en todos losservicios posteriores y proporciona una vista más completa de su sistema.
Para obtener más información, consulte Integración de X-Ray EventBridge en la EventBridge Guía delusuario de .
Visualización del origen y los destinos en el mapa deX-Ray servicioEl mapa X-Ray ??? (p. 51) de servicio muestra un nodo de EventBridge evento que conecta los serviciosde origen y de destino, como en el siguiente ejemplo:
203
AWS X-Ray Guía para desarrolladoresPropagar el contexto de seguimiento
a los destinos de eventos
Propagar el contexto de seguimiento a los destinos deeventosEl X-Ray SDK permite que el origen de EventBridge eventos propague el contexto de seguimiento a losdestinos de eventos posteriores. Los siguientes ejemplos específicos del lenguaje muestran cómo llamar aEventBridge desde una función de Lambda en la que está habilitado el rastreo activo:
Java
Añada las dependencias necesarias para X-Ray:
• AWS X-Ray SDK para Java• AWS X-Ray SDK de grabadora de para Java
package example;
import com.amazonaws.services.lambda.runtime.Context;import com.amazonaws.services.lambda.runtime.RequestHandler;import com.amazonaws.services.lambda.runtime.events.SQSEvent;import com.amazonaws.xray.AWSXRay;import com.amazonaws.services.eventbridge.AmazonEventBridge;import com.amazonaws.services.eventbridge.AmazonEventBridgeClientBuilder;import com.amazonaws.services.eventbridge.model.PutEventsRequest;import com.amazonaws.services.eventbridge.model.PutEventsRequestEntry;import com.amazonaws.services.eventbridge.model.PutEventsResult;import com.amazonaws.services.eventbridge.model.PutEventsResultEntry;import com.amazonaws.xray.handlers.TracingHandler;
import org.slf4j.Logger;import org.slf4j.LoggerFactory;
import java.lang.StringBuilder;import java.util.Map;import java.util.List;import java.util.Date;import java.util.Collections;
/* Add the necessary dependencies for XRay: https://mvnrepository.com/artifact/com.amazonaws/aws-java-sdk-xray https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk*/public class Handler implements RequestHandler<SQSEvent, String>{ private static final Logger logger = LoggerFactory.getLogger(Handler.class);
/* build EventBridge client */ private static final AmazonEventBridge eventsClient = AmazonEventBridgeClientBuilder .standard() // instrument the EventBridge client with the XRay Tracing Handler. // the AWSXRay globalRecorder will retrieve the tracing-context // from the lambda function and inject it into the HTTP header. // be sure to enable 'active tracing' on the lambda function. .withRequestHandlers(new TracingHandler(AWSXRay.getGlobalRecorder())) .build();
@Override public String handleRequest(SQSEvent event, Context context) { PutEventsRequestEntry putEventsRequestEntry0 = new PutEventsRequestEntry();
204
AWS X-Ray Guía para desarrolladoresPropagar el contexto de seguimiento
a los destinos de eventos
putEventsRequestEntry0.setTime(new Date()); putEventsRequestEntry0.setSource("my-lambda-function"); putEventsRequestEntry0.setDetailType("my-lambda-event"); putEventsRequestEntry0.setDetail("{\"lambda-source\":\"sqs\"}"); PutEventsRequest putEventsRequest = new PutEventsRequest(); putEventsRequest.setEntries(Collections.singletonList(putEventsRequestEntry0)); // send the event(s) to EventBridge PutEventsResult putEventsResult = eventsClient.putEvents(putEventsRequest); try { logger.info("Put Events Result: {}", putEventsResult); } catch(Exception e) { e.getStackTrace(); } return "success"; }}
Python
Añada la siguiente dependencia a su archivo requirements.txt:
aws-xray-sdk==2.4.3
import boto3from aws_xray_sdk.core import xray_recorderfrom aws_xray_sdk.core import patch_all
# apply the XRay handler to all clients.patch_all()
client = boto3.client('events')
def lambda_handler(event, context): response = client.put_events( Entries=[ { 'Source': 'foo', 'DetailType': 'foo', 'Detail': '{\"foo\": \"foo\"}' }, ] ) return response
Go
package main
import ( "context" "github.com/aws/aws-lambda-go/lambda" "github.com/aws/aws-lambda-go/events" "github.com/aws/aws-sdk-go/aws/session" "github.com/aws/aws-xray-sdk-go/xray" "github.com/aws/aws-sdk-go/service/eventbridge" "fmt")
var client = eventbridge.New(session.New())
func main() { //Wrap the eventbridge client in the AWS XRay tracer
205
AWS X-Ray Guía para desarrolladoresPropagar el contexto de seguimiento
a los destinos de eventos
xray.AWS(client.Client) lambda.Start(handleRequest)}
func handleRequest(ctx context.Context, event events.SQSEvent) (string, error) { _, err := callEventBridge(ctx) if err != nil { return "ERROR", err } return "success", nil}
func callEventBridge(ctx context.Context) (string, error) { entries := make([]*eventbridge.PutEventsRequestEntry, 1) detail := "{ \"foo\": \"foo\"}" detailType := "foo" source := "foo" entries[0] = &eventbridge.PutEventsRequestEntry{ Detail: &detail, DetailType: &detailType, Source: &source, }
input := &eventbridge.PutEventsInput{ Entries: entries, }
// Example sending a request using the PutEventsRequest method. resp, err := client.PutEventsWithContext(ctx, input)
success := "yes" if err == nil { // resp is now filled success = "no" fmt.Println(resp) } return success, err}
Node.js
const AWSXRay = require('aws-xray-sdk')//Wrap the aws-sdk client in the AWS XRay tracerconst AWS = AWSXRay.captureAWS(require('aws-sdk'))const eventBridge = new AWS.EventBridge()
exports.handler = async (event) => {
let myDetail = { "name": "Alice" }
const myEvent = { Entries: [{ Detail: JSON.stringify({ myDetail }), DetailType: 'myDetailType', Source: 'myApplication', Time: new Date }] }
// Send to EventBridge const result = await eventBridge.putEvents(myEvent).promise()
// Log the result console.log('Result: ', JSON.stringify(result, null, 2))
206
AWS X-Ray Guía para desarrolladoresPropagar el contexto de seguimiento
a los destinos de eventos
}
C#
Añada los siguientes X-Ray paquetes a sus dependencias de C#:
<PackageReference Include="AWSXRayRecorder.Core" Version="2.6.2" /><PackageReference Include="AWSXRayRecorder.Handlers.AwsSdk" Version="2.7.2" />
using System;using System.Collections.Generic;using System.Linq;using System.Threading.Tasks;using Amazon;using Amazon.Util;using Amazon.Lambda;using Amazon.Lambda.Model;using Amazon.Lambda.Core;using Amazon.EventBridge;using Amazon.EventBridge.Model;using Amazon.Lambda.SQSEvents;using Amazon.XRay.Recorder.Core;using Amazon.XRay.Recorder.Handlers.AwsSdk;using Newtonsoft.Json;using Newtonsoft.Json.Serialization;
[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.Json.JsonSerializer))]
namespace blankCsharp{ public class Function { private static AmazonEventBridgeClient eventClient;
static Function() { initialize(); }
static async void initialize() { //Wrap the AWS SDK clients in the AWS XRay tracer AWSSDKHandler.RegisterXRayForAllServices(); eventClient = new AmazonEventBridgeClient(); }
public async Task<PutEventsResponse> FunctionHandler(SQSEvent invocationEvent, ILambdaContext context) { PutEventsResponse response; try { response = await callEventBridge(); } catch (AmazonLambdaException ex) { throw ex; }
return response; }
public static async Task<PutEventsResponse> callEventBridge() { var request = new PutEventsRequest(); var entry = new PutEventsRequestEntry();
207
AWS X-Ray Guía para desarrolladoresLambda
entry.DetailType = "foo"; entry.Source = "foo"; entry.Detail = "{\"instance_id\":\"A\"}"; List<PutEventsRequestEntry> entries = new List<PutEventsRequestEntry>(); entries.Add(entry); request.Entries = entries; var response = await eventClient.PutEventsAsync(request); return response; } }}
AWS Lambda y AWS X-RayPuede utilizar AWS X-Ray para rastrear las funciones de AWS Lambda. Lambda ejecuta el demonio de X-Ray (p. 171) y registra un segmento con detalles sobre la invocación y ejecución de las funciones. Pararealizar una instrumentación adicional, puede agrupar el SDK de X-Ray con su función para registrar lasllamadas salientes y añadir anotaciones y metadatos.
Si otro servicio instrumentado llama a la función Lambda, Lambda rastrea las solicitudes que ya se hayanmuestreado sin necesidad de realizar ninguna configuración adicional. El servicio principal puede ser unaaplicación web instrumentada u otra función Lambda. El servicio puede invocar la función directamentecon un cliente AWS del SDK de instrumentado o llamando a una API Gateway API de con un cliente HTTPinstrumentado.
Si un servicio que no está instrumentado invoca la función Lambda o dicha función se ejecuta en unaprogramación, puede configurar Lambda para que muestree y registre las invocaciones con el rastreoactivo.
Para configurar la integración con X-Ray en una función AWS Lambda, realice los siguientespasos:
1. Abra la consola de AWS Lambda.2. Seleccione Functions (Funciones) en la barra de navegación izquierda.3. Elija su función.4. En la pestaña Configuration (Configuración), desplácese hacia abajo hasta la tarjeta Monitoring tools
(Herramientas de monitorización) y seleccione Edit (Editar).5. En AWS X-Ray, habilite Active tracing (Rastreo activo).
En los tiempos de ejecución con un SDK de X-Ray correspondiente, Lambda también ejecuta el demoniode X-Ray.
X-Ray SDK de en Lambda
• SDK de X-Ray para Go – Go 1.7 y tiempos de ejecución posteriores• X-Ray SDK for Java – Tiempo de ejecución en Java 8• X-Ray SDK for Node.js – Node.js 4.3 y tiempos de ejecución posteriores• SDK de X-Ray para Python – Python 2.7, Python 3.6 y tiempos de ejecución más recientes• X-Ray SDK for .NET – .NET Core 2.0 y tiempos de ejecución más recientes
Para utilizar el SDK de X-Ray en Lambda, empaquételo con el código de la función cada vez que creeuna nueva versión. Puede instrumentar las funciones de Lambda con los mismos métodos que utiliza parainstrumentar aplicaciones que se ejecutan en otros servicios. La diferencia principal es que no utiliza elSDK para instrumentar las solicitudes entrantes, tomar decisiones de muestreo y crear segmentos.
208
AWS X-Ray Guía para desarrolladoresAmazon SNS
La otra diferencia entre la instrumentación de funciones Lambda y aplicaciones web es que el código desu función no puede modificar el segmento que Lambda crea y envía a X-Ray. Puede crear subsegmentosy registrar anotaciones y metadatos en ellos, pero no puede añadir anotaciones y metadatos al segmentoprincipal.
Para obtener más información, consulte Uso de AWS X-Ray en la Guía para AWS Lambda desarrolladoresde .
Amazon SNS y AWS X-RayAWS X-Ray se integra con Amazon Simple Notification Service (Amazon SNS) para hacer un rastreode los mensajes que pasan a través de Amazon SNS. Si un editor de Amazon SNS hace un rastreo desu cliente con el SDK de X-Ray, el suscriptor puede recuperar el encabezado de rastreo (p. 26) y seguirpropagando el rastreo original a partir del editor con el mismo ID de rastro. Esta continuidad permite a losusuarios rastrear, analizar y depurar en servicios posteriores.
Amazon SNSLa propagación actual del contexto del rastro de es compatible con los siguientessuscriptores:
• HTTP/HTTPS – Para los suscriptores HTTP/HTTPS, puede utilizar el X-Ray SDK de para rastrearla solicitud de mensajes entrantes. Para obtener más información y ejemplos en Java, consulteSeguimiento de solicitudes entrantes con el X-Ray SDK for Java (p. 250).
• AWS Lambda – Para los Lambda suscriptores con rastreo activo habilitado, Lambda registra unsegmento con detalles sobre la invocación de la función de y lo envía al rastreo del publicador. Paraobtener más información, consulte AWS Lambda y AWS X-Ray (p. 208).
Utilice las siguientes instrucciones para obtener información sobre cómo crear un contexto básico entreX-Ray y Amazon SNS mediante un suscriptor de Lambda. Creará dos funciones de Lambda y un temade Amazon SNS. A continuación, en la consola de X-Ray, podrá ver el ID de rastro propagado en susinteracciones.
Requirements• Node.js 8 con npm• El shell Bash. Se incluye de forma predeterminada para Linux y macOS. En Windows 10, puede instalar
el Windows Subsystem para Linux para obtener una versión de Ubuntu y Bash integrada con Windows.• La AWS CLI de
Creación de una función de suscriptor LambdaEn los siguientes pasos, la Lambda función de ejemplo MessageSubscriber se implementa en Node.jsy se suscribe como punto de enlace a un Amazon SNS tema de . La MessageSubscriber La funcióncrea un custom process_message subsegmento con el AWSXRay.captureFunc comando . La funciónescribe un mensaje sencillo como una anotación al subsegmento.
Para crear el paquete de suscriptor
1. Crear una carpeta de archivos y asignarle un nombre para indicar que es la función del suscriptor (porejemplo, sns-xray-subscriber).
2. Cree dos archivos: index.js y package.json.3. Pegue el siguiente código en index.js.
var AWSXRay = require('aws-xray-sdk');
209
AWS X-Ray Guía para desarrolladoresCreación de un tema de Amazon SNS
exports.handler = function(event, context, callback) { AWSXRay.captureFunc('process_message', function(subsegment) { var message = event.Records[0].Sns.Message; subsegment.addAnnotation('message_content', message); subsegment.close(); }); callback(null, "Message received.");};
4. Pegue el siguiente código en package.json.
{ "name": "sns-xray-subscriber", "version": "1.0.0", "description": "A demo service to test SNS X-Ray trace header propagation", "dependencies": { "aws-xray-sdk": "^2.2.0" }}
5. Ejecute el siguiente script en el sns-xray-subscriber folder. Crea un archivo package-lock.json y una carpeta node_modules, que gestionan todas las dependencias.
npm install --production
6. Compresión del sns-xray-subscriber en un archivo .zip.
Para crear una función de suscriptor y habilitar X-Ray
1. Abra la consola Lambda y, a continuación, elija Create a function (Crear una función).2. Elija Author from scratch (Crear desde cero):
• En Function name (Nombre de función), proporcione un nombre (por ejemplo,MessageSubscriber).
• En Runtime (Tiempo de ejecución), utilice Node.js 10.x.3. Elija Create function (Crear función) para crear y visualizar su función en la consola de Lambda.4. En Function code (Código de función), en Code entry type (Tipo de entrada de código), elija Upload
a .ZIP file (Cargar un archivo .ZIP).5. Elija el paquete de suscriptor que creó. Para cargar, seleccione Save (Guardar) en la parte superior
derecha de la consola.6. En Debugging and error handling (Depuración y control de errores), seleccione la casilla Enable X-
Ray (AWSHabilitar X-Ray).7. Elija Save (Guardar).
Creación de un tema de Amazon SNSCuando Amazon SNS recibe solicitudes, propaga el encabezado de seguimiento a su suscriptor del puntode enlace. En los siguientes pasos, crea un tema y establece el punto de enlace como la función deLambda que ha creado antes.
Para crear un tema de Amazon SNS y suscribir una función de Lambda
1. Abra la consola de SNS.
210
AWS X-Ray Guía para desarrolladoresCreación de una función de editor Lambda
2. Elija Topics (Temas) y, a continuación, seleccione el Create topic (Crear tema). Para Name (Nombre)introduzca un nombre.
3. En Subscriptions (Suscripciones), elija Create subscription (Crear suscripción).4. Registre el ARN del tema (por ejempl, arn:aws:sns:{region}:{account id}:{topic name}).5. Elija Create Subscription (Crear suscripción).
• En Protocol (Protocolo), elija AWS Lambda.• En EndPoint (Punto de enlace), seleccione el ARN de la función de Lambda del receptor que creó
para la lista de funciones deLambda disponibles.6. Seleccione Create subscription.
Creación de una función de editor LambdaEn los siguientes pasos, la Lambda función de ejemplo MessagePublisher se implementa en Node.js.La función envía un mensaje al tema de Amazon SNS que creó anteriormente. La función utiliza elAWS SDK for JavaScript para enviar notificaciones desde Amazon SNSy el X-Ray SDK for Node.js parainstrumentar el cliente del AWS SDK.
Para crear el paquete del editor
1. Crear una carpeta de archivos y asignarle un nombre para indicar que es la función de editor (porejemplo, sns-xray-publisher).
2. Cree dos archivos: index.js y package.json.3. Pegue el siguiente código en index.js.
var AWSXRay = require('aws-xray-sdk');var AWS = AWSXRay.captureAWS(require('aws-sdk'));
exports.handler = function(event, context, callback) { var sns = new AWS.SNS();
sns.publish({ // You can replace the following line with your custom message. Message: process.env.MESSAGE || "Testing X-Ray trace header propagation", TopicArn: process.env.TOPIC_ARN }, function(err, data) { if (err) { console.log(err.stack); callback(err); } else { callback(null, "Message sent."); } });};
4. Pegue el siguiente código en package.json.
{ "name": "sns-xray-publisher", "version": "1.0.0", "description": "A demo service to test SNS X-Ray trace header propagation", "dependencies": { "aws-xray-sdk": "^2.2.0" }}
5. Ejecute el siguiente script en el sns-xray-publisher folder. Crea un archivo package-lock.json y una carpeta node_modules, que gestionan todas las dependencias.
211
AWS X-Ray Guía para desarrolladoresComprobación y validación de la propagación de contexto
npm install --production
6. Compresión del sns-xray-publisher en un archivo .zip.
Para crear una función de editor y habilitar X-Ray
1. Abra la consola Lambda y, a continuación, elija Create a function (Crear una función).2. Elija Author from scratch (Crear desde cero):
• En Name (Nombre), proporcione un nombre (por ejemplo, MessagePublisher).• En Runtime (Tiempo de ejecución), utilice Node.js 10.x.
3. En Permissions (Permisos), expanda Choose or create an execution role (Seleccionar o crear un rolde ejecución):
• En Execution role (Rol de ejecución), elija Create a new role from policy templates (Crear un nuevorol a partir de plantillas de AWS política).
• Para Role name (Nombre del rol), facilite un nombre.• Para Policy templates (Plantillas de políticas), elija Amazon SNS publish policy (Política de
publicación de Amazon SNS).4. Elija Create function (Crear función) para crear y visualizar su función en la consola de Lambda.5. En Function code (Código de función), en Code entry type (Tipo de entrada de código), elija Upload
a .ZIP file (Cargar un archivo .ZIP).6. Elija el paquete de editor que ha creado. Para cargar, seleccione Save (Guardar) en la parte superior
derecha de la consola.7. En Environment variables (Variables de entorno), añada una variable:
• En Key (Clave), utilice el nombre de clave TOPIC_ARN, que se define en la función de editor.• Para Value (Valor), utilice el ARN del tema de Amazon SNS que ha registrado anteriormente.
8. También puede añadir otra variable:
• En Key (Clave), proporcione un nombre de clave (por ejemplo, MESSAGE).• Para Value (Valor), introduzca un mensaje personalizado.
9. En Debugging and error handling (Depuración y control de errores), seleccione la casilla Enable X-Ray (AWSHabilitar X-Ray).
10. Elija Save (Guardar).
Comprobación y validación de la propagación decontextoTanto las funciones de editor como de suscriptor permiten el rastreo activo de Lambda al enviar rastreos.La función de editor utiliza el SDK de X-Ray para captar la llamada a la API de SNS publish. Acontinuación, Amazon SNS propaga el encabezado de rastreo al suscriptor. Por último, el suscriptorrecoge el encabezado de rastreo y continúa el rastreo. Siga el ID de rastreo en los siguientes pasos.
Para crear una función de editor y habilitar X-Ray
1. Abra la consola de Lambda y, a continuación, seleccione la función de editor que creó anteriormente.2. Seleccione Test (Probar).3. Elija Create new test event (Crear un nuevo evento de prueba):
212
AWS X-Ray Guía para desarrolladoresStep Functions
• Para Event template (Plantilla del evento), seleccione la plantilla Hello World (Hola mundo).• Para Event name (Nombre del evento) introduzca un nombre.
4. Seleccione Create (Crear).5. Elija Test (Probar) de nuevo.6. Para comprobar, abra la consola X-Ray. Espere al menos 10 segundos para que aparezca el rastreo.7. Cuando el mapa de servicios se genere, compruebe que sus dos funciones de Lambda y el tema
Amazon SNS aparecen.8. Elija el icono MessageSubscriber y, a continuación, elija View traces.9. Seleccione el rastreo de la lista para llegar a la página Details (Detalles).10. Elija el subsegmento process_message.11. Elija la pestaña Annotations (Anotaciones) para ver la clave de message_content con el valor del
mensaje del remitente.
AWS Step Functions y AWS X-RayAWS X-Ray se integra con AWS Step Functions para rastrear y analizar solicitudes de Step Functions.Puede visualizar los componentes de la máquina de estado, identificar los cuellos de botella derendimiento y solucionar los problemas de las solicitudes que generaron un error. Para obtener másinformación, consulte AWS X-Ray y Step Functions en la Guía AWS Step Functions para desarrolladoresde .
Para habilitar el X-Ray rastreo de al crear una nueva máquina de estado
1. Abra la consola de Step Functions en https://console.aws.amazon.com/states/.2. Elija Create a state machine (Crear una máquina de estado).3. En la página Define state machine (Definir máquina de estado), elija Author with code snippets (Crear
con fragmentos de código) o Start with a template (Comenzar con una plantilla). Si decide ejecutar unproyecto de muestra, no podrá habilitar el X-Ray rastreo de durante la creación. En su lugar, habilite elX-Ray rastreo de después de crear la máquina de estado.
4. Seleccione Next (Siguiente).5. En la página Specify details (Especificar detalles), configure la máquina de estado.6. Elija Enable tracing X-Ray(Habilitar rastreo).
Para habilitar el X-Ray rastreo de en una máquina de estado existente
1. En la Step Functions consola de , seleccione la máquina de estado para la que desea habilitar elrastreo.
2. Elija Edit.3. Elija Enable tracing X-Ray(Habilitar rastreo).4. (Opcional) Genere automáticamente un nuevo rol para que la máquina de estado incluya X-Ray
permisos eligiendo Create new role (Crear nuevo rol) en la ventana Permissions (Permisos).
213
AWS X-Ray Guía para desarrolladoresAmazon SQS
5. Elija Save (Guardar).
Note
Al crear una nueva máquina de estado, se rastrea automáticamente si se realiza un muestreo dela solicitud y se habilita el rastreo de en un servicio ascendente como Amazon API Gateway oAWS Lambda. Para cualquier máquina de estado existente que no esté configurada a través de laconsola de , por ejemplo, a través de una AWS CloudFormation plantilla de , compruebe que tieneuna IAM política de que conceda permisos suficientes para habilitar X-Ray los rastros.
Amazon SQS y AWS X-RayAWS X-Ray se integra con Amazon Simple Queue Service (Amazon SQS) para rastrear los mensajesque pasan a través de una cola de Amazon SQS. Si un servicio rastrea las solicitudes utilizando el X-RaySDK, Amazon SQS puede enviar el encabezado de rastreo y continuar propagando el rastro original entreel remitente y el consumidor con un ID de rastro coherente. Esta continuidad permite que los usuariospuedan rastrear, analizar y depurar en otros servicios posteriores.
Amazon SQS admite la siguiente instrumentación de encabezado de rastreo:
• Encabezado HTTP – predeterminado: la rellena X-Ray SDK automáticamente el encabezado de rastreocomo encabezado HTTP cuando llama a Amazon SQS a través del AWS SDK. lleva el encabezadode rastreo X-Amzn-Trace-Id predeterminado, que se corresponde con todos los mensajes incluidos
214
AWS X-Ray Guía para desarrolladoresEnviar el encabezado de seguimiento HTTP
en una SendMessage solicitud SendMessageBatch o . Para obtener más información sobre elencabezado HTTP predeterminado, consulte Encabezado de seguimiento (p. 26).
• AWSTraceHeader Atributo del sistema – es AWSTraceHeader un atributo del sistema de mensajesreservado por Amazon SQS para llevar el encabezado de X-Ray rastreo con mensajes en la cola.AWSTraceHeader está disponible para su uso incluso cuando no lo X-Ray SDK está la instrucciónautomática a través de la , por ejemplo, al crear un SDK de seguimiento para un nuevo lenguaje.Cuando se establecen las instrumentaciones de los dos encabezados, el atributo del sistema demensajes anula el encabezado de rastreo HTTP.
Cuando se ejecuta en Amazon EC2, Amazon SQS solo permite procesar un mensaje cada vez. Estoes aplicable tanto cuando se ejecuta un host en las instalaciones como cuando se utilizan servicios decontenedor, como AWS Fargate, Amazon ECS o AWS App Mesh.
El encabezado de rastreo no se incluye en las cuotas de Amazon SQS tamaño y atributo de mensaje. Alhabilitar el rastreo de X-Ray, no se superan las cuotas de Amazon SQS. Para obtener más informaciónacerca de las cuotas de AWS, consulte Cuotas de Amazon SQS.
Note
Actualmente no es posible conectar un rastro pasado a una cola de SQS a Lambdaconsumiéndolo en el otro extremo. Esto se debe a que, aunque el encabezado de rastreo sepropaga en el mensaje de SQS, no puede establecerlo en Lambda porque los segmentos deLambda son inmutables.
Enviar el encabezado de seguimiento HTTPLos componentes del remitente de Amazon SQS pueden enviar el encabezado de rastreoautomáticamente a través de la SendMessageBatch llamada SendMessage o . Cuando se instrumentanclientes del SDK de AWS, se puede realizar un seguimiento automático en todos los lenguajes en el X-RaySDK. AWS Los servicios y recursos rastreados a los que accede dentro de dichos servicios (por ejemplo,un Amazon S3 bucket de o una Amazon SQS cola de ) aparecen como nodos posteriores en el mapa deservicio de la X-Ray consola de .
Para obtener información sobre cómo rastrear llamadas al AWS SDK con su lenguaje preferido, consultelos siguientes temas en los SDKs compatibles:
• Go – Seguimiento de llamadas al AWS SDK con la SDK de X-Ray para Go (p. 226)• Java: – Seguimiento de llamadas al AWS SDK con la X-Ray SDK for Java (p. 254)• Node.js – Seguimiento de llamadas al AWS SDK con la X-Ray SDK for Node.js (p. 279)• Python – Seguimiento de llamadas al AWS SDK con la SDK de X-Ray para Python (p. 300)• Ruby – Seguimiento de llamadas al AWS SDK con la SDK de X-Ray para Ruby (p. 322)• .NET – Seguimiento de llamadas al AWS SDK con la X-Ray SDK for .NET (p. 336)
Recuperar el encabezado y el contexto deseguimientoPara continuar la propagación del contexto con Amazon SQS, debe instrumentar manualmente la entregaal componente receptor.
Hay tres pasos principales para recuperar el contexto de rastreo:
• Recibir el mensaje de la cola del atributo AWSTraceHeader llamando a la API ReceiveMessage.• Recuperar el encabezado de rastreo del atributo.
215
AWS X-Ray Guía para desarrolladoresAmazon S3
• Recuperar el ID de rastreo del encabezado. Si lo desea, también puede añadir otras métricas alsegmento.
A continuación se muestra un ejemplo de una implementación escrita con X-Ray SDK for Java.
Example : Recuperar el encabezado y el contexto de seguimiento
// Receive the message from the queue, specifying the "AWSTraceHeader"ReceiveMessageRequest receiveMessageRequest = new ReceiveMessageRequest() .withQueueUrl(QUEUE_URL) .withAttributeNames("AWSTraceHeader");List<Message> messages = sqs.receiveMessage(receiveMessageRequest).getMessages();
if (!messages.isEmpty()) { Message message = messages.get(0); // Retrieve the trace header from the AWSTraceHeader message system attribute String traceHeaderStr = message.getAttributes().get("AWSTraceHeader"); if (traceHeaderStr != null) { TraceHeader traceHeader = TraceHeader.fromString(traceHeaderStr);
// Recover the trace context from the trace header Segment segment = AWSXRay.getCurrentSegment(); segment.setTraceId(traceHeader.getRootTraceId()); segment.setParentId(traceHeader.getParentId()); segment.setSampled(traceHeader.getSampled().equals(TraceHeader.SampleDecision.SAMPLED)); }}
Amazon S3 y AWS X-RayAWS X-Ray se integra con Amazon S3 para rastrear solicitudes ascendentes para actualizar los bucketsde S3 de su aplicación. Si un servicio rastrea solicitudes mediante el X-Ray SDK de , Amazon S3 puedeenviar los encabezados de rastreo a suscriptores de eventos posteriores como AWS Lambda AmazonSQS, y Amazon SNS. X-Ray habilita los mensajes de rastreo para las notificaciones de Amazon S3eventos.
Puede utilizar el mapa de X-Ray servicio para ver las conexiones entre Amazon S3 y otros servicios de queutiliza su aplicación. También puede utilizar la consola para ver métricas como la latencia media y las tasasde errores. Para obtener más información acerca de la consola de X-Ray, consulte AWS X-RayConsola de (p. 51).
Amazon S3 admite la instrumentación de encabezado http predeterminada. El X-Ray SDK rellenaautomáticamente el encabezado de rastreo como encabezado HTTP cuando llama a Amazon S3 a travésdel AWS SDK. lleva el encabezado de rastreo X-Amzn-Trace-Idpredeterminado. Para obtener másinformación sobre el rastreo de encabezados, consulte Encabezado de seguimiento (p. 26) en la páginade concepto de . La propagación del contexto de Amazon S3 rastreo de admite los siguientes suscriptores:Lambda, SQS y SNS.
Configurar notificaciones Amazon S3 de eventosCon la característica de Amazon S3 notificaciones de , recibirá notificaciones cuando se produzcandeterminados eventos en el bucket de . Estas notificaciones se pueden propagar a los siguientes destinosdentro de su aplicación:
• Amazon Simple Notification Service (Amazon SNS)
216
AWS X-Ray Guía para desarrolladoresConfigurar notificaciones Amazon S3 de eventos
• Amazon Simple Queue Service (Amazon SQS)• AWS Lambda
Para obtener una lista de eventos compatibles, consulte Tipos de eventos compatibles en la guía AmazonS3para desarrolladores de .
Amazon SNS y Amazon SQSPara publicar notificaciones en un tema de SNS o una cola de SQS, primero debe conceder AmazonS3 permisos. Para conceder estos permisos, debe asociar una política de AWS Identity and AccessManagement (IAM) al tema de SNS o la cola de SQS de destino. Para obtener más información sobre laspolíticas de IAM necesarias, consulte Concesión de permisos para publicar mensajes en un tema de SNSo una cola de SQS.
Para obtener información sobre la integración de SNS y SQS con , X-Ray consulte Amazon SNS y AWS X-Ray (p. 209) y Amazon SQS y AWS X-Ray (p. 214).
AWS LambdaCuando se utiliza la Amazon S3 consola para configurar notificaciones de eventos en un bucket de S3 parauna función Lambda, la consola configura los permisos necesarios en la función Lambda para que AmazonS3 tenga permisos para invocar la función desde el bucket. Para obtener más información, consulte¿Cómo puedo habilitar y configurar notificaciones de eventos para un bucket de S3? en la guía del usuariode la consola de Amazon Simple Storage Service.
También puede conceder Amazon S3 permisos desde AWS Lambda para invocar su función Lambda.Para obtener más información, consulte Tutorial: Uso de AWS Lambda con Amazon S3 en la Guía paradesarrolladores de AWS Lambda.
Para obtener más información acerca de la integración Lambda con X-Ray, consulte Instrumentación decódigo Java en AWS Lambda.
217
AWS X-Ray Guía para desarrolladores
AWS X-RaySDK de para GoEl SDK de X-Ray para Go es un conjunto de bibliotecas para aplicaciones Go que proporcionan clasesy métodos para generar y enviar datos de rastreo al demonio de X-Ray. Los datos de rastreo incluyeninformación sobre las solicitudes HTTP entrantes que atiende la aplicación y las llamadas que la aplicaciónrealiza a los servicios posteriores mediante el AWS SDK de , clientes HTTP o un conector de base dedatos SQL. También puede crear segmentos de forma manual y agregar información de depuración enanotaciones y metadatos.
Descargue el SDK desde su repositorio de GitHub con go get:
$ go get -u github.com/aws/aws-xray-sdk-go/...
Para las aplicaciones web, comience por utilizar la función xray.Handler (p. 224) para realizar elseguimiento de las solicitudes entrantes. El controlador de mensajes crea un segmento (p. 21) para cadasolicitud rastreada y lo completa cuando se envía la respuesta. Mientras el segmento está abierto, puedeutilizar los métodos del cliente del SDK para añadir información al segmento y crear subsegmentos pararastrear llamadas posteriores. El SDK también registra automáticamente las excepciones que produce suaplicación mientras el segmento está abierto.
Para las funciones de Lambda a las que se ha llamado desde una aplicación o un servicio instrumentados,Lambda lee el encabezado de rastreo (p. 26) y rastrea las solicitudes muestreadas automáticamente.Para las demás funciones, es posible configurar Lambda (p. 208) para muestrear y seguir las solicitudesentrantes. En cualquiera de los dos casos, Lambda crea el segmento y se lo proporciona al SDK de X-Ray.
Note
En Lambda, el SDK de X-Ray es opcional. Si no lo utiliza en la función, el mapa de servicioseguirá incluyendo un nodo para el servicio de Lambda y uno para cada función de Lambda.Si incorpora el SDK, puede instrumentar el código de la función para añadir subsegmentos alsegmento de la función registrado por Lambda. Para obtener más información, consulte AWSLambda y AWS X-Ray (p. 208).
A continuación, envuelva su cliente con una llamada a la función AWS (p. 226). Este paso garantiza queX-Ray instrumente las llamadas a cualquier método del cliente. También puede instrumentar llamadas abases de datos SQL (p. 228).
En cuanto empiece a utilizar el SDK, personalice su comportamiento configurando la grabadora y elmiddleware (p. 219). Puede añadir complementos para registrar los datos sobre los recursos informáticosque ejecutan su aplicación, personalizar el comportamiento de muestreo mediante la definición dereglas de muestreo y definir el nivel de log para ver más o menos información del SDK en los logs de lasaplicaciones.
Registre información adicional acerca de las solicitudes y el trabajo que la aplicación realiza enanotaciones y metadatos (p. 229). Las anotaciones son pares sencillos de clave-valor que se indexanpara su uso con expresiones de filtro (p. 64) para poder buscar rastros que contengan datos específicos.Las entradas de metadatos son menos restrictivas y pueden registrar objetos y matrices completos —esdecir, todo lo que se pueda serializar en JSON.
Anotaciones y metadatos
Las anotaciones y los metadatos son texto arbitrario que se añade a los segmentos con el SDK deX-Ray. Las anotaciones se indexan para su uso con expresiones de filtro. Los metadados no seindexan, pero se pueden consultar en un segmento sin formato con la consola o la API de X-Ray.Todas las personas a las que otorgue acceso de lectura a X-Ray pueden ver estos datos.
218
AWS X-Ray Guía para desarrolladoresRequirements
Cuando tenga muchos clientes instrumentados en su código, un único segmento de solicitudpuede contener un gran número de subsegmentos, uno para cada llamada realizada con un clienteinstrumentado. Puede organizar y agrupar los subsegmentos incluyendo las llamadas del clienteen subsegmentos personalizados (p. 228). Puede crear un subsegmento personalizado para unafunción completa o para cualquier sección de código, y registrar los metadatos y las anotaciones en elsubsegmento en lugar de escribirlo todo en el segmento principal.
RequirementsEl SDK de X-Ray para Go requiere Go 1.9 o una versión posterior.
El SDK depende de las siguientes bibliotecas durante la compilación y el tiempo de ejecución:
• AWS SDK de para Go versión 1.10.0 o posterior
Estas dependencias se han declarado en el archivo README.md del SDK.
Documentación de referenciaUna vez que haya descargado el SDK, compile y aloje la documentación localmente para verla en unnavegador web.
Para ver la documentación de referencia
1. Vaya al directorio $GOPATH/src/github.com/aws/aws-xray-sdk-go (Linux o Mac) o la carpeta%GOPATH%\src\github.com\aws\aws-xray-sdk-go (Windows)
2. Ejecute el godoc comando .
$ godoc -http=:6060
3. Abra un navegador en http://localhost:6060/pkg/github.com/aws/aws-xray-sdk-go/.
Configuración del SDK de X-Ray para GoPuede especificar la configuración para SDK de X-Ray para Go a través de variables de entorno, llamandoa Configure con un objeto Config o suponiendo valores predeterminados. Las variables de entornotienen prioridad sobre los valores Config, que tienen prioridad sobre cualquier valor predeterminado.
Secciones• Complementos del servicio (p. 219)• Reglas de muestreo (p. 221)• Registro de (p. 222)• Variables de entorno (p. 223)• Uso de la opción configure (p. 223)
Complementos del servicioUtilice plugins para registrar información sobre el servicio que aloja su aplicación.
219
AWS X-Ray Guía para desarrolladoresComplementos del servicio
Complementos
• Amazon EC2: EC2Plugin agrega el ID de instancia, la zona de disponibilidad y el grupo de CloudWatchLogs.
• Elastic Beanstalk – ElasticBeanstalkPlugin añade el nombre de entorno, la etiqueta de versión y elID de implementación.
• Amazon ECS – ECSPlugin añade el ID del contenedor.
Para utilizar un complemento, importe uno de los siguientes paquetes.
"github.com/aws/aws-xray-sdk-go/awsplugins/ec2""github.com/aws/aws-xray-sdk-go/awsplugins/ecs""github.com/aws/aws-xray-sdk-go/awsplugins/beanstalk"
Cada complemento tiene una llamada de función Init() explícita que lo carga.
Example ec2.Init()
import ( "os"
"github.com/aws/aws-xray-sdk-go/awsplugins/ec2" "github.com/aws/aws-xray-sdk-go/xray"
220
AWS X-Ray Guía para desarrolladoresReglas de muestreo
)
func init() { // conditionally load plugin if os.Getenv("ENVIRONMENT") == "production" { ec2.Init() }
xray.Configure(xray.Config{ ServiceVersion: "1.2.3",
})}
El SDK también utiliza la configuración del complemento para establecer el campo origin del segmento.Esto indica el tipo de recurso de AWS que ejecuta la aplicación. El tipo de recurso aparece bajo el nombrede la aplicación en el mapa del servicio. Por ejemplo, AWS::ElasticBeanstalk::Environment.
Cuando utiliza varios complementos, el SDK utiliza la siguiente orden de resolución para determinar elorigen: ElasticBeanstalk > EKS > ECS > EC2.
Reglas de muestreoEl SDK utiliza reglas de muestreo que usted define en la consola de X-Ray para determinar qué solicitudesdebe registrar. La regla predeterminada rastrea la primera solicitud de cada segundo y un cinco porciento de todas las solicitudes adicionales en todos los servicios que envían rastros a X-Ray. Cree reglasadicionales en la consola de X-Ray (p. 76) para personalizar la cantidad de datos registrados para cadauna de sus aplicaciones.
El SDK aplica las reglas personalizadas en el orden en que se definen. Si una solicitud coincide con variasreglas personalizadas, el SDK aplica solo la primera regla.
Note
Si el SDK no puede conectar con X-Ray para obtener las reglas de muestreo, utiliza una reglapredeterminada local de la primera solicitud de cada segundo y un cinco por ciento de todas lassolicitudes adicionales para cada host. Esto puede ocurrir si el host no tiene permiso para llamara las API de muestreo o no puede conectarse con el daemon de X-Ray, que actúa como un proxyTCP para las llamadas a la API realizadas por el SDK.
También puede configurar el SDK para que cargue las reglas de muestreo desde un documento JSON. ElSDK puede usar reglas locales como reserva para aquellos casos en los que el muestreo de X-Ray no estédisponible, o bien usar reglas locales exclusivamente.
221
AWS X-Ray Guía para desarrolladoresRegistro de
Example sampling-rules.json
{ "version": 2, "rules": [ { "description": "Player moves.", "host": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 }}
Este ejemplo define una regla personalizada y una regla predeterminada. La regla personalizada aplica unporcentaje de muestreo del cinco por ciento sin un número mínimo de solicitudes para rastrear las rutas deacceso de /api/move/. La regla predeterminada rastrea la primera solicitud cada segundo y un 10 porciento de las solicitudes adicionales.
El inconveniente de definir reglas localmente es que cada instancia del grabador aplica el porcentaje fijode forma independiente, en lugar de dejar que se encargue el servicio de X-Ray. Cuando implemente máshosts, la tasa fija se multiplicará, lo que hará que sea más difícil controlar la cantidad de datos registrados.
En AWS Lambda, no se puede modificar la frecuencia de muestreo. Si un servicio instrumentado llamaa la función, Lambda registrará las solicitudes generadas por llamadas que fueron muestreadas porese servicio. Si el rastreo activo está activado y no hay ningún encabezado de rastreo, Lambda toma ladecisión de muestreo.
Para proporcionar reglas de copia de seguridad, apunte al archivo JSON de muestreo local medianteNewCentralizedStrategyWithFilePath.
Example main.go: regla de muestreo local
s, _ := sampling.NewCentralizedStrategyWithFilePath("sampling.json") // path to local sampling jsonxray.Configure(xray.Config{SamplingStrategy: s})
Para utilizar solo reglas locales, apunte al archivo JSON de muestreo local medianteNewLocalizedStrategyFromFilePath.
Example main.go: deshabilitar el muestreo
s, _ := sampling.NewLocalizedStrategyFromFilePath("sampling.json") // path to local sampling jsonxray.Configure(xray.Config{SamplingStrategy: s})
Registro deNote
Los campos xray.Config{} LogLevel y LogFormat están obsoletos desde la versión 1.0.0-rc.10.
222
AWS X-Ray Guía para desarrolladoresVariables de entorno
X-Ray utiliza la siguiente interfaz para el registro. El registrador predeterminado escribe en stdout aLogLevelInfo y superior.
type Logger interface { Log(level LogLevel, msg fmt.Stringer)}
const ( LogLevelDebug LogLevel = iota + 1 LogLevelInfo LogLevelWarn LogLevelError)
Example escribir en io.Writer
xray.SetLogger(xraylog.NewDefaultLogger(os.Stderr, xraylog.LogLevelError))
Variables de entornoPuede utilizar variables de entorno para configurar el SDK de X-Ray para Go. El SDK admite las siguientesvariables.
• AWS_XRAY_TRACING_NAME: establece el nombre de servicio que el SDK utiliza para los segmentos.• AWS_XRAY_DAEMON_ADDRESS: configure el host y el puerto del agente de escucha del daemon de
X-Ray. De forma predeterminada, el SDK envía los datos de rastreo a 127.0.0.1:2000. Use estavariable si ha configurado el daemon para que esté a la escucha en un puerto diferente (p. 174) o si seejecuta en un host diferente.
• AWS_XRAY_CONTEXT_MISSING: establezca el valor para determinar cómo el SDK gestiona los erroresde falta de contexto. Se pueden producir errores relativos a segmentos o subsegmentos inexistentesal intentar usar un cliente instrumentado en el código de inicio que se ejecuta cuando no hay ningunasolicitud abierta o en el código que inicia un nuevo subproceso.• RUNTIME_ERROR: de forma predeterminada, el SDK está configurado para lanzar una excepción en
tiempo de ejecución.• LOG_ERROR: registrar un error y continuar.
Las variables de entorno anulan los valores equivalentes establecidos en el código.
Uso de la opción configureTambién puede configurar el SDK de X-Ray para Go con el método Configure. Configure toma unargumento, un objeto Config con los siguientes campos opcionales.
DaemonAddr
Esta cadena especifica el host y el puerto del agente de escucha del demonio de X-Ray. Si no seespecifica, X-Ray utiliza el valor de la variable de entorno AWS_XRAY_DAEMON_ADDRESS. Si dichovalor no está establecido, utiliza "127.0.0.1:2000".
ServiceVersion
Esta cadena especifica la versión del servicio. Si no se especifica, X-Ray utiliza la cadena vacía ("").SamplingStrategy
Este objeto SamplingStrategy especifica las llamadas de aplicación a las que se realizaseguimiento. Si no se especifica, X-Ray utiliza una LocalizedSamplingStrategy, que adopta laestrategia tal como se define en xray/resources/DefaultSamplingRules.json.
223
AWS X-Ray Guía para desarrolladoresSolicitudes entrantes
StreamingStrategy
Este objeto StreamingStrategy especifica si se debe transmitir un segmentocuando RequiresStreaming devuelve true. Si no se especifica, X-Ray utiliza unDefaultStreamingStrategy que transmite un segmento muestreado si el número desubsegmentos es mayor que 20.
ExceptionFormattingStrategy
Este objeto ExceptionFormattingStrategy especifica la forma en que desea gestionar diversasexcepciones. Si no se especifica, X-Ray utiliza una DefaultExceptionFormattingStrategy conun XrayError de tipo error, el mensaje de error y seguimiento de la pila.
Instrumentación de solicitudes HTTP entrantes conel SDK de X-Ray para Go
Puede utilizar el SDK de X-Ray para rastrear las solicitudes HTTP entrantes que su aplicación atiende enuna instancia EC2 en Amazon EC2, AWS Elastic Beanstalk o Amazon ECS.
Utilice xray.Handler para instrumentar las solicitudes HTTP entrantes. El SDK de X-Ray para Goimplementa la interfaz http.Handler de la biblioteca de Go estándar en la clase xray.Handler parainterceptar solicitudes web. La clase xray.Handler envuelve el http.Handler proporcionado conxray.Capture utilizando el contexto de la solicitud, analizando los encabezados entrantes, añadiendoencabezados de respuesta si es necesario y establece los campos de rastreo específicos de HTTP.
Al utilizar esta clase para gestionar solicitudes HTTP y respuestas, el SDK de X-Ray para Go crea unsegmento para cada solicitud muestreada. Este segmento incluye el momento, el método y la disposiciónde la solicitud HTTP. La instrumentación adicional crea subsegmentos en este segmento.
Note
Para las funciones de AWS Lambda, Lambda crea un segmento para cada solicitud muestreada.Para obtener más información, consulte AWS Lambda y AWS X-Ray (p. 208).
El siguiente ejemplo intercepta solicitudes en el puerto 8000 y devuelve "Hello!" como respuesta. Crea elsegmento myApp e instrumenta llamadas a través de cualquier aplicación.
Example main.go
func main() { http.Handle("/", xray.Handler(xray.NewFixedSegmentNamer("MyApp"), http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.Write([]byte("Hello!")) })))
http.ListenAndServe(":8000", nil)}
Cada segmento tiene un nombre que identifica su aplicación en el mapa de servicio. Puede asignarun nombre al segmento de manera estática o puede configurar el SDK para que asigne el nombredinámicamente en función de encabezado de host de la solicitud entrante. La designación dinámica denombres le permite agrupar los rastros en función del nombre de dominio de la solicitud y aplicar unnombre predeterminado si el nombre no coincide con un patrón previsto (por ejemplo, si el encabezado dehost ha sido falsificado).
Solicitudes reenviadas
Si un balanceador de carga u otro intermediario reenvía una solicitud a la aplicación, X-Ray tomala dirección IP del cliente del encabezado X-Forwarded-For de la solicitud, en lugar de hacerlo
224
AWS X-Ray Guía para desarrolladoresConfiguración de una estrategiade nomenclatura de segmentos
de la dirección IP de origen del paquete IP. La dirección IP del cliente que se registra para unasolicitud reenviada puede falsificarse, por lo que no se debe confiar en ella.
Cuando se reenvía una solicitud, el SDK crea un campo adicional en el segmento para indicar que serealizó esta acción. Si el segmento contiene el campo x_forwarded_for establecido en true, ladirección IP del cliente se obtuvo del encabezado X-Forwarded-For de la solicitud HTTP.
El controlador crea un segmento para cada solicitud entrante con un bloque http que contiene la siguienteinformación:
• Método HTTP: GET, POST, PUT, DELETE, etc.• Dirección del cliente: la dirección IP del cliente que envió la solicitud.• Código de respuesta: el código de respuesta HTTP para la solicitud finalizada.• Intervalo: la hora de inicio (cuando se recibió la solicitud) y la hora de finalización (cuando se envió la
respuesta).• Agente del usuario: el user-agent de la solicitud.• Longitud de contenido: la content-length de la respuesta.
Configuración de una estrategia de nomenclatura desegmentosAWS X-Ray usa un nombre de servicio para identificar su aplicación y diferenciarla de las demásaplicaciones, bases de datos, API externas y recursos de AWS que usa la aplicación. Cuando el SDK deX-Ray genera segmentos para las solicitudes entrantes, registra el nombre de servicio de la aplicación enel campo de nombre del segmento (p. 124).
El SDK de X-Ray puede utilizar el nombre de host del encabezado de la solicitud HTTP para lossegmentos. Sin embargo, este encabezado se puede falsificar, por lo que podrían crearse nodosinesperados en el mapa de servicio. Para impedir que el SDK asigne incorrectamente nombres a lossegmentos debido a solicitudes con encabezados de host falsificados, debe especificar un nombrepredeterminado para las solicitudes entrantes.
Si la aplicación atiende solicitudes de varios dominios, puede configurar el SDK para que use unaestrategia de designación dinámica que refleje este comportamiento en los nombres de segmento. Conuna estrategia de designación dinámica, el SDK puede utilizar el nombre del host en las solicitudes quecoinciden con un patrón previsto y aplicar un nombre predeterminado en caso contrario.
Por ejemplo, puede tener una aplicación que sirva solicitudes a tres subdominios: www.example.com,api.example.com y static.example.com. Puede usar una estrategia de designación dinámicade nombres con el patrón *.example.com para identificar los segmentos de cada subdominio con unnombre diferente, lo que daría lugar a tres nodos de servicio en el mapa de servicio. Si la aplicación recibesolicitudes con un nombre de host que no coincide con el patrón, aparecerá un cuarto nodo en el mapa deservicio con el nombre alternativo que especifique.
Si desea utilizar el mismo nombre para todos los segmentos de solicitud, especifique el nombre de laaplicación cuando cree el controlador, tal y como se muestra en la sección anterior.
Note
Puede anular el nombre de servicio predeterminado que ha definido en el código mediante laAWS_XRAY_TRACING_NAMEvariable de entorno (p. 223).
Una estrategia de nomenclatura dinámica define un patrón con el que deben coincidir los nombres de hosty un nombre predeterminado que se utiliza si el nombre de host de la solicitud HTTP no coincide con elpatrón. Para nombrar segmentos de forma dinámica, utilice NewDynamicSegmentNamer para configurarel nombre predeterminado y el patrón que coincida.
225
AWS X-Ray Guía para desarrolladoresAWS Clientes de SDK
Example main.go
Si el nombre de host de la solicitud coincide con el patrón *.example.com, utilice el nombre de host. Delo contrario, utilice MyApp.
func main() { http.Handle("/", xray.Handler(xray.NewDynamicSegmentNamer("MyApp", "*.example.com"), http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.Write([]byte("Hello!")) })))
http.ListenAndServe(":8000", nil)}
Seguimiento de llamadas al AWS SDK con la SDKde X-Ray para Go
Cuando la aplicación realiza llamadas a AWS servicios de para almacenar datos, escribir en una cola oenviar notificaciones, el realiza un SDK de X-Ray para Go seguimiento de las llamadas posteriores en (p. 228)subsegmentos. AWS Los servicios y recursos rastreados a los que accede dentro de dichosservicios (por ejemplo, un Amazon S3 bucket de o una Amazon SQS cola de ) aparecen como nodosposteriores en el mapa de servicio de la X-Ray consola de .
Para rastrear clientes del SDK de AWS, envuelva el objeto de cliente con la llamada xray.AWS(), tal ycomo se muestra en el siguiente ejemplo.
Example main.go
var dynamo *dynamodb.DynamoDBfunc main() { dynamo = dynamodb.New(session.Must(session.NewSession())) xray.AWS(dynamo.Client)}
A continuación, cuando utilice el cliente del SDK de AWS, utilice la versión withContext del método dellamada y transfiera el context desde el objeto http.Request transferido al handler (p. 224).
Example main.go llamada al – AWS SDK
func listTablesWithContext(ctx context.Context) { output := dynamo.ListTablesWithContext(ctx, &dynamodb.ListTablesInput{}) doSomething(output)}
En todos los servicios, puede ver el nombre de la API a la que se ha llamado en la consola de X-Ray. Paraun subconjunto de servicios, el SDK de X-Ray añade información al segmento para proporcionar un mapadel servicio más detallado.
Por ejemplo, cuanto hace una llamada con un cliente de DynamoDB instrumentado, el SDK añade elnombre de la tabla al segmento para las llamadas cuyo destino es una tabla. En la consola, cada tablaaparece como un nodo distinto en el mapa del servicio, con un nodo genérico de DynamoDB para lasllamadas que no van dirigidas a una tabla.
Example Subsegmento para una llamada a DynamoDB para guardar un elemento
{
226
AWS X-Ray Guía para desarrolladoresLlamadas a HTTP salientes
"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", }}
Cuando accede a recursos designados, las llamadas a los siguientes servicios crean nodos adicionales enel mapa de servicio. Las llamadas que no están dirigidas a recursos concretos crean un nodo genérico enel servicio.
• Amazon DynamoDB: nombre de la tabla• Amazon Simple Storage Service: nombre de bucket y de clave• Amazon Simple Queue Service: nombre de la cola
Seguimiento de llamadas a servicios web HTTPposteriores con el SDK de X-Ray para Go
Cuando la aplicación realiza llamadas a las API de HTTP público o microservicios, puede utilizar elxray.Client para instrumentar dichas llamadas como subsegmentos de su aplicación Go, tal y como semuestra en el siguiente ejemplo, donde http-client es un cliente HTTP.
El cliente crea una copia superficial del cliente HTTP proporcionado, con el valor predeterminadohttp.DefaultClient, con roundtripper envuelto con xray.RoundTripper.
Example
<caption>main.go – cliente HTTP</caption>
myClient := xray.Client(http-client)
<caption>main.go Permite – rastrear llamadas HTTP posteriores con la biblioteca ctxhttp</caption>
En el siguiente ejemplo se instrumenta la llamada HTTP saliente con la biblioteca ctxhttp mediantexray.Client. ctx se puede pasar desde la llamada ascendente. Esto garantiza que se utilice el contextode segmento existente. Por ejemplo, X-Ray no permite crear un nuevo segmento dentro de una funciónLambda, por lo que se debe utilizar el contexto de segmentos Lambda existente.
resp, err := ctxhttp.Get(ctx, xray.Client(nil), url)
227
AWS X-Ray Guía para desarrolladoresConsultas SQL
Seguimiento de consultas SQL con el SDK de X-Ray para Go
Para rastrear llamadas de SQL a PostgreSQL o MySQL, sustituyendo llamadas de sql.Open axray.SQLContext, tal y como se muestra en el siguiente ejemplo. Utilice URL en lugar de cadenas deconfiguración si es posible.
Example main.go
func main() { db, err := xray.SQLContext("postgres", "postgres://user:password@host:port/db") row, err := db.QueryRowContext(ctx, "SELECT 1") // Use as normal}
Generación de subsegmentos personalizados conel SDK de X-Ray para Go
Los subsegmentos extienden el segmento (p. 21) de un rastro con detalles sobre el trabajo realizado paraatender una solicitud. Cada vez que se realiza una llamada con un cliente instrumentado, el SDK de X-Rayregistra la información generada en un subsegmento. Puede crear subsegmentos adicionales para agruparotros subsegmentos, para medir el desempeño de una sección de código o para registrar anotaciones ymetadatos.
Utilice el método Capture para crear un subsegmento en torno a una función.
Example main.go: subsegmento personalizado
func criticalSection(ctx context.Context) { //this is an example of a subsegment xray.Capture(ctx, "GameModel.saveGame", func(ctx1 context.Context) error { var err error
section.Lock() result := someLockedResource.Go() section.Unlock()
xray.AddMetadata(ctx1, "ResourceResult", result) })
En la siguiente captura de pantalla se muestra un ejemplo de cómo podría aparecer el subsegmentosaveGame en rastreos para la aplicación Scorekeep.
228
AWS X-Ray Guía para desarrolladoresAnotaciones y metadatos
Agregar anotaciones y metadatos a los segmentoscon el SDK de X-Ray para Go
Puede registrar información adicional sobre las solicitudes, el entorno o la aplicación con anotaciones ymetadatos. Puede añadir anotaciones y metadatos a los segmentos creados por el SDK de X-Ray o a lossubsegmentos personalizados creados por usted.
Las anotaciones son pares de clave-valor con valores de cadena, numéricos o booleanos. Las anotacionesse indexan para su uso con expresiones de filtro (p. 64). Utilice anotaciones para registrar los datos quedesee utilizar para agrupar rastros en la consola o cuando llame a la API de GetTraceSummaries.
Metadata son los pares clave-valor que pueden tener valores de cualquier tipo, incluso objetos y listas,pero que no se indexan para su uso con expresiones de filtro. Utilice los metadatos para registrar otrosdatos que desee almacenar en el rastro, pero que no necesite usar para buscar.
Además de anotaciones y metadatos, también puede registrar cadenas de ID de usuario (p. 230) en lossegmentos. Los identificadores de usuario se registran en un campo aparte en segmentos y se indexanpara su uso con la búsqueda.
Secciones• Registro de anotaciones con el SDK de X-Ray para Go (p. 229)• Registro de metadatos con el SDK de X-Ray para Go (p. 230)• Registro de ID de usuario con el SDK de X-Ray para Go (p. 230)
Registro de anotaciones con el SDK de X-Ray paraGoUtilice anotaciones para registrar información sobre segmentos que desee indexar para las búsquedas.
Requisitos de anotación
• Claves: hasta 500 caracteres alfanuméricos. Sin espacios ni símbolos excepto el guion bajo.• Valores: hasta 1,000 caracteres Unicode.• Entradas: hasta 50 anotaciones por rastro.
229
AWS X-Ray Guía para desarrolladoresRegistro de metadatos con el SDK de X-Ray para Go
Para grabar anotaciones, llame a AddAnnotation con una cadena que contenga los metadatos quedesea asociar con el segmento.
xray.AddAnnotation(key string, value interface{})
El SDK registra las anotaciones como pares de clave-valor en un objeto annotations del documentode segmento. Si llama dos veces a AddAnnotation con la misma clave, se sobrescriben los valorespreviamente registrados en el mismo segmento.
Para encontrar rastros que tengan anotaciones con valores específicos, utilice la palabra claveannotations.key en una expresión de filtro (p. 64).
Registro de metadatos con el SDK de X-Ray para GoUtilice los metadatos para registrar información sobre segmentos que no necesite indexar para lasbúsquedas.
Para registrar metadatos, llame a AddMetadata con una cadena que contenga los metadatos que deseaasociar con el segmento.
xray.AddMetadata(key string, value interface{})
Registro de ID de usuario con el SDK de X-Ray paraGoRegistre identificadores de usuario en segmentos de solicitud para identificar al usuario que envió lasolicitud.
Para registrar identificadores de usuario
1. Obtenga una referencia al segmento actual desde AWSXRay.
import ( "context" "github.com/aws/aws-xray-sdk-go/xray")
mySegment := xray.GetSegment(context)
2. Llame a setUser con un ID de cadena del usuario que envió la solicitud.
mySegment.User = "U12345"
Para buscar rastros de un ID de usuario, utilice la palabra clave user en una expresión de filtro (p. 64).
230
AWS X-Ray Guía para desarrolladores
AWS X-Ray SDK para JavaEl X-Ray SDK for Java es un conjunto de bibliotecas para aplicaciones web Java que proporcionan clasesy métodos para generar y enviar datos de rastreo al demonio de X-Ray. Los datos de rastreo incluyeninformación sobre las solicitudes HTTP entrantes que atiende la aplicación y las llamadas que la aplicaciónrealiza a los servicios posteriores mediante el AWS SDK de , clientes HTTP o un conector de base dedatos SQL. También puede crear segmentos de forma manual y agregar información de depuración enanotaciones y metadatos.
Note
El X-Ray SDK for Java es un proyecto de código abierto. Puede seguir el proyecto, enviarproblemas y solicitudes de extracción en GitHub: github.com/aws/aws-xray-sdk-java
Comience añadiendo AWSXRayServletFilter como filtro de servlet (p. 250) para rastrear lassolicitudes entrantes. Los filtros de servlets crean un segmento (p. 21). Mientras el segmento está abierto,puede utilizar los métodos del cliente del SDK para añadir información al segmento y crear subsegmentospara rastrear llamadas posteriores. El SDK también registra automáticamente las excepciones que producesu aplicación mientras el segmento está abierto.
A partir de la versión 1.3, puede instrumentar una aplicación mediante la programación orientada aaspectos (AOP) de Spring (p. 267). Esto significa que puede instrumentar la aplicación mientras se estáejecutando en AWSsin añadir ningún código al tiempo de ejecución de la aplicación.
A continuación, utilice el X-Ray SDK for Java para instrumentar sus clientes de AWS SDK for Javamediante la inclusión del submódulo Instrumentor del SDK (p. 233) en la configuración de compilación.Siempre que realice una llamada a un AWS servicio o recurso posterior con un cliente instrumentado, elSDK de registra información sobre la llamada en un subsegmento. AWS Los servicios de y los recursosa los que accede dentro de los servicios aparecen como nodos posteriores en el mapa de servicio paraayudarle a identificar errores y problemas de limitación controlada en conexiones individuales.
Si no desea instrumentar todas las llamadas posteriores a AWS los servicios de , puede omitir elsubmódulo Instrumentor y elegir qué clientes instrumentar. Instrumente clientes individuales añadiendo unTracingHandler (p. 254) a un cliente de servicio AWS del SDK.
Otros submódulos del X-Ray SDK for Java proporcionan instrumentación para las llamadas posterioresa API de web HTTP y a bases de datos SQL. Puede utilizar las versiones de X-Ray SDK for Java yHTTPClient del HTTPClientBuilder (p. 255) en el submódulo Apache HTTP para instrumentarclientes Apache HTTP. Para instrumentar consultas SQL, añada el interceptor del SDK al origen dedatos (p. 257).
En cuanto empiece a utilizar el SDK, personalice su comportamiento configurando el grabador y el filtrode servlet (p. 242). Puede añadir complementos para registrar los datos sobre los recursos informáticosque ejecutan su aplicación, personalizar el comportamiento de muestreo mediante la definición dereglas de muestreo y definir el nivel de log para ver más o menos información del SDK en los logs de lasaplicaciones.
Registre información adicional acerca de las solicitudes y el trabajo que la aplicación realiza enanotaciones y metadatos (p. 260). Las anotaciones son pares sencillos de clave-valor que se indexanpara su uso con expresiones de filtro (p. 64) para poder buscar rastros que contengan datos específicos.Las entradas de metadatos son menos restrictivas y pueden registrar objetos y matrices completos —esdecir, todo lo que se pueda serializar en JSON.
Anotaciones y metadatos
Las anotaciones y los metadatos son texto arbitrario que se añade a los segmentos con el SDK deX-Ray. Las anotaciones se indexan para su uso con expresiones de filtro. Los metadados no se
231
AWS X-Ray Guía para desarrolladoresSubmodules
indexan, pero se pueden consultar en un segmento sin formato con la consola o la API de X-Ray.Todas las personas a las que otorgue acceso de lectura a X-Ray pueden ver estos datos.
Si tiene un gran número de clientes instrumentados en su código, un único segmento de solicitudpuede contener muchos subsegmentos, uno por cada llamada realizada con un cliente instrumentado.Puede organizar y agrupar los subsegmentos incluyendo las llamadas del cliente en subsegmentospersonalizados (p. 258). Puede crear un subsegmento personalizado para una función completa o paracualquier sección de código, y registrar los metadatos y las anotaciones en el subsegmento en lugar deescribirlo todo en el segmento principal.
SubmodulesPuede descargar el X-Ray SDK for Java desde Maven. El X-Ray SDK for Java está dividido ensubmódulos por caso de uso, con una factura de materiales para la administración de las versiones:
• aws-xray-recorder-sdk-core (obligatorio) – funcionalidad básica para la creación y transmisión desegmentos. Incluye AWSXRayServletFilter para instrumentar solicitudes entrantes.
• aws-xray-recorder-sdk-aws-sdk – instrumenta llamadas a AWS servicios realizados con AWSSDK for Java clientes de añadiendo un cliente de rastreo como controlador de solicitudes.
• aws-xray-recorder-sdk-aws-sdk-v2 – instrumenta llamadas a AWS servicios realizadoscon clientes AWS SDK for Java 2.2 y versiones posteriores añadiendo un cliente de rastreo comointerceptador de solicitudes.
• aws-xray-recorder-sdk-aws-sdk-instrumentor – con aws-xray-recorder-sdk-aws-sdk,instrumenta todos los clientes AWS SDK for Java de forma automática.
• aws-xray-recorder-sdk-aws-sdk-v2-instrumentor – con aws-xray-recorder-sdk-aws-sdk, instrumenta de forma automática todos los clientes de AWS SDK for Java 2.2 y versionesposteriores.
• aws-xray-recorder-sdk-apache-http – instrumenta llamadas HTTP salientes realizadas conclientes Apache HTTP.
• aws-xray-recorder-sdk-spring – proporciona interceptores para las aplicaciones del marco detrabajo Spring AOP.
• aws-xray-recorder-sdk-sql-postgres – instrumenta llamadas salientes a la base de datosPostgreSQL realizadas con JDBC.
• aws-xray-recorder-sdk-sql-mysql – instrumenta llamadas salientes a la base de datos MySQLrealizadas con JDBC.
• aws-xray-recorder-sdk-bom – proporciona una lista de materiales que puede utilizar paraespecificar la versión que se debe utilizar en todos los submódulos.
• aws-xray-recorder-sdk-metrics – Publique Amazon CloudWatch métricas sin muestrear de los X-Ray segmentos recopilados.
Si utiliza Maven o Gradle para crear la aplicación, añada el X-Ray SDK for Java a la configuración decompilación (p. 233).
Para ver la documentación de referencia de las clases y los métodos del SDK, consulte AWS X-Ray SDKfor Java API Reference.
RequirementsEl X-Ray SDK for Java requiere Java 8 o una versión posterior, Servlet API 3, el AWS SDK y Jackson.
El SDK depende de las siguientes bibliotecas durante la compilación y el tiempo de ejecución:
232
AWS X-Ray Guía para desarrolladoresAdministración de dependencias
• AWS SDK para Java versión 1.11.398 o posterior• Servlet API 3.1.0
Estas dependencias se declaran en el archivo pom.xml del SDK y se incluyen de forma automática sirealiza la compilación con Maven o Gradle.
Si utiliza una biblioteca que se incluye en el X-Ray SDK for Java, debe utilizar la versión que se incluye.Por ejemplo, si ya depende de Jackson durante el tiempo de ejecución e incluye archivos JAR en laimplementación de esa dependencia, debe eliminar dichos archivos porque el archivo JAR del SDK incluyesus propias versiones de las bibliotecas Jackson.
Administración de dependenciasEl X-Ray SDK for Java se encuentra disponible en Maven:
• Grupo – com.amazonaws• Artefacto – aws-xray-recorder-sdk-bom• Versión – 2.4.0
Si utiliza Maven para compilar la aplicación, añada el SDK como dependencia en su archivo pom.xml.
Example pom.xml - Dependencias
<dependencyManagement> <dependencies> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-bom</artifactId> <version>2.4.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies></dependencyManagement><dependencies> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-core</artifactId> </dependency> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-apache-http</artifactId> </dependency> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-aws-sdk</artifactId> </dependency> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-aws-sdk-instrumentor</artifactId> </dependency> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-sql-postgres</artifactId> </dependency> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-sql-mysql</artifactId>
233
AWS X-Ray Guía para desarrolladoresAWS X-Ray Agente de instrucción automática de para Java
</dependency></dependencies>
Si utiliza Gradle, añada el SDK como dependencia de tiempo de compilación en su archivobuild.gradle.
Example build.gradle - Dependencias
dependencies { compile("org.springframework.boot:spring-boot-starter-web") testCompile("org.springframework.boot:spring-boot-starter-test") compile("com.amazonaws:aws-java-sdk-dynamodb") compile("com.amazonaws:aws-xray-recorder-sdk-core") compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk") compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk-instrumentor") compile("com.amazonaws:aws-xray-recorder-sdk-apache-http") compile("com.amazonaws:aws-xray-recorder-sdk-sql-postgres") compile("com.amazonaws:aws-xray-recorder-sdk-sql-mysql") testCompile("junit:junit:4.11")}dependencyManagement { imports { mavenBom('com.amazonaws:aws-java-sdk-bom:1.11.39') mavenBom('com.amazonaws:aws-xray-recorder-sdk-bom:2.4.0') }}
Si utiliza Elastic Beanstalk para implementar la aplicación, puede utilizar Maven o Gradle para compilar laaplicación en la instancia cada vez que realice la implementación, en lugar de compilar y cargar un archivode gran tamaño que incluya todas sus dependencias. Consulte la aplicación de ejemplo (p. 137) para verun ejemplo en el que se utiliza Gradle.
AWS X-Ray Agente de instrucción automática depara Java
El agente de implementación AWS X-Ray automática de para Java es una solución de rastreo queinstrumenta sus aplicaciones web Java con un esfuerzo de desarrollo mínimo. El agente de habilitaautomáticamente el rastreo de para aplicaciones basadas en servlet y todas las solicitudes posterioresdel agente realizadas con marcos y bibliotecas compatibles. Esto incluye las solicitudes HTTP de Apacheposteriores, las solicitudes AWS SDK y las consultas SQL realizadas con un controlador JDBC. El agentepropaga automáticamente el X-Ray contexto, incluidos todos los segmentos y subsegmentos activos, entresubprocesos. Todas las configuraciones y la flexibilidad del X-Ray SDK siguen estando disponibles conel agente de Java, y se eligieron los valores predeterminados adecuados para garantizar que el agentefuncione de inmediato.
La solución X-Ray del agente es más adecuada para servidores de aplicaciones web Java basados enservlet y de respuesta de solicitudes. Si la aplicación utiliza un marco asíncrono o no está bien modeladacomo un servicio de solicitud-respuesta, es posible que desee considerar la instrumentación manual con elSDK en su lugar.
El X-Ray agente de se crea con el Distributed Systems Comprehension Toolkit o DiSCo. DiSCo es unmarco de código abierto para crear agentes de Java que se pueden utilizar en sistemas distribuidos.Aunque no es necesario entender DiSCo para utilizar el X-Ray agente, puede obtener más informaciónsobre el proyecto visitando su página de inicio en GitHub. El X-Ray agente también tiene código abiertocompleto. Para ver el código fuente, hacer contribuciones o plantear problemas sobre el agente, visite surepositorio en GitHub.
234
AWS X-Ray Guía para desarrolladoresAplicación de muestra
Aplicación de muestraLa aplicación de ejemplo eb-java-scorekeep se ha adaptado para instrumentarse con el X-Ray agente de .Esta ramificación no contiene ninguna configuración de filtro de servlet ni de grabadora, ya que el agentede realiza estas funciones. Para ejecutar la aplicación localmente o utilizar AWS recursos de , siga lospasos que se indican en el archivo readme de la aplicación de ejemplo. Las instrucciones para utilizar laaplicación de muestra para generar X-Ray rastros se encuentran en el tutorial (p. 137)de la aplicación demuestra.
IntroducciónPara comenzar a utilizar el agente de Java de instrucción X-Ray automática en su propia aplicación, sigaestos pasos.
1. Ejecute el X-Ray demonio de en su entorno. Para obtener más información, consulte X-Ray demoniode .
2. Descargue la última distribución del agente de . Descomprima el archivo y anote su ubicación en elsistema de archivos. Su contenido debe ser similar al siguiente.
disco ### disco-java-agent.jar ### disco-plugins ### aws-xray-agent-plugin.jar ### disco-java-agent-aws-plugin.jar ### disco-java-agent-sql-plugin.jar ### disco-java-agent-web-plugin.jar
3. Modifique los argumentos de JVM de la aplicación para incluir lo siguiente, lo que habilita el agentede . Asegúrese de que el -javaagent argumento se coloca antes que el -jar argumento si procede.El proceso para modificar argumentos de JVM varía en función de las herramientas y los marcos detrabajo que utilice para lanzar el servidor Java; por tanto, consulte la documentación del marco deservidores para obtener instrucciones específicas.
-javaagent:/<path-to-disco>/disco-java-agent.jar=pluginPath=/<path-to-disco>/disco-plugins
4. Para especificar el nombre de la aplicación tal como aparecerá en la X-Ray consola,establezca la variable de AWS_XRAY_TRACING_NAMEentorno o la propiedadcom.amazonaws.xray.strategy.tracingNamedel sistema. Si no se proporciona ningún nombre,se utiliza un nombre predeterminado.
5. Reinicie el servidor o el contenedor. Las solicitudes entrantes y sus llamadas posteriores ahora serastrean. Si no ve los resultados esperados, consulte the section called “Troubleshooting” (p. 241).
ConfigurationEl X-Ray agente se configura mediante un archivo JSON externo proporcionado por el usuario. Deforma predeterminada, este archivo se encuentra en la raíz del classpath del usuario (por ejemplo, en suresourcesdirectorio ) denominado xray-agent.json. Puede configurar una ubicación personalizadapara el archivo de configuración estableciendo la propiedad com.amazonaws.xray.configFile delsistema en la ruta absoluta del sistema de archivos de su archivo de configuración.
A continuación se muestra un archivo de configuración de ejemplo.
{ "serviceName": "XRayInstrumentedService",
235
AWS X-Ray Guía para desarrolladoresConfiguration
"contextMissingStrategy": "LOG_ERROR", "daemonAddress": "127.0.0.1:2000", "tracingEnabled": true, "samplingStrategy": "CENTRAL", "traceIdInjectionPrefix": "prefix", "samplingRulesManifest": "/path/to/manifest", "awsServiceHandlerManifest": "/path/to/manifest", "awsSdkVersion": 2, "maxStackTraceLength": 50, "streamingThreshold": 100, "traceIdInjection": true, "pluginsEnabled": true, "collectSqlQueries": false }
Especificación de configuraciónEn la siguiente tabla se describen los valores válidos para cada propiedad. Los nombres de propiedaddistinguen entre mayúsculas y minúsculas, pero sus claves no. Para propiedades que las variables deentorno y las propiedades del sistema pueden anular, el orden de prioridad es siempre variable de entorno,luego propiedad del sistema y, a continuación, archivo de configuración. Consulte los X-Ray documentospara obtener información sobre las propiedades que puede anular. Todos los campos son opcionales.
Nombre dela propiedad
Tipo Valoresválidos
Descripción Variable deentorno
Propiedaddel sistema
Valorpredeterminado
serviceName Cadena Cualquiercadena
El nombredel servicioinstrumentadotal y comoapareceráen la X-Rayconsola de .
AWS_XRAY_TRACING_NAME(NOMBRE_DE_RASTREO_DE_AWS_XRAY)
com.amazonaws.xray.strategy.tracingNameXRayInstrumentedService
contextMissingStrategyCadena LOG_ERROR,IGNORE_ERROR(ERROR_DE_REGISTRO),IGNORE_ERROR(ERROR_DE_IGNORACIÓN)
La acciónrealizada porel agentecuandointentautilizar elcontextode X-Raysegmento,pero no estápresenteninguno.
AWS_XRAY_CONTEXT_MISSINGcom.amazonaws.xray.strategy.contextMissingStrategyERROR_REGISTRO
daemonAddressCadena Dirección IPcon formatoy puerto,o lista dedireccionesTCP y UDP
La direcciónque elagenteutiliza paracomunicarsecon el X-Raydemonio de .
DIRECCIÓN_DE_DAEMON_DE_AWS_XRAYcom.amazonaws.xray.emitter.daemonAddress127.0.0.1:2000
tracingEnabledBooleano Verdadero,falso
Habilita lainstrumentaciónpor parte
AWS_XRAY_TRACING_ENABLED(AWS_XRAY_TRACING_ENABLED)
com.amazonaws.xray.tracingEnabledTRUE
236
AWS X-Ray Guía para desarrolladoresConfiguration
Nombre dela propiedad
Tipo Valoresválidos
Descripción Variable deentorno
Propiedaddel sistema
Valorpredeterminado
del X-Rayagente.
samplingStrategyCadena CENTRAL,LOCAL,NINGUNO,TODOS
La estrategiade muestreoutilizada porel agente.ALL capturatodas lassolicitudes,NONE nocapturaningunasolicitud.Consultelas reglashttps://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-java-configuration.html#xray-sdk-java-configuration-samplingdemuestreo.
N/A N/A CENTRAL
traceIdInjectionPrefixCadena Cualquiercadena
Incluyeel prefijoproporcionadoantes de losIDs de rastroinyectadosen losregistros de .
N/A N/A Ninguno(cadenavacía)
237
AWS X-Ray Guía para desarrolladoresConfiguration
Nombre dela propiedad
Tipo Valoresválidos
Descripción Variable deentorno
Propiedaddel sistema
Valorpredeterminado
samplingRulesManifestCadena Una rutade archivoabsoluta
La ruta a unarchivo dereglas demuestreopersonalizadoque se va autilizar comoorigen dereglas demuestreopara laestrategiade muestreolocal olas reglasalternativaspara laestrategiacentral.
N/A N/A DefaultSamplingRules.json
awsServiceHandlerManifestCadena Una rutade archivoabsoluta
La ruta a unparámetropersonalizadopermite lalista , quecapturainformaciónadicional delos clientesdel AWSSDK.
N/A N/A DefaultOperationParameterWhitelist.json
awsSdkVersionEntero 1, 2 Versión delAWS SDKpara Javaque estáutilizando.Se pasa poralto si noawsServiceHandlerManifestsehaestablecidotambién .
N/A N/A 2
maxStackTraceLengthEntero Númerosenteros nonegativos
Las líneasmáximasde unseguimientode pila quese van aregistraren unseguimiento.
N/A N/A 50
238
AWS X-Ray Guía para desarrolladoresConfiguration
Nombre dela propiedad
Tipo Valoresválidos
Descripción Variable deentorno
Propiedaddel sistema
Valorpredeterminado
streamingThresholdEntero Númerosenteros nonegativos
Despuésde que secierren almenos estossubsegmentos,setransmitenal demoniofuera debandapara evitarque losfragmentosseandemasiadograndes.
N/A N/A 100
traceIdInjectionBooleano Verdadero,falso
Habilita lainyección deID de X-Rayrastro enregistros desi tambiénse hanañadido lasdependenciasy laconfiguracióndescritasen laconfiguraciónde inlogging.De locontrario, nohace nada.
N/A N/A TRUE
pluginsEnabledBooleano Verdadero,falso
Habilitacomplementosque registranmetadatossobrelos AWSentornosen los queopera.ConsulteComplementosde .
N/A N/A TRUE
239
AWS X-Ray Guía para desarrolladoresConfiguration
Nombre dela propiedad
Tipo Valoresválidos
Descripción Variable deentorno
Propiedaddel sistema
Valorpredeterminado
collectSqlQueriesBooleano Verdadero,falso
Registracadenasde consultaSQL ensubsegmentosSQL en lamedida de loposible.
N/A N/A FALSE
contextPropagationBooleano Verdadero,falso
propagael X-Raycontextoautomáticamenteentresubprocesossi esverdadero.De locontrario,utilizaThreadLocal paraalmacenarel contextoy serequiere lapropagaciónmanual entresubprocesos.
N/A N/A TRUE
Instrumentación manualSi desea realizar la instrumentación manual además de la instrumentación automática del agente, añadael X-Ray SDK como dependencia al proyecto. Tenga en cuenta que los filtros de servlet personalizados delSDK mencionados en Rastreo de solicitudes entrantes (p. 250) no son compatibles con el X-Ray agentede .
Note
Debe utilizar la versión más reciente del X-Ray SDK para realizar la instrumentación manual ytambién utilizar el agente de .
Si está trabajando en un proyecto de Maven, añada las siguientes dependencias al pom.xmlarchivo .
<dependencies> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-core</artifactId> <version>2.8.0</version> </dependency> </dependencies>
Si está trabajando en un proyecto de Gradle, añada las siguientes dependencias albuild.gradlearchivo .
240
AWS X-Ray Guía para desarrolladoresTroubleshooting
implementation 'com.amazonaws:aws-xray-recorder-sdk-core:2.8.0'
Puede añadir subsegmentos (p. 258) personalizados, así como anotaciones, metadatos e IDs (p. 260)usuario al utilizar el agente, como haría con el SDK normal. El agente propaga automáticamente elcontexto entre subprocesos, por lo que no deben ser necesarias soluciones para propagar contextocuando se trabaja con aplicaciones con varios subprocesos.
TroubleshootingDado que el agente ofrece una instrumentación totalmente automática, puede ser difícil identificar la causaraíz de un problema cuando está experimentando problemas. Si el X-Ray agente no funciona segúnlo previsto, revise los siguientes problemas y soluciones. El X-Ray agente de y el SDK utilizan JakartaCommons Logging (JCL), por lo que para ver la salida de registro, tendrá que asegurarse de que hay unpuente que conecta JCL al backend de registro en el classpath, por log4j-jcl ejemplo, o jcl-over-slf4j.
Problema: he habilitado el agente de Java de en mi aplicación,pero no veo nada en la X-Ray consola de¿El X-Ray demonio de se está ejecutando en la misma máquina?
En caso contrario, consulte la documentación del X-Ray demonio para configurarlo.
En los logs de la aplicación, aparece un mensaje como "Initializing the X-Ray agent recorder"?
Este mensaje se registra en el nivel INFO cuando se inicia la aplicación, antes de empezar a recibirsolicitudes, si ha añadido correctamente el agente de a la aplicación. Si este mensaje no aparece, elagente de Java no se está ejecutando con el proceso de Java. Asegúrese de que ha seguido todos lospasos de configuración correctamente sin errores tipográficos.
En los logs de la aplicación, ¿verá varios mensajes de error que indican algo como "Supresión de unaexcepción que falta en AWS X-Ray el contexto"?
Estos errores se producen porque el agente está intentando instrumentar solicitudes posteriores, comosolicitudes AWS del SDK o consultas SQL, pero el agente no ha podido crear automáticamente unsegmento. Si observa muchos de estos errores, es posible que el agente no sea la mejor herramientapara su caso de uso y que, en su lugar, desee considerar la instrumentación manual con el X-Ray SDK.También puede habilitar los registrosX-Ray de depuración https://docs.aws.amazon.com/xray/latest/devguide/ray-sdk-java-configuration.html#xray-sdk-java-configuration-loggingdel SDK para ver el rastro dela pila de donde se producen las excepciones que faltan en el contexto. Puede envolver estas partes delcódigo con segmentos personalizados, lo que debería resolver estos errores. Para ver un ejemplo de cómoencapsular solicitudes posteriores con segmentos personalizados, consulte el código de muestra de códigode implementación de código de inicio.
Problema: algunos de los segmentos que esperaba no aparecenen la X-Ray consola de¿Utiliza la aplicación múltiples subprocesos?
Si algunos segmentos que espera que se creen no aparecen en la consola de , los subprocesos ensegundo plano de la aplicación podrían ser la causa. Si la aplicación realiza tareas utilizando subprocesosen segundo plano que son "disparar y olvidarse", como realizar una llamada única a una función Lambdacon el AWS SDK o sondear algún punto de enlace HTTP periódicamente, esto puede confundir al agente
241
AWS X-Ray Guía para desarrolladoresConfiguración
mientras propaga el contexto entre subprocesos. Para verificar que este es el problema, habilite losregistros de depuración del X-Ray SDK y compruebe si hay mensajes como: No emitiendo un segmentodenominado <NAME > como subsegmentos en curso principales. Para solucionar este problema, puedeintentar unir los subprocesos en segundo plano antes de que el servidor vuelva para asegurarse deque se registre todo el trabajo realizado en ellos. O bien, puede establecer la contextPropagationconfiguración del agente en false para deshabilitar la propagación de contexto en subprocesos ensegundo plano. Si lo hace, tendrá que instrumentar manualmente esos subprocesos con segmentospersonalizados o hacer caso omiso de las excepciones que faltan en el contexto que producen.
¿Ha configurado reglas de muestreo?
Si parece parecer que hay segmentos aleatorios o inesperados en la X-Ray consola, o los segmentosque espera que estén en la consola no lo están, es posible que haya un problema de muestreo. El X-Rayagente aplica el muestreo centralizado a todos los segmentos que crea, utilizando las reglas de la X-Rayconsola de . La regla predeterminada es de 1 segmento por segundo, más el 5 % de los segmentos acontinuación se muestrean. Esto significa que es posible que no se muestreen los segmentos que se creanrápidamente con el agente. Para resolver esto, debe crear reglas de muestreo personalizadas en la X-Rayconsola de que muestreen de forma adecuada los segmentos deseados. Para obtener más información,consulte Muestreo de .
Configuración del X-Ray SDK for JavaEl X-Ray SDK for Java incluye una clase denominada AWSXRay que proporciona la grabadora global. Estoes un TracingHandler que puede utilizar para instrumentar su código. Puede configurar la grabadoraglobal para que personalice el AWSXRayServletFilter que crea los segmentos para las llamadas HTTPentrantes.
Secciones• Complementos del servicio (p. 242)• Reglas de muestreo (p. 244)• Logging (p. 246)• Agentes de escucha de segmento (p. 249)• Variables de entorno (p. 250)• Propiedades del sistema (p. 250)
Complementos del servicioUtilice plugins para registrar información sobre el servicio que aloja su aplicación.
Plugins
• Amazon EC2: EC2Plugin agrega el ID de instancia, la zona de disponibilidad y el grupo de CloudWatchLogs.
• Elastic Beanstalk – ElasticBeanstalkPlugin añade el nombre de entorno, la etiqueta de versión y elID de implementación.
• Amazon ECS – ECSPlugin añade el ID del contenedor.• Amazon EKS: EKSPlugin agrega el ID del contenedor, el nombre del clúster, el ID del pod y el grupo de
CloudWatch Logs.
242
AWS X-Ray Guía para desarrolladoresComplementos del servicio
Para utilizar un complemento, llame a withPlugin en su AWSXRayRecorderBuilder.
Example src/main/java/scorekeep/WebConfig.java: grabadora
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.AWSXRayRecorderBuilder;import com.amazonaws.xray.plugins.EC2Plugin;import com.amazonaws.xray.plugins.ElasticBeanstalkPlugin;import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;
@Configurationpublic class WebConfig {... static { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()).withPlugin(new ElasticBeanstalkPlugin());
243
AWS X-Ray Guía para desarrolladoresReglas de muestreo
URL ruleFile = WebConfig.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build()); }}
El SDK también utiliza la configuración del complemento para establecer el campo origin del segmento.Esto indica el tipo de recurso de AWS que ejecuta la aplicación. El tipo de recurso aparece bajo el nombrede la aplicación en el mapa del servicio. Por ejemplo, AWS::ElasticBeanstalk::Environment.
Cuando utiliza varios complementos, el SDK utiliza la siguiente orden de resolución para determinar elorigen: ElasticBeanstalk > EKS > ECS > EC2.
Reglas de muestreoEl SDK utiliza reglas de muestreo que usted define en la consola de X-Ray para determinar qué solicitudesdebe registrar. La regla predeterminada rastrea la primera solicitud de cada segundo y un cinco porciento de todas las solicitudes adicionales en todos los servicios que envían rastros a X-Ray. Cree reglasadicionales en la consola de X-Ray (p. 76) para personalizar la cantidad de datos registrados para cadauna de sus aplicaciones.
El SDK aplica las reglas personalizadas en el orden en que se definen. Si una solicitud coincide con variasreglas personalizadas, el SDK aplica solo la primera regla.
Note
Si el SDK no puede conectar con X-Ray para obtener las reglas de muestreo, utiliza una reglapredeterminada local de la primera solicitud de cada segundo y un cinco por ciento de todas lassolicitudes adicionales para cada host. Esto puede ocurrir si el host no tiene permiso para llamara las API de muestreo o no puede conectarse con el daemon de X-Ray, que actúa como un proxyTCP para las llamadas a la API realizadas por el SDK.
También puede configurar el SDK para que cargue las reglas de muestreo desde un documento JSON. ElSDK puede usar reglas locales como reserva para aquellos casos en los que el muestreo de X-Ray no estédisponible, o bien usar reglas locales exclusivamente.
Example sampling-rules.json
{ "version": 2,
244
AWS X-Ray Guía para desarrolladoresReglas de muestreo
"rules": [ { "description": "Player moves.", "host": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 }}
Este ejemplo define una regla personalizada y una regla predeterminada. La regla personalizada aplica unporcentaje de muestreo del cinco por ciento sin un número mínimo de solicitudes para rastrear las rutas deacceso de /api/move/. La regla predeterminada rastrea la primera solicitud cada segundo y un 10 porciento de las solicitudes adicionales.
El inconveniente de definir reglas localmente es que cada instancia del grabador aplica el porcentaje fijode forma independiente, en lugar de dejar que se encargue el servicio de X-Ray. Cuando implemente máshosts, la tasa fija se multiplicará, lo que hará que sea más difícil controlar la cantidad de datos registrados.
En AWS Lambda, no se puede modificar la frecuencia de muestreo. Si un servicio instrumentado llamaa la función, Lambda registrará las solicitudes generadas por llamadas que fueron muestreadas porese servicio. Si el rastreo activo está activado y no hay ningún encabezado de rastreo, Lambda toma ladecisión de muestreo.
Para proporcionar reglas de copia de seguridad en Spring, configure la grabadora global con unaCentralizedSamplingStrategy en una clase de configuración:
Example src/main/java/myapp/WebConfig.java: configuración de la grabadora
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.AWSXRayRecorderBuilder;import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;import com.amazonaws.xray.plugins.EC2Plugin;import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;
@Configurationpublic class WebConfig {
static { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin());
URL ruleFile = WebConfig.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build());}
Para Tomcat, añada un agente de escucha que amplíe ServletContextListener y registre el agentede escucha en el descriptor de la implementación.
Example src/com/myapp/web/Startup.java
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.AWSXRayRecorderBuilder;
245
AWS X-Ray Guía para desarrolladoresLogging
import com.amazonaws.xray.plugins.EC2Plugin;import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;
import java.net.URL;import javax.servlet.ServletContextEvent;import javax.servlet.ServletContextListener;
public class Startup implements ServletContextListener {
@Override public void contextInitialized(ServletContextEvent event) { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin());
URL ruleFile = Startup.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build()); }
@Override public void contextDestroyed(ServletContextEvent event) { }}
Example WEB-INF/web.xml
... <listener> <listener-class>com.myapp.web.Startup</listener-class> </listener>
Para utilizar reglas locales solo, reemplace la CentralizedSamplingStrategy porLocalizedSamplingStrategy.
builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));
LoggingDe manera predeterminada, el SDK genera mensajes con el nivel SEVERE y el nivel ERROR y los incluye enlos registro de la aplicación. Puede habilitar el registro de nivel de depuración en el SDK para incluir logsmás detallados en el archivo log de la aplicación.
Example application.properties
Configure el nivel de registro con la propiedad logging.level.com.amazonaws.xray.
logging.level.com.amazonaws.xray = DEBUG
Utilice registros de depuración para identificar problemas como la presencia de subsegmentos sin cerrar algenerar subsegmentos de forma manual (p. 258).
Inyección de ID de registro de seguimiento en los registrosPara exponer el ID de seguimiento completo actual en las instrucciones del registro, puede incluir el IDen el contexto de diagnóstico asignado (MDC). Mediante la SegmentListener interfaz , se llama a losmétodos desde la X-Ray grabadora durante los eventos del ciclo de vida del segmento. Cuando comienzaun segmento o subsegmento, el ID de seguimiento completo se incluye en el MDC con la clave AWS-
246
AWS X-Ray Guía para desarrolladoresLogging
XRAY-TRACE-ID. Cuando termina ese segmento, se elimina la clave del MDC. Esto expone el ID deregistro de seguimiento a la biblioteca de registro en uso. Cuando termina un subsegmento, su ID principalse incluye en el MDC.
Example ID de seguimiento completo
El ID completo se representa como TraceID@EntityID
1-5df42873-011e96598b447dfca814c156@541b3365be3dafc3
Esta característica funciona con las aplicaciones de Java instrumentadas con el AWS X-Ray SDK for Javay es compatible con las siguientes configuraciones de registro:
• API front-end SLF4J con backend Logback• API front-end SLF4J con backend Log4J2• API front-end Log4J2 con backend Log4J2
Consulte las siguientes pestañas para conocer las necesidades de cada front end y backend.
SLF4J Frontend
1. Agregue la siguiente dependencia de Maven a su proyecto.
<dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-slf4j</artifactId> <version>2.4.0</version></dependency>
2. Incluya el método withSegmentListener al construir la AWSXRayRecorder. Esto agrega unaclase de SegmentListener, que inyecta automáticamente nuevos ID de registro de seguimientoen el MDC SLF4J.
SegmentListener toma una cadena opcional como parámetro para configurar el prefijo de lainstrucción de registro. El prefijo se puede configurar de las siguientes maneras:
• None: – utiliza el AWS-XRAY-TRACE-ID prefijo predeterminado.• Empty: – utiliza una cadena vacía (por ejemplo, "").• – Custom: utiliza un prefijo personalizado tal y como se define en la cadena.
Example AWSXRayRecorderBuilder Instrucción
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder .standard().withSegmentListener(new SLF4JSegmentListener("CUSTOM-PREFIX"));
Log4J2 front end
1. Agregue la siguiente dependencia de Maven a su proyecto.
<dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-log4j</artifactId> <version>2.4.0</version></dependency>
247
AWS X-Ray Guía para desarrolladoresLogging
2. Incluya el método withSegmentListener al construir la AWSXRayRecorder. Esto agregaráuna clase de SegmentListener, que incluye automáticamente nuevos ID de seguimientocompleto en el MDC SLF4J.
SegmentListener toma una cadena opcional como parámetro para configurar el prefijo de lainstrucción de registro. El prefijo se puede configurar de las siguientes maneras:
• None: – utiliza el AWS-XRAY-TRACE-ID prefijo predeterminado.• Empty: – utiliza una cadena vacía (por ejemplo, "") y elimina el prefijo.• – Custom: utiliza el prefijo personalizado definido en la cadena.
Example AWSXRayRecorderBuilder Instrucción
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder .standard().withSegmentListener(new Log4JSegmentListener("CUSTOM-PREFIX"));
Logback backend
Para insertar el ID de registro de seguimiento en los eventos de registro, debe modificar elPatternLayout del registrador, que da formato a cada instrucción de registro.
1. Busque dónde está configurado el patternLayout. Puede hacerlo mediante programación o através de un archivo de configuración XML. Para obtener más información, consulte Configuraciónde Logback.
2. Inserte en %X{AWS-XRAY-TRACE-ID} cualquier lugar del patternLayout para insertar el IDde rastro en futuras instrucciones de registro. %X{} indica que está recuperando un valor con laclave proporcionada del MDC. Para obtener más información sobre PatternLayouts en Logback,consulte PatternLayout.
Log4J2 backend
1. Busque dónde está configurado el patternLayout. Puede hacerlo mediante programación oa través de un archivo de configuración escrito en XML, JSON, YAML o con las propiedades delformato.
Para obtener más información sobre la configuración de Log4J2 ´mediante un archivo deconfiguración, consulte Configuración.
Para obtener más información sobre la configuración de Log4J2 mediante programación, consulteConfiguración programática.
2. Inserte en %X{AWS-XRAY-TRACE-ID} cualquier lugar del PatternLayout para insertar el ID derastro en futuras instrucciones de registro. %X{} indica que está recuperando un valor con la claveproporcionada del MDC. Para obtener más información sobre PatternLayouts en Log4J2, consulteDiseño del patrón.
Ejemplo de inyección de ID de registro de seguimiento
A continuación se muestra una cadena de PatternLayout modificada para incluir el ID de registro deseguimiento. El ID de registro de seguimiento se imprime después del nombre del subproceso (%t) y antesdel nivel de registro (%-5p).
Example PatternLayout Con inyección de ID
%d{HH:mm:ss.SSS} [%t] %X{AWS-XRAY-TRACE-ID} %-5p %m%n
248
AWS X-Ray Guía para desarrolladoresAgentes de escucha de segmento
AWS X-Ray imprime automáticamente la clave y el ID de registro de seguimiento en la instrucción delregistro para facilitar el análisis. A continuación se muestra una instrucción de registro que utiliza elmodificad PatternLayout.
Example Instrucción de registro con inyección de ID
2019-09-10 18:58:30.844 [nio-5000-exec-4] AWS-XRAY-TRACE-ID: 1-5d77f256-19f12e4eaa02e3f76c78f46a@1ce7df03252d99e1 WARN 1 - Your logging message here
El mensaje de registro en sí está alojado en el patrón %m y se establece al llamar al registrador.
Agentes de escucha de segmentoLos agentes de escucha de segmento son una interfaz para interceptar eventos del ciclo de vida, como elcomienzo y el final de segmentos producidos por AWSXRayRecorder. La implementación de una funciónde evento de agente de escucha de segmento podría consistir en añadir la misma anotación a todos lossubsegmentos cuando se crean con onBeginSubsegment , registrar un mensaje después de que cadasegmento se envíe al demonio mediante afterEndSegmento registrar las consultas enviadas por losinterceptores SQL mediante beforeEndSubsegment para verificar si el subsegmento representa unaconsulta SQL, agregando metadatos adicionales en tal caso.
Para ver la lista completa de SegmentListener funciones, consulte la documentación de la API del SDKde AWS X-Ray grabadores de para Java.
En el ejemplo siguiente se muestra cómo agregar una anotación coherente a todos los subsegmentosal crear con onBeginSubsegment e imprimir un mensaje de registro al final de cada segmento conafterEndSegment.
Example MySegmentListener.java
import com.amazonaws.xray.entities.Segment;import com.amazonaws.xray.entities.Subsegment;import com.amazonaws.xray.listeners.SegmentListener;
public class MySegmentListener implements SegmentListener { ..... @Override public void onBeginSubsegment(Subsegment subsegment) { subsegment.putAnnotation("annotationKey", "annotationValue"); } @Override public void afterEndSegment(Segment segment) { // Be mindful not to mutate the segment logger.info("Segment with ID " + segment.getId()); }}
A continuación, se hace referencia a este agente de escucha de segmento personalizado cuando se creaAWSXRayRecorder.
Example Instrucción AWSXRayRecorderBuilder
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder .standard().withSegmentListener(new MySegmentListener());
249
AWS X-Ray Guía para desarrolladoresVariables de entorno
Variables de entornoPuede utilizar variables de entorno para configurar el X-Ray SDK for Java. El SDK admite las siguientesvariables.
• AWS_XRAY_TRACING_NAME – Establece un nombre de servicio que el SDK utiliza para lossegmentos. Anula el nombre de servicio que se ha establecido en la estrategia de nomenclatura desegmento (p. 252) del filtro de servlet.
• AWS_XRAY_DAEMON_ADDRESS: configure el host y el puerto del agente de escucha del daemon de X-Ray. De forma predeterminada, el SDK usa 127.0.0.1:2000 para los datos de rastreo (UDP) y para elmuestreo (TCP). Use esta variable si ha configurado el daemon para que esté a la escucha en un puertodiferente (p. 174) o si se ejecuta en un host diferente.
Formato• Mismo puerto: address:port• Puertos diferentes: tcp:address:port udp:address:port
• AWS_XRAY_CONTEXT_MISSING: establezca esta opción en LOG_ERROR para evitar que se produzcanexcepciones cuando el código instrumentado intente registrar datos sin que haya ningún segmentoabierto.
Valores válidos• RUNTIME_ERROR: iniciar una excepción en tiempo de ejecución (predeterminado).• LOG_ERROR: registrar un error y continuar.
Se pueden producir errores relativos a segmentos o subsegmentos inexistentes al intentar usar uncliente instrumentado en el código de inicio que se ejecuta cuando no hay ninguna solicitud abierta o enel código que inicia un nuevo subproceso.
Las variables de entorno anulan las propiedades de sistema (p. 250) equivalentes y los valoresestablecidos en el código.
Propiedades del sistemaPuede utilizar las propiedades del sistema como una alternativa específica de JVM para las variables deentorno (p. 250). El SDK admite las propiedades siguientes:
• com.amazonaws.xray.strategy.tracingName – Equivalente a AWS_XRAY_TRACING_NAME.• com.amazonaws.xray.emitters.daemonAddress – Equivalente a AWS_XRAY_DAEMON_ADDRESS.• com.amazonaws.xray.strategy.contextMissingStrategy – Equivalente aAWS_XRAY_CONTEXT_MISSING.
Si se ha establecido tanto una propiedad del sistema y como su variable de entorno equivalente, se utilizael valor de la variable de entorno. En cualquier caso, esos valores anulan los valores establecidos en elcódigo.
Seguimiento de solicitudes entrantes con el X-RaySDK for Java
Puede utilizar el SDK de X-Ray para rastrear las solicitudes HTTP entrantes que su aplicación atiende enuna instancia EC2 en Amazon EC2, AWS Elastic Beanstalk o Amazon ECS.
250
AWS X-Ray Guía para desarrolladoresAgregar un filtro de seguimiento a la aplicación (Tomcat)
Utilice un Filter para instrumentar las solicitudes HTTP entrantes. Cuando añade el filtro de servletde X-Ray a su aplicación, el X-Ray SDK for Java crea un segmento para cada solicitud muestreada.Este segmento incluye el momento, el método y la disposición de la solicitud HTTP. La instrumentaciónadicional crea subsegmentos en este segmento.
Note
Para las funciones de AWS Lambda, Lambda crea un segmento para cada solicitud muestreada.Para obtener más información, consulte AWS Lambda y AWS X-Ray (p. 208).
Cada segmento tiene un nombre que identifica su aplicación en el mapa de servicio. Puede asignarun nombre al segmento de manera estática o puede configurar el SDK para que asigne el nombredinámicamente en función de encabezado de host de la solicitud entrante. La designación dinámica denombres le permite agrupar los rastros en función del nombre de dominio de la solicitud y aplicar unnombre predeterminado si el nombre no coincide con un patrón previsto (por ejemplo, si el encabezado dehost ha sido falsificado).
Solicitudes reenviadas
Si un balanceador de carga u otro intermediario reenvía una solicitud a la aplicación, X-Ray tomala dirección IP del cliente del encabezado X-Forwarded-For de la solicitud, en lugar de hacerlode la dirección IP de origen del paquete IP. La dirección IP del cliente que se registra para unasolicitud reenviada puede falsificarse, por lo que no se debe confiar en ella.
Cuando se reenvía una solicitud, el SDK crea un campo adicional en el segmento para indicar que serealizó esta acción. Si el segmento contiene el campo x_forwarded_for establecido en true, ladirección IP del cliente se obtuvo del encabezado X-Forwarded-For de la solicitud HTTP.
El controlador de mensajes crea un segmento para cada solicitud entrante con un bloque http quecontiene la siguiente información:
• Método HTTP: GET, POST, PUT, DELETE, etc.• Dirección del cliente: la dirección IP del cliente que envió la solicitud.• Código de respuesta: el código de respuesta HTTP para la solicitud finalizada.• Intervalo: la hora de inicio (cuando se recibió la solicitud) y la hora de finalización (cuando se envió la
respuesta).• Agente del usuario: el user-agent de la solicitud.• Longitud de contenido: la content-length de la respuesta.
Secciones• Agregar un filtro de seguimiento a la aplicación (Tomcat) (p. 251)• Agregar un filtro de seguimiento a la aplicación (Spring) (p. 252)• Configuración de una estrategia de nomenclatura de segmentos (p. 252)
Agregar un filtro de seguimiento a la aplicación(Tomcat)Para Tomcat, añada un <filter> al archivo web.xml de su proyecto. Use el parámetro fixedName paraespecificar un nombre de servicio (p. 252) que se aplique a los segmentos creados para las solicitudesentrantes.
Example WEB-INF/web.xml - Tomcat
<filter>
251
AWS X-Ray Guía para desarrolladoresAgregar un filtro de seguimiento a la aplicación (Spring)
<filter-name>AWSXRayServletFilter</filter-name> <filter-class>com.amazonaws.xray.javax.servlet.AWSXRayServletFilter</filter-class> <init-param> <param-name>fixedName</param-name> <param-value>MyApp</param-value> </init-param></filter><filter-mapping> <filter-name>AWSXRayServletFilter</filter-name> <url-pattern>*</url-pattern></filter-mapping>
Agregar un filtro de seguimiento a la aplicación(Spring)Para Spring, añada un Filter a la clase WebConfig. Pase el nombre del segmento al constructorAWSXRayServletFilter como una cadena.
Example src/main/java/myapp/WebConfig.java: Spring
package myapp;import org.springframework.context.annotation.Configuration;import org.springframework.context.annotation.Bean;import javax.servlet.Filter;import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;
@Configurationpublic class WebConfig {
@Bean public Filter TracingFilter() { return new AWSXRayServletFilter("Scorekeep"); }}
Configuración de una estrategia de nomenclatura desegmentosAWS X-Ray usa un nombre de servicio para identificar su aplicación y diferenciarla de las demásaplicaciones, bases de datos, API externas y recursos de AWS que usa la aplicación. Cuando el SDK deX-Ray genera segmentos para las solicitudes entrantes, registra el nombre de servicio de la aplicación enel campo de nombre del segmento (p. 124).
El SDK de X-Ray puede utilizar el nombre de host del encabezado de la solicitud HTTP para lossegmentos. Sin embargo, este encabezado se puede falsificar, por lo que podrían crearse nodosinesperados en el mapa de servicio. Para impedir que el SDK asigne incorrectamente nombres a lossegmentos debido a solicitudes con encabezados de host falsificados, debe especificar un nombrepredeterminado para las solicitudes entrantes.
Si la aplicación atiende solicitudes de varios dominios, puede configurar el SDK para que use unaestrategia de designación dinámica que refleje este comportamiento en los nombres de segmento. Conuna estrategia de designación dinámica, el SDK puede utilizar el nombre del host en las solicitudes quecoinciden con un patrón previsto y aplicar un nombre predeterminado en caso contrario.
Por ejemplo, puede tener una aplicación que sirva solicitudes a tres subdominios: www.example.com,api.example.com y static.example.com. Puede usar una estrategia de designación dinámica
252
AWS X-Ray Guía para desarrolladoresConfiguración de una estrategiade nomenclatura de segmentos
de nombres con el patrón *.example.com para identificar los segmentos de cada subdominio con unnombre diferente, lo que daría lugar a tres nodos de servicio en el mapa de servicio. Si la aplicación recibesolicitudes con un nombre de host que no coincide con el patrón, aparecerá un cuarto nodo en el mapa deservicio con el nombre alternativo que especifique.
Para utilizar el mismo nombre para todos los segmentos de solicitud, especifique el nombre de laaplicación cuando inicie el filtro de servlet, tal y como se muestra en la sección anterior (p. 251).El efecto es el mismo que cuando se crea un objeto SegmentNamingStrategy fijo llamando aSegmentNamingStrategy.fixed() y se lo pasa al constructor AWSXRayServletFilter.
Note
Puede anular el nombre de servicio predeterminado que ha definido en el código mediante laAWS_XRAY_TRACING_NAMEvariable de entorno (p. 250).
Una estrategia de nomenclatura dinámica define un patrón con el que deben coincidir los nombres de hosty un nombre predeterminado que se utiliza si el nombre de host de la solicitud HTTP no coincide con elpatrón. Para asignar nombres de forma dinámica en Tomcat, utilice dynamicNamingRecognizedHostsy dynamicNamingFallbackName para definir el patrón y el nombre predeterminado, respectivamente.
Example WEB-INF/web.xml: filtro de servlet con nomenclatura dinámica
<filter> <filter-name>AWSXRayServletFilter</filter-name> <filter-class>com.amazonaws.xray.javax.servlet.AWSXRayServletFilter</filter-class> <init-param> <param-name>dynamicNamingRecognizedHosts</param-name> <param-value>*.example.com</param-value> </init-param> <init-param> <param-name>dynamicNamingFallbackName</param-name> <param-value>MyApp</param-value> </init-param></filter><filter-mapping> <filter-name>AWSXRayServletFilter</filter-name> <url-pattern>*</url-pattern></filter-mapping>
Para Spring, cree un SegmentNamingStrategy dinámico llamando aSegmentNamingStrategy.dynamic() y páselo al constructor AWSXRayServletFilter.
Example src/main/java/myapp/WebConfig.java: filtro de servlet con nomenclatura dinámica
package myapp;import org.springframework.context.annotation.Configuration;import org.springframework.context.annotation.Bean;import javax.servlet.Filter;import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;import com.amazonaws.xray.strategy.SegmentNamingStrategy;
@Configurationpublic class WebConfig {
@Bean public Filter TracingFilter() { return new AWSXRayServletFilter(SegmentNamingStrategy().dynamic("MyApp", "*.example.com")); }}
253
AWS X-Ray Guía para desarrolladoresAWS Clientes de SDK
Seguimiento de llamadas al AWS SDK con la X-Ray SDK for Java
Cuando la aplicación realiza llamadas a AWS servicios de para almacenar datos, escribir en una colao enviar notificaciones, el realiza un X-Ray SDK for Java seguimiento de las llamadas posteriores en (p. 258)subsegmentos. AWS Los servicios y recursos rastreados a los que accede dentro de dichosservicios (por ejemplo, un Amazon S3 bucket de o una Amazon SQS cola de ) aparecen como nodosposteriores en el mapa de servicio de la X-Ray consola de .
El instrumenta X-Ray SDK for Java automáticamente todos los clientes del SDK de AWS cuando seincluye el aws-sdk y aws-sdk-instrumentor submódulos (p. 232) en la compilación. Si no incluye elsubmódulo Instrumentor, puede elegir instrumentar ciertos clientes a la vez que omite otros.
Para instrumentar clientes individuales, elimine el aws-sdk-instrumentor submódulo de su compilacióny añada un XRayClient como TracingHandler en su cliente AWS de SDK utilizando el compilador declientes del servicio.
Por ejemplo, para instrumentar un cliente AmazonDynamoDB, transfiera un controlador de rastros aAmazonDynamoDBClientBuilder.
Example MyModel.java: cliente de DynamoDB
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.handlers.TracingHandler;
...public class MyModel { private AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard() .withRegion(Regions.fromName(System.getenv("AWS_REGION"))) .withRequestHandlers(new TracingHandler(AWSXRay.getGlobalRecorder())) .build();...
En todos los servicios, puede ver el nombre de la API a la que se ha llamado en la consola de X-Ray. Paraun subconjunto de servicios, el SDK de X-Ray añade información al segmento para proporcionar un mapadel servicio más detallado.
Por ejemplo, cuanto hace una llamada con un cliente de DynamoDB instrumentado, el SDK añade elnombre de la tabla al segmento para las llamadas cuyo destino es una tabla. En la consola, cada tablaaparece como un nodo distinto en el mapa del servicio, con un nodo genérico de DynamoDB para lasllamadas que no van dirigidas a una tabla.
Example Subsegmento para una llamada a DynamoDB para 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": {
254
AWS X-Ray Guía para desarrolladoresLlamadas a HTTP salientes
"table_name": "scorekeep-user", "operation": "UpdateItem", "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG", }}
Cuando accede a recursos designados, las llamadas a los siguientes servicios crean nodos adicionales enel mapa de servicio. Las llamadas que no están dirigidas a recursos concretos crean un nodo genérico enel servicio.
• Amazon DynamoDB: nombre de la tabla• Amazon Simple Storage Service: nombre de bucket y de clave• Amazon Simple Queue Service: nombre de la cola
Para instrumentar las llamadas posteriores que se realicen a los servicios de AWS con AWS SDKfor Java 2.2 y versiones posteriores, puede omitir el módulo aws-xray-recorder-sdk-aws-sdk-v2-instrumentor de la configuración de compilación. Incluya aws-xray-recorder-sdk-aws-sdk-v2 module en su lugar y después instrumente los clientes por separado configurándolos conTracingInterceptor.
Example AWS SDK for Java 2.2 y versiones posteriores: interceptor de rastreo
import com.amazonaws.xray.interceptors.TracingInterceptor;import software.amazon.awssdk.core.client.config.ClientOverrideConfigurationimport software.amazon.awssdk.services.dynamodb.DynamoDbClient;//...public class MyModel {private DynamoDbClient client = DynamoDbClient.builder().region(Region.US_WEST_2).overrideConfiguration(ClientOverrideConfiguration.builder().addExecutionInterceptor(new TracingInterceptor()).build()).build();//...
Seguimiento de llamadas a servicios web HTTPposteriores con el X-Ray SDK for Java
Cuando su aplicación realiza llamadas a microservicios o a API de HTTP públicas, puede utilizar la versiónde HttpClient del X-Ray SDK for Java para instrumentar dichas llamadas y añadir la API al gráfico deservicios como un servicios posterior.
El X-Ray SDK for Java incluye las clases DefaultHttpClient y HttpClientBuilder que puedenutilizarse en lugar de los equivalentes a Apache HttpComponents para instrumentar llamadas HTTPsalientes.
• com.amazonaws.xray.proxies.apache.http.DefaultHttpClient -org.apache.http.impl.client.DefaultHttpClient
• com.amazonaws.xray.proxies.apache.http.HttpClientBuilder -org.apache.http.impl.client.HttpClientBuilder
Estas bibliotecas se encuentran en el submódulo aws-xray-recorder-sdk-apache-http (p. 231).
255
AWS X-Ray Guía para desarrolladoresLlamadas a HTTP salientes
Puede sustituir las instrucciones actuales de importación con el equivalente a X-Ray para instrumentartodos los clientes, o bien utilizar el nombre completo cuando inicie un cliente para instrumentar clientesespecíficos.
Example HttpClientBuilder
import com.fasterxml.jackson.databind.ObjectMapper;import org.apache.http.HttpEntity;import org.apache.http.client.methods.CloseableHttpResponse;import org.apache.http.client.methods.HttpGet;import org.apache.http.impl.client.CloseableHttpClient;import org.apache.http.util.EntityUtils;import com.amazonaws.xray.proxies.apache.http.HttpClientBuilder;... public String randomName() throws IOException { CloseableHttpClient httpclient = HttpClientBuilder.create().build(); HttpGet httpGet = new HttpGet("http://names.example.com/api/"); CloseableHttpResponse response = httpclient.execute(httpGet); try { HttpEntity entity = response.getEntity(); InputStream inputStream = entity.getContent(); ObjectMapper mapper = new ObjectMapper(); Map<String, String> jsonMap = mapper.readValue(inputStream, Map.class); String name = jsonMap.get("name"); EntityUtils.consume(entity); return name; } finally { response.close(); } }
Cuando instrumenta una llamada a una API web posterior, el X-Ray SDK for Java registra un subsegmentocon información acerca de la solicitud HTTP y la respuesta. X-Ray utiliza el subsegmento para generar unsegmento inferido de la API remota.
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-5880168b-fd5153bb58284b67678aa78c", "start_time": 1484786387.131,
256
AWS X-Ray Guía para desarrolladoresConsultas SQL
"end_time": 1484786387.501, "parent_id": "004f72be19cddc2a", "http": { "request": { "method": "GET", "url": "https://names.example.com/" }, "response": { "content_length": -1, "status": 200 } }, "inferred": true}
Seguimiento de consultas SQL con el X-Ray SDKfor Java
Instrumente consultas de base de datos SQL añadiendo el interceptor JDBC del X-Ray SDK for Java a laconfiguración del origen de datos.
• PostgreSQL: com.amazonaws.xray.sql.postgres.TracingInterceptor• MySQL: com.amazonaws.xray.sql.mysql.TracingInterceptor
Estos interceptadores están en los submódulos aws-xray-recorder-sql-postgresy aws-xray-recorder-sql-mysql (p. 231), respectivamente. Implementanorg.apache.tomcat.jdbc.pool.JdbcInterceptor y son compatibles con grupos de conexiónTomcat.
Note
Los interceptores de SQL no registran la consulta SQL en subsegmentos por motivos deseguridad.
Para Spring, añada el interceptor a un archivo de propiedades y cree el origen de datos conDataSourceBuilder de Spring Boot.
Example src/main/java/resources/application.properties: interceptor JDBC dePostgreSQL
spring.datasource.continue-on-error=truespring.jpa.show-sql=falsespring.jpa.hibernate.ddl-auto=create-dropspring.datasource.jdbc-interceptors=com.amazonaws.xray.sql.postgres.TracingInterceptorspring.jpa.database-platform=org.hibernate.dialect.PostgreSQL94Dialect
Example src/main/java/myapp/WebConfig.java: origen de datos
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;import org.springframework.boot.autoconfigure.jdbc.DataSourceBuilder;import org.springframework.boot.context.properties.ConfigurationProperties;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
import javax.servlet.Filter;
257
AWS X-Ray Guía para desarrolladoresSubsegmentos de personalizados
import javax.sql.DataSource;import java.net.URL;
@Configuration@EnableAutoConfiguration@EnableJpaRepositories("myapp")public class RdsWebConfig {
@Bean @ConfigurationProperties(prefix = "spring.datasource") public DataSource dataSource() { logger.info("Initializing PostgreSQL datasource"); return DataSourceBuilder.create() .driverClassName("org.postgresql.Driver") .url("jdbc:postgresql://" + System.getenv("RDS_HOSTNAME") + ":" + System.getenv("RDS_PORT") + "/ebdb") .username(System.getenv("RDS_USERNAME")) .password(System.getenv("RDS_PASSWORD")) .build(); }...}
Para Tomcat, llame a setJdbcInterceptors en el origen de datos JDBC con una referencia a la clasedel X-Ray SDK for Java.
Example src/main/myapp/model.java: origen de datos
import org.apache.tomcat.jdbc.pool.DataSource;...DataSource source = new DataSource();source.setUrl(url);source.setUsername(user);source.setPassword(password);source.setDriverClassName("com.mysql.jdbc.Driver");source.setJdbcInterceptors("com.amazonaws.xray.sql.mysql.TracingInterceptor;");
El X-Ray SDK for Java incluye la biblioteca de origen de datos JDBC Tomcat, pero puede declararla comouna dependencia para documentar su uso.
Example pom.xml: origen de datos JDBC
<dependency> <groupId>org.apache.tomcat</groupId> <artifactId>tomcat-jdbc</artifactId> <version>8.0.36</version> <scope>provided</scope></dependency>
Generación de subsegmentos personalizados conel X-Ray SDK for Java
Los subsegmentos extienden el segmento (p. 21) de un rastro con detalles sobre el trabajo realizado paraatender una solicitud. Cada vez que se realiza una llamada con un cliente instrumentado, el SDK de X-Rayregistra la información generada en un subsegmento. Puede crear subsegmentos adicionales para agruparotros subsegmentos, para medir el desempeño de una sección de código o para registrar anotaciones ymetadatos.
258
AWS X-Ray Guía para desarrolladoresSubsegmentos de personalizados
Para administrar los subsegmentos, utilice los métodos beginSubsegment y endSubsegment.
Example GameModel.java: subsegmento personalizado
import com.amazonaws.xray.AWSXRay;... public void saveGame(Game game) throws SessionNotFoundException { // wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("Save Game"); try { // check session String sessionId = game.getSession(); if (sessionModel.loadSession(sessionId) == null ) { throw new SessionNotFoundException(sessionId); } mapper.save(game); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } }
En este ejemplo, el código dentro del subsegmento carga la sesión de la partida desde DynamoDB con unmétodo disponible en el modelo de sesión y utiliza el mapeador de AWS SDK for Java de DynamoDB paraguardar la partida. Cuando se encapsula este código en un subsegmento, las llamadas a DynamoDB seconvierten en elementos secundarios del subsegmento Save Game en la vista de rastros en la consola.
Si en el código en su subsegmentos aparecen excepciones comprobadas, envuélvalo en un bloque try yllame a AWSXRay.endSubsegment() en un bloque finally para garantizar que el subsegmento estásiempre cerrado. Si un subsegmento no está cerrado, el segmento primario no se puede completar y no seenvía a X-Ray.
En los códigos donde no aparecen excepciones comprobadas, puede transferir el código aAWSXRay.CreateSubsegment como una función de Lambda.
Example Función Lambda de subsegmento
import com.amazonaws.xray.AWSXRay;
AWSXRay.createSubsegment("getMovies", (subsegment) -> { // function code});
259
AWS X-Ray Guía para desarrolladoresAnotaciones y metadatos
Cuando crea un subsegmento dentro de un segmento o de otro subsegmento, el X-Ray SDK for Javagenera un ID para dicho subsegmento y registra la hora de inicio y la hora de finalización.
Example Subsegmentos con metadatos
"subsegments": [{ "id": "6f1605cd8a07cb70", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "Custom subsegment for UserModel.saveUser function", "metadata": { "debug": { "test": "Metadata string from UserModel.saveUser" } },
Para la programación asíncrona y multiproceso, debe pasar manualmente el subsegmento alendSubsegment() método para asegurarse de que se cierra correctamente, ya que el X-Ray contextopuede modificarse durante la ejecución asíncrona. Si un subsegmento asíncrono se cierra despuésde cerrar su segmento principal, este método transmitirá automáticamente todo el segmento al X-Raydemonio.
Example Subsegmento asíncrono
@GetMapping("/api")public ResponseEntity<?> api() { CompletableFuture.runAsync(() -> { Subsegment subsegment = AWSXRay.beginSubsegment("Async Work"); try { Thread.sleep(3000); } catch (InterruptedException e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(subsegment); } }); return ResponseEntity.ok().build();}
Agregar anotaciones y metadatos a los segmentoscon el X-Ray SDK for Java
Puede registrar información adicional sobre las solicitudes, el entorno o la aplicación con anotaciones ymetadatos. Puede añadir anotaciones y metadatos a los segmentos creados por el SDK de X-Ray o a lossubsegmentos personalizados creados por usted.
Las anotaciones son pares de clave-valor con valores de cadena, numéricos o booleanos. Las anotacionesse indexan para su uso con expresiones de filtro (p. 64). Utilice anotaciones para registrar los datos quedesee utilizar para agrupar rastros en la consola o cuando llame a la API de GetTraceSummaries.
Metadata son los pares clave-valor que pueden tener valores de cualquier tipo, incluso objetos y listas,pero que no se indexan para su uso con expresiones de filtro. Utilice los metadatos para registrar otrosdatos que desee almacenar en el rastro, pero que no necesite usar para buscar.
260
AWS X-Ray Guía para desarrolladoresRegistro de anotaciones con el X-Ray SDK for Java
Además de anotaciones y metadatos, también puede registrar cadenas de ID de usuario (p. 263) en lossegmentos. Los identificadores de usuario se registran en un campo aparte en segmentos y se indexanpara su uso con la búsqueda.
Secciones• Registro de anotaciones con el X-Ray SDK for Java (p. 261)• Registro de metadatos con el X-Ray SDK for Java (p. 262)• Registro de ID de usuario con el X-Ray SDK for Java (p. 263)
Registro de anotaciones con el X-Ray SDK for JavaUtilice anotaciones para registrar información sobre segmentos o subsegmentos que desee indexar paralas búsquedas.
Requisitos de anotación
• Claves: hasta 500 caracteres alfanuméricos. Sin espacios ni símbolos excepto el guion bajo.• Valores: hasta 1,000 caracteres Unicode.• Entradas: hasta 50 anotaciones por rastro.
Para registrar anotaciones
1. Obtenga una referencia al segmento o subsegmento actual desde AWSXRay.
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.entities.Segment;...Segment document = AWSXRay.getCurrentSegment();
o bien
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.entities.Subsegment;...Subsegment document = AWSXRay.getCurrentSubsegment();
2. Llame a putAnnotation con una clave de cadena y un valor booleano, numérico o de cadena.
document.putAnnotation("mykey", "my value");
El SDK registra las anotaciones como pares de clave-valor en un objeto annotations del documentode segmento. Si llama dos veces a putAnnotation con la misma clave, se sobrescriben los valorespreviamente registrados en ese segmento o subsegmento.
Para encontrar rastros que tengan anotaciones con valores específicos, utilice la palabra claveannotations.key en una expresión de filtro (p. 64).
Example src/main/java/scorekeep/GameModel.java: anotaciones y metadatos
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.entities.Segment;import com.amazonaws.xray.entities.Subsegment;
261
AWS X-Ray Guía para desarrolladoresRegistro de metadatos con el X-Ray SDK for Java
... public void saveGame(Game game) throws SessionNotFoundException { // wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame"); try { // check session String sessionId = game.getSession(); if (sessionModel.loadSession(sessionId) == null ) { throw new SessionNotFoundException(sessionId); } Segment segment = AWSXRay.getCurrentSegment(); subsegment.putMetadata("resources", "game", game); segment.putAnnotation("gameid", game.getId()); mapper.save(game); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } }
Registro de metadatos con el X-Ray SDK for JavaUtilice los metadatos para registrar información sobre segmentos o subsegmentos que no necesite indexarpara las búsquedas. Los valores de metadatos pueden ser cadenas, números, booleanos o cualquierobjeto que se pueda serializar en un objeto o matriz JSON.
Para registrar metadatos
1. Obtenga una referencia al segmento o subsegmento actual desde AWSXRay.
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.entities.Segment;...Segment document = AWSXRay.getCurrentSegment();
o bien
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.entities.Subsegment;...Subsegment document = AWSXRay.getCurrentSubsegment();
2. Llame a putMetadata con un espacio de nombres de cadena, una clave de cadena y un valorbooleano, numérico, de cadena o de objeto.
document.putMetadata("my namespace", "my key", "my value");
o bien
Llame a putMetadata con solo una clave y un valor.
document.putMetadata("my key", "my value");
Si no especifica un espacio de nombres, el SDK utiliza default. Si llama dos veces a putMetadata conla misma clave, se sobrescriben los valores previamente registrados en ese segmento o subsegmento.
262
AWS X-Ray Guía para desarrolladoresRegistro de ID de usuario con el X-Ray SDK for Java
Example src/main/java/scorekeep/GameModel.java: anotaciones y metadatos
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.entities.Segment;import com.amazonaws.xray.entities.Subsegment;... public void saveGame(Game game) throws SessionNotFoundException { // wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame"); try { // check session String sessionId = game.getSession(); if (sessionModel.loadSession(sessionId) == null ) { throw new SessionNotFoundException(sessionId); } Segment segment = AWSXRay.getCurrentSegment(); subsegment.putMetadata("resources", "game", game); segment.putAnnotation("gameid", game.getId()); mapper.save(game); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } }
Registro de ID de usuario con el X-Ray SDK for JavaRegistre identificadores de usuario en segmentos de solicitud para identificar al usuario que envió lasolicitud.
Para registrar identificadores de usuario
1. Obtenga una referencia al segmento actual desde AWSXRay.
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.entities.Segment;...Segment document = AWSXRay.getCurrentSegment();
2. Llame a setUser con un ID de cadena del usuario que envió la solicitud.
document.setUser("U12345");
Puede llamar a setUser en sus controladores para registrar el ID de usuario en cuanto la aplicaciónempiece a procesar la solicitud. Si solo va a utilizar el segmento para establecer el ID de usuario, puedeencadenar las llamadas en una sola línea.
Example src/main/java/scorekeep/MoveController.java: ID de usuario
import com.amazonaws.xray.AWSXRay;... @RequestMapping(value="/{userId}", method=RequestMethod.POST) public Move newMove(@PathVariable String sessionId, @PathVariable String gameId, @PathVariable String userId, @RequestBody String move) throws SessionNotFoundException, GameNotFoundException, StateNotFoundException, RulesException { AWSXRay.getCurrentSegment().setUser(userId);
263
AWS X-Ray Guía para desarrolladoresMonitorización
return moveFactory.newMove(sessionId, gameId, userId, move); }
Para buscar rastros de un ID de usuario, utilice la palabra clave user en una expresión de filtro (p. 64).
AWS X-Ray Métricas de para X-Ray SDK for JavaEn este tema se describen el espacio de nombres, las métricas y las dimensiones de AWS X-Ray.Puede utilizar X-Ray SDK for Java para publicar las métricas de Amazon CloudWatch sin muestrear desus segmentos de X-Ray recopilados. Estas métricas se derivan de la horade inicio y finalización delsegmento, y los marcadores de estado limitado, fallo y error. Utilice estas métricas de seguimiento paraexponer los reintentos y los problemas de dependencia con los subsegmentos.
CloudWatch es básicamente un repositorio de métricas. Una métrica es el concepto fundamental deCloudWatch y representa un conjunto de puntos de datos ordenados cronológicamente. El usuario (olos servicios de AWS) publican los puntos de datos de las métricas en CloudWatch y el usuario recuperaestadísticas sobre esos puntos de datos en un conjunto ordenado de datos de series temporales.
Las métricas se definen de forma exclusiva mediante un nombre, un espacio de nombres y una o variasdimensiones. Cada punto de datos tiene una marca temporal y, opcionalmente, una unidad de medida.Cuando se solicitan estadísticas, el flujo de datos devuelto se identifica mediante el espacio de nombres, elnombre de la métrica y la dimensión.
Para obtener más información sobre CloudWatch, consulte la Guía del usuario de Amazon CloudWatch.
Métricas de X-Ray para CloudWatchEl espacio de nombres de ServiceMetrics/SDK incluye las siguientes métricas.
Métrica Estadísticas disponibles Descripción Unidades
Latency Media, mínima, máxima,recuento
La diferencia entrela hora de inicio yfinalización. Media,mínima y máximadescriben la latenciaoperativa. Recuentodescribe el recuento dellamadas.
Milisegundos
ErrorRate Media, Suma La tasa de solicitudesque fallaron con uncódigo de estado 4xxClient Error, lo queda lugar a un error.
Porcentaje
FaultRate Media, Suma La tasa de seguimientosque fallaron con uncódigo de estado 5xxServer Error, lo queda lugar a un fallo.
Porcentaje
ThrottleRate Media, Suma La tasa de registroslimitas que devuelvenun código de estado
Porcentaje
264
AWS X-Ray Guía para desarrolladoresDimensiones de X-Ray para CloudWatch
Métrica Estadísticas disponibles Descripción Unidades419. Se trata de unsubconjunto de lamétrica ErrorRate.
OkRate Media, Suma La tasa de solicitudesrastreadas que danlugar a un código deestado OK.
Porcentaje
Dimensiones de X-Ray para CloudWatchUtilice las dimensiones de la siguiente tabla para ajustar las métricas devueltas para sus aplicaciones deJava instrumentadas de X-Ray.
Dimensión Descripción
ServiceType El tipo de servicio, por ejemplo,AWS::EC2::Instance o NONE, si no se conoce.
ServiceName El nombre canónico del servicio.
Habilitar las métricas de X-Ray para CloudWatchutilice el siguiente procedimiento para habilitar métricas de seguimiento en su aplicación de Javainstrumentada.
Para configurar las métricas de seguimiento
1. Agregue el paquete aws-xray-recorder-sdk-metrics como una dependencia de Maven. Paraobtener más información, consulte Submódulos de X-Ray SDK for Java (p. 232).
2. Habilite un nuevo MetricsSegmentListener() como parte de la compilación de la grabadoraglobal.
Example src/com/myapp/web/Startup.java
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.AWSXRayRecorderBuilder;import com.amazonaws.xray.plugins.EC2Plugin;import com.amazonaws.xray.plugins.ElasticBeanstalkPlugin;import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;
@Configurationpublic class WebConfig {... static { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder .standard() .withPlugin(new EC2Plugin()) .withPlugin(new ElasticBeanstalkPlugin()) .withSegmentListener(new MetricsSegmentListener());
URL ruleFile = WebConfig.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));
265
AWS X-Ray Guía para desarrolladoresMultiproceso
AWSXRay.setGlobalRecorder(builder.build()); }}
3. Implemente el agente de CloudWatch para recopilar las métricas mediante Amazon Elastic ComputeCloud (Amazon EC2), Amazon Elastic Container Service (Amazon ECS) o Amazon Elastic KubernetesService (Amazon EKS):
• Para configurar Amazon EC2, consulte Implementación del agente de CloudWatch y el X-Raydemonio de en Amazon EC2
• Para configurar Amazon ECS, consulte Implementación del agente de CloudWatch y el X-Raydemonio de en Amazon ECS.
• Para configurar Amazon EKS, consulte Implementación del agente de CloudWatch y el X-Raydemonio de en Amazon EKS.
4. Configura el SDK para que se comunique con el agente de CloudWatch. De forma predeterminada,el SDK se comunica con el agente de CloudWatch en la dirección 127.0.0.1. Puede configurardirecciones alternativas al configurar el entorno variable o la propiedad de Java en address:port.
Example Variable de entorno
AWS_XRAY_METRICS_DAEMON_ADDRESS=address:port
Example Propiedad de Java
com.amazonaws.xray.metrics.daemonAddress=address:port
Para validar la configuración
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/.
2. Abra la pestaña Metrics (Métricas) para observar el flujo de sus métricas.3. (Opcional) En la consola de CloudWatch, en la pestaña Logs (Registros), abra el grupo de registros
ServiceMetricsSDK. Busque un flujo de registros que coincida con las métricas del host y confirmelos mensajes del registro.
Transmisión de contexto de segmento entresubprocesos en una aplicación multiproceso
Cuando se crea un nuevo subproceso en la aplicación, el AWSXRayRecorder no mantiene una referenciaal segmento o subsegmento Entity actual. Si utiliza un cliente instrumentado en el nuevo subproceso, elSDK intenta escribir en un segmento que no existe, provocando una SegmentNotFoundException.
Para evitar lanzar excepciones durante el desarrollo, puede configurar la grabadora con unaContextMissingStrategy que indique que registre un error en su lugar. Puede configurar la estrategiaen el código con SetContextMissingStrategy o configurar opciones equivalentes con una variable deentorno (p. 250) o una propiedad del sistema (p. 250).
Una forma de abordar el error consiste en utilizar un segmento nuevo llamando a beginSegment al iniciarel subproceso y a endSegment al cerrarlo. Esto funciona si está instrumentando código que no se ejecutaen respuesta a una solicitud HTTP, como código que se ejecuta cuando se inicia la aplicación.
266
AWS X-Ray Guía para desarrolladoresUso de X-Ray con programación asíncrona
Si utiliza varios subprocesos para gestionar las solicitudes entrantes, puede transferir el segmento osubsegmento actual al nuevo subproceso y facilitarlo a la grabadora global. De este modo, se garantizaque la información registrada en el nuevo subproceso esté asociada al mismo segmento que el restode la información registrada sobre dicha solicitud. Una vez que el segmento esté disponible en el nuevosubproceso, puede ejecutar cualquier ejecutable con acceso al contexto de ese segmento mediante elsegment.run(() -> { ... }) método .
Consulte Uso de clientes instrumentados en subprocesos de trabajo (p. 168) para ver un ejemplo.
Uso de X-Ray con programación asíncronaEl X-Ray SDK para Java se puede utilizar en programas de Java asíncronos conSegmentContextExecutors El SegmentContextExecutor implementa la interfaz Executor, lo que significaque se puede pasar a todas las operaciones asíncronas de CompletableFuture Esto garantiza que todaslas operaciones asíncronas se ejecuten con el segmento correcto en su contexto.
Example Ejemplo de App.java: Pasar SegmentContextExecutor aCompletableFuture
DynamoDbAsyncClient client = DynamoDbAsyncClient.create();
AWSXRay.beginSegment();
// ...
client.getItem(request).thenComposeAsync(response -> { // If we did not provide the segment context executor, this request would not be traced correctly. return client.getItem(request2);}, SegmentContextExecutors.newSegmentContextExecutor());
AOP con Spring y el X-Ray SDK for JavaEn este tema se describe cómo utilizar el SDK de X-Ray y el marco de trabajo Spring para instrumentaruna aplicación sin cambiar su lógica básica. Esto significa que ahora hay una forma no invasiva deinstrumentar las aplicaciones que se ejecutan de forma remota en AWS.
Para habilitar AOP en Spring
1. Configure Spring (p. 267)2. Agregar un filtro de rastreo a la aplicación (p. 268)3. Comente el código o implemente una interfaz (p. 268)4. Activar X-Ray en su aplicación (p. 268)
Configuración de SpringPuede utilizar Maven o Gradle para configurar Spring para que utilice AOP con el fin de instrumentar laaplicación.
Si utiliza Maven para compilar la aplicación, añada la siguiente dependencia al archivo pom.xml.
<dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-spring</artifactId> <version>2.4.0</version> </dependency>
267
AWS X-Ray Guía para desarrolladoresAgregar un filtro de rastreo a la aplicación
Para Gradle, añada la siguiente dependencia al archivo build.gradle.
compile 'com.amazonaws:aws-xray-recorder-sdk-spring:2.4.0'
Agregar un filtro de rastreo a la aplicaciónAñada un Filter a su WebConfig clase . Pase el nombre del segmento al AWSXRayServletFilterconstructor como una cadena. Para obtener más información acerca de los filtros de rastreo einstrumentar las solicitudes entrantes, consulte Seguimiento de solicitudes entrantes con el X-Ray SDK forJava (p. 250).
Example src/main/java/myapp/WebConfig.java: Spring
package myapp;import org.springframework.context.annotation.Configuration;import org.springframework.context.annotation.Bean;import javax.servlet.Filter;import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;
@Configurationpublic class WebConfig {
@Bean public Filter TracingFilter() { return new AWSXRayServletFilter("Scorekeep"); }}
Anotación del código o implementación de una interfazLas clases deben anotarse con la anotación @XRayEnabled o bien debe implementarse la interfazXRayTraced . Esto indica al sistema AOP que encapsule las funciones de la clase afectada para la X-Rayinstrumentación.
Activación de X-Ray en la aplicaciónPara activar X-Ray el rastreo de en la aplicación, el código debe ampliar la clase abstractaAbstractXRayInterceptor anulando los siguientes métodos.
• generateMetadata—Esta función permite la personalización de los metadatos asociados al rastro dela función actual. De forma predeterminada, el nombre de clase de la función que se ejecuta se registraen los metadatos. Puede añadir más datos si necesita información adicional.
• xrayEnabledClasses—Esta función está vacía y debe seguir así. Sirve para alojar un conjunto depuntos de unión (pointcut) que indica al interceptor los métodos que debe encapsular. Defina el pointcutespecificando las clases que se han anotado con @XRayEnabled que se deben rastrear. La siguienteinstrucción pointcut indica al interceptor que encapsule todos los beans del controlador anotados con laanotación @XRayEnabled.
@Pointcut(“@within(com.amazonaws.xray.spring.aop.XRayEnabled) && bean(*Controller)”)
ExampleEl siguiente código extiende la clase abstracta AbstractXRayInterceptor.
268
AWS X-Ray Guía para desarrolladoresExample
@Aspect@Componentpublic class XRayInspector extends AbstractXRayInterceptor { @Override protected Map<String, Map<String, Object>> generateMetadata(ProceedingJoinPoint proceedingJoinPoint, Subsegment subsegment) throws Exception { return super.generateMetadata(proceedingJoinPoint, subsegment); } @Override @Pointcut("@within(com.amazonaws.xray.spring.aop.XRayEnabled) && bean(*Controller)") public void xrayEnabledClasses() {} }
El código siguiente es una clase que instrumentará X-Ray.
@Service@XRayEnabledpublic class MyServiceImpl implements MyService { private final MyEntityRepository myEntityRepository; @Autowired public MyServiceImpl(MyEntityRepository myEntityRepository) { this.myEntityRepository = myEntityRepository; } @Transactional(readOnly = true) public List<MyEntity> getMyEntities(){ try(Stream<MyEntity> entityStream = this.myEntityRepository.streamAll()){ return entityStream.sorted().collect(Collectors.toList()); } }}
Si ha configurado correctamente la aplicación, debe ver la pila de llamadas completa de la aplicación,desde el controlador hasta las llamadas a los servicios, tal y como se muestra en la siguiente captura depantalla de la consola.
269
AWS X-Ray Guía para desarrolladores
AWS X-Ray SDK for Node.jsEl X-Ray SDK for Node.js es una biblioteca para las aplicaciones web de Express y funciones de Lambdade Node.js que proporciona clases y métodos para generar y enviar datos de rastreo al demonio de X-Ray.Los datos de rastreo incluyen información sobre las solicitudes HTTP entrantes que atiende la aplicacióny las llamadas que la aplicación realiza a los servicios posteriores mediante el AWS SDK o los clientesHTTP.
Note
El X-Ray SDK for Node.js es un proyecto de código abierto. Puede seguir el proyecto, enviarproblemas y solicitudes de extracción en GitHub: github.com/aws/aws-xray-sdk-node
Si usa Express, empiece agregando el SDK como middleware (p. 276) en el servidor de aplicacionespara rastrear solicitudes entrantes. El middleware crea un segmento (p. 21) para cada solicitud rastreaday lo completa cuando se envía la respuesta. Mientras el segmento está abierto, puede utilizar los métodosdel cliente del SDK para añadir información al segmento y crear subsegmentos para rastrear llamadasposteriores. El SDK también registra automáticamente las excepciones que produce su aplicación mientrasel segmento está abierto.
Para las funciones de Lambda a las que se ha llamado desde una aplicación o un servicio instrumentados,Lambda lee el encabezado de rastreo (p. 26) y rastrea las solicitudes muestreadas automáticamente.Para las demás funciones, es posible configurar Lambda (p. 208) para muestrear y seguir las solicitudesentrantes. En cualquiera de los dos casos, Lambda crea el segmento y se lo proporciona al SDK de X-Ray.
Note
En Lambda, el SDK de X-Ray es opcional. Si no lo utiliza en la función, el mapa de servicioseguirá incluyendo un nodo para el servicio de Lambda y uno para cada función de Lambda.Si incorpora el SDK, puede instrumentar el código de la función para añadir subsegmentos alsegmento de la función registrado por Lambda. Para obtener más información, consulte AWSLambda y AWS X-Ray (p. 208).
A continuación, utilice el X-Ray SDK for Node.js para instrumentar sus clientes de AWS SDK for JavaScriptin Node.js (p. 279). Siempre que realice una llamada a un AWS servicio o recurso posterior con uncliente instrumentado, el SDK de registra información sobre la llamada en un subsegmento. AWS Losservicios de y los recursos a los que accede dentro de los servicios aparecen como nodos posteriores enel mapa de servicio para ayudarle a identificar errores y problemas de limitación controlada en conexionesindividuales.
El X-Ray SDK for Node.js también realiza la instrumentación de llamadas posteriores a API web HTTPy consultas SQL. Incluya su cliente HTTP en el método de captura del SDK (p. 280) para registrarinformación sobre las llamadas HTTP salientes. Para los clientes SQL, utilice el método de captura para eltipo de base de datos (p. 281).
El middleware aplica reglas de muestreo a las solicitudes entrantes para determinar qué solicitudes sedeben rastrear. Puede configurar la X-Ray SDK for Node.js (p. 272) para ajustar el comportamientode muestreo o para registrar información sobre los recursos AWS informáticos en los que se ejecuta laaplicación.
Registre información adicional acerca de las solicitudes y el trabajo que la aplicación realiza enanotaciones y metadatos (p. 284). Las anotaciones son pares sencillos de clave-valor que se indexanpara su uso con expresiones de filtro (p. 64) para poder buscar rastros que contengan datos específicos.Las entradas de metadatos son menos restrictivas y pueden registrar objetos y matrices completos —esdecir, todo lo que se pueda serializar en JSON.
270
AWS X-Ray Guía para desarrolladoresRequirements
Anotaciones y metadatos
Las anotaciones y los metadatos son texto arbitrario que se añade a los segmentos con el SDK deX-Ray. Las anotaciones se indexan para su uso con expresiones de filtro. Los metadados no seindexan, pero se pueden consultar en un segmento sin formato con la consola o la API de X-Ray.Todas las personas a las que otorgue acceso de lectura a X-Ray pueden ver estos datos.
Cuando tenga muchos clientes instrumentados en su código, un único segmento de solicitudpuede contener un gran número de subsegmentos, uno para cada llamada realizada con un clienteinstrumentado. Puede organizar y agrupar los subsegmentos incluyendo las llamadas del clienteen subsegmentos personalizados (p. 282). Puede crear un subsegmento personalizado para unafunción completa o para cualquier sección de código, y registrar los metadatos y las anotaciones en elsubsegmento en lugar de escribirlo todo en el segmento principal.
Para obtener documentación de referencia sobre las clases y los métodos del SDK, consulte AWS X-RaySDK for Node.js API Reference.
RequirementsEl X-Ray SDK for Node.js requiere Node.js y las siguientes bibliotecas:
• atomic-batcher – 1.0.2• cls-hooked – 4.2.2• pkginfo – 0.4.0• semver – 5.3.0
El SDK obtiene estas bibliotecas cuando se instala con NPM.
Para rastrear clientes AWS del SDK, el X-Ray SDK for Node.js requiere una versión mínima del AWS SDKfor JavaScript in Node.js.
• aws-sdk – 2.7.15
Administración de dependenciasEl X-Ray SDK for Node.js está disponible desde NPM.
• Paquete – aws-xray-sdk
Para el desarrollo local, instale el SDK en el directorio del proyecto con npm.
~/nodejs-xray$ npm install [email protected]### [email protected]# ### [email protected]# ### [email protected]# # ### [email protected]# # # ### [email protected]# # ### [email protected]# # ### [email protected]# ### [email protected] # ### [email protected]### [email protected]
271
AWS X-Ray Guía para desarrolladoresEjemplos de Node.js
### [email protected]### [email protected]
Use la opción --save para guardar el SDK como una dependencia en el archivo package.json de laaplicación.
~/nodejs-xray$ npm install aws-xray-sdk [email protected]
Ejemplos de Node.jsTrabaje con el AWS X-Ray SDK de para Node.js para obtener una vista integral de las solicitudes amedida que avanzan a través de sus aplicaciones Node.js.
• Node.js sample application en GitHub.
Configuración dX-Ray SDK for Node.jsPuede configurar el X-Ray SDK for Node.js mediante el uso de complementos a fin de incluir informaciónsobre el servicio que sus aplicaciones ejecutan, modificar la conducta predeterminada de muestreo oagregar reglas de muestreo que se aplican a las solicitudes dirigidas a rutas específicas.
Secciones• Complementos del servicio (p. 272)• Reglas de muestreo (p. 273)• Registro de (p. 274)• Dirección del demonio de X-Ray (p. 275)• Variables de entorno (p. 275)
Complementos del servicioUtilice plugins para registrar información sobre el servicio que aloja su aplicación.
Complementos
• Amazon EC2: EC2Plugin agrega el ID de instancia, la zona de disponibilidad y el grupo de CloudWatchLogs.
• Elastic Beanstalk – ElasticBeanstalkPlugin añade el nombre de entorno, la etiqueta de versión y elID de implementación.
• Amazon ECS – ECSPlugin añade el ID del contenedor.
Para utilizar un complemento, configure el cliente X-Ray SDK for Node.js mediante el método config.
Example app.js: complementos
var AWSXRay = require('aws-xray-sdk');AWSXRay.config([AWSXRay.plugins.EC2Plugin,AWSXRay.plugins.ElasticBeanstalkPlugin]);
272
AWS X-Ray Guía para desarrolladoresReglas de muestreo
El SDK también utiliza la configuración del complemento para establecer el campo origin del segmento.Esto indica el tipo de recurso de AWS que ejecuta la aplicación. El tipo de recurso aparece bajo el nombrede la aplicación en el mapa del servicio. Por ejemplo, AWS::ElasticBeanstalk::Environment.
Cuando utiliza varios complementos, el SDK utiliza la siguiente orden de resolución para determinar elorigen: ElasticBeanstalk > EKS > ECS > EC2.
Reglas de muestreoEl SDK utiliza reglas de muestreo que usted define en la consola de X-Ray para determinar qué solicitudesdebe registrar. La regla predeterminada rastrea la primera solicitud de cada segundo y un cinco porciento de todas las solicitudes adicionales en todos los servicios que envían rastros a X-Ray. Cree reglasadicionales en la consola de X-Ray (p. 76) para personalizar la cantidad de datos registrados para cadauna de sus aplicaciones.
El SDK aplica las reglas personalizadas en el orden en que se definen. Si una solicitud coincide con variasreglas personalizadas, el SDK aplica solo la primera regla.
Note
Si el SDK no puede conectar con X-Ray para obtener las reglas de muestreo, utiliza una reglapredeterminada local de la primera solicitud de cada segundo y un cinco por ciento de todas lassolicitudes adicionales para cada host. Esto puede ocurrir si el host no tiene permiso para llamara las API de muestreo o no puede conectarse con el daemon de X-Ray, que actúa como un proxyTCP para las llamadas a la API realizadas por el SDK.
También puede configurar el SDK para que cargue las reglas de muestreo desde un documento JSON. ElSDK puede usar reglas locales como reserva para aquellos casos en los que el muestreo de X-Ray no estédisponible, o bien usar reglas locales exclusivamente.
Example sampling-rules.json
{ "version": 2, "rules": [ { "description": "Player moves.", "host": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 }
273
AWS X-Ray Guía para desarrolladoresRegistro de
], "default": { "fixed_target": 1, "rate": 0.1 }}
Este ejemplo define una regla personalizada y una regla predeterminada. La regla personalizada aplica unporcentaje de muestreo del cinco por ciento sin un número mínimo de solicitudes para rastrear las rutas deacceso de /api/move/. La regla predeterminada rastrea la primera solicitud cada segundo y un 10 porciento de las solicitudes adicionales.
El inconveniente de definir reglas localmente es que cada instancia del grabador aplica el porcentaje fijode forma independiente, en lugar de dejar que se encargue el servicio de X-Ray. Cuando implemente máshosts, la tasa fija se multiplicará, lo que hará que sea más difícil controlar la cantidad de datos registrados.
En AWS Lambda, no se puede modificar la frecuencia de muestreo. Si un servicio instrumentado llamaa la función, Lambda registrará las solicitudes generadas por llamadas que fueron muestreadas porese servicio. Si el rastreo activo está activado y no hay ningún encabezado de rastreo, Lambda toma ladecisión de muestreo.
Para configurar reglas de copia de seguridad, indique a X-Ray SDK for Node.js que cargue reglas demuestreo desde un archivo con setSamplingRules.
Example app.js: reglas de muestreo de un archivo
var AWSXRay = require('aws-xray-sdk');AWSXRay.middleware.setSamplingRules('sampling-rules.json');
También puede definir las reglas en código y pasarlas a setSamplingRules como un objeto.
Example app.js: reglas de muestreo de un objeto
var AWSXRay = require('aws-xray-sdk');var rules = { "rules": [ { "description": "Player moves.", "service_name": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 }, "version": 1 }
AWSXRay.middleware.setSamplingRules(rules);
Para utilizar solo reglas locales, llame a disableCentralizedSampling.
AWSXRay.middleware.disableCentralizedSampling()
Registro dePara registrar la salida del SDK, llame a AWSXRay.setLogger(logger), donde logger es un objetoque proporciona métodos de registro estándar (warn, info, etc.).
Example app.js - registro
var AWSXRay = require('aws-xray-sdk');
// Create your own logger, or instantiate one using a library.
274
AWS X-Ray Guía para desarrolladoresDirección del demonio de X-Ray
var logger = { error: (message, meta) => { /* logging code */ }, warn: (message, meta) => { /* logging code */ }, info: (message, meta) => { /* logging code */ }, debug: (message, meta) => { /* logging code */ }}
AWSXRay.setLogger(logger);AWSXRay.config([AWSXRay.plugins.EC2Plugin]);
Llame a setLogger antes de ejecutar otros métodos de configuración, con el fin de asegurarse decapturar la salida de estas operaciones.
Para obtener una lista de valores de nivel de registro válidos, consulte los detalles en la sección Variablesde entorno (p. 275) .
Para configurar el SDK de modo que envíe los registros de salida a la consola sin utilizar una biblioteca deregistro, utilice la variable de entorno AWS_XRAY_DEBUG_MODE.
Dirección del demonio de X-RaySi el demonio de X-Ray escucha en un puerto o host que no sea 127.0.0.1:2000, puede configurar elX-Ray SDK for Node.js para enviar datos de rastreo a otra dirección.
AWSXRay.setDaemonAddress('host:port');
Puede especificar el host por su nombre o por la dirección IPv4.
Example app.js: dirección del demonio
var AWSXRay = require('aws-xray-sdk');AWSXRay.setDaemonAddress('daemonhost:8082');
Si ha configurado el demonio para que escuche en diferentes puertos para TCP y UDP, puede especificarambos en la configuración de dirección del demonio.
Example app.js: dirección del demonio en puertos independientes
var AWSXRay = require('aws-xray-sdk');AWSXRay.setDaemonAddress('tcp:daemonhost:8082 udp:daemonhost:8083');
También puede establecer la dirección del demonio utilizando la variable de entorno (p. 275)AWS_XRAY_DAEMON_ADDRESS.
Variables de entornoPuede utilizar variables de entorno para configurar el X-Ray SDK for Node.js. El SDK admite las siguientesvariables.
• AWS_XRAY_CONTEXT_MISSING: establezca esta opción en LOG_ERROR para evitar que se produzcanexcepciones cuando el código instrumentado intente registrar datos sin que haya ningún segmentoabierto.
Valores válidos• RUNTIME_ERROR: iniciar una excepción en tiempo de ejecución (predeterminado).
275
AWS X-Ray Guía para desarrolladoresSolicitudes entrantes
• LOG_ERROR: registrar un error y continuar.
Se pueden producir errores relativos a segmentos o subsegmentos inexistentes al intentar usar uncliente instrumentado en el código de inicio que se ejecuta cuando no hay ninguna solicitud abierta o enel código que inicia un nuevo subproceso.
• AWS_XRAY_DAEMON_ADDRESS: configure el host y el puerto del agente de escucha del daemon de X-Ray. De forma predeterminada, el SDK usa 127.0.0.1:2000 para los datos de rastreo (UDP) y para elmuestreo (TCP). Use esta variable si ha configurado el daemon para que esté a la escucha en un puertodiferente (p. 174) o si se ejecuta en un host diferente.
Formato• Mismo puerto: address:port• Puertos diferentes: tcp:address:port udp:address:port
• AWS_XRAY_DEBUG_MODE: debe establecerse en TRUE para configurar el SDK de modo que envíe losregistros de salida a la consola, en lugar de configurar una función de registro (p. 274).
• AWS_XRAY_LOG_LEVEL : establezca un nivel de registro para el registrador. Los valores válidos sondebug, info, warn, error y silent. Este valor se omite cuando AWS_XRAY_DEBUG_MODE seestablece en TRUE.
• AWS_XRAY_TRACING_NAME: establece un nombre de servicio que el SDK utiliza para los segmentos.Anula el nombre de segmento que se ha establecido en el middleware de Express (p. 276).
Seguimiento de solicitudes entrantes con el X-RaySDK for Node.js
Puede utilizar el X-Ray SDK for Node.js para rastrear las solicitudes HTTP entrantes que las aplicacionesExpress y Restify atiendan en una instancia EC2 en Amazon EC2, AWS Elastic Beanstalk o Amazon ECS.
El X-Ray SDK for Node.js proporciona middleware para aplicaciones que utilizan los marcos de trabajoExpress y Restify. Cuando añade el middleware de X-Ray a su aplicación, el X-Ray SDK for Node.jscrea un segmento para cada solicitud muestreada. Este segmento incluye el momento, el método y ladisposición de la solicitud HTTP. La instrumentación adicional crea subsegmentos en este segmento.
Note
Para las funciones de AWS Lambda, Lambda crea un segmento para cada solicitud muestreada.Para obtener más información, consulte AWS Lambda y AWS X-Ray (p. 208).
Cada segmento tiene un nombre que identifica su aplicación en el mapa de servicio. Puede asignarun nombre al segmento de manera estática o puede configurar el SDK para que asigne el nombredinámicamente en función de encabezado de host de la solicitud entrante. La designación dinámica denombres le permite agrupar los rastros en función del nombre de dominio de la solicitud y aplicar unnombre predeterminado si el nombre no coincide con un patrón previsto (por ejemplo, si el encabezado dehost ha sido falsificado).
Solicitudes reenviadas
Si un balanceador de carga u otro intermediario reenvía una solicitud a la aplicación, X-Ray tomala dirección IP del cliente del encabezado X-Forwarded-For de la solicitud, en lugar de hacerlode la dirección IP de origen del paquete IP. La dirección IP del cliente que se registra para unasolicitud reenviada puede falsificarse, por lo que no se debe confiar en ella.
Cuando se reenvía una solicitud, el SDK crea un campo adicional en el segmento para indicar que serealizó esta acción. Si el segmento contiene el campo x_forwarded_for establecido en true, ladirección IP del cliente se obtuvo del encabezado X-Forwarded-For de la solicitud HTTP.
276
AWS X-Ray Guía para desarrolladoresSeguimiento de solicitudes entrantes con Express
El controlador de mensajes crea un segmento para cada solicitud entrante con un bloque http quecontiene la siguiente información:
• Método HTTP: GET, POST, PUT, DELETE, etc.• Dirección del cliente: la dirección IP del cliente que envió la solicitud.• Código de respuesta: el código de respuesta HTTP para la solicitud finalizada.• Intervalo: la hora de inicio (cuando se recibió la solicitud) y la hora de finalización (cuando se envió la
respuesta).• Agente del usuario: el user-agent de la solicitud.• Longitud de contenido: la content-length de la respuesta.
Secciones• Seguimiento de solicitudes entrantes con Express (p. 277)• Seguimiento de solicitudes entrantes con Restify (p. 277)• Configuración de una estrategia de nomenclatura de segmentos (p. 278)
Seguimiento de solicitudes entrantes con ExpressPara usar el middleware Express, inicie el cliente del SDK y utilice el middleware que devolvió la funciónexpress.openSegment antes de definir las rutas que desea usar.
Example app.js - Express
var app = express();
var AWSXRay = require('aws-xray-sdk');app.use(AWSXRay.express.openSegment('MyApp'));
app.get('/', function (req, res) { res.render('index');});
app.use(AWSXRay.express.closeSegment());
Después de definir las rutas, utilice el resultado de express.closeSegment tal como se muestra parapoder solucionar los errores que X-Ray SDK for Node.js haya devuelto.
Seguimiento de solicitudes entrantes con RestifyPara utilizar el middleware Restify, inicialice el cliente del SDK y ejecute enable. Indique su servidor deRestify y el nombre de segmento.
Example app.js: restify
var AWSXRay = require('aws-xray-sdk');var AWSXRayRestify = require('aws-xray-sdk-restify');
var restify = require('restify');var server = restify.createServer();AWSXRayRestify.enable(server, 'MyApp'));
server.get('/', function (req, res) { res.render('index');
277
AWS X-Ray Guía para desarrolladoresConfiguración de una estrategiade nomenclatura de segmentos
});
Configuración de una estrategia de nomenclatura desegmentosAWS X-Ray usa un nombre de servicio para identificar su aplicación y diferenciarla de las demásaplicaciones, bases de datos, API externas y recursos de AWS que usa la aplicación. Cuando el SDK deX-Ray genera segmentos para las solicitudes entrantes, registra el nombre de servicio de la aplicación enel campo de nombre del segmento (p. 124).
El SDK de X-Ray puede utilizar el nombre de host del encabezado de la solicitud HTTP para lossegmentos. Sin embargo, este encabezado se puede falsificar, por lo que podrían crearse nodosinesperados en el mapa de servicio. Para impedir que el SDK asigne incorrectamente nombres a lossegmentos debido a solicitudes con encabezados de host falsificados, debe especificar un nombrepredeterminado para las solicitudes entrantes.
Si la aplicación atiende solicitudes de varios dominios, puede configurar el SDK para que use unaestrategia de designación dinámica que refleje este comportamiento en los nombres de segmento. Conuna estrategia de designación dinámica, el SDK puede utilizar el nombre del host en las solicitudes quecoinciden con un patrón previsto y aplicar un nombre predeterminado en caso contrario.
Por ejemplo, puede tener una aplicación que sirva solicitudes a tres subdominios: www.example.com,api.example.com y static.example.com. Puede usar una estrategia de designación dinámicade nombres con el patrón *.example.com para identificar los segmentos de cada subdominio con unnombre diferente, lo que daría lugar a tres nodos de servicio en el mapa de servicio. Si la aplicación recibesolicitudes con un nombre de host que no coincide con el patrón, aparecerá un cuarto nodo en el mapa deservicio con el nombre alternativo que especifique.
Si desea utilizar el mismo nombre para todos los segmentos de solicitud, especifique el nombre de laaplicación cuando inicie el middleware, tal y como se muestra en las secciones anteriores.
Note
Puede anular el nombre de servicio predeterminado que ha definido en el código mediante lavariable de entorno (p. 275) AWS_XRAY_TRACING_NAME.
Una estrategia de nomenclatura dinámica define un patrón con el que deben coincidir losnombres de host y un nombre predeterminado que se utiliza si el nombre de host de lasolicitud HTTP no coincide con el patrón. Para nombrar los segmentos dinámicamente, useAWSXRay.middleware.enableDynamicNaming.
Example app.js: nombres de segmentos dinámicos
Si el nombre de host de la solicitud coincide con el patrón *.example.com, utilice el nombre de host. Delo contrario, utilice MyApp.
var app = express();
var AWSXRay = require('aws-xray-sdk');app.use(AWSXRay.express.openSegment('MyApp'));AWSXRay.middleware.enableDynamicNaming('*.example.com'); app.get('/', function (req, res) { res.render('index');});
app.use(AWSXRay.express.closeSegment());
278
AWS X-Ray Guía para desarrolladoresAWS Clientes de SDK
Seguimiento de llamadas al AWS SDK con la X-Ray SDK for Node.js
Cuando la aplicación realiza llamadas a AWS servicios de para almacenar datos, escribir en una cola oenviar notificaciones, el realiza un X-Ray SDK for Node.js seguimiento de las llamadas posteriores en (p. 282)subsegmentos. AWS Los servicios rastreados y los recursos a los que accede dentro de dichosservicios (por ejemplo, un Amazon S3 bucket de o una Amazon SQS cola de ) aparecen como nodosposteriores en el mapa de servicio de la X-Ray consola de .
Puede instrumentar todos los clientes del SDK de AWS mediante el encapsulamiento de su instrucción derequisito de aws-sdk en una llamada a AWSXRay.captureAWS.
Example app.js: instrumentación de AWS SDK
var AWS = AWSXRay.captureAWS(require('aws-sdk'));
Para instrumentar clientes individuales, encapsule su cliente del SDK de AWS en una llamada aAWSXRay.captureAWSClient. Por ejemplo, para instrumentar un cliente de AmazonDynamoDB:
Example app.js: instrumentación de clientes de DynamoDB
var AWSXRay = require('aws-xray-sdk');... var ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
Warning
No use captureAWS y captureAWSClient conjuntamente. Esto dará lugar a subsegmentosduplicados.
En todos los servicios, puede ver el nombre de la API a la que se ha llamado en la consola de X-Ray. Paraun subconjunto de servicios, el SDK de X-Ray añade información al segmento para proporcionar un mapadel servicio más detallado.
Por ejemplo, cuanto hace una llamada con un cliente de DynamoDB instrumentado, el SDK añade elnombre de la tabla al segmento para las llamadas cuyo destino es una tabla. En la consola, cada tablaaparece como un nodo distinto en el mapa del servicio, con un nodo genérico de DynamoDB para lasllamadas que no van dirigidas a una tabla.
Example Subsegmento para una llamada a DynamoDB para 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",
279
AWS X-Ray Guía para desarrolladoresLlamadas a HTTP salientes
"operation": "UpdateItem", "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG", }}
Cuando accede a recursos designados, las llamadas a los siguientes servicios crean nodos adicionales enel mapa de servicio. Las llamadas que no están dirigidas a recursos concretos crean un nodo genérico enel servicio.
• Amazon DynamoDB: nombre de la tabla• Amazon Simple Storage Service: nombre de bucket y de clave• Amazon Simple Queue Service: nombre de la cola
Seguimiento de llamadas a servicios web HTTPposteriores utilizando el X-Ray SDK for Node.js
Cuando su aplicación realiza llamadas a microservicios o a API de HTTP públicas, puede utilizar el clientede X-Ray SDK for Node.js para instrumentar dichas llamadas y añadir la API al gráfico de servicios comoun servicios posterior.
Pase su cliente http o https al método captureHTTPs del X-Ray SDK for Node.js para rastrearllamadas salientes.
Note
Las llamadas que utilizan bibliotecas de solicitudes HTTP de terceros, como Axios o Superagent,son compatibles a través de la API captureHTTPsGlobal() y se seguirán rastreando cuandoutilicen el módulo http nativo.
Example app.js: cliente HTTP
var AWSXRay = require('aws-xray-sdk');var http = AWSXRay.captureHTTPs(require('http'));
Para habilitar el rastreo en todos los clientes HTTP, llame a captureHTTPsGlobal antes de cargar http.
Example app.js: cliente HTTP (global)
var AWSXRay = require('aws-xray-sdk');AWSXRay.captureHTTPsGlobal(require('http'));var http = require('http');
Cuando instrumenta una llamada a una API web posterior, el X-Ray SDK for Node.js registra unsubsegmento que contiene información acerca de la solicitud HTTP y la respuesta. X-Ray utiliza elsubsegmento para generar un segmento inferido de la API remota.
Example Subsegmento para una llamada HTTP posterior
{ "id": "004f72be19cddc2a", "start_time": 1484786387.131, "end_time": 1484786387.501, "name": "names.example.com",
280
AWS X-Ray Guía para desarrolladoresConsultas SQL
"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-5880168b-fd5153bb58284b67678aa78c", "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}
Seguimiento de consultas SQL con el X-Ray SDKfor Node.js
Instrumente las consultas de base de datos SQL incluyendo su cliente SQL en el método del cliente X-RaySDK for Node.js correspondiente.
• PostgreSQL – AWSXRay.capturePostgres()
var AWSXRay = require('aws-xray-sdk');var pg = AWSXRay.capturePostgres(require('pg'));var client = new pg.Client();
• MySQL –AWSXRay.captureMySQL()
var AWSXRay = require('aws-xray-sdk');var mysql = AWSXRay.captureMySQL(require('mysql'));...var connection = mysql.createConnection(config);
Cuando se utiliza un cliente instrumentado para realizar consultas SQL, el X-Ray SDK de para Node.jsregistra información sobre la conexión y consultas en un subsegmento.
281
AWS X-Ray Guía para desarrolladoresInclusión de datos adicionales en subsegmentos SQL
Inclusión de datos adicionales en subsegmentos SQLPuede agregar información adicional a los subsegmentos generados para consultas SQL, siempre quese asigne a un campo SQL de la lista blanca. Por ejemplo, para registrar la cadena de consultas SQLsaneada en un subsegmento, puede agregarla directamente al objeto SQL del subsegmento.
Example Asignar SQL al subsegmento
const queryString = 'SELECT * FROM MyTable';connection.query(queryString, ...);
// Retrieve the most recently created subsegmentconst subs = AWSXRay.getSegment().subsegments;
if (subs & & subs.length > 0) { var sqlSub = subs[subs.length - 1]; sqlSub.sql.sanitized_query = queryString;}
Para obtener una lista completa de campos SQL incluidos en la lista blanca, consulte Consultas SQL en laGuía del desarrollador de AWS X-Ray.
Generación de subsegmentos personalizados conel X-Ray SDK for Node.js
Los subsegmentos extienden el segmento (p. 21) de un rastro con detalles sobre el trabajo realizado paraatender una solicitud. Cada vez que se realiza una llamada con un cliente instrumentado, el SDK de X-Rayregistra la información generada en un subsegmento. Puede crear subsegmentos adicionales para agruparotros subsegmentos, para medir el desempeño de una sección de código o para registrar anotaciones ymetadatos.
Subsegmentos Express personalizadosPara crear un subsegmento personalizado para una función que realiza llamadas a servicios posteriores,utilice la función captureAsyncFunc.
Example app.js: subsegmentos personalizados Express
var AWSXRay = require('aws-xray-sdk');
app.use(AWSXRay.express.openSegment('MyApp'));
app.get('/', function (req, res) { var host = 'api.example.com';
AWSXRay.captureAsyncFunc('send', function(subsegment) { sendRequest(host, function() { console.log('rendering!'); res.render('index'); subsegment.close(); }); });});
282
AWS X-Ray Guía para desarrolladoresSubsegmentos de Lambda personalizados
app.use(AWSXRay.express.closeSegment());
function sendRequest(host, cb) { var options = { host: host, path: '/', };
var callback = function(response) { var str = '';
response.on('data', function (chunk) { str += chunk; });
response.on('end', function () { cb(); }); }
http.request(options, callback).end();};
En este ejemplo, la aplicación crea un subsegmento personalizado denominado send para las llamadas ala sendRequest función . captureAsyncFunc transfiere un subsegmento que debe cerrar en la funciónde devolución de llamada cuando se completen las llamadas asíncronas que realiza.
Para las funciones síncronas, puede utilizar la función captureFunc, la cual cierra de forma automática elsubsegmento en cuanto el bloque de funciones termina de ejecutarse.
Cuando crea un subsegmento dentro de un segmento o de otro subsegmento, el X-Ray SDK for Node.jsgenera un ID para dicho subsegmento y registra la hora de inicio y la hora de finalización.
Example Subsegmentos con metadatos
"subsegments": [{ "id": "6f1605cd8a07cb70", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "Custom subsegment for UserModel.saveUser function", "metadata": { "debug": { "test": "Metadata string from UserModel.saveUser" } },
Subsegmentos de Lambda personalizadosEl SDK está configurado para crear automáticamente un segmento de fachada de marcador de posicióncuando detecta que se está ejecutando en Lambda. Para crear un subsegmento básico, que creará unúnico AWS::Lambda::Function nodo en el mapa de X-Ray servicio, llame y reasigne el segmento defachada. Si crea manualmente un nuevo segmento con un nuevo ID (mientras comparte el ID de registrode seguimiento, el ID principal y la decisión de muestreo) podrá enviar un nuevo segmento.
Example app.js - subsegmentos personalizados manuales
const segment = AWSXRay.getSegment(); //returns the facade segmentconst subsegment = segment.addNewSubsegment('subseg');
283
AWS X-Ray Guía para desarrolladoresAnotaciones y metadatos
...subsegment.close();//the segment is closed by the SDK automatically
Agregar anotaciones y metadatos a los segmentoscon el X-Ray SDK for Node.js
Puede registrar información adicional sobre las solicitudes, el entorno o la aplicación con anotaciones ymetadatos. Puede añadir anotaciones y metadatos a los segmentos creados por el SDK de X-Ray o a lossubsegmentos personalizados creados por usted.
Las anotaciones son pares de clave-valor con valores de cadena, numéricos o booleanos. Las anotacionesse indexan para su uso con expresiones de filtro (p. 64). Utilice anotaciones para registrar los datos quedesee utilizar para agrupar rastros en la consola o cuando llame a la API de GetTraceSummaries.
Metadata son los pares clave-valor que pueden tener valores de cualquier tipo, incluso objetos y listas,pero que no se indexan para su uso con expresiones de filtro. Utilice los metadatos para registrar otrosdatos que desee almacenar en el rastro, pero que no necesite usar para buscar.
Además de anotaciones y metadatos, también puede registrar cadenas de ID de usuario (p. 286) en lossegmentos. Los identificadores de usuario se registran en un campo aparte en segmentos y se indexanpara su uso con la búsqueda.
Secciones• Registro de anotaciones con el X-Ray SDK for Node.js (p. 284)• Registro de metadatos con el X-Ray SDK for Node.js (p. 285)• Registro de ID de usuario con el X-Ray SDK for Node.js (p. 286)
Registro de anotaciones con el X-Ray SDK for Node.jsUtilice anotaciones para registrar información sobre segmentos o subsegmentos que desee indexar paralas búsquedas.
Requisitos de anotación
• Claves: hasta 500 caracteres alfanuméricos. Sin espacios ni símbolos excepto el guion bajo.• Valores: hasta 1,000 caracteres Unicode.• Entradas: hasta 50 anotaciones por rastro.
Para registrar anotaciones
1. Obtenga una referencia al segmento o subsegmento actual.
var AWSXRay = require('aws-xray-sdk');...var document = AWSXRay.getSegment();
2. Llame a addAnnotation con una clave de cadena y un valor booleano, numérico o de cadena.
document.addAnnotation("mykey", "my value");
284
AWS X-Ray Guía para desarrolladoresRegistro de metadatos con el X-Ray SDK for Node.js
El SDK registra las anotaciones como pares de clave-valor en un objeto annotations del documentode segmento. Si llama dos veces a addAnnotation con la misma clave, se sobrescriben los valorespreviamente registrados en ese segmento o subsegmento.
Para encontrar rastros que tengan anotaciones con valores específicos, utilice la palabra claveannotations.key en una expresión de filtro (p. 64).
Example app.js: anotaciones
var AWS = require('aws-sdk');var AWSXRay = require('aws-xray-sdk');var ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());...app.post('/signup', function(req, res) { var item = { 'email': {'S': req.body.email}, 'name': {'S': req.body.name}, 'preview': {'S': req.body.previewAccess}, 'theme': {'S': req.body.theme} };
var seg = AWSXRay.getSegment(); seg.addAnnotation('theme', req.body.theme); ddb.putItem({ 'TableName': ddbTable, 'Item': item, 'Expected': { email: { Exists: false } } }, function(err, data) {...
Registro de metadatos con el X-Ray SDK for Node.jsUtilice los metadatos para registrar información sobre segmentos o subsegmentos que no necesite indexarpara las búsquedas. Los valores de metadatos pueden ser cadenas, números, booleanos o cualquier otroobjeto que se pueda serializar en un objeto o matriz JSON.
Para registrar metadatos
1. Obtenga una referencia al segmento o subsegmento actual.
var AWSXRay = require('aws-xray-sdk');...var document = AWSXRay.getSegment();
2. Llame a addMetadata con una clave de cadena, un valor booleano, numérico, de cadena o de objetoy un espacio de nombres de cadena.
document.addMetadata("my key", "my value", "my namespace");
o bien
Llame a addMetadata con solo una clave y un valor.
document.addMetadata("my key", "my value");
Si no especifica un espacio de nombres, el SDK utiliza default. Si llama dos veces a addMetadata conla misma clave, se sobrescriben los valores previamente registrados en ese segmento o subsegmento.
285
AWS X-Ray Guía para desarrolladoresRegistro de ID de usuario con el X-Ray SDK for Node.js
Registro de ID de usuario con el X-Ray SDK forNode.jsRegistre identificadores de usuario en segmentos de solicitud para identificar al usuario que envió lasolicitud. Esta operación no es compatible con las funciones de AWS Lambda porque los segmentos de losentornos de Lambda son inmutables. La llamada setUser solo se puede efectuar con segmentos, no consubsegmentos.
Para registrar identificadores de usuario
1. Obtenga una referencia al segmento o subsegmento actual.
var AWSXRay = require('aws-xray-sdk');...var document = AWSXRay.getSegment();
2. Llame a setUser() con un ID de cadena del usuario que envió la solicitud.
var user = 'john123';
AWSXRay.getSegment().setUser(user);
Puede llamar a setUser para registrar el ID de usuario en cuanto la aplicación rápida comience aprocesar una solicitud. Si va a utilizar el segmento únicamente para establecer el ID de usuario, puedeencadenar las llamadas en una sola línea.
Example app.js: ID de usuario
var AWS = require('aws-sdk');var AWSXRay = require('aws-xray-sdk');var uuidv4 = require('uuid/v4');var ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());... app.post('/signup', function(req, res) { var userId = uuidv4(); var item = { 'userId': {'S': userId}, 'email': {'S': req.body.email}, 'name': {'S': req.body.name} };
var seg = AWSXRay.getSegment().setUser(userId); ddb.putItem({ 'TableName': ddbTable, 'Item': item, 'Expected': { email: { Exists: false } } }, function(err, data) {...
Para buscar rastros de un ID de usuario, utilice la palabra clave user en una expresión de filtro.
286
AWS X-Ray Guía para desarrolladores
AWS X-RaySDK de para PythonEl SDK de X-Ray para Python es una biblioteca para las aplicaciones web de Python que proporcionaclases y métodos para generar y enviar datos de rastreo al demonio de X-Ray. Los datos de rastreoincluyen información sobre las solicitudes HTTP entrantes que atiende la aplicación y las llamadas quela aplicación realiza a los servicios posteriores mediante el AWS SDK de , clientes HTTP o un conectorde base de datos SQL. También puede crear segmentos de forma manual y agregar información dedepuración en anotaciones y metadatos.
Puede descargar el SDK con pip.
$ pip install aws-xray-sdk
Note
El SDK de X-Ray para Python es un proyecto de código abierto. Puede seguir el proyecto, enviarproblemas y solicitudes de extracción en GitHub: github.com/aws/aws-xray-sdk-python
Si usa Django o Flask, empiece agregando el middleware del SDK a la aplicación (p. 294) para rastrearlas solicitudes entrantes. El middleware crea un segmento (p. 21) para cada solicitud rastreada y locompleta cuando se envía la respuesta. Mientras el segmento está abierto, puede utilizar los métodosdel cliente del SDK para añadir información al segmento y crear subsegmentos para rastrear llamadasposteriores. El SDK también registra automáticamente las excepciones que produce su aplicación mientrasel segmento está abierto. Para otras aplicaciones, puede crear segmentos manualmente (p. 297).
Para las funciones de Lambda a las que se ha llamado desde una aplicación o un servicio instrumentados,Lambda lee el encabezado de rastreo (p. 26) y rastrea las solicitudes muestreadas automáticamente.Para las demás funciones, es posible configurar Lambda (p. 208) para muestrear y seguir las solicitudesentrantes. En cualquiera de los dos casos, Lambda crea el segmento y se lo proporciona al SDK de X-Ray.
Note
En Lambda, el SDK de X-Ray es opcional. Si no lo utiliza en la función, el mapa de servicioseguirá incluyendo un nodo para el servicio de Lambda y uno para cada función de Lambda.Si incorpora el SDK, puede instrumentar el código de la función para añadir subsegmentos alsegmento de la función registrado por Lambda. Para obtener más información, consulte AWSLambda y AWS X-Ray (p. 208).
Consulte Worker (p. 159) para ver un ejemplo de una función de Python instrumentada en Lambda.
A continuación, utilice el SDK de X-Ray para Python para instrumentar llamadas posteriores aplicandoparches a las bibliotecas de su aplicación (p. 298). El SDK admite las siguientes bibliotecas.
Bibliotecas compatibles
• botocore, boto3: instrumentar clientes AWS SDK for Python (Boto).• pynamodb: instrumenta la versión PynamoDB del cliente de Amazon DynamoDB.• aiobotocore, aioboto3: instrumenta las versiones integradas en asyncio de los clientes del SDK for
Python.• requests, aiohttp: instrumenta clientes HTTP de alto nivel.• httplib, http.client: instrumenta los clientes HTTP de bajo nivel y las bibliotecas de más alto nivel
que los utilizan.
287
AWS X-Ray Guía para desarrolladoresRequirements
• sqlite3: instrumenta los clientes SQLite.• mysql-connector-python: instrumenta los clientes MySQL.• pg8000: instrumenta la interfaz de Pure-Python PostgreSQL.• psycopg2: instrumenta el adaptador de bases de datos de PostgreSQL.• pymongo: instrumenta los clientes de MongoDB.• pymysql: instrumenta los clientes basados en PyMySQL para MySQL y MariaDB.
Cuando la aplicación realiza llamadas a AWS, una base de datos SQL u otros servicios HTTP, el SDKregistra información acerca de la llamada en un subsegmento. Los servicios de AWS y los recursos a losque accede dentro de los servicios se muestran como nodos posteriores en el mapa del servicio paraayudarle a identificar errores y problemas de limitación en conexiones individuales.
En cuanto empiece a utilizar el SDK, personalice su comportamiento configurando la grabadora y elmiddleware (p. 289). Puede añadir complementos para registrar los datos sobre los recursos informáticosque ejecutan su aplicación, personalizar el comportamiento de muestreo mediante la definición dereglas de muestreo y definir el nivel de log para ver más o menos información del SDK en los logs de lasaplicaciones.
Registre información adicional acerca de las solicitudes y el trabajo que la aplicación realiza enanotaciones y metadatos (p. 304). Las anotaciones son pares sencillos de clave-valor que se indexanpara su uso con expresiones de filtro (p. 64) para poder buscar rastros que contengan datos específicos.Las entradas de metadatos son menos restrictivas y pueden registrar objetos y matrices completos —esdecir, todo lo que se pueda serializar en JSON.
Anotaciones y metadatos
Las anotaciones y los metadatos son texto arbitrario que se añade a los segmentos con el SDK deX-Ray. Las anotaciones se indexan para su uso con expresiones de filtro. Los metadados no seindexan, pero se pueden consultar en un segmento sin formato con la consola o la API de X-Ray.Todas las personas a las que otorgue acceso de lectura a X-Ray pueden ver estos datos.
Cuando tenga muchos clientes instrumentados en su código, un único segmento de solicitudpuede contener un gran número de subsegmentos, uno para cada llamada realizada con un clienteinstrumentado. Puede organizar y agrupar los subsegmentos incluyendo las llamadas del cliente ensubsegmentos personalizados (p. 302). Puede crear un subsegmento personalizado para toda unafunción o cualquier sección de código. A continuación, puede registrar metadatos y anotaciones en elsubsegmento en lugar de escribir todo en el segmento principal.
Para obtener documentación de referencia sobre las clases y los métodos del SDK, consulte AWS X-RaySDK for Python API Reference.
RequirementsEl SDK de X-Ray para Python admite las siguientes versiones de lenguaje y biblioteca.
• Python – 2.7, 3.4 y posteriores• Django – 1.10 y versiones posteriores• – Flask: 0.10 y posteriores• – aiohttp: 2.3.0 y posteriores• AWS SDK for Python (Boto) – 1.4.0 y posteriores• botocore – 1.5.0 y posterior• enum – 0.4.7 y posteriores, para Python versiones 3.4.0 y anteriores
288
AWS X-Ray Guía para desarrolladoresAdministración de dependencias
• jsonpickle – 1.0.0 y versiones posteriores• setuptools – 40.6.3 y posteriores• wrapt – 1.11.0 y posteriores
Administración de dependenciasEl SDK de X-Ray para Python está disponible desde pip.
• Paquete – aws-xray-sdk
Añada el SDK como una dependencia en su archivo requirements.txt.
Example requirements.txt
aws-xray-sdk==2.4.2boto3==1.4.4botocore==1.5.55Django==1.11.3
Si utiliza Elastic Beanstalk para implementar su aplicación, Elastic Beanstalk instala todos los paquetes enrequirements.txt de forma automática.
Configuración del SDK de X-Ray para PythonEl SDK de X-Ray para Python tiene una clase denominada xray_recorder que proporciona la grabadoraglobal. Puede configurar la grabadora global para que personalice el middleware que crea los segmentospara las llamadas HTTP entrantes.
Secciones• Complementos del servicio (p. 289)• Reglas de muestreo (p. 291)• Logging (p. 292)• Configuración de la grabadora en código (p. 292)• Configuración de la grabadora con Django (p. 293)• Variables de entorno (p. 294)
Complementos del servicioUtilice plugins para registrar información sobre el servicio que aloja su aplicación.
Plugins
• Amazon EC2: EC2Plugin agrega el ID de instancia, la zona de disponibilidad y el grupo de CloudWatchLogs.
• Elastic Beanstalk – ElasticBeanstalkPlugin añade el nombre de entorno, la etiqueta de versión y elID de implementación.
• Amazon ECS – ECSPlugin añade el ID del contenedor.
289
AWS X-Ray Guía para desarrolladoresComplementos del servicio
Para utilizar un complemento, llame a configure en el xray_recorder.
from aws_xray_sdk.core import xray_recorderfrom aws_xray_sdk.core import patch_all
xray_recorder.configure(service='My app')plugins = ('ElasticBeanstalkPlugin', 'EC2Plugin')xray_recorder.configure(plugins=plugins)patch_all()
Note
Dado que plugins se transfieren como una tupla, asegúrese de incluir un final , al especificar unúnico complemento. Por ejemplo, plugins = ('EC2Plugin',)
También puede utilizar las variables de entorno (p. 294), que tienen prioridad frente a los valoresestablecidos en código, para configurar la grabadora.
Configure los complementos antes de aplicar parches en las bibliotecas (p. 289) para registrar lasllamadas posteriores.
El SDK también utiliza la configuración del complemento para establecer el campo origin del segmento.Esto indica el tipo de recurso de AWS que ejecuta la aplicación. El tipo de recurso aparece bajo el nombrede la aplicación en el mapa del servicio. Por ejemplo, AWS::ElasticBeanstalk::Environment.
290
AWS X-Ray Guía para desarrolladoresReglas de muestreo
Cuando utiliza varios complementos, el SDK utiliza la siguiente orden de resolución para determinar elorigen: ElasticBeanstalk > EKS > ECS > EC2.
Reglas de muestreoEl SDK utiliza reglas de muestreo que usted define en la consola de X-Ray para determinar qué solicitudesdebe registrar. La regla predeterminada rastrea la primera solicitud de cada segundo y un cinco porciento de todas las solicitudes adicionales en todos los servicios que envían rastros a X-Ray. Cree reglasadicionales en la consola de X-Ray (p. 76) para personalizar la cantidad de datos registrados para cadauna de sus aplicaciones.
El SDK aplica las reglas personalizadas en el orden en que se definen. Si una solicitud coincide con variasreglas personalizadas, el SDK aplica solo la primera regla.
Note
Si el SDK no puede conectar con X-Ray para obtener las reglas de muestreo, utiliza una reglapredeterminada local de la primera solicitud de cada segundo y un cinco por ciento de todas lassolicitudes adicionales para cada host. Esto puede ocurrir si el host no tiene permiso para llamara las API de muestreo o no puede conectarse con el daemon de X-Ray, que actúa como un proxyTCP para las llamadas a la API realizadas por el SDK.
También puede configurar el SDK para que cargue las reglas de muestreo desde un documento JSON. ElSDK puede usar reglas locales como reserva para aquellos casos en los que el muestreo de X-Ray no estédisponible, o bien usar reglas locales exclusivamente.
Example sampling-rules.json
{ "version": 2, "rules": [ { "description": "Player moves.", "host": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1
291
AWS X-Ray Guía para desarrolladoresLogging
}}
Este ejemplo define una regla personalizada y una regla predeterminada. La regla personalizada aplica unporcentaje de muestreo del cinco por ciento sin un número mínimo de solicitudes para rastrear las rutas deacceso de /api/move/. La regla predeterminada rastrea la primera solicitud cada segundo y un 10 porciento de las solicitudes adicionales.
El inconveniente de definir reglas localmente es que cada instancia del grabador aplica el porcentaje fijode forma independiente, en lugar de dejar que se encargue el servicio de X-Ray. Cuando implemente máshosts, la tasa fija se multiplicará, lo que hará que sea más difícil controlar la cantidad de datos registrados.
En AWS Lambda, no se puede modificar la frecuencia de muestreo. Si un servicio instrumentado llamaa la función, Lambda registrará las solicitudes generadas por llamadas que fueron muestreadas porese servicio. Si el rastreo activo está activado y no hay ningún encabezado de rastreo, Lambda toma ladecisión de muestreo.
Para configurar reglas de muestreo de copia de seguridad, llame a xray_recorder.configure, tal ycomo se muestra en el siguiente ejemplo, donde rules es un diccionario de reglas o la ruta absoluta a unarchivo JSON que contiene reglas de muestreo.
xray_recorder.configure(sampling_rules=rules)
Para utilizar solo reglas locales, configure la grabadora con un LocalSampler.
from aws_xray_sdk.core.sampling.local.sampler import LocalSamplerxray_recorder.configure(sampler=LocalSampler())
También puede configurar la grabadora global para deshabilitar el muestreo e instrumentar todas lassolicitudes entrantes.
Example – main.py: deshabilitar el muestreo
xray_recorder.configure(sampling=False)
LoggingEl SDK utiliza el módulo logging integrado de Python. Obtenga una referencia al registrador para la claseaws_xray_sdk y llame setLevel en la misma para configurar el nivel de log diferente para la biblioteca yel resto de la aplicación.
Example – app.py: registro
logging.basicConfig(level='WARNING')logging.getLogger('aws_xray_sdk').setLevel(logging.DEBUG)
Utilice registros de depuración para identificar problemas como la presencia de subsegmentos sin cerrar algenerar subsegmentos de forma manual (p. 302).
Configuración de la grabadora en códigoHay disponibles ajustes adicionales a partir del método configure en xray_recorder.
• context_missing – Establezca esta opción en LOG_ERROR para evitar que se produzcan excepcionescuando el código instrumentado intente registrar datos sin que haya ningún segmento abierto.
• daemon_address – configure el host y el puerto del agente de escucha del demonio de X-Ray.
292
AWS X-Ray Guía para desarrolladoresConfiguración de la grabadora con Django
• service – Establece un nombre de servicio que el SDK utiliza para los segmentos.• plugins – Registre información sobre los AWS recursos de su aplicación.• sampling – Establézcalo en False para deshabilitar el muestreo.• sampling_rules – Establezca la ruta del archivo JSON que contiene las reglas ??? (p. 291)de
muestreo.
Example main.py – deshabilitar excepciones de falta de contexto
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(context_missing='LOG_ERROR')
Configuración de la grabadora con DjangoSi utiliza el marco de Django, puede utilizar el archivo settings.py de Django para configurar opcionesen la grabadora global.
• AUTO_INSTRUMENT (Solo Django) – Registre subsegmentos para operaciones de representación deplantillas y bases de datos integradas.
• AWS_XRAY_CONTEXT_MISSING – Establezca esta opción en LOG_ERROR para evitar que se produzcanexcepciones cuando el código instrumentado intente registrar datos sin que haya ningún segmentoabierto.
• AWS_XRAY_DAEMON_ADDRESS – configure el host y el puerto del agente de escucha del demonio de X-Ray.
• AWS_XRAY_TRACING_NAME – Establece un nombre de servicio que el SDK utiliza para los segmentos.• PLUGINS – Registre información sobre los AWS recursos de su aplicación.• SAMPLING – Establézcalo en False para deshabilitar el muestreo.• SAMPLING_RULES – Establezca la ruta del archivo JSON que contiene las reglas ??? (p. 291)de
muestreo.
Para habilitar la configuración de la grabadora en settings.py, añada el middleware de Django a la listade aplicaciones instaladas.
Example settings.py: aplicaciones – instaladas
INSTALLED_APPS = [ ... 'django.contrib.sessions', 'aws_xray_sdk.ext.django',]
Configure los ajustes disponibles en un diccionario denominado XRAY_RECORDER.
Example settings.py: aplicaciones – instaladas
XRAY_RECORDER = { 'AUTO_INSTRUMENT': True, 'AWS_XRAY_CONTEXT_MISSING': 'LOG_ERROR', 'AWS_XRAY_DAEMON_ADDRESS': '127.0.0.1:5000', 'AWS_XRAY_TRACING_NAME': 'My application', 'PLUGINS': ('ElasticBeanstalkPlugin', 'EC2Plugin', 'ECSPlugin'), 'SAMPLING': False,}
293
AWS X-Ray Guía para desarrolladoresVariables de entorno
Variables de entornoPuede utilizar variables de entorno para configurar el SDK de X-Ray para Python. El SDK admite lassiguientes variables:
• AWS_XRAY_TRACING_NAME – Establece un nombre de servicio que el SDK utiliza para los segmentos.Anula el nombre de servicio que se establece mediante programación.
• AWS_XRAY_SDK_ENABLED – Cuando se establece en false, deshabilita el SDK. De formapredeterminada, el SDK está habilitado a menos que la variable de entorno esté establecida en false.• Cuando está deshabilitado, el grabador global genera automáticamente segmentos y subsegmentos
ficticios que no se envían al demonio y se deshabilita la aplicación automática de parches.El middleware se registra como un contenedor en el grabador local. Todos los segmentos ysubsegmentos que se generan a través del middleware también se vuelven ficticios.
• Establezca el valor de AWS_XRAY_SDK_ENABLED a través de la variable de entorno o interactuandodirectamente con el objeto global_sdk_config de la biblioteca aws_xray_sdk. La configuraciónde la variable de entorno invalida estas interacciones.
• AWS_XRAY_DAEMON_ADDRESS: configure el host y el puerto del agente de escucha del daemon de X-Ray. De forma predeterminada, el SDK usa 127.0.0.1:2000 para los datos de rastreo (UDP) y para elmuestreo (TCP). Use esta variable si ha configurado el daemon para que esté a la escucha en un puertodiferente (p. 174) o si se ejecuta en un host diferente.
Formato
• Mismo puerto: address:port• Puertos diferentes: tcp:address:port udp:address:port
• AWS_XRAY_CONTEXT_MISSING: establezca esta opción en LOG_ERROR para evitar que se produzcanexcepciones cuando el código instrumentado intente registrar datos sin que haya ningún segmentoabierto.
Valores válidos
• RUNTIME_ERROR: iniciar una excepción en tiempo de ejecución (predeterminado).• LOG_ERROR: registrar un error y continuar.
Se pueden producir errores relativos a segmentos o subsegmentos inexistentes al intentar usar uncliente instrumentado en el código de inicio que se ejecuta cuando no hay ninguna solicitud abierta o enel código que inicia un nuevo subproceso.
Las variables de entorno anulan los valores establecidos en el código.
Seguimiento de solicitudes entrantes con elmiddleware del SDK de X-Ray para Python
Cuando añade el middleware a su aplicación y configura un nombre de segmento, el SDK de X-Ray paraPython crea un segmento para cada solicitud muestreada. Este segmento incluye el momento, el método yla disposición de la solicitud HTTP. La instrumentación adicional crea subsegmentos en este segmento.
El SDK de X-Ray para Python admite el siguiente middleware para instrumentar solicitudes HTTPentrantes:
• Django• Flask
294
AWS X-Ray Guía para desarrolladoresAgregar el middleware a su aplicación (Django)
• Bottle
Note
Para las funciones de AWS Lambda, Lambda crea un segmento para cada solicitud muestreada.Para obtener más información, consulte AWS Lambda y AWS X-Ray (p. 208).
Consulte Worker (p. 159) para ver un ejemplo de una función de Python instrumentada en Lambda.
Para scripts o aplicaciones Python en otros marcos de trabajo, puede crear los segmentosmanualmente (p. 297).
Cada segmento tiene un nombre que identifica su aplicación en el mapa de servicio. Puede asignarun nombre al segmento de manera estática o puede configurar el SDK para que asigne el nombredinámicamente en función de encabezado de host de la solicitud entrante. La designación dinámica denombres le permite agrupar los rastros en función del nombre de dominio de la solicitud y aplicar unnombre predeterminado si el nombre no coincide con un patrón previsto (por ejemplo, si el encabezado dehost ha sido falsificado).
Solicitudes reenviadas
Si un balanceador de carga u otro intermediario reenvía una solicitud a la aplicación, X-Ray tomala dirección IP del cliente del encabezado X-Forwarded-For de la solicitud, en lugar de hacerlode la dirección IP de origen del paquete IP. La dirección IP del cliente que se registra para unasolicitud reenviada puede falsificarse, por lo que no se debe confiar en ella.
Cuando se reenvía una solicitud, el SDK crea un campo adicional en el segmento para indicar que serealizó esta acción. Si el segmento contiene el campo x_forwarded_for establecido en true, ladirección IP del cliente se obtuvo del encabezado X-Forwarded-For de la solicitud HTTP.
El middleware crea un segmento para cada solicitud entrante con un bloque http que contiene lasiguiente información:
• Método HTTP: GET, POST, PUT, DELETE, etc.• Dirección del cliente: la dirección IP del cliente que envió la solicitud.• Código de respuesta: el código de respuesta HTTP para la solicitud finalizada.• Intervalo: la hora de inicio (cuando se recibió la solicitud) y la hora de finalización (cuando se envió la
respuesta).• Agente del usuario: el user-agent de la solicitud.• Longitud de contenido: la content-length de la respuesta.
Secciones• Agregar el middleware a su aplicación (Django) (p. 295)• Agregar el middleware a su aplicación (flask) (p. 296)• Agregar el middleware a su aplicación (Bottle) (p. 297)• Instrumentación manual del código de Python (p. 297)• Configuración de una estrategia de nomenclatura de segmentos (p. 297)
Agregar el middleware a su aplicación (Django)Añada el middleware a la lista MIDDLEWARE en su archivo settings.py. El X-Ray middleware debe serla primera línea del settings.py archivo para garantizar que se registren las solicitudes que fallan enotro middleware.
295
AWS X-Ray Guía para desarrolladoresAgregar el middleware a su aplicación (flask)
Example settings.py - SDK de X-Ray para Python middleware
MIDDLEWARE = [ 'aws_xray_sdk.ext.django.middleware.XRayMiddleware', 'django.middleware.security.SecurityMiddleware', 'django.contrib.sessions.middleware.SessionMiddleware', 'django.middleware.common.CommonMiddleware', 'django.middleware.csrf.CsrfViewMiddleware', 'django.contrib.auth.middleware.AuthenticationMiddleware', 'django.contrib.messages.middleware.MessageMiddleware', 'django.middleware.clickjacking.XFrameOptionsMiddleware']
Añada la aplicación Django del SDK de X-Ray a la INSTALLED_APPS lista del settings.py archivo .Esto permitirá configurar la X-Ray grabadora durante el inicio de la aplicación.
Example settings.py: aplicación SDK de X-Ray para Python de Django
INSTALLED_APPS = [ 'aws_xray_sdk.ext.django', 'django.contrib.admin', 'django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', 'django.contrib.messages', 'django.contrib.staticfiles',]
Configure un nombre de segmento en su settings.py archivo (p. 293).
Example settings.py: nombre – del segmento
XRAY_RECORDER = { 'AWS_XRAY_TRACING_NAME': 'My application', 'PLUGINS': ('EC2Plugin'),}
Esto indica a la grabadora de X-Ray que rastree solicitudes servidas por la aplicación Django con latasa de muestreo predeterminada. Puede configurar la grabadora con el archivo de configuración deDjango (p. 293) para aplicar reglas de muestreo personalizadas o cambiar otros ajustes.
Agregar el middleware a su aplicación (flask)Para instrumentar su aplicación Flask, en primer lugar configure un nombre de segmento en elxray_recorder. A continuación, utilice la función XRayMiddleware para aplicar un parche a suaplicación Flask en código.
Example app.py
from aws_xray_sdk.core import xray_recorderfrom aws_xray_sdk.ext.flask.middleware import XRayMiddleware
app = Flask(__name__)
xray_recorder.configure(service='My application')XRayMiddleware(app, xray_recorder)
296
AWS X-Ray Guía para desarrolladoresAgregar el middleware a su aplicación (Bottle)
Esto indica a la grabadora de X-Ray que rastree solicitudes servidas por la aplicación Flask con la tasade muestreo predeterminada. Puede configurar la grabadora en código (p. 292) para aplicar reglas demuestreo personalizadas o cambiar otros ajustes.
Agregar el middleware a su aplicación (Bottle)Para instrumentar su aplicación Bottle, en primer lugar configure un nombre de segmento en elxray_recorder. A continuación, utilice la función XRayMiddleware para aplicar un parche a suaplicación Bottle en código.
Example app.py
from aws_xray_sdk.core import xray_recorderfrom aws_xray_sdk.ext.bottle.middleware import XRayMiddleware app = Bottle() xray_recorder.configure(service='fallback_name', dynamic_naming='My application')app.install(XRayMiddleware(xray_recorder))
Esto indica a la grabadora de X-Ray que rastree solicitudes servidas por la aplicación Bottle con la tasade muestreo predeterminada. Puede configurar la grabadora en código (p. 292) para aplicar reglas demuestreo personalizadas o cambiar otros ajustes.
Instrumentación manual del código de PythonSi no utiliza Django o Flask, puede crear segmentos manualmente. Puede crear un segmento para cadasolicitud entrante o crear segmentos en torno a clientes HTTP o AWS SDK con parches para proporcionarcontexto a la grabadora para añadir subsegmentos.
Example main.py: instrumentación – manual
from aws_xray_sdk.core import xray_recorder
# Start a segmentsegment = xray_recorder.begin_segment('segment_name')# Start a subsegmentsubsegment = xray_recorder.begin_subsegment('subsegment_name')
# Add metadata and annotationssegment.put_metadata('key', dict, 'namespace')subsegment.put_annotation('key', 'value')
# Close the subsegment and segmentxray_recorder.end_subsegment()xray_recorder.end_segment()
Configuración de una estrategia de nomenclatura desegmentosAWS X-Ray usa un nombre de servicio para identificar su aplicación y diferenciarla de las demásaplicaciones, bases de datos, API externas y recursos de AWS que usa la aplicación. Cuando el SDK deX-Ray genera segmentos para las solicitudes entrantes, registra el nombre de servicio de la aplicación enel campo de nombre del segmento (p. 124).
El SDK de X-Ray puede utilizar el nombre de host del encabezado de la solicitud HTTP para lossegmentos. Sin embargo, este encabezado se puede falsificar, por lo que podrían crearse nodos
297
AWS X-Ray Guía para desarrolladoresAplicación de parches a bibliotecas
inesperados en el mapa de servicio. Para impedir que el SDK asigne incorrectamente nombres a lossegmentos debido a solicitudes con encabezados de host falsificados, debe especificar un nombrepredeterminado para las solicitudes entrantes.
Si la aplicación atiende solicitudes de varios dominios, puede configurar el SDK para que use unaestrategia de designación dinámica que refleje este comportamiento en los nombres de segmento. Conuna estrategia de designación dinámica, el SDK puede utilizar el nombre del host en las solicitudes quecoinciden con un patrón previsto y aplicar un nombre predeterminado en caso contrario.
Por ejemplo, puede tener una aplicación que sirva solicitudes a tres subdominios: www.example.com,api.example.com y static.example.com. Puede usar una estrategia de designación dinámicade nombres con el patrón *.example.com para identificar los segmentos de cada subdominio con unnombre diferente, lo que daría lugar a tres nodos de servicio en el mapa de servicio. Si la aplicación recibesolicitudes con un nombre de host que no coincide con el patrón, aparecerá un cuarto nodo en el mapa deservicio con el nombre alternativo que especifique.
Si desea utilizar el mismo nombre para todos los segmentos de solicitud, especifique el nombre de laaplicación cuando configure la grabadora, como se muestra en las secciones anteriores (p. 295).
Una estrategia de nomenclatura dinámica define un patrón con el que deben coincidir los nombres de hosty un nombre predeterminado que se utiliza si el nombre de host de la solicitud HTTP no coincide con elpatrón. Para nombrar segmentos de forma dinámica en Django, añada la configuración DYNAMIC_NAMINGa su archivo settings.py (p. 293).
Example settings.py nomenclatura – dinámica
XRAY_RECORDER = { 'AUTO_INSTRUMENT': True, 'AWS_XRAY_TRACING_NAME': 'My application', 'DYNAMIC_NAMING': '*.example.com', 'PLUGINS': ('ElasticBeanstalkPlugin', 'EC2Plugin')}
Puede utilizar "*" en el patrón para buscar coincidencia con cualquier cadena o "?" para buscarcoincidencias con cualquier carácter único. Para Flask, configure la grabadora en código (p. 292).
Example main.py: nombre del – segmento.
from aws_xray_sdk.core import xray_recorderxray_recorder.configure(service='My application')xray_recorder.configure(dynamic_naming='*.example.com')
Note
Puede anular el nombre de servicio predeterminado que ha definido en el código mediante laAWS_XRAY_TRACING_NAMEvariable de entorno (p. 294).
Aplicación de parches a bibliotecas parainstrumentar llamadas posteriores
Para instrumentar llamadas posteriores, utilice el SDK de X-Ray para Python para aplicar parches a lasbibliotecas que utiliza la aplicación. El SDK de X-Ray para Python puede aplicar parches a las siguientesbibliotecas.
298
AWS X-Ray Guía para desarrolladoresAplicación de parches a bibliotecas
Bibliotecas compatibles
• botocore, boto3: instrumentar clientes AWS SDK for Python (Boto).• pynamodb: instrumenta la versión PynamoDB del cliente de Amazon DynamoDB.• aiobotocore, aioboto3: instrumenta las versiones integradas en asyncio de los clientes del SDK for
Python.• requests, aiohttp: instrumenta clientes HTTP de alto nivel.• httplib, http.client: instrumenta los clientes HTTP de bajo nivel y las bibliotecas de más alto nivel
que los utilizan.• sqlite3: instrumenta los clientes SQLite.• mysql-connector-python: instrumenta los clientes MySQL.• pg8000: instrumenta la interfaz de Pure-Python PostgreSQL.• psycopg2: instrumenta el adaptador de bases de datos de PostgreSQL.• pymongo: instrumenta los clientes de MongoDB.• pymysql: instrumenta los clientes basados en PyMySQL para MySQL y MariaDB.
Al utilizar una biblioteca con parches, el SDK de X-Ray para Python crea un subsegmento para la llamaday registra información desde la solicitud y la respuesta. Debe haber un segmento disponible para que elSDK cree el subsegmento, ya sea desde el middleware del SDK o desde AWS Lambda.
Note
Si utiliza el ORM de SQLAlchemy, puede instrumentar sus consultas SQL importando la versióndel SDK de la sesión y las clases de consulta de SQLAlchemy. Consulte Use ORM SQLAlchemypara obtener instrucciones.
Para aplicar parches a todas las bibliotecas disponibles, utilice la función patch_all enaws_xray_sdk.core. Es posible que algunas bibliotecas, como httplib y urllib, necesiten habilitarla aplicación de parches dobles llamando a patch_all(double_patch=True).
Example – main.py: parchea todas las bibliotecas compatibles
import boto3import botocoreimport requestsimport sqlite3
from aws_xray_sdk.core import xray_recorderfrom aws_xray_sdk.core import patch_all
patch_all()
Para aplicar parches a una sola biblioteca, llame a patch con una tupla del nombre de la biblioteca. Paraello, deberá proporcionar una sola lista de elementos.
Example – main.py: aplicar parches a bibliotecas específicas
import boto3import botocoreimport requestsimport mysql-connector-python
from aws_xray_sdk.core import xray_recorderfrom aws_xray_sdk.core import patch
299
AWS X-Ray Guía para desarrolladoresSeguimiento del contexto para el funcionamiento asíncrono
libraries = (['botocore'])patch(libraries)
Note
En algunos casos, la clave que se utiliza aplicar parches a una biblioteca no coincide con elnombre de la biblioteca. Algunas claves sirven como alias para una o varias bibliotecas.
Alias de las bibliotecas
• httplib – httplib y http.client• mysql – mysql-connector-python
Seguimiento del contexto para el funcionamientoasíncronoPara las bibliotecas integradas de asyncio o para crear subsegmentos para funcionesasíncronas (p. 302), también debe configurar el SDK de X-Ray para Python con un contexto asíncrono.Importe la clase AsyncContext y pase una instancia de ella a la grabadora de X-Ray.
Note
Las bibliotecas compatibles con el marco de trabajo web, como AIOHTTP, no se gestionan através del módulo aws_xray_sdk.core.patcher. No aparecerán en el catálogo de bibliotecasadmitidas depatcher.
Example – main.py: parche aioboto3
import asyncioimport aioboto3import requests
from aws_xray_sdk.core.async_context import AsyncContextfrom aws_xray_sdk.core import xray_recorderxray_recorder.configure(service='my_service', context=AsyncContext())from aws_xray_sdk.core import patch
libraries = ('aioboto3')patch(libraries)
Seguimiento de llamadas al AWS SDK con la SDKde X-Ray para Python
Cuando la aplicación realiza llamadas a AWS servicios de para almacenar datos, escribir en una cola oenviar notificaciones, el realiza un SDK de X-Ray para Python seguimiento de las llamadas posterioresen (p. 302)subsegmentos. AWS Los servicios y recursos rastreados a los que accede dentro de dichosservicios (por ejemplo, un Amazon S3 bucket de o una Amazon SQS cola de ) aparecen como nodosposteriores en el mapa de servicio de la X-Ray consola de .
El instrumenta SDK de X-Ray para Python automáticamente todos los clientes AWS del SDK cuando seaplican parches a la botocore (p. 298)biblioteca. No puede instrumentar clientes individuales.
300
AWS X-Ray Guía para desarrolladoresLlamadas a HTTP salientes
En todos los servicios, puede ver el nombre de la API a la que se ha llamado en la consola de X-Ray. Paraun subconjunto de servicios, el SDK de X-Ray añade información al segmento para proporcionar un mapadel servicio más detallado.
Por ejemplo, cuanto hace una llamada con un cliente de DynamoDB instrumentado, el SDK añade elnombre de la tabla al segmento para las llamadas cuyo destino es una tabla. En la consola, cada tablaaparece como un nodo distinto en el mapa del servicio, con un nodo genérico de DynamoDB para lasllamadas que no van dirigidas a una tabla.
Example Subsegmento para una llamada a DynamoDB para 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", }}
Cuando accede a recursos designados, las llamadas a los siguientes servicios crean nodos adicionales enel mapa de servicio. Las llamadas que no están dirigidas a recursos concretos crean un nodo genérico enel servicio.
• Amazon DynamoDB: nombre de la tabla• Amazon Simple Storage Service: nombre de bucket y de clave• Amazon Simple Queue Service: nombre de la cola
Seguimiento de llamadas a servicios web HTTPposteriores utilizando el SDK de X-Ray para Python
Cuando una aplicación realiza llamadas a microservicios o a API de HTTP públicas, se puede utilizar elSDK de X-Ray para Python para instrumentar dichas llamadas y añadir la API al gráfico de servicios comoun servicio posterior.
Para instrumentar clientes HTTP, debe aplicar parches a la biblioteca (p. 298) que se utiliza para realizarllamadas salientes. Si utiliza requests o el cliente HTTP integrado de Python, eso es lo único que tieneque hacer. Para aiohttp, también debe configurar la grabadora con un contexto asíncrono (p. 300).
Si utiliza la API del cliente de aiohttp 3, es posible que también deba configurar la sesión deClientSession con una instancia de la configuración de seguimiento proporcionada en el SDK.
Example API del cliente 3 de aiohttp
from aws_xray_sdk.ext.aiohttp.client import aws_xray_trace_config
301
AWS X-Ray Guía para desarrolladoresSubsegmentos personalizados
async def foo(): trace_config = aws_xray_trace_config() async with ClientSession(loop=loop, trace_configs=[trace_config]) as session: async with session.get(url) as resp await resp.read()
Cuando instrumenta una llamada a una API web posterior, el SDK de X-Ray para Python registra unsubsegmento que contiene información acerca de la solicitud HTTP y la respuesta. X-Ray utiliza elsubsegmento para generar un segmento inferido de la API remota.
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-5880168b-fd5153bb58284b67678aa78c", "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}
Generación de subsegmentos personalizados conel SDK de X-Ray para Python
Los subsegmentos extienden el segmento (p. 21) de un rastro con detalles sobre el trabajo realizado paraatender una solicitud. Cada vez que se realiza una llamada con un cliente instrumentado, el SDK de X-Ray
302
AWS X-Ray Guía para desarrolladoresSubsegmentos personalizados
registra la información generada en un subsegmento. Puede crear subsegmentos adicionales para agruparotros subsegmentos, para medir el desempeño de una sección de código o para registrar anotaciones ymetadatos.
Para administrar los subsegmentos, utilice los métodos begin_subsegment y end_subsegment.
Example main.py: subsegmento personalizado
from aws_xray_sdk.core import xray_recorder
subsegment = xray_recorder.begin_subsegment('annotations')subsegment.put_annotation('id', 12345)xray_recorder.end_subsegment()
Para crear un subsegmento para una función síncrona, utilice el decorador @xray_recorder.capture.Puede transferir un nombre para el subsegmento a la función de captura o dejarlo para utilizar el nombrede la función.
Example main.py: subsegmento de función
from aws_xray_sdk.core import xray_recorder
@xray_recorder.capture('## create_user')def create_user():...
Si se trata de una función asíncrona, utilice el decorador @xray_recorder.capture_async y pase uncontexto asíncrono a la grabadora.
Example main.py: subsegmento de función asíncrona
from aws_xray_sdk.core.async_context import AsyncContextfrom aws_xray_sdk.core import xray_recorderxray_recorder.configure(service='my_service', context=AsyncContext())
@xray_recorder.capture_async('## create_user')async def create_user(): ...
async def main(): await myfunc()
Cuando crea un subsegmento dentro de un segmento o de otro subsegmento, el SDK de X-Ray paraPython genera un ID para dicho subsegmento y registra la hora de inicio y la hora de finalización.
Example Subsegmentos con metadatos
"subsegments": [{ "id": "6f1605cd8a07cb70", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "Custom subsegment for UserModel.saveUser function", "metadata": { "debug": { "test": "Metadata string from UserModel.saveUser" } },
303
AWS X-Ray Guía para desarrolladoresAnotaciones y metadatos
Agregar anotaciones y metadatos a los segmentoscon el SDK de X-Ray para Python
Puede registrar información adicional sobre las solicitudes, el entorno o la aplicación con anotaciones ymetadatos. Puede añadir anotaciones y metadatos a los segmentos creados por el SDK de X-Ray o a lossubsegmentos personalizados creados por usted.
Las anotaciones son pares de clave-valor con valores de cadena, numéricos o booleanos. Las anotacionesse indexan para su uso con expresiones de filtro (p. 64). Utilice anotaciones para registrar los datos quedesee utilizar para agrupar rastros en la consola o cuando llame a la API de GetTraceSummaries.
Metadata son los pares clave-valor que pueden tener valores de cualquier tipo, incluso objetos y listas,pero que no se indexan para su uso con expresiones de filtro. Utilice los metadatos para registrar otrosdatos que desee almacenar en el rastro, pero que no necesite usar para buscar.
Además de anotaciones y metadatos, también puede registrar cadenas de ID de usuario (p. 306) en lossegmentos. Los identificadores de usuario se registran en un campo aparte en segmentos y se indexanpara su uso con la búsqueda.
Secciones• Registro de anotaciones con el SDK de X-Ray para Python (p. 304)• Registro de metadatos con el SDK de X-Ray para Python (p. 305)• Registro de identificadores de usuario con el SDK de X-Ray para Python (p. 306)
Registro de anotaciones con el SDK de X-Ray paraPythonUtilice anotaciones para registrar información sobre segmentos o subsegmentos que desee indexar paralas búsquedas.
Requisitos de anotación
• Claves: hasta 500 caracteres alfanuméricos. Sin espacios ni símbolos excepto el guion bajo.• Valores: hasta 1,000 caracteres Unicode.• Entradas: hasta 50 anotaciones por rastro.
Para registrar anotaciones
1. Obtenga una referencia al segmento o subsegmento actual desde xray_recorder.
from aws_xray_sdk.core import xray_recorder ... document = xray_recorder.current_segment()
o bien
from aws_xray_sdk.core import xray_recorder ... document = xray_recorder.current_subsegment()
2. Llame a put_annotation con una clave de cadena y un valor booleano, numérico o de cadena.
document.put_annotation("mykey", "my value");
304
AWS X-Ray Guía para desarrolladoresRegistro de metadatos con el SDK de X-Ray para Python
También puede utilizar el método put_annotation en el xray_recorder. Este método registra lasanotaciones en el subsegmento actual o, si no hay ningún subsegmento abierto, en el segmento.
xray_recorder.put_annotation("mykey", "my value");
El SDK registra las anotaciones como pares de clave-valor en un objeto annotations del documentode segmento. Si llama dos veces a put_annotation con la misma clave, se sobrescriben los valorespreviamente registrados en ese segmento o subsegmento.
Para encontrar rastros que tengan anotaciones con valores específicos, utilice la palabra claveannotations.key en una expresión de filtro (p. 64).
Registro de metadatos con el SDK de X-Ray paraPythonUtilice los metadatos para registrar información sobre segmentos o subsegmentos que no necesite indexarpara las búsquedas. Los valores de metadatos pueden ser cadenas, números, booleanos o cualquierobjeto que se pueda serializar en un objeto o matriz JSON.
Para registrar metadatos
1. Obtenga una referencia al segmento o subsegmento actual desde xray_recorder.
from aws_xray_sdk.core import xray_recorder ... document = xray_recorder.current_segment()
o bien
from aws_xray_sdk.core import xray_recorder ... document = xray_recorder.current_subsegment()
2. Llame a put_metadata con una clave de cadena; un valor booleano, numérico, de cadena o deobjeto y un espacio de nombres de cadena.
document.put_metadata("my key", "my value", "my namespace");
o bien
Llame a put_metadata con solo una clave y un valor.
document.put_metadata("my key", "my value");
También puede utilizar el método put_metadata en el xray_recorder. Este método registra losmetadatos en el subsegmento actual o, si no hay ningún subsegmento abierto, en el segmento.
xray_recorder.put_metadata("my key", "my value");
Si no especifica un espacio de nombres, el SDK utiliza default. Si llama dos veces a put_metadatacon la misma clave, se sobrescriben los valores previamente registrados en ese segmento o subsegmento.
305
AWS X-Ray Guía para desarrolladoresRegistro de identificadores de usuario
con el SDK de X-Ray para Python
Registro de identificadores de usuario con el SDK deX-Ray para PythonRegistre identificadores de usuario en segmentos de solicitud para identificar al usuario que envió lasolicitud.
Para registrar identificadores de usuario
1. Obtenga una referencia al segmento actual desde xray_recorder.
from aws_xray_sdk.core import xray_recorder ... document = xray_recorder.current_segment()
2. Llame a setUser con un ID de cadena del usuario que envió la solicitud.
document.set_user("U12345");
Puede llamar a set_user en sus controladores para registrar el ID de usuario en cuanto la aplicaciónempiece a procesar la solicitud.
Para buscar rastros de un ID de usuario, utilice la palabra clave user en una expresión de filtro (p. 64).
Instrumentación de marcos de trabajo webimplementados en entornos sin servidor
AWS SDK de X-Ray para Python permite instrumentar los macos de trabajo web implementados enaplicaciones sin servidor. La arquitectura nativa de la nube carece de servidores, lo que le permite delegarmás responsabilidades de gestión en AWS y mejorar la agilidad y la innovación.
La arquitectura sin servidor es un modelo de aplicaciones de software que permite crear y ejecutaraplicaciones y servicios sin preocuparse por los servidores. En esta arquitectura, ya no son necesariaslas tareas de administración de la infraestructura, como el aprovisionamiento de servidores o clústeres,la aplicación de parches, el mantenimiento del sistema operativo y el aprovisionamiento de capacidad.Puede crear soluciones sin servidor para prácticamente cualquier tipo de aplicación o servicio de backend.Además, será usted quien se encargue de administrar todo lo necesario para ejecutar y escalar lasaplicaciones con alta disponibilidad.
En este tutorial, se explica cómo se instrumenta automáticamente AWS X-Ray en un marco de trabajoweb, como Flask o Django, que se implementa en un entorno sin servidor. La instrumentación de lasaplicaciones de X-Ray le permite ver todas las llamadas anteriores que se realizaron, desde Amazon APIGateway hasta la función de AWS Lambda, así como las llamadas salientes que hace la aplicación.
SDK de X-Ray para Python admite los siguientes marcos de trabajo de aplicaciones de Python:
• Flask versión 0.8 o posteriores• Django versión 1.0 o posteriores
En este tutorial, se detalla una aplicación sin servidor de ejemplo que está implementada en Lambda y seinvoca a través de API Gateway. En este tutorial, se utiliza Zappa para implementar automáticamente laaplicación en Lambda y para configurar el punto de enlace de API Gateway.
306
AWS X-Ray Guía para desarrolladoresPrerequisites
Prerequisites• Zappa• Python – versión 2.7 o 3.6.• AWS CLI – Compruebe que la AWS CLI está configurada con la cuenta y la AWS región de en las que
va a implementar la aplicación.• Pip• Virtualenv
Paso 1: Crear un entornoEn este paso, va a crear un entorno virtual utilizando virtualenv para hospedar la aplicación.
1. Cree un directorio para la aplicación a través de la AWS CLI. A continuación, cambie al nuevodirectorio.
mkdir serverless_applicationcd serverless_application
2. Cree un entorno virtual en este nuevo directorio. Utilice el comando siguiente para activarlo.
# Create our virtual environmentvirtualenv serverless_env
# Activate itsource serverless_env/bin/activate
3. Instale X-Ray, Flask, Zappa y la biblioteca de solicitudes en el entorno.
# Install X-Ray, Flask, Zappa, and Requests into your environmentpip install aws-xray-sdk flask zappa requests
4. Añada el código de la aplicación al directorio serverless_application. En este caso, puedeutilizar como referencia el ejemplo Hello World de Flasks.
En el directorio serverless_application, cree un archivo llamado my_app.py. A continuación,utilice un editor de texto para añadir los siguientes comandos. Esta aplicación instrumenta la bibliotecade solicitudes, aplica parches en el middleware de la aplicación de Flask y abre el punto de enlace'/'.
# Import the X-Ray modulesfrom aws_xray_sdk.ext.flask.middleware import XRayMiddlewarefrom aws_xray_sdk.core import patcher, xray_recorderfrom flask import Flaskimport requests
# Patch the requests module to enable automatic instrumentationpatcher.patch(('requests',))
app = Flask(__name__)
# Configure the X-Ray recorder to generate segments with our service namexray_recorder.configure(service='My First Serverless App')
# Instrument the Flask applicationXRayMiddleware(app, xray_recorder)
307
AWS X-Ray Guía para desarrolladoresPaso 2: Crear e implementar un entorno de Zappa
@app.route('/')def hello_world(): resp = requests.get("https://aws.amazon.com") return 'Hello, World: %s' % resp.url
Paso 2: Crear e implementar un entorno de ZappaEn este paso, utilizará Zappa para configurar automáticamente un punto de enlace API Gateway eimplementarlo en Lambda.
1. Inicialice Zappa desde dentro del directorio serverless_application. En este ejemplo, hemosutilizado la configuración predeterminada. Sin embargo, si tiene sus propias preferencias depersonalización, Zappa le mostrará las instrucciones de configuración.
zappa init
What do you want to call this environment (default 'dev'): dev...What do you want to call your bucket? (default 'zappa-*******'): zappa-*******......It looks like this is a Flask application.What's the modular path to your app's function?This will likely be something like 'your_module.app'.We discovered: my_app.appWhere is your app's function? (default 'my_app.app'): my_app.app...Would you like to deploy this application globally? (default 'n') [y/n/(p)rimary]: n
2. Habilite X-Ray. Abra el archivo zappa_settings.json y compruebe que sea similar al del ejemplo.
{ "dev": { "app_function": "my_app.app", "aws_region": "us-west-2", "profile_name": "default", "project_name": "serverless-exam", "runtime": "python2.7", "s3_bucket": "zappa-*********" }}
3. Añada "xray_tracing": true como entrada en el archivo de configuración.
{ "dev": { "app_function": "my_app.app", "aws_region": "us-west-2", "profile_name": "default", "project_name": "serverless-exam", "runtime": "python2.7", "s3_bucket": "zappa-*********", "xray_tracing": true }}
4. Implemente la aplicación. Esto configurará automáticamente el punto de enlace de API Gateway ycargará el código en Lambda.
308
AWS X-Ray Guía para desarrolladoresPaso 3: Habilitar el seguimiento de X-Ray en API Gateway
zappa deploy
...Deploying API Gateway..Deployment complete!: https://**********.execute-api.us-west-2.amazonaws.com/dev
Paso 3: Habilitar el seguimiento de X-Ray en APIGatewayEn este paso, interactuará con la consola de API Gateway para habilitar el seguimiento de X-Ray.
1. Inicie sesión en la Consola de administración de AWS y abra la consola de API Gateway en https://console.aws.amazon.com/apigateway/.
2. Busque la API que acaba de generar. La URL debería parecerse a esta: serverless-exam-dev.3. Elija Stages (Etapas).4. Seleccione el nombre de la etapa de implementación. El valor predeterminado es dev.5. En la pestaña Logs/Tracing (Registros/rastreo), active la casilla Enable X-Ray Tracing (Habilitar
rastreo de X-Ray).6. Elija Save changes (Guardar cambios).7. Obtenga acceso al punto de enlace a través del navegador. Si utilizó la aplicación Hello World de
ejemplo, debería aparecer lo siguiente.
"Hello, World: https://aws.amazon.com/"
Paso 4: Consultar el registro de seguimiento creadoEn este paso, interactuará con la consola de X-Ray para ver el seguimiento creado por la aplicaciónde ejemplo. Para ver una explicación detallada del análisis del seguimiento, consulte Uso del mapa deservicio.
1. Inicie sesión en Consola de administración de AWS y abra la consola de X-Ray en https://console.aws.amazon.com/xray/home.
2. Consulte los segmentos generados por API Gateway, la función Lambda y el contenedor de Lambda.3. En el segmento de la función Lambda, consulte un subsegmento llamado My First Serverless
App. Detrás hay un segundo subsegmento llamado https://aws.amazon.com.4. Durante la inicialización, Lambda podría generar también un tercer subsegmento llamado
initialization.
309
AWS X-Ray Guía para desarrolladoresPaso 5: Eliminación
Paso 5: EliminaciónTermine siempre los recursos que ya no utilice para evitar que se acumulen costos inesperados. Tal ycomo se explica en este tutorial, existen herramientas como Zappa que optimizan la implementación sinservidor.
Para eliminar la aplicación de Lambda, API Gateway y Amazon S3, ejecute el siguiente comando en eldirectorio del proyecto a través de la AWS CLI.
zappa undeploy dev
310
AWS X-Ray Guía para desarrolladoresPasos siguientes
Pasos siguientesAñada más características a la aplicación incorporando clientes de AWS e instrumentándolos con X-Ray.Consulte más información sobre las opciones de computación sin servidor de AWS en Sin servidor.
311
AWS X-Ray Guía para desarrolladores
AWS X-RaySDK de para RubyEl X-Ray SDK es una biblioteca para las aplicaciones web de Ruby que proporciona clases y métodospara generar y enviar datos de rastreo al demonio de X-Ray. Los datos de rastreo incluyen informaciónsobre las solicitudes HTTP entrantes que atiende la aplicación y las llamadas que la aplicación realizaa los servicios posteriores mediante el AWS SDK de , clientes HTTP o un cliente de registro activo.También puede crear segmentos de forma manual y agregar información de depuración en anotaciones ymetadatos.
Puede descargar el SDK añadiéndolo a su archivo Gemfile y ejecutando bundle install.
Example Gemfile
gem 'aws-sdk'
Si utiliza Rails, en primer lugar añada el middleware del SDK de X-Ray (p. 319) para rastrear lassolicitudes entrantes. Un filtro de solicitudes crea un segmento (p. 21). Mientras el segmento está abierto,puede utilizar los métodos del cliente del SDK para añadir información al segmento y crear subsegmentospara rastrear llamadas posteriores. El SDK también registra automáticamente las excepciones que producesu aplicación mientras el segmento está abierto. Para las aplicaciones que no son de Rails, puede crearsegmentos manualmente (p. 320).
A continuación, utilice el X-Ray SDK para instrumentar los clientes HTTP, SQL y del AWS SDK parar Rubymediante la configuración de la grabadora (p. 321) para aplicar parches a las bibliotecas asociadas.Siempre que realice una llamada a un AWS servicio o recurso posterior con un cliente instrumentado, elSDK de registra información sobre la llamada en un subsegmento. AWS Los servicios de y los recursosa los que accede dentro de los servicios aparecen como nodos posteriores en el mapa de servicio paraayudarle a identificar errores y problemas de limitación controlada en conexiones individuales.
En cuanto empiece a utilizar el SDK, personalice su comportamiento configurando la grabadora (p. 313).Puede añadir complementos para registrar datos sobre los recursos informáticos que ejecutan laaplicación, personalizar el comportamiento de muestreo mediante la definición de reglas de muestreo yproporcionar un registrador para ver más o menos información del SDK en los logs de la aplicación.
Registre información adicional acerca de las solicitudes y el trabajo que la aplicación realiza enanotaciones y metadatos (p. 323). Las anotaciones son pares sencillos de clave-valor que se indexanpara su uso con expresiones de filtro (p. 64) para poder buscar rastros que contengan datos específicos.Las entradas de metadatos son menos restrictivas y pueden registrar objetos y matrices completos —esdecir, todo lo que se pueda serializar en JSON.
Anotaciones y metadatos
Las anotaciones y los metadatos son texto arbitrario que se añade a los segmentos con el SDK deX-Ray. Las anotaciones se indexan para su uso con expresiones de filtro. Los metadados no seindexan, pero se pueden consultar en un segmento sin formato con la consola o la API de X-Ray.Todas las personas a las que otorgue acceso de lectura a X-Ray pueden ver estos datos.
Cuando tenga muchos clientes instrumentados en su código, un único segmento de solicitudpuede contener un gran número de subsegmentos, uno para cada llamada realizada con un clienteinstrumentado. Puede organizar y agrupar los subsegmentos incluyendo las llamadas del cliente
312
AWS X-Ray Guía para desarrolladoresRequirements
en subsegmentos personalizados (p. 323). Puede crear un subsegmento personalizado para unafunción completa o para cualquier sección de código, y registrar los metadatos y las anotaciones en elsubsegmento en lugar de escribirlo todo en el segmento principal.
Para obtener documentación de referencia sobre las clases y los métodos del SDK, consulte AWS X-RaySDK for Ruby API Reference.
RequirementsEl X-Ray SDK requiere Ruby 2.3 o posterior y es compatible con las siguientes bibliotecas:
• AWS SDK parar Ruby versión 3.0 o posterior• Rails versión 5.1 o posterior
Configuración del SDK de X-Ray para RubyEl SDK de X-Ray para Ruby tiene una clase denominada XRay.recorder que proporciona la grabadoraglobal. Puede configurar la grabadora global para que personalice el middleware que crea los segmentospara las llamadas HTTP entrantes.
Secciones• Complementos del servicio (p. 313)• Reglas de muestreo (p. 315)• Logging (p. 317)• Configuración de la grabadora en código (p. 317)• Configuración de la grabadora con Rails (p. 318)• Variables de entorno (p. 318)
Complementos del servicioUtilice plugins para registrar información sobre el servicio que aloja su aplicación.
Plugins
• Amazon EC2 – ec2 añade el ID y la zona de disponibilidad de la instancia.• Elastic Beanstalk – elastic_beanstalk añade el nombre de entorno, la etiqueta de versión y el ID de
implementación.• Amazon ECS – ecs añade el ID del contenedor.
313
AWS X-Ray Guía para desarrolladoresComplementos del servicio
Para utilizar complementos, especifíquelos en el objeto de configuración que se pasa a la grabadora.
Example main.rb: configuración del – complemento
my_plugins = %I[ec2 elastic_beanstalk]
config = { plugins: my_plugins, name: 'my app',}
XRay.recorder.configure(config)
También puede utilizar las variables de entorno (p. 318), que tienen prioridad frente a los valoresestablecidos en código, para configurar la grabadora.
El SDK también utiliza la configuración del complemento para establecer el campo origin del segmento.Esto indica el tipo de recurso de AWS que ejecuta la aplicación. El tipo de recurso aparece bajo el nombrede la aplicación en el mapa del servicio. Por ejemplo, AWS::ElasticBeanstalk::Environment.
314
AWS X-Ray Guía para desarrolladoresReglas de muestreo
Cuando utiliza varios complementos, el SDK utiliza la siguiente orden de resolución para determinar elorigen: ElasticBeanstalk > EKS > ECS > EC2.
Reglas de muestreoEl SDK utiliza reglas de muestreo que usted define en la consola de X-Ray para determinar qué solicitudesdebe registrar. La regla predeterminada rastrea la primera solicitud de cada segundo y un cinco porciento de todas las solicitudes adicionales en todos los servicios que envían rastros a X-Ray. Cree reglasadicionales en la consola de X-Ray (p. 76) para personalizar la cantidad de datos registrados para cadauna de sus aplicaciones.
El SDK aplica las reglas personalizadas en el orden en que se definen. Si una solicitud coincide con variasreglas personalizadas, el SDK aplica solo la primera regla.
Note
Si el SDK no puede conectar con X-Ray para obtener las reglas de muestreo, utiliza una reglapredeterminada local de la primera solicitud de cada segundo y un cinco por ciento de todas lassolicitudes adicionales para cada host. Esto puede ocurrir si el host no tiene permiso para llamara las API de muestreo o no puede conectarse con el daemon de X-Ray, que actúa como un proxyTCP para las llamadas a la API realizadas por el SDK.
También puede configurar el SDK para que cargue las reglas de muestreo desde un documento JSON. ElSDK puede usar reglas locales como reserva para aquellos casos en los que el muestreo de X-Ray no estédisponible, o bien usar reglas locales exclusivamente.
Example sampling-rules.json
{ "version": 2, "rules": [ { "description": "Player moves.", "host": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": {
315
AWS X-Ray Guía para desarrolladoresReglas de muestreo
"fixed_target": 1, "rate": 0.1 }}
Este ejemplo define una regla personalizada y una regla predeterminada. La regla personalizada aplica unporcentaje de muestreo del cinco por ciento sin un número mínimo de solicitudes para rastrear las rutas deacceso de /api/move/. La regla predeterminada rastrea la primera solicitud cada segundo y un 10 porciento de las solicitudes adicionales.
El inconveniente de definir reglas localmente es que cada instancia del grabador aplica el porcentaje fijode forma independiente, en lugar de dejar que se encargue el servicio de X-Ray. Cuando implemente máshosts, la tasa fija se multiplicará, lo que hará que sea más difícil controlar la cantidad de datos registrados.
Para configurar reglas de copia de seguridad, defina un hash para el documento en el objeto deconfiguración que se pasa a la grabadora.
Example main.rb: configuración de la regla de copia de – seguridad
require 'aws-xray-sdk'my_sampling_rules = { version: 1, default: { fixed_target: 1, rate: 0.1 }}config = { sampling_rules: my_sampling_rules, name: 'my app',}XRay.recorder.configure(config)
Para almacenar las reglas de muestreo por separado, defina el hash en un archivo independiente y hagaque el archivo lo incorpore a la aplicación.
Example config/sampling-rules.rb
my_sampling_rules = { version: 1, default: { fixed_target: 1, rate: 0.1 }}
Example main.rb: regla – de muestreo de un archivo
require 'aws-xray-sdk'require config/sampling-rules.rb
config = { sampling_rules: my_sampling_rules, name: 'my app',}XRay.recorder.configure(config)
Para utilizar solo reglas locales, requiera las reglas de muestreo y configure el LocalSampler.
316
AWS X-Ray Guía para desarrolladoresLogging
Example main.rb: muestreo de regla – local
require 'aws-xray-sdk'require 'aws-xray-sdk/sampling/local/sampler'
config = { sampler: LocalSampler.new, name: 'my app',}XRay.recorder.configure(config)
También puede configurar la grabadora global para deshabilitar el muestreo e instrumentar todas lassolicitudes entrantes.
Example – main.rb: deshabilitar el muestreo
require 'aws-xray-sdk'config = { sampling: false, name: 'my app',}XRay.recorder.configure(config)
LoggingDe forma predeterminada, la grabadora muestra los eventos de nivel informativo en $stdout. Puedepersonalizar el registro mediante la definición de un registrador en el objeto de configuración que se pasa ala grabadora.
Example – main.rb: registro
require 'aws-xray-sdk'config = { logger: my_logger, name: 'my app',}XRay.recorder.configure(config)
Utilice registros de depuración para identificar problemas como la presencia de subsegmentos sin cerrar algenerar subsegmentos de forma manual (p. 323).
Configuración de la grabadora en códigoHay disponibles ajustes adicionales a partir del método configure en XRay.recorder.
• context_missing – Establezca esta opción en LOG_ERROR para evitar que se produzcan excepcionescuando el código instrumentado intente registrar datos sin que haya ningún segmento abierto.
• daemon_address – configure el host y el puerto del agente de escucha del demonio de X-Ray.• name – Establece un nombre de servicio que el SDK utiliza para los segmentos.• naming_pattern – Establezca un patrón de nombre de dominio para utilizar la nomenclatura
??? (p. 320)dinámica.• plugins – Registre información sobre los AWS recursos de su aplicación con complementos de
(p. 313).• sampling – Establézcalo en false para deshabilitar el muestreo.
317
AWS X-Ray Guía para desarrolladoresConfiguración de la grabadora con Rails
• sampling_rules – Establezca el hash que contiene las reglas ??? (p. 315)de muestreo.
Example – main.rb: deshabilitar excepciones de falta de contexto
require 'aws-xray-sdk'config = { context_missing: 'LOG_ERROR'}
XRay.recorder.configure(config)
Configuración de la grabadora con RailsSi utiliza el marco de trabajo Rails, puede configurar las opciones de la grabadora global en un archivode Ruby situado en app_root/initializers. El SDK de X-Ray admite una clave de configuraciónadicional para su uso con Rails.
• active_record – Establézcalo en true para registrar subsegmentos para transacciones de base dedatos de registros activos.
Configure los ajustes disponibles en un objeto de configuración denominadoRails.application.config.xray.
Example config/initializers/aws_xray.rb
Rails.application.config.xray = { name: 'my app', patch: %I[net_http aws_sdk], active_record: true}
Variables de entornoPuede utilizar variables de entorno para configurar el SDK de X-Ray para Ruby. El SDK admite lassiguientes variables:
• AWS_XRAY_TRACING_NAME – Establece un nombre de servicio que el SDK utiliza para lossegmentos. Anula el nombre de servicio que se ha establecido en la estrategia de nomenclatura desegmento (p. 320) del filtro de servlet.
• AWS_XRAY_DAEMON_ADDRESS: configure el host y el puerto del agente de escucha del daemon deX-Ray. De forma predeterminada, el SDK envía los datos de rastreo a 127.0.0.1:2000. Use estavariable si ha configurado el daemon para que esté a la escucha en un puerto diferente (p. 174) o si seejecuta en un host diferente.
• AWS_XRAY_CONTEXT_MISSING: establezca esta opción en LOG_ERROR para evitar que se produzcanexcepciones cuando el código instrumentado intente registrar datos sin que haya ningún segmentoabierto.
Valores válidos• RUNTIME_ERROR: iniciar una excepción en tiempo de ejecución (predeterminado).• LOG_ERROR: registrar un error y continuar.
Se pueden producir errores relativos a segmentos o subsegmentos inexistentes al intentar usar uncliente instrumentado en el código de inicio que se ejecuta cuando no hay ninguna solicitud abierta o enel código que inicia un nuevo subproceso.
318
AWS X-Ray Guía para desarrolladoresSolicitudes entrantes
Las variables de entorno anulan los valores establecidos en el código.
Seguimiento de solicitudes entrantes con elmiddleware del SDK de X-Ray para Ruby
Puede utilizar el SDK de X-Ray para rastrear las solicitudes HTTP entrantes que su aplicación atiende enuna instancia EC2 en Amazon EC2, AWS Elastic Beanstalk o Amazon ECS.
Si utiliza Rails, use el middleware de Rails para instrumentar las solicitudes HTTP entrantes. Cuandoañade el middleware a su aplicación y configura un nombre de segmento, el SDK de X-Ray paraRuby crea un segmento para cada solicitud muestreada. Cualquier segmento que se haya creado coninstrumentación adicional se convierte en subsegmentos del segmento en nivel de la solicitud, el cualprovee información sobre la solicitud HTTP y la respuesta. Esta información incluye el momento, el métodoy la disposición de la solicitud.
Cada segmento tiene un nombre que identifica su aplicación en el mapa de servicio. Puede asignarun nombre al segmento de manera estática o puede configurar el SDK para que asigne el nombredinámicamente en función de encabezado de host de la solicitud entrante. La designación dinámica denombres le permite agrupar los rastros en función del nombre de dominio de la solicitud y aplicar unnombre predeterminado si el nombre no coincide con un patrón previsto (por ejemplo, si el encabezado dehost ha sido falsificado).
Solicitudes reenviadas
Si un balanceador de carga u otro intermediario reenvía una solicitud a la aplicación, X-Ray tomala dirección IP del cliente del encabezado X-Forwarded-For de la solicitud, en lugar de hacerlode la dirección IP de origen del paquete IP. La dirección IP del cliente que se registra para unasolicitud reenviada puede falsificarse, por lo que no se debe confiar en ella.
Cuando se reenvía una solicitud, el SDK crea un campo adicional en el segmento para indicar que serealizó esta acción. Si el segmento contiene el campo x_forwarded_for establecido en true, ladirección IP del cliente se obtuvo del encabezado X-Forwarded-For de la solicitud HTTP.
El middleware crea un segmento para cada solicitud entrante con un bloque http que contiene lasiguiente información:
• Método HTTP: GET, POST, PUT, DELETE, etc.• Dirección del cliente: la dirección IP del cliente que envió la solicitud.• Código de respuesta: el código de respuesta HTTP para la solicitud finalizada.• Intervalo: la hora de inicio (cuando se recibió la solicitud) y la hora de finalización (cuando se envió la
respuesta).• Agente del usuario: el user-agent de la solicitud.• Longitud de contenido: la content-length de la respuesta.
Uso del middleware de RailsPara utilizar el middleware, actualice el archivo Gemfile para que incluya el railtie necesario.
Example Archivo Gemfile: rails
gem 'aws-xray-sdk', require: ['aws-xray-sdk/facets/rails/railtie']
319
AWS X-Ray Guía para desarrolladoresInstrumentación manual del código
Para utilizar el middleware, también debe configurar la grabadora (p. 318) con un nombre que representea la aplicación en el mapa de servicios.
Example config/initializers/aws_xray.rb
Rails.application.config.xray = { name: 'my app'}
Instrumentación manual del códigoSi no utiliza Rails, cree los segmentos manualmente. Puede crear un segmento para cada solicitudentrante o crear segmentos en torno a clientes HTTP o AWS SDK con parches para proporcionar contextoa la grabadora para añadir subsegmentos.
# Start a segmentsegment = XRay.recorder.begin_segment 'my_service'# Start a subsegmentsubsegment = XRay.recorder.begin_subsegment 'outbound_call', namespace: 'remote'
# Add metadata or annotation here if necessarymy_annotations = { k1: 'v1', k2: 1024}segment.annotations.update my_annotations
# Add metadata to default namespacesubsegment.metadata[:k1] = 'v1'
# Set user for the segment (subsegment is not supported)segment.user = 'my_name'
# End segment/subsegmentXRay.recorder.end_subsegmentXRay.recorder.end_segment
Configuración de una estrategia de nomenclatura desegmentosAWS X-Ray usa un nombre de servicio para identificar su aplicación y diferenciarla de las demásaplicaciones, bases de datos, API externas y recursos de AWS que usa la aplicación. Cuando el SDK deX-Ray genera segmentos para las solicitudes entrantes, registra el nombre de servicio de la aplicación enel campo de nombre del segmento (p. 124).
El SDK de X-Ray puede utilizar el nombre de host del encabezado de la solicitud HTTP para lossegmentos. Sin embargo, este encabezado se puede falsificar, por lo que podrían crearse nodosinesperados en el mapa de servicio. Para impedir que el SDK asigne incorrectamente nombres a lossegmentos debido a solicitudes con encabezados de host falsificados, debe especificar un nombrepredeterminado para las solicitudes entrantes.
Si la aplicación atiende solicitudes de varios dominios, puede configurar el SDK para que use unaestrategia de designación dinámica que refleje este comportamiento en los nombres de segmento. Conuna estrategia de designación dinámica, el SDK puede utilizar el nombre del host en las solicitudes quecoinciden con un patrón previsto y aplicar un nombre predeterminado en caso contrario.
Por ejemplo, puede tener una aplicación que sirva solicitudes a tres subdominios: www.example.com,api.example.com y static.example.com. Puede usar una estrategia de designación dinámica
320
AWS X-Ray Guía para desarrolladoresAplicación de parches a bibliotecas
de nombres con el patrón *.example.com para identificar los segmentos de cada subdominio con unnombre diferente, lo que daría lugar a tres nodos de servicio en el mapa de servicio. Si la aplicación recibesolicitudes con un nombre de host que no coincide con el patrón, aparecerá un cuarto nodo en el mapa deservicio con el nombre alternativo que especifique.
Si desea utilizar el mismo nombre para todos los segmentos de solicitud, especifique el nombre de laaplicación cuando configure la grabadora, como se muestra en las secciones anteriores (p. 319).
Una estrategia de nomenclatura dinámica define un patrón con el que deben coincidir los nombres de hosty un nombre predeterminado que se utiliza si el nombre de host de la solicitud HTTP no coincide con elpatrón. Para asignar nombre a los segmentos de forma dinámica, especifique un patrón de nomenclaturaen el hash config.
Example main.rb nomenclatura – dinámica
config = { naming_pattern: '*mydomain*', name: 'my app',}
XRay.recorder.configure(config)
Puede utilizar "*" en el patrón para buscar coincidencia con cualquier cadena o "?" para buscarcoincidencias con cualquier carácter único.
Note
Puede anular el nombre de servicio predeterminado que ha definido en el código mediante laAWS_XRAY_TRACING_NAMEvariable de entorno (p. 318).
Aplicación de parches a bibliotecas parainstrumentar llamadas posteriores
Para instrumentar llamadas posteriores, utilice el SDK de X-Ray para Ruby para aplicar parches a lasbibliotecas que utiliza la aplicación. El SDK de X-Ray para Ruby puede aplicar parches a las siguientesbibliotecas.
Bibliotecas compatibles
• net/http: instrumentar clientes HTTP.• aws-sdk: instrumentar clientes del AWS SDK parar Ruby.
Al utilizar una biblioteca con parches, el SDK de X-Ray para Ruby crea un subsegmento para la llamaday registra información desde la solicitud y la respuesta. Debe haber un segmento disponible paraque el SDK cree el subsegmento, ya sea desde el middleware del SDK o mediante una llamada aXRay.recorder.begin_segment.
Para aplicar parches a las bibliotecas, especifíquelos en el objeto de configuración que se pasa a lagrabadora de X-Ray.
Example – main.rb: aplicar parches a las bibliotecas
require 'aws-xray-sdk'
321
AWS X-Ray Guía para desarrolladoresAWS Clientes de SDK
config = { name: 'my app', patch: %I[net_http aws_sdk]}
XRay.recorder.configure(config)
Seguimiento de llamadas al AWS SDK con la SDKde X-Ray para Ruby
Cuando la aplicación realiza llamadas a AWS servicios de para almacenar datos, escribir en una cola oenviar notificaciones, el realiza un SDK de X-Ray para Ruby seguimiento de las llamadas posteriores en (p. 323)subsegmentos. AWS Los servicios y recursos rastreados a los que accede dentro de dichosservicios (por ejemplo, un Amazon S3 bucket de o una Amazon SQS cola de ) aparecen como nodosposteriores en el mapa de servicio de la X-Ray consola de .
El instrumenta SDK de X-Ray para Ruby automáticamente todos los clientes AWS del SDK cuando seaplican parches a la aws-sdk (p. 321)biblioteca. No puede instrumentar clientes individuales.
En todos los servicios, puede ver el nombre de la API a la que se ha llamado en la consola de X-Ray. Paraun subconjunto de servicios, el SDK de X-Ray añade información al segmento para proporcionar un mapadel servicio más detallado.
Por ejemplo, cuanto hace una llamada con un cliente de DynamoDB instrumentado, el SDK añade elnombre de la tabla al segmento para las llamadas cuyo destino es una tabla. En la consola, cada tablaaparece como un nodo distinto en el mapa del servicio, con un nodo genérico de DynamoDB para lasllamadas que no van dirigidas a una tabla.
Example Subsegmento para una llamada a DynamoDB para 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", }}
Cuando accede a recursos designados, las llamadas a los siguientes servicios crean nodos adicionales enel mapa de servicio. Las llamadas que no están dirigidas a recursos concretos crean un nodo genérico enel servicio.
• Amazon DynamoDB: nombre de la tabla• Amazon Simple Storage Service: nombre de bucket y de clave
322
AWS X-Ray Guía para desarrolladoresSubsegmentos personalizados
• Amazon Simple Queue Service: nombre de la cola
Generación de subsegmentos personalizados conel X-Ray SDK
Los subsegmentos extienden el segmento (p. 21) de un rastro con detalles sobre el trabajo realizado paraatender una solicitud. Cada vez que se realiza una llamada con un cliente instrumentado, el SDK de X-Rayregistra la información generada en un subsegmento. Puede crear subsegmentos adicionales para agruparotros subsegmentos, para medir el desempeño de una sección de código o para registrar anotaciones ymetadatos.
Para administrar los subsegmentos, utilice los métodos begin_subsegment y end_subsegment.
subsegment = XRay.recorder.begin_subsegment name: 'annotations', namespace: 'remote'my_annotations = { id: 12345 }subsegment.annotations.update my_annotationsXRay.recorder.end_subsegment
Para crear un subsegmento para una función, encapsúlelo en una llamada a XRay.recorder.capture.
XRay.recorder.capture('name_for_subsegment') do |subsegment| resp = myfunc() # myfunc is your function subsegment.annotations.update k1: 'v1' respend
Cuando se crea un subsegmento dentro de un segmento o de otro subsegmento, el X-Ray SDK genera unID para dicho subsegmento y registra la hora de inicio y la hora de finalización.
Example Subsegmentos con metadatos
"subsegments": [{ "id": "6f1605cd8a07cb70", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "Custom subsegment for UserModel.saveUser function", "metadata": { "debug": { "test": "Metadata string from UserModel.saveUser" } },
Agregar anotaciones y metadatos a los segmentoscon el SDK de X-Ray para Ruby
Puede registrar información adicional sobre las solicitudes, el entorno o la aplicación con anotaciones ymetadatos. Puede añadir anotaciones y metadatos a los segmentos creados por el SDK de X-Ray o a lossubsegmentos personalizados creados por usted.
Las anotaciones son pares de clave-valor con valores de cadena, numéricos o booleanos. Las anotacionesse indexan para su uso con expresiones de filtro (p. 64). Utilice anotaciones para registrar los datos quedesee utilizar para agrupar rastros en la consola o cuando llame a la API de GetTraceSummaries.
323
AWS X-Ray Guía para desarrolladoresRegistro de anotaciones con el SDK de X-Ray para Ruby
Metadata son los pares clave-valor que pueden tener valores de cualquier tipo, incluso objetos y listas,pero que no se indexan para su uso con expresiones de filtro. Utilice los metadatos para registrar otrosdatos que desee almacenar en el rastro, pero que no necesite usar para buscar.
Además de anotaciones y metadatos, también puede registrar cadenas de ID de usuario (p. 325) en lossegmentos. Los identificadores de usuario se registran en un campo aparte en segmentos y se indexanpara su uso con la búsqueda.
Secciones• Registro de anotaciones con el SDK de X-Ray para Ruby (p. 324)• Registro de metadatos con el SDK de X-Ray para Ruby (p. 325)• Registro de ID de usuario con el SDK de X-Ray para Ruby (p. 325)
Registro de anotaciones con el SDK de X-Ray paraRubyUtilice anotaciones para registrar información sobre segmentos o subsegmentos que desee indexar paralas búsquedas.
Requisitos de anotación
• Claves: hasta 500 caracteres alfanuméricos. Sin espacios ni símbolos excepto el guion bajo.• Valores: hasta 1,000 caracteres Unicode.• Entradas: hasta 50 anotaciones por rastro.
Para registrar anotaciones
1. Obtenga una referencia al segmento o subsegmento actual desde xray_recorder.
require 'aws-xray-sdk'...document = XRay.recorder.current_segment
o bien
require 'aws-xray-sdk'...document = XRay.recorder.current_subsegment
2. Llame a update con un valor hash.
my_annotations = { id: 12345 }document.annotations.update my_annotations
El SDK registra las anotaciones como pares de clave-valor en un objeto annotations del documentode segmento. Si llama dos veces a add_annotations con la misma clave, se sobrescriben los valorespreviamente registrados en ese segmento o subsegmento.
Para encontrar rastros que tengan anotaciones con valores específicos, utilice la palabra claveannotations.key en una expresión de filtro (p. 64).
324
AWS X-Ray Guía para desarrolladoresRegistro de metadatos con el SDK de X-Ray para Ruby
Registro de metadatos con el SDK de X-Ray paraRubyUtilice los metadatos para registrar información sobre segmentos o subsegmentos que no necesite indexarpara las búsquedas. Los valores de metadatos pueden ser cadenas, números, booleanos o cualquierobjeto que se pueda serializar en un objeto o matriz JSON.
Para registrar metadatos
1. Obtenga una referencia al segmento o subsegmento actual desde xray_recorder.
require 'aws-xray-sdk'...document = XRay.recorder.current_segment
o bien
require 'aws-xray-sdk'...document = XRay.recorder.current_subsegment
2. Llame a metadata con una clave de cadena; un valor booleano, numérico, de cadena o de objeto yun espacio de nombres de cadena.
my_metadata = { my_namespace: { key: 'value' }}subsegment.metadata my_metadata
Si llama dos veces a metadata con la misma clave, se sobrescriben los valores previamente registradosen ese segmento o subsegmento.
Registro de ID de usuario con el SDK de X-Ray paraRubyRegistre identificadores de usuario en segmentos de solicitud para identificar al usuario que envió lasolicitud.
Para registrar identificadores de usuario
1. Obtenga una referencia al segmento actual desde xray_recorder.
require 'aws-xray-sdk'...document = XRay.recorder.current_segment
2. Especifique el ID de cadena del usuario que envió la solicitud en el campo de usuario del segmento.
segment.user = 'U12345'
325
AWS X-Ray Guía para desarrolladoresRegistro de ID de usuario con el SDK de X-Ray para Ruby
Puede establecer el usuario en los controladores para registrar el ID de usuario tan pronto como laaplicación comience a procesar la solicitud.
Para buscar rastros de un ID de usuario, utilice la palabra clave user en una expresión de filtro (p. 64).
326
AWS X-Ray Guía para desarrolladores
AWS X-Ray SDK para .NETEl X-Ray SDK for .NET es una biblioteca para instrumentar aplicaciones web C# .NET, aplicacionesweb .NET Core y funciones de .NET Core de AWS Lambda. Proporciona clases y métodos para generary enviar datos de rastreo al demonio de X-Ray (p. 171). Esto incluye información sobre las solicitudesentrantes que atiende la aplicación y las llamadas que la aplicación realiza a AWS servicios posteriores,APIs web HTTP y bases de datos SQL.
Note
El X-Ray SDK for .NET es un proyecto de código abierto. Puede seguir el proyecto, enviarproblemas y solicitudes de extracción en GitHub: github.com/aws/aws-xray-sdk-dotnet
Para las aplicaciones web, comience por añadir un controlador de mensajes a su configuraciónweb (p. 333) para realizar el seguimiento de las solicitudes entrantes. El controlador de mensajes creaun segmento (p. 21) para cada solicitud rastreada y lo completa cuando se envía la respuesta. Mientras elsegmento está abierto, puede utilizar los métodos del cliente del SDK para añadir información al segmentoy crear subsegmentos para rastrear llamadas posteriores. El SDK también registra automáticamente lasexcepciones que produce su aplicación mientras el segmento está abierto.
Para las funciones de Lambda a las que se ha llamado desde una aplicación o un servicio instrumentados,Lambda lee el encabezado de rastreo (p. 26) y rastrea las solicitudes muestreadas automáticamente.Para las demás funciones, es posible configurar Lambda (p. 208) para muestrear y seguir las solicitudesentrantes. En cualquiera de los dos casos, Lambda crea el segmento y se lo proporciona al SDK de X-Ray.
Note
En Lambda, el SDK de X-Ray es opcional. Si no lo utiliza en la función, el mapa de servicioseguirá incluyendo un nodo para el servicio de Lambda y uno para cada función de Lambda.Si incorpora el SDK, puede instrumentar el código de la función para añadir subsegmentos alsegmento de la función registrado por Lambda. Para obtener más información, consulte AWSLambda y AWS X-Ray (p. 208).
A continuación, utilice el X-Ray SDK for .NET para instrumentar sus clientes de AWS SDKpara .NET (p. 336). Siempre que realice una llamada a un AWS servicio o recurso posterior con uncliente instrumentado, el SDK de registra información sobre la llamada en un subsegmento. AWS Losservicios de y los recursos a los que accede dentro de los servicios aparecen como nodos posteriores enel mapa de servicio para ayudarle a identificar errores y problemas de limitación controlada en conexionesindividuales.
El X-Ray SDK for .NET también realiza la instrumentación de llamadas posteriores a API webHTTP (p. 338) y bases de datos SQL (p. 339). El método de extensión GetResponseTraced paraSystem.Net.HttpWebRequest rastrea llamadas HTTP salientes. Puede utilizar la versión de X-RaySDK for .NET del SqlCommand para instrumentar consultas SQL.
En cuanto empiece a utilizar el SDK, personalice su comportamiento configurando la grabadora y elcontrolador de mensajes (p. 328). Puede añadir complementos para registrar los datos sobre losrecursos informáticos que ejecutan su aplicación, personalizar el comportamiento de muestreo mediante ladefinición de reglas de muestreo y definir el nivel de log para ver más o menos información del SDK en loslogs de las aplicaciones.
Registre información adicional acerca de las solicitudes y el trabajo que la aplicación realiza enanotaciones y metadatos (p. 342). Las anotaciones son pares sencillos de clave-valor que se indexanpara su uso con expresiones de filtro (p. 64) para poder buscar rastros que contengan datos específicos.
327
AWS X-Ray Guía para desarrolladoresRequirements
Las entradas de metadatos son menos restrictivas y pueden registrar objetos y matrices completos —esdecir, todo lo que se pueda serializar en JSON.
Anotaciones y metadatos
Las anotaciones y los metadatos son texto arbitrario que se añade a los segmentos con el SDK deX-Ray. Las anotaciones se indexan para su uso con expresiones de filtro. Los metadados no seindexan, pero se pueden consultar en un segmento sin formato con la consola o la API de X-Ray.Todas las personas a las que otorgue acceso de lectura a X-Ray pueden ver estos datos.
Cuando tenga muchos clientes instrumentados en su código, un único segmento de solicitudpuede contener un gran número de subsegmentos, uno para cada llamada realizada con un clienteinstrumentado. Puede organizar y agrupar los subsegmentos incluyendo las llamadas del clienteen subsegmentos personalizados (p. 341). Puede crear un subsegmento personalizado para unafunción completa o para cualquier sección de código, y registrar los metadatos y las anotaciones en elsubsegmento en lugar de escribirlo todo en el segmento principal.
Para acceder a documentos de referencia sobre las clases y los métodos de SDK, consulte lo siguiente:
• AWS X-Ray Referencia de la API del SDK para .NET• AWS X-Ray Referencia de la API del SDK para .NET Core
El mismo paquete admite tanto .NET como .NET Core, pero las clases que se utilizan varían. Los ejemplosde este capítulo contienen un enlace a la referencia del API de .NET, a menos que la clase sea específicade .NET Core.
RequirementsX-Ray SDK for .NET requiere .NET Framework 4.5 o posterior y AWS SDK para .NET.
Para las aplicaciones y funciones de .NET Core, el SDK requiere .NET Core 2.0 o posterior.
Agregar el X-Ray SDK for .NET a su aplicaciónUtilice NuGet para añadir el X-Ray SDK for .NET a su aplicación.
Para instalar el X-Ray SDK for .NET con NuGet package manager en Visual Studio
1. Elija Tools (Herramientas), NuGet Package Manager (Administrador de paquetes NuGet) y ManageNuGet Packages for Solution (Administrar paquetes NuGet para la solución).
2. Busque la opción AWSXRayRecorder.3. Elija el paquete y, a continuación, haga clic en Install (Instalar).
Configuración dX-Ray SDK for .NETPuede configurar el X-Ray SDK for .NET mediante el uso de complementos a fin de incluir informaciónsobre el servicio que sus aplicaciones ejecutan, modificar la conducta predeterminada de muestreo oagregar reglas de muestreo que se aplican a las solicitudes dirigidas a rutas específicas.
Para las aplicaciones web .NET, añada claves a la sección appSettings del archivo Web.config.
328
AWS X-Ray Guía para desarrolladoresComplementos
Example Web.config
<configuration> <appSettings> <add key="AWSXRayPlugins" value="EC2Plugin"/> <add key="SamplingRuleManifest" value="sampling-rules.json"/> </appSettings></configuration>
Para .NET Core, cree un archivo denominado appsettings.json con una clave de nivel superiorllamada XRay.
Example .NET appsettings.json
{ "XRay": { "AWSXRayPlugins": "EC2Plugin", "SamplingRuleManifest": "sampling-rules.json" }}
A continuación, en el código de la aplicación, cree un objeto de configuración y utilícelo para inicializar lagrabadora de X-Ray. Hágalo antes de inicializar la grabadora (p. 335).
Example .NET Core Program.cs: configuración de la grabadora
using Amazon.XRay.Recorder.Core;...AWSXRayRecorder.InitializeInstance(configuration);
Si está instrumentando una aplicación web de .NET Core, también puede pasar el objeto de configuraciónal método UseXRay al configurar el controlador de mensajes (p. 335). Para las funciones de Lambda,utilice el método InitializeInstance como se muestra más arriba.
Para obtener más información acerca del API de configuración de .NET Core, consulte Configurar unaaplicación ASP.NET Core en docs.microsoft.com.
Secciones• Complementos (p. 329)• Reglas de muestreo (p. 330)• Registro (.NET) (p. 332)• Registro (.NET Core) (p. 332)• Variables de entorno (p. 333)
ComplementosUtilice complementos para agregar datos sobre el servicio que aloja su aplicación.
Complementos
• Amazon EC2: EC2Plugin agrega el ID de instancia, la zona de disponibilidad y el grupo de CloudWatchLogs.
• Elastic Beanstalk – ElasticBeanstalkPlugin añade el nombre de entorno, la etiqueta de versión y elID de implementación.
329
AWS X-Ray Guía para desarrolladoresReglas de muestreo
• Amazon ECS – ECSPlugin añade el ID del contenedor.
Para utilizar un complemento, agregue el ajuste AWSXRayPlugins para configurar el cliente del X-Ray SDK for .NET. Si hay varios complementos para su aplicación, especifíquelos todos en la mismaconfiguración, separados por comas.
Example Web.config - complementos
<configuration> <appSettings> <add key="AWSXRayPlugins" value="EC2Plugin,ElasticBeanstalkPlugin"/> </appSettings></configuration>
Example .NET Core appsettings.json: complementos
{ "XRay": { "AWSXRayPlugins": "EC2Plugin,ElasticBeanstalkPlugin" }}
Reglas de muestreoEl SDK utiliza reglas de muestreo que usted define en la consola de X-Ray para determinar qué solicitudesdebe registrar. La regla predeterminada rastrea la primera solicitud de cada segundo y un cinco porciento de todas las solicitudes adicionales en todos los servicios que envían rastros a X-Ray. Cree reglasadicionales en la consola de X-Ray (p. 76) para personalizar la cantidad de datos registrados para cadauna de sus aplicaciones.
El SDK aplica las reglas personalizadas en el orden en que se definen. Si una solicitud coincide con variasreglas personalizadas, el SDK aplica solo la primera regla.
Note
Si el SDK no puede conectar con X-Ray para obtener las reglas de muestreo, utiliza una reglapredeterminada local de la primera solicitud de cada segundo y un cinco por ciento de todas lassolicitudes adicionales para cada host. Esto puede ocurrir si el host no tiene permiso para llamara las API de muestreo o no puede conectarse con el daemon de X-Ray, que actúa como un proxyTCP para las llamadas a la API realizadas por el SDK.
También puede configurar el SDK para que cargue las reglas de muestreo desde un documento JSON. ElSDK puede usar reglas locales como reserva para aquellos casos en los que el muestreo de X-Ray no estédisponible, o bien usar reglas locales exclusivamente.
Example sampling-rules.json
{ "version": 2, "rules": [ { "description": "Player moves.", "host": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0,
330
AWS X-Ray Guía para desarrolladoresReglas de muestreo
"rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 }}
Este ejemplo define una regla personalizada y una regla predeterminada. La regla personalizada aplica unporcentaje de muestreo del cinco por ciento sin un número mínimo de solicitudes para rastrear las rutas deacceso de /api/move/. La regla predeterminada rastrea la primera solicitud cada segundo y un 10 porciento de las solicitudes adicionales.
El inconveniente de definir reglas localmente es que cada instancia del grabador aplica el porcentaje fijode forma independiente, en lugar de dejar que se encargue el servicio de X-Ray. Cuando implemente máshosts, la tasa fija se multiplicará, lo que hará que sea más difícil controlar la cantidad de datos registrados.
En AWS Lambda, no se puede modificar la frecuencia de muestreo. Si un servicio instrumentado llamaa la función, Lambda registrará las solicitudes generadas por llamadas que fueron muestreadas porese servicio. Si el rastreo activo está activado y no hay ningún encabezado de rastreo, Lambda toma ladecisión de muestreo.
Para configurar reglas de copia de seguridad, indique a X-Ray SDK for .NET que cargue reglas demuestreo desde un archivo con la configuración SamplingRuleManifest.
Example .NET Web.config: reglas de muestreo
<configuration> <appSettings> <add key="SamplingRuleManifest" value="sampling-rules.json"/> </appSettings></configuration>
Example .NET Core appsettings.json: reglas de muestreo
{ "XRay": { "SamplingRuleManifest": "sampling-rules.json" }}
Para utilizar solo reglas locales, cree la grabadora con una LocalizedSamplingStrategy. Si tienereglas de copia de seguridad configuradas, elimine dicha configuración.
Example .NET global.asax: reglas de muestreo locales
var recorder = new AWSXRayRecorderBuilder().WithSamplingStrategy(new LocalizedSamplingStrategy(samplingrules.json)).Build();AWSXRayRecorder.InitializeInstance(recorder);
Example .NET Core Program.cs: reglas de muestreo locales
var recorder = new AWSXRayRecorderBuilder().WithSamplingStrategy(new LocalizedSamplingStrategy(sampling-rules.json)).Build();AWSXRayRecorder.InitializeInstance(configuration,recorder);
331
AWS X-Ray Guía para desarrolladoresRegistro (.NET)
Registro (.NET)El X-Ray SDK for .NET utiliza el mismo mecanismo de registro que AWS SDK para .NET. Si ya haconfigurado su aplicación para que registre la salida de AWS SDK para .NET, se aplicará la mismaconfiguración a la salida del X-Ray SDK for .NET.
Para configurar el registro, añada una sección de configuración denominada aws al archivo App.config oWeb.config.
Example Web.config - registro
...<configuration> <configSections> <section name="aws" type="Amazon.AWSSection, AWSSDK.Core"/> </configSections> <aws> <logging logTo="Log4Net"/> </aws></configuration>
Para obtener más información, consulte Configuración de su aplicación AWS SDK para .NET en la Guíapara desarrolladores del AWS SDK para .NET.
Registro (.NET Core)Para las aplicaciones de .NET Core, el SDK de X-Ray admite las opciones de registro de la enumeraciónLoggingOptions del AWS SDK para .NET. Para configurar el registro, pase una de estas opciones almétodo RegisterLogger.
AWSXRayRecorder.RegisterLogger(LoggingOptions.Console);
Por ejemplo, para utilizar log4net, cree un archivo de configuración que defina el registrador, el formato desalida y la ubicación del archivo.
Example .NET Core log4net.config
<?xml version="1.0" encoding="utf-8" ?><log4net> <appender name="FileAppender" type="log4net.Appender.FileAppender,log4net"> <file value="c:\logs\sdk-log.txt" /> <layout type="log4net.Layout.PatternLayout"> <conversionPattern value="%date [%thread] %level %logger - %message%newline" /> </layout> </appender> <logger name="Amazon"> <level value="DEBUG" /> <appender-ref ref="FileAppender" /> </logger></log4net>
A continuación, cree el registrador y aplique la configuración en el código del programa.
Example .NET Core Program.cs: registro
using log4net;using Amazon.XRay.Recorder.Core;
332
AWS X-Ray Guía para desarrolladoresVariables de entorno
class Program{ private static ILog log; static Program() { var logRepository = LogManager.GetRepository(Assembly.GetEntryAssembly()); XmlConfigurator.Configure(logRepository, new FileInfo("log4net.config")); log = LogManager.GetLogger(typeof(Program)); AWSXRayRecorder.RegisterLogger(LoggingOptions.Log4Net); } static void Main(string[] args) { ... }}
Para obtener más información sobre cómo configurar log4net, consulte Configuración enlogging.apache.org.
Variables de entornoPuede utilizar variables de entorno para configurar el X-Ray SDK for .NET. El SDK admite las siguientesvariables.
• AWS_XRAY_TRACING_NAME: establece un nombre de servicio que el SDK utiliza para lossegmentos. Anula el nombre de servicio que se ha establecido en la estrategia de nomenclatura desegmento (p. 335) del filtro de servlet.
• AWS_XRAY_DAEMON_ADDRESS: configure el host y el puerto del agente de escucha del daemon de X-Ray. De forma predeterminada, el SDK usa 127.0.0.1:2000 para los datos de rastreo (UDP) y para elmuestreo (TCP). Use esta variable si ha configurado el daemon para que esté a la escucha en un puertodiferente (p. 174) o si se ejecuta en un host diferente.
Formato
• Mismo puerto: address:port• Puertos diferentes: tcp:address:port udp:address:port
• AWS_XRAY_CONTEXT_MISSING: establezca esta opción en LOG_ERROR para evitar que se produzcanexcepciones cuando el código instrumentado intente registrar datos sin que haya ningún segmentoabierto.
Valores válidos
• RUNTIME_ERROR: iniciar una excepción en tiempo de ejecución (predeterminado).• LOG_ERROR: registrar un error y continuar.
Se pueden producir errores relativos a segmentos o subsegmentos inexistentes al intentar usar uncliente instrumentado en el código de inicio que se ejecuta cuando no hay ninguna solicitud abierta o enel código que inicia un nuevo subproceso.
Instrumentación de solicitudes HTTP entrantes conel X-Ray SDK for .NET
Puede utilizar el SDK de X-Ray para rastrear las solicitudes HTTP entrantes que su aplicación atiende enuna instancia EC2 en Amazon EC2, AWS Elastic Beanstalk o Amazon ECS.
333
AWS X-Ray Guía para desarrolladoresInstrumentación de las solicitudes entrantes (.NET)
Utilice un controlador de mensajes para instrumentar las solicitudes HTTP entrantes. Cuando agrega elcontrolador de mensajes de X-Ray a su aplicación, el X-Ray SDK for .NET crea un segmento para cadasolicitud muestreada. Este segmento incluye el momento, el método y la disposición de la solicitud HTTP.La instrumentación adicional crea subsegmentos en este segmento.
Note
Para las funciones de AWS Lambda, Lambda crea un segmento para cada solicitud muestreada.Para obtener más información, consulte AWS Lambda y AWS X-Ray (p. 208).
Cada segmento tiene un nombre que identifica su aplicación en el mapa de servicio. Puede asignarun nombre al segmento de manera estática o puede configurar el SDK para que asigne el nombredinámicamente en función de encabezado de host de la solicitud entrante. La designación dinámica denombres le permite agrupar los rastros en función del nombre de dominio de la solicitud y aplicar unnombre predeterminado si el nombre no coincide con un patrón previsto (por ejemplo, si el encabezado dehost ha sido falsificado).
Solicitudes reenviadas
Si un balanceador de carga u otro intermediario reenvía una solicitud a la aplicación, X-Ray tomala dirección IP del cliente del encabezado X-Forwarded-For de la solicitud, en lugar de hacerlode la dirección IP de origen del paquete IP. La dirección IP del cliente que se registra para unasolicitud reenviada puede falsificarse, por lo que no se debe confiar en ella.
El controlador de mensajes crea un segmento para cada solicitud entrante con un bloque http quecontiene la siguiente información:
• Método HTTP: GET, POST, PUT, DELETE, etc.• Dirección del cliente: la dirección IP del cliente que envió la solicitud.• Código de respuesta: el código de respuesta HTTP para la solicitud finalizada.• Intervalo: la hora de inicio (cuando se recibió la solicitud) y la hora de finalización (cuando se envió la
respuesta).• Agente del usuario: el user-agent de la solicitud.• Longitud de contenido: la content-length de la respuesta.
Secciones• Instrumentación de las solicitudes entrantes (.NET) (p. 334)• Instrumentación de las solicitudes entrantes (.NET Core) (p. 335)• Configuración de una estrategia de nomenclatura de segmentos (p. 335)
Instrumentación de las solicitudes entrantes (.NET)Para instrumentar las solicitudes que atiende su aplicación, llame a RegisterXRay en el método Init delarchivo global.asax.
Example global.asax: controlador de mensajes
using System.Web.Http;mediante Amazon.XRay.Recorder.Handlers.AspNet;
namespace SampleEBWebApplication{ public class MvcApplication : System.Web.HttpApplication { public override void Init() {
334
AWS X-Ray Guía para desarrolladoresInstrumentación de las solicitudes entrantes (.NET Core)
base.Init(); AWSXRayASPNET.RegisterXRay(this, "MyApp"); } }}
Instrumentación de las solicitudes entrantes (.NETCore)Para instrumentar las solicitudes servidas por su aplicación, llame al UseXRay método antes de quecualquier otro middleware en el Configure método de su clase Startup como X-Ray middlewareidealmente debe ser el primer middleware en procesar la solicitud y el último middleware para procesar larespuesta en la canalización.
Note
Para .NET Core 2.0, si tiene un UseExceptionHandler método en la aplicación, asegúresede llamar a UseXRay después del UseExceptionHandler método para asegurarse de que seregistren las excepciones.
Example Startup.cs<caption>.NET Core 2.1 and above</caption>
using Microsoft.AspNetCore.Builder;
public void Configure(IApplicationBuilder app, IHostingEnvironment env) { app.UseXRay("MyApp"); // additional middleware ... }
<caption>.NET Core 2.0</caption>
using Microsoft.AspNetCore.Builder;
public void Configure(IApplicationBuilder app, IHostingEnvironment env) { app.UseExceptionHandler("/Error"); app.UseXRay("MyApp"); // additional middleware ... }
El método UseXRay también puede tomar un objeto de configuración (p. 328) como segundo argumento.
app.UseXRay("MyApp", configuration);
Configuración de una estrategia de nomenclatura desegmentosAWS X-Ray usa un nombre de servicio para identificar su aplicación y diferenciarla de las demásaplicaciones, bases de datos, API externas y recursos de AWS que usa la aplicación. Cuando el SDK deX-Ray genera segmentos para las solicitudes entrantes, registra el nombre de servicio de la aplicación enel campo de nombre del segmento (p. 124).
335
AWS X-Ray Guía para desarrolladoresAWS Clientes de SDK
El SDK de X-Ray puede utilizar el nombre de host del encabezado de la solicitud HTTP para lossegmentos. Sin embargo, este encabezado se puede falsificar, por lo que podrían crearse nodosinesperados en el mapa de servicio. Para impedir que el SDK asigne incorrectamente nombres a lossegmentos debido a solicitudes con encabezados de host falsificados, debe especificar un nombrepredeterminado para las solicitudes entrantes.
Si la aplicación atiende solicitudes de varios dominios, puede configurar el SDK para que use unaestrategia de designación dinámica que refleje este comportamiento en los nombres de segmento. Conuna estrategia de designación dinámica, el SDK puede utilizar el nombre del host en las solicitudes quecoinciden con un patrón previsto y aplicar un nombre predeterminado en caso contrario.
Por ejemplo, puede tener una aplicación que sirva solicitudes a tres subdominios: www.example.com,api.example.com y static.example.com. Puede usar una estrategia de designación dinámicade nombres con el patrón *.example.com para identificar los segmentos de cada subdominio con unnombre diferente, lo que daría lugar a tres nodos de servicio en el mapa de servicio. Si la aplicación recibesolicitudes con un nombre de host que no coincide con el patrón, aparecerá un cuarto nodo en el mapa deservicio con el nombre alternativo que especifique.
Para utilizar el mismo nombre para todos los segmentos de solicitud, especifique el nombre dela aplicación cuando inicialice el controlador de mensajes, tal y como se muestra en la secciónanterior (p. 334). Esto tiene el mismo efecto que crear un FixedSegmentNamingStrategy y pasárseloal método RegisterXRay.
AWSXRayASPNET.RegisterXRay(this, new FixedSegmentNamingStrategy("MyApp"));
Note
Puede anular el nombre de servicio predeterminado que ha definido en el código mediante laAWS_XRAY_TRACING_NAMEvariable de entorno (p. 333).
Una estrategia de nomenclatura dinámica define un patrón con el que deben coincidir los nombresde host y un nombre predeterminado que se utiliza si el nombre de host de la solicitud HTTP nocoincide con el patrón. Para asignar nombres a los segmentos dinámicamente, cree un objetoDynamicSegmentNamingStrategy y páseselo al método RegisterXRay.
AWSXRayASPNET.RegisterXRay(this, new DynamicSegmentNamingStrategy("MyApp", "*.example.com"));
Seguimiento de llamadas al AWS SDK con la X-Ray SDK for .NET
Cuando la aplicación realiza llamadas a AWS servicios de para almacenar datos, escribir en una colao enviar notificaciones, el realiza un X-Ray SDK for .NET seguimiento de las llamadas posteriores en (p. 341)subsegmentos. AWS Los servicios y recursos rastreados a los que accede dentro de dichosservicios (por ejemplo, un Amazon S3 bucket de o una Amazon SQS cola de ) aparecen como nodosposteriores en el mapa de servicio de la X-Ray consola de .
Puede instrumentar todos los clientes de AWS SDK para .NET llamando aRegisterXRayForAllServices antes de crearlos.
Example SampleController.cs: instrumentación de clientes de DynamoDB
using Amazon;
336
AWS X-Ray Guía para desarrolladoresAWS Clientes de SDK
using Amazon.Util;using Amazon.DynamoDBv2;using Amazon.DynamoDBv2.DocumentModel;using Amazon.XRay.Recorder.Core;using Amazon.XRay.Recorder.Handlers.AwsSdk;
namespace SampleEBWebApplication.Controllers{ public class SampleController : ApiController { AWSSDKHandler.RegisterXRayForAllServices(); private static readonly Lazy<AmazonDynamoDBClient> LazyDdbClient = new Lazy<AmazonDynamoDBClient>(() => { var client = new AmazonDynamoDBClient(EC2InstanceMetadata.Region ?? RegionEndpoint.USEast1); return client; });
Si desea instrumentar clientes para algunos servicios y no para otros, llame a RegisterXRay en lugar deRegisterXRayForAllServices. Reemplace el texto resaltado por el nombre de la interfaz de clientedel servicio.
AWSSDKHandler.RegisterXRay<IAmazonDynamoDB>()
En todos los servicios, puede ver el nombre de la API a la que se ha llamado en la consola de X-Ray. Paraun subconjunto de servicios, el SDK de X-Ray añade información al segmento para proporcionar un mapadel servicio más detallado.
Por ejemplo, cuanto hace una llamada con un cliente de DynamoDB instrumentado, el SDK añade elnombre de la tabla al segmento para las llamadas cuyo destino es una tabla. En la consola, cada tablaaparece como un nodo distinto en el mapa del servicio, con un nodo genérico de DynamoDB para lasllamadas que no van dirigidas a una tabla.
Example Subsegmento para una llamada a DynamoDB para 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", }}
Cuando accede a recursos designados, las llamadas a los siguientes servicios crean nodos adicionales enel mapa de servicio. Las llamadas que no están dirigidas a recursos concretos crean un nodo genérico enel servicio.
• Amazon DynamoDB: nombre de la tabla
337
AWS X-Ray Guía para desarrolladoresLlamadas a HTTP salientes
• Amazon Simple Storage Service: nombre de bucket y de clave• Amazon Simple Queue Service: nombre de la cola
Seguimiento de llamadas a servicios web HTTPposteriores con el X-Ray SDK for .NET
Cuando su aplicación realiza llamadas a microservicios o a las API de HTTP públicas, puede utilizar elmétodo GetResponseTraced del X-Ray SDK for .NET para System.Net.HttpWebRequest parainstrumentar dichas llamadas y agregar la API al gráfico de servicios como servicio posterior.
Example HttpWebRequest
using System.Net;using Amazon.XRay.Recorder.Core;using Amazon.XRay.Recorder.Handlers.System.Net;
private void MakeHttpRequest(){ HttpWebRequest request = (HttpWebRequest)WebRequest.Create("http://names.example.com/api"); request.GetResponseTraced();}
Para las llamadas asíncronas, utilice GetAsyncResponseTraced.
request.GetAsyncResponseTraced();
Si utiliza system.net.http.httpclient, utilice el controlador de delegaciónHttpClientXRayTracingHandler para registrar las llamadas.
Example HttpClient
using System.Net.Http;using Amazon.XRay.Recorder.Core;using Amazon.XRay.Recorder.Handlers.System.Net;
private void MakeHttpRequest(){ var httpClient = new HttpClient(new HttpClientXRayTracingHandler(new HttpClientHandler())); httpClient.GetAsync(URL);}
Cuando instrumenta una llamada a una API web posterior, el X-Ray SDK for .NET registra unsubsegmento con información acerca de la solicitud HTTP y la respuesta. X-Ray utiliza el subsegmentopara generar un segmento inferido de la API.
Example Subsegmento para una llamada HTTP posterior
{ "id": "004f72be19cddc2a", "start_time": 1484786387.131, "end_time": 1484786387.501, "name": "names.example.com",
338
AWS X-Ray Guía para desarrolladoresConsultas SQL
"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-5880168b-fd5153bb58284b67678aa78c", "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}
Seguimiento de consultas SQL con el X-Ray SDKfor .NET
El X-Ray SDK for .NET proporciona una clase de encapsulamiento paraSystem.Data.SqlClient.SqlCommand, denominada TraceableSqlCommand, que puede utilizar enlugar de SqlCommand. Puede inicializar un comando SQL con la clase TraceableSqlCommand.
Seguimiento de consultas SQL con métodos síncronosy asíncronosLos siguientes ejemplos muestran cómo utilizar TraceableSqlCommand para rastrear automáticamentelas consultas de SQL Server de forma síncrona y asíncrona.
Example Controller.cs: instrumentación de cliente de SQL (síncrono)
using Amazon;using Amazon.Util;using Amazon.XRay.Recorder.Core;using Amazon.XRay.Recorder.Handlers.SqlServer;
339
AWS X-Ray Guía para desarrolladoresRecopilación de consultas SQL realizadas a SQL Server
private void QuerySql(int id){ var connectionString = ConfigurationManager.AppSettings["RDS_CONNECTION_STRING"]; using (var sqlConnection = new SqlConnection(connectionString)) using (var sqlCommand = new TraceableSqlCommand("SELECT " + id, sqlConnection)) { sqlCommand.Connection.Open(); sqlCommand.ExecuteNonQuery(); }}
Puede ejecutar la consulta de forma asíncrona utilizando el método ExecuteReaderAsync.
Example Controller.cs: instrumentación de clientes de SQL (asíncronos)
using Amazon;using Amazon.Util;using Amazon.XRay.Recorder.Core;using Amazon.XRay.Recorder.Handlers.SqlServer;private void QuerySql(int id){ var connectionString = ConfigurationManager.AppSettings["RDS_CONNECTION_STRING"]; using (var sqlConnection = new SqlConnection(connectionString)) using (var sqlCommand = new TraceableSqlCommand("SELECT " + id, sqlConnection)) { await sqlCommand.ExecuteReaderAsync(); }}
Recopilación de consultas SQL realizadas a SQLServerPuede habilitar la captura de SqlCommand.CommandText como parte del subsegmento creado por laconsulta SQL. SqlCommand.CommandText aparece como el campo sanitized_query en el JSON delsubsegmento. De forma predeterminada, esta característica está deshabilitada por motivos de seguridad.
Note
No habilite la característica de recopilación si está incluyendo información confidencial como textosin cifrar en sus consultas SQL.
Puede habilitar la recopilación de consultas SQL de dos formas:
• Establezca la propiedad CollectSqlQueries en true en la configuración global de su aplicación.• Establezca el parámetro collectSqlQueries de la instancia TraceableSqlCommand en true para
recopilar llamadas dentro de la instancia.
Habilitar la propiedad CollectSqlQueries globalLos siguientes ejemplos muestran cómo habilitar la propiedad CollectSqlQueries para .NET y .NETCore.
.NET
Para establecer la propiedad CollectSqlQueries en true en la configuración global de suaplicación en .NET, modifique el appsettings de su archivo Web.config o App.config, tal ycomo se muestra.
340
AWS X-Ray Guía para desarrolladoresSubsegmentos personalizados
Example App.config o Web.config: habilitar la recopilación de consultas SQL globalmente
<configuration><appSettings> <add key="CollectSqlQueries" value="true"></appSettings></configuration>
.NET Core
Para establecer la propiedad CollectSqlQueries en true en la configuración global de suaplicación en .NET Core, modifique el archivo appsettings.json en la clave de X-Ray, tal y comose muestra.
Example appsettings.json: habilitar la recopilación de consultas SQL globalmente
{ "XRay": { "CollectSqlQueries":"true" }}
Habilitar el parámetro collectSqlQueriesPuede establecer el parámetro collectSqlQueries en la instancia TraceableSqlCommand en truepara recopilar el texto de consulta SQL para las consultas de SQL Server realizadas con esa instancia. Sise establece el parámetro en false se deshabilita la característica CollectSqlQuery para la instanciaTraceableSqlCommand.
Note
El valor de collectSqlQueries en la instancia TraceableSqlCommand anula el valorestablecido en la configuración global de la propiedad CollectSqlQueries.
Example Ejemplo de Controller.cs: habilitar la recopilación de consultas SQL para la instancia
using Amazon;using Amazon.Util;using Amazon.XRay.Recorder.Core;using Amazon.XRay.Recorder.Handlers.SqlServer;
private void QuerySql(int id){ var connectionString = ConfigurationManager.AppSettings["RDS_CONNECTION_STRING"]; using (var sqlConnection = new SqlConnection(connectionString)) using (var command = new TraceableSqlCommand("SELECT " + id, sqlConnection, collectSqlQueries: true)) { command.ExecuteNonQuery(); }}
Creación de subsegmentos adicionalesLos subsegmentos extienden el segmento (p. 21) de un rastro con detalles sobre el trabajo realizado paraatender una solicitud. Cada vez que se realiza una llamada con un cliente instrumentado, el SDK de X-Ray
341
AWS X-Ray Guía para desarrolladoresAnotaciones y metadatos
registra la información generada en un subsegmento. Puede crear subsegmentos adicionales para agruparotros subsegmentos, para medir el desempeño de una sección de código o para registrar anotaciones ymetadatos.
Para administrar los subsegmentos, utilice los métodos BeginSubsegment y EndSubsegment. Realiceel trabajo que desee en el subsegmento en un bloque try y utilice AddException para rastrearexcepciones. Llame a EndSubsegment en un bloque finally para asegurarse de que el subsegmentoestá cerrado.
Example Controller.cs: subsegmento personalizado
AWSXRayRecorder.Instance.BeginSubsegment("custom method");try{ DoWork();}catch (Exception e){ AWSXRayRecorder.Instance.AddException(e);}finally{ AWSXRayRecorder.Instance.EndSubsegment();}
Cuando crea un subsegmento dentro de un segmento o de otro subsegmento, el X-Ray SDK for .NETgenera un ID para dicho subsegmento y registra la hora de inicio y la hora de finalización.
Example Subsegmentos con metadatos
"subsegments": [{ "id": "6f1605cd8a07cb70", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "Custom subsegment for UserModel.saveUser function", "metadata": { "debug": { "test": "Metadata string from UserModel.saveUser" } },
Agregar anotaciones y metadatos a los segmentoscon el X-Ray SDK for .NET
Puede registrar información adicional sobre las solicitudes, el entorno o la aplicación con anotaciones ymetadatos. Puede añadir anotaciones y metadatos a los segmentos creados por el SDK de X-Ray o a lossubsegmentos personalizados creados por usted.
Las anotaciones son pares de clave-valor con valores de cadena, numéricos o booleanos. Las anotacionesse indexan para su uso con expresiones de filtro (p. 64). Utilice anotaciones para registrar los datos quedesee utilizar para agrupar rastros en la consola o cuando llame a la API de GetTraceSummaries.
Metadata son los pares clave-valor que pueden tener valores de cualquier tipo, incluso objetos y listas,pero que no se indexan para su uso con expresiones de filtro. Utilice los metadatos para registrar otrosdatos que desee almacenar en el rastro, pero que no necesite usar para buscar.
Secciones
342
AWS X-Ray Guía para desarrolladoresRegistro de anotaciones con el X-Ray SDK for .NET
• Registro de anotaciones con el X-Ray SDK for .NET (p. 343)• Registro de metadatos con el X-Ray SDK for .NET (p. 343)
Registro de anotaciones con el X-Ray SDK for .NETUtilice anotaciones para registrar información sobre segmentos o subsegmentos que desee indexar paralas búsquedas.
Requisitos de anotación
• Claves: hasta 500 caracteres alfanuméricos. Sin espacios ni símbolos excepto el guion bajo.• Valores: hasta 1,000 caracteres Unicode.• Entradas: hasta 50 anotaciones por rastro.
Para registrar anotaciones
1. Obtenga una instancia de AWSXRayRecorder.
using Amazon.XRay.Recorder.Core;...AWSXRayRecorder recorder = AWSXRayRecorder.Instance;
2. Llame a addAnnotation con una clave de cadena y un valor booleano, Int32, Int64, doble o decadena.
recorder.AddAnnotation("mykey", "my value");
El SDK registra las anotaciones como pares de clave-valor en un objeto annotations del documentode segmento. Si llama dos veces a addAnnotation con la misma clave, se sobrescriben los valorespreviamente registrados en ese segmento o subsegmento.
Para encontrar rastros que tengan anotaciones con valores específicos, utilice la palabra claveannotations.key en una expresión de filtro (p. 64).
Registro de metadatos con el X-Ray SDK for .NETUtilice los metadatos para registrar información sobre segmentos o subsegmentos que no necesite indexarpara las búsquedas. Los valores de metadatos pueden ser cadenas, números, booleanos o cualquier otroobjeto que se pueda serializar en un objeto o matriz JSON.
Para registrar metadatos
1. Obtenga una instancia de AWSXRayRecorder.
using Amazon.XRay.Recorder.Core;...AWSXRayRecorder recorder = AWSXRayRecorder.Instance;
2. Llame a AddMetadata con un espacio de nombres de cadenas, clave de cadena y un valor de objeto.
segment.AddMetadata("my namespace", "my key", "my value");
o bien
343
AWS X-Ray Guía para desarrolladoresRegistro de metadatos con el X-Ray SDK for .NET
Llame a putMetadata con solo una clave y un valor.
segment.AddMetadata("my key", "my value");
Si no especifica un espacio de nombres, el SDK utiliza default. Si llama dos veces a AddMetadata conla misma clave, se sobrescriben los valores previamente registrados en ese segmento o subsegmento.
344
AWS X-Ray Guía para desarrolladores
AWS X-Ray con la distribución deAWS para OpenTelemetry
La distribución de AWS para OpenTelemetry es una distribución de AWS basada en el proyectoOpenTelemetry de informática nativa en la nube (CNCF). OpenTelemetry proporciona un único conjunto deAPIs, bibliotecas y agentes de código abierto para recopilar rastros distribuidos y métricas. Este conjuntode herramientas es una distribución de componentes de OpenTelemetry ascendentes que incluye SDKs,agentes de instrumentación automática y recopiladores que son probados, optimizados, protegidosy compatibles con AWS. Con la distribución de AWS para OpenTelemetry, los ingenieros puedeninstrumentar sus aplicaciones una vez y enviar métricas y rastros correlacionados a varias soluciones demonitorización de AWS, incluidas Amazon CloudWatch, AWS X-Ray y Amazon Elasticsearch Service. Ladistribución de AWS para OpenTelemetry incluye compatibilidad con Java, Python, Go y JavaScript con unagente de instrumentación automática en Java.
De forma parecida al uso de AWS X-Ray, el uso de X-Ray con OpenTelemetry requiere dos componentes:un SDK de OpenTelemetry habilitado para el uso con y la distribución de X-Ray para el recopilador de para el uso con AWS.OpenTelemetryX-Ray
Para obtener más información acerca de cómo utilizar la distribución de AWS para OpenTelemetrycon AWS X-Ray y otros servicios de AWS, consulte AWS Distro for OpenTelemetry o la AWSDistro forOpenTelemetry Documentation.
Para obtener más información sobre el uso y la compatibilidad de los lenguajes, consulte Observabilidadde AWS en GitHub.
345
AWS X-Ray Guía para desarrolladores
Etiquetado de reglas y grupos X-Rayde muestreo
Las etiquetas son palabras o frases que puede utilizar para identificar y organizar sus AWS recursos de .Puede añadir varias etiquetas a cada recurso. Cada etiqueta incluye una clave y un valor opcional queusted define. Por ejemplo, una clave de etiqueta podría ser domainy el valor de la etiqueta podría serexample.com. Puede buscar y filtrar los recursos en función de las etiquetas que añada. Para obtenermás información acerca de las formas de utilizar etiquetas, consulte Etiquetado de AWS recursos de en laReferencia AWS general de .
Los siguientes ejemplos muestran cómo las etiquetas pueden resultar útiles en X-Ray:
• Utilizar etiquetas para realizar un seguimiento de la información de facturación en diferentes categorías.Al aplicar etiquetas a X-Ray grupos y reglas de muestreo, y activar las etiquetas, AWS genera uninforme de asignación de costos como archivo de valores separados por comas (CSV) con el uso y loscostos agregados por etiquetas activas. Puede aplicar etiquetas que representen categorías de negocio(por ejemplo, centros de costos, nombres de aplicación o propietarios) para estructurar los costos entrediferentes servicios. Para obtener más información acerca del uso de etiquetas para la asignación decostos, consulte Uso de etiquetas de asignación de costos en la Guía del usuario de AWS Billing andCost Management.
• Utilizar etiquetas para aplicar permisos basados en etiquetas a las distribuciones de CloudFront. Paraobtener más información, consulte Control del acceso a AWS los recursos de mediante etiquetas derecursos.
Note
Tag Editor y AWS Resource Groups no admiten actualmente X-Ray recursos de . Puede añadir yadministrar etiquetas mediante la AWS X-Ray consola o la API de .
Puede aplicar etiquetas a los recursos de mediante la X-Ray consola de , la API de , la , SDKs de yAWS CLI.Herramientas de AWS para Windows PowerShell Para obtener más información, consulte ladocumentación siguiente:
• API de X-Ray – consulte las siguientes operaciones en la Referencia de la API de AWS X-Ray:• ListTagsForResource• CreateSamplingRule• CreateGroup• TagResource• UntagResource
• AWS CLI – Consulte XRay en la . AWS CLI Command Reference• SDKs–: consulte la documentación del SDK aplicable en la página AWS Documentación de
Note
Si no puede añadir o cambiar etiquetas en un X-Ray recurso de o no puede añadir un recurso quetenga etiquetas específicas, es posible que no tenga permisos para realizar esta operación. Para
346
AWS X-Ray Guía para desarrolladoresRestricciones de las etiquetas
solicitar acceso, póngase en contacto con un AWS usuario de de su empresa que tenga permisosde administrador en X-Ray.
Temas• Restricciones de las etiquetas (p. 347)• Administración de etiquetas en la consola de (p. 347)• Administración de etiquetas en la AWS CLI (p. 349)• Controlar el acceso a X-Ray los recursos de en función de las etiquetas (p. 352)
Restricciones de las etiquetasSe aplican las siguientes restricciones a las etiquetas.
• Número máximo de etiquetas por recurso: – 50• Longitud máxima de la clave–: 128 caracteres Unicode.• Longitud máxima del valor–: 256 caracteres Unicode.• Valores válidos para claves y valores – a-z, A-Z, 0-9, espacio y los siguientes caracteres: _ . : / = + - y @• Las claves y los valores de las etiquetas distinguen entre mayúsculas y minúsculas.• No utilice aws: como prefijo para las claves, ya que su AWS uso está reservado a .
Note
No puede editar ni eliminar etiquetas del sistema.
Administración de etiquetas en la consola dePuede añadir etiquetas opcionales al crear un X-Ray grupo de o una regla de muestreo. Las etiquetastambién se pueden cambiar o eliminar más adelante en la consola de .
Los siguientes procedimientos explican cómo añadir, editar y eliminar etiquetas para sus grupos y reglasde muestreo en la X-Ray consola de .
Temas• Agregar etiquetas a un nuevo grupo de (consola) (p. 347)• Agregar etiquetas a una nueva regla de muestreo (consola) (p. 348)• Editar o eliminar etiquetas de un grupo (consola) (p. 348)• Editar o eliminar etiquetas de una regla de muestreo (consola) (p. 349)
Agregar etiquetas a un nuevo grupo de (consola)Al crear un nuevo X-Ray grupo, puede agregar etiquetas opcionales en la página Create group (Creargrupo).
1. Inicie sesión en Consola de administración de AWS y abra la consola de X-Ray en https://console.aws.amazon.com/xray/home.
347
AWS X-Ray Guía para desarrolladoresAgregar etiquetas a una nueva regla de muestreo (consola)
2. En el panel de navegación, expanda Configuration (Configuración) y elija Groups (Grupos).3. Elija Create group (Crear grupo).4. En la página Create group (Crear grupo), especifique un nombre y una expresión de filtro para el
grupo. Para obtener más información sobre estas propiedades, consulte Configuración de grupos deen la consola X-Ray de (p. 92).
5. En Tags (Etiquetas), escriba una clave de etiqueta y, opcionalmente, un valor de etiqueta. Porejemplo, puede introducir una clave de etiqueta de Stagey un valor de etiqueta de Productionparaindicar que este grupo es para uso en producción. Al añadir una etiqueta, aparece una nueva líneapara que añada otra etiqueta, si es necesario. Consulte Restricciones de las etiquetas (p. 347) eneste tema para conocer las limitaciones de las etiquetas.
6. Cuando haya terminado de agregar etiquetas, elija Create group (Crear grupo).
Agregar etiquetas a una nueva regla de muestreo(consola)Al crear una nueva regla X-Ray de muestreo, puede añadir etiquetas en la página Create sampling rule(Crear regla de muestreo).
1. Inicie sesión en Consola de administración de AWS y abra la consola de X-Ray en https://console.aws.amazon.com/xray/home.
2. En el panel de navegación, expanda Configuration (Configuración) y elija Sampling (Muestreo).3. Elija Create sampling rule (Crear regla de muestreo).4. En la página Create sampling rule (Crear regla de muestreo), especifique un nombre, prioridad,
límites, criterios coincidentes y atributos coincidentes. Para obtener más información sobre estaspropiedades, consulte Configuración de reglas de muestreo en la consola de X-Ray (p. 76).
5. En Tags (Etiquetas), escriba una clave de etiqueta y, de forma opcional, un valor de etiqueta. Porejemplo, puede introducir una clave de etiqueta de Stagey un valor de etiqueta de Productionparaindicar que esta regla de muestreo es para uso en producción. Al añadir una etiqueta, apareceuna nueva línea para que añada otra etiqueta, si es necesario. Consulte Restricciones de lasetiquetas (p. 347) en este tema para conocer las limitaciones de las etiquetas.
6. Cuando haya terminado de agregar etiquetas, elija Create sampling rule (Crear regla de muestreo).
Editar o eliminar etiquetas de un grupo (consola)Puede cambiar o eliminar etiquetas en un X-Ray grupo de en la página Edit group (Editar grupo).
1. Inicie sesión en Consola de administración de AWS y abra la consola de X-Ray en https://console.aws.amazon.com/xray/home.
2. En el panel de navegación, expanda Configuration (Configuración) y elija Groups (Grupos).3. En la tabla Groups (Grupos), elija el nombre de un grupo.4. En la página Edit group (Editar grupo), en Tags (Etiquetas), edite las claves y los valores de las
etiquetas. No puede tener claves de etiqueta duplicadas. Los valores de etiqueta son opcionales;puede eliminar valores si lo desea. Para obtener más información acerca de otras propiedades en lapágina Edit group (Editar grupo), consulte Configuración de grupos de en la consola X-Ray de (p. 92).Consulte Restricciones de las etiquetas (p. 347) en este tema para conocer las limitaciones de lasetiquetas.
5. Para eliminar una etiqueta, elija X a la derecha de la etiqueta.6. Cuando haya terminado de editar o eliminar etiquetas, elija Update group (Actualizar grupo).
348
AWS X-Ray Guía para desarrolladoresEditar o eliminar etiquetas de
una regla de muestreo (consola)
Editar o eliminar etiquetas de una regla de muestreo(consola)Puede cambiar o eliminar etiquetas en una regla de X-Ray muestreo en la página Edit sampling rule (Editarregla de muestreo).
1. Inicie sesión en Consola de administración de AWS y abra la consola de X-Ray en https://console.aws.amazon.com/xray/home.
2. En el panel de navegación, expanda Configuration (Configuración) y elija Sampling (Muestreo).3. En la tabla Reglas de muestreo, elija el nombre de una regla de muestreo.4. En Tags (Etiquetas), edite las claves y los valores de las etiquetas. No puede tener claves de etiqueta
duplicadas. Los valores de etiqueta son opcionales; puede eliminar valores si lo desea. Para obtenermás información acerca de otras propiedades en la página Edit sampling rule (Editar regla demuestreo), consulte Configuración de reglas de muestreo en la consola de X-Ray (p. 76). ConsulteRestricciones de las etiquetas (p. 347) en este tema para conocer las limitaciones de las etiquetas.
5. Para eliminar una etiqueta, elija X a la derecha de la etiqueta.6. Cuando haya terminado de editar o eliminar etiquetas, elija Update sampling rule (Actualizar regla de
muestreo).
Administración de etiquetas en la AWS CLIPuede agregar etiquetas al crear un X-Ray grupo de o una regla de muestreo. También puede utilizar laAWS CLI para crear y administrar etiquetas. Para actualizar las etiquetas de un grupo existente o una reglade muestreo, utilice la AWS X-Ray consola de o las APIs TagResource o UntagResource.
Temas• Agregar etiquetas a un nuevo X-Ray grupo o regla de muestreo (CLI) (p. 349)• Agregar etiquetas a un recurso existente (CLI) (p. 351)• Enumerar etiquetas en un recurso (CLI) (p. 351)• Eliminar etiquetas en un recurso (CLI) (p. 352)
Agregar etiquetas a un nuevo X-Ray grupo o regla demuestreo (CLI)Para añadir etiquetas opcionales a medida que crea un nuevo X-Ray grupo o regla de muestreo, utilice unode los siguientes comandos.
• Para añadir etiquetas a un nuevo grupo de , ejecute el siguiente comando, sustituyendo group_namepor el nombre de su grupo, mydomain.com con el punto de enlace de su servicio, key_name con unaclave de etiqueta y, de forma opcional, value con un valor de etiqueta. Para obtener más informaciónacerca de cómo crear un grupo, consulte Groups (p. 120).
aws xray create-group \ --group-name "group_name" \ --filter-expression "service(\"mydomain.com\") {fault OR error}" \ --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
A continuación se muestra un ejemplo.
349
AWS X-Ray Guía para desarrolladoresAgregar etiquetas a un nuevo X-
Ray grupo o regla de muestreo (CLI)
aws xray create-group \ --group-name "AdminGroup" \ --filter-expression "service(\"mydomain.com\") {fault OR error}" \ --tags [{"Key": "Stage","Value": "Prod"},{"Key": "Department","Value": "QA"}]
• Para añadir etiquetas a una nueva regla de muestreo, ejecute el siguiente comando, sustituyendokey_name con una clave de etiqueta y, de forma opcional, value con un valor de etiqueta. Estecomando especifica los valores en el --sampling-rule parámetro como un archivo JSON.Para obtener más información acerca de cómo crear una regla de muestreo, consulte Reglas demuestreo (p. 117).
aws xray create-sampling-rule \ --cli-input-json file://file_name.json
A continuación se muestra el contenido del archivo JSON file_name.json que se especifica medianteel --cli-input-json parámetro .
{ "SamplingRule": { "RuleName": "rule_name", "RuleARN": "string", "ResourceARN": "string", "Priority": integer, "FixedRate": double, "ReservoirSize": integer, "ServiceName": "string", "ServiceType": "string", "Host": "string", "HTTPMethod": "string", "URLPath": "string", "Version": integer, "Attributes": {"attribute_name": "value","attribute_name": "value"...} } "Tags": [ { "Key":"key_name", "Value":"value" }, { "Key":"key_name", "Value":"value" } ]}
El siguiente comando es un ejemplo.
aws xray create-sampling-rule \ --cli-input-json file://9000-base-scorekeep.json
A continuación se muestra el contenido del 9000-base-scorekeep.json archivo de ejemploespecificado por el --cli-input-json parámetro .
{ "SamplingRule": { "RuleName": "base-scorekeep", "ResourceARN": "*", "Priority": 9000, "FixedRate": 0.1,
350
AWS X-Ray Guía para desarrolladoresAgregar etiquetas a un recurso existente (CLI)
"ReservoirSize": 5, "ServiceName": "Scorekeep", "ServiceType": "*", "Host": "*", "HTTPMethod": "*", "URLPath": "*", "Version": 1 } "Tags": [ { "Key":"Stage", "Value":"Prod" }, { "Key":"Department", "Value":"QA" } ]}
Agregar etiquetas a un recurso existente (CLI)Puede ejecutar el tag-resource comando para añadir etiquetas a un X-Ray grupo de o regla demuestreo existente. Este método puede ser más sencillo que añadir etiquetas ejecutando update-groupo update-sampling-rule.
Para añadir etiquetas a un grupo o una regla de muestreo, ejecute el siguiente comando, sustituyendo elARN por el ARN del recurso y especificando las claves y los valores opcionales de las etiquetas que deseaañadir.
aws xray tag-resource \ --resource-arn "ARN" \ --tag-keys [{"Key":"key_name","Value":"value"}, {"Key":"key_name","Value":"value"}]
A continuación se muestra un ejemplo.
aws xray tag-resource \ --resource-arn "arn:aws:xray:us-east-2:01234567890:group/AdminGroup" \ --tag-keys [{"Key": "Stage","Value": "Prod"},{"Key": "Department","Value": "QA"}]
Enumerar etiquetas en un recurso (CLI)Puede ejecutar el list-tags-for-resource comando para enumerar las etiquetas de un X-Ray grupode o una regla de muestreo.
Para obtener una lista de las etiquetas asociadas a un grupo o una regla de muestreo, ejecute el siguientecomando, sustituyendo el ARN por el ARN del recurso.
aws xray list-tags-for-resource \ --resource-arn "ARN"
A continuación se muestra un ejemplo.
aws xray list-tags-for-resource \ --resource-arn "arn:aws:xray:us-east-2:01234567890:group/AdminGroup"
351
AWS X-Ray Guía para desarrolladoresEliminar etiquetas en un recurso (CLI)
Eliminar etiquetas en un recurso (CLI)Puede ejecutar el untag-resource comando para quitar etiquetas de un X-Ray grupo de o una regla demuestreo de .
Para eliminar etiquetas de un grupo o una regla de muestreo, ejecute el siguiente comando, sustituyendoel ARN por el ARN del recurso y especificando las claves de las etiquetas que desea eliminar.
Solo puede eliminar etiquetas enteras con el untag-resource comando . Para eliminar valores deetiqueta, utilice la X-Ray consola de o elimine etiquetas y añada nuevas etiquetas con las mismas claves,pero diferentes o vacíos.
aws xray untag-resource \ --resource-arn "ARN" \ --tag-keys ["key_name","key_name"]
A continuación se muestra un ejemplo.
aws xray untag-resource \ --resource-arn "arn:aws:xray:us-east-2:01234567890:group/group_name" \ --tag-keys ["Stage","Department"]
Controlar el acceso a X-Ray los recursos de enfunción de las etiquetas
Puede asociar etiquetas a X-Ray grupos de o reglas de muestreo, o pasar etiquetas en una solicitud a X-Ray. Para controlar el acceso en función de etiquetas, debe proporcionar información de las etiquetas enel elemento de condición de una política utilizando las claves de condición xray:ResourceTag/key-name, aws:RequestTag/key-name o aws:TagKeys. Para obtener más información sobre estas clavesde condición, consulte Control del acceso a AWS recursos de mediante etiquetas de recursos.
Para ver un ejemplo de política basada en identidades para limitar el acceso a un recurso en función delas etiquetas de dicho recurso, consulte Administración del acceso a X-Ray grupos y reglas de muestreobasadas en etiquetas (p. 42).
352
AWS X-Ray Guía para desarrolladoresX-Ray SDK for Java
Solución de problemas de AWS X-Ray
En este tema se enumeran errores y problemas comunes que podrían surgir cuando se utiliza la consola,la API o los SDK de X-Ray. Si se encuentra con un problema que no aparezca en esta lista, puede utilizarel botón Feedback (Comentarios) de esta página para notificarlo.
Secciones• X-Ray SDK for Java (p. 353)• X-Ray SDK for Node.js (p. 353)• El demonio de X-Ray (p. 354)
X-Ray SDK for JavaError: Exception in thread "Thread-1" com.amazonaws.xray.exceptions.SegmentNotFoundException:Failed to begin subsegment named 'AmazonSNS': segment cannot be found.
Este error indica que el SDK de X-Ray ha intentado registrar una llamada saliente a AWS, pero no hapodido encontrar un segmento abierto. Esto podría darse en las siguientes situaciones:
• No se ha configurado un filtro de – servlet: el X-Ray SDK crea segmentos para las solicitudes entrantescon un filtro denominado AWSXRayServletFilter. Configure un filtro de servlet (p. 250) parainstrumentar las solicitudes entrantes.
• Está utilizando clientes instrumentados fuera del código – servlet: si utiliza un cliente instrumentadopara realizar llamadas en código de inicio u otro código que no se ejecute en respuesta a una solicitudentrante, debe crear un segmento manualmente. Para ver ejemplos, consulte Instrumentación de códigode inicio (p. 162).
• Está utilizando clientes instrumentados en subprocesos de – trabajo: al crear un nuevo subproceso,la X-Ray grabadora pierde su referencia al segmento abierto. Puede utilizar los getTraceEntitymétodos setTraceEntity y para obtener una referencia al segmento o subsegmento actual (Entity)y volver a pasarlo a la grabadora dentro del subproceso. Consulte Uso de clientes instrumentados ensubprocesos de trabajo (p. 168) para ver un ejemplo.
X-Ray SDK for Node.jsProblema: CLS no funciona con Sequelize
Transfiera el espacio de nombres del X-Ray SDK for Node.js a Sequelize con el método cls.
var AWSXRay = require('aws-xray-sdk');const Sequelize = require('sequelize');Sequelize.cls = AWSXRay.getNamespace();const sequelize = new Sequelize('database', 'username', 'password');
Problema: CLS no funciona con Bluebird
Utilice cls-bluebird para que Bluebird funcione con CLS.
353
AWS X-Ray Guía para desarrolladoresEl demonio de X-Ray
var AWSXRay = require('aws-xray-sdk');var Promise = require('bluebird');var clsBluebird = require('cls-bluebird');clsBluebird(AWSXRay.getNamespace());
El demonio de X-RayProblema: El demonio está utilizando credenciales incorrectas
El demonio utiliza el AWS SDK para cargar las credenciales. Si se emplean varios métodos paraproporcionar las credenciales, se utilizará el método que tenga la máxima prioridad. Para obtener másinformación, consulte Ejecutar el demonio (p. 173).
354
AWS X-Ray Guía para desarrolladores
Historial de revisión de AWS X-RayEn la siguiente tabla se describen los cambios importantes en la documentación para AWS X-Ray. Paraobtener notificaciones sobre las actualizaciones de esta documentación, puede suscribirse a una fuenteRSS.
Última actualización de la documentación:15 de octubre de 2020
update-history-change update-history-description update-history-date
Agregar funcionalidad (p. 355) AWS X-Ray ahora admitenotificaciones relacionadas conconocimientos para AmazonEventBridge. Esto le permiterealizar acciones automáticasen conocimientos medianteEventBridge. Para obtenermás información, consulteNotificaciones de Insights.
October 15, 2020
Se han añadido demoniosdescargables (p. 355)
AWS X-Ray presenta el demoniode compatibilidad con LinuxARM64. Para obtener másinformación, consulte AWS X-Ray daemonbrazil ws.
October 1, 2020
Se añadiófuncionalidad (p. 355)
AWS X-Ray ahora admite laintegración activa con AmazonCloudWatch Synthetics. Estole permite ver detalles sobreun nodo cliente de canary deSynthetics como el tiempo derespuesta y el estado. Tambiénpuede realizar análisis en laconsola de Analytics en funciónde la información de un nodode cliente de valor controladode Synthetics. Para obtenermás información, consulte Depuración de canaries deCloudWatch synthetics medianteX-Ray .
September 24, 2020
Se añadiófuncionalidad (p. 355)
AWS X-Ray ahora admite elrastreo de flujos de trabajo deextremo a extremo para AWSStep Functions. Puede visualizarlos componentes de la máquinade estado, identificar los cuellosde botella de rendimiento ysolucionar los problemas delas solicitudes que generaronun error. Para obtener másinformación, consulte AWS StepFunctions y AWS X-Ray.
September 14, 2020
355
AWS X-Ray Guía para desarrolladores
Se añadiófuncionalidad (p. 355)
AWS X-Ray presenta Insightspara analizar continuamente losdatos de rastreo en su cuentapara identificar problemasemergentes en sus aplicaciones.Insights registra incidentesy realiza un seguimiento delimpacto de los incidentes hastasu resolución. Para obtener másinformación, consulte Uso deconocimientos de en la consolaAWS X-Ray de
September 3, 2020
Se añadiófuncionalidad (p. 355)
AWS X-Ray presenta el agentede instrucción automática deJava, que permite a los clientesrecopilar datos de rastreo sintener que modificar la aplicaciónbasada en Java existente. Ahorapuede rastrear aplicacionesweb Java y basadas en servletcon un cambio de configuraciónmínimo y sin cambios de código.Para obtener más información,consulte Agente de instrucciónAWS X-Ray automática de paraJava.
September 3, 2020
Se añadiófuncionalidad (p. 355)
AWS X-Ray ha añadido unanueva página Groups (Grupos) ala X-Ray consola de para facilitarla creación y administración degrupos de rastros. Para obtenermás información, consulteConfiguración de grupos de en laX-Ray consola de .
August 24, 2020
Se añadiófuncionalidad (p. 355)
AWS X-Ray ahora le permiteañadir etiquetas a grupos yreglas de muestreo. Tambiénpuede controlar el acceso agrupos y reglas de muestreoen función de las etiquetas.Para obtener más información,consulte Etiquetado de reglasy grupos X-Ray de muestreo yAdministración del acceso a X-Ray grupos y reglas de muestreobasadas en etiquetas.
August 24, 2020
356
AWS X-Ray Guía para desarrolladores
Las traducciones son generadas a través de traducción automática. En caso de conflicto entre latraducción y la version original de inglés, prevalecerá la version en inglés.
ccclvii
Recommended
