AWS X-Ray SDK para Node.js

X-Ray SDK for Node.js es una biblioteca para aplicaciones web Express y funciones Lambda de Node.js que proporciona clases y métodos para generar y enviar datos de rastreo al daemon X-Ray. Los datos de rastreo incluyen información sobre HTTP las solicitudes entrantes atendidas por la aplicación y las llamadas que la aplicación realiza a los servicios descendentes mediante los AWS SDK clientes o. HTTP

nota

X-Ray SDK for Node.js es un proyecto de código abierto compatible con las versiones 14.x y posteriores de Node.js. Puedes seguir el proyecto y enviar ediciones y solicitudes de cambios en GitHub: github.com/aws/ aws-xray-sdk-node

Si utilizas Express, empieza por añadir el software SDK as middleware a tu servidor de aplicaciones para rastrear las solicitudes entrantes. El middleware crea un segmento para cada solicitud rastreada y lo completa cuando se envía la respuesta. Mientras el segmento esté abierto, puede utilizar los métodos del SDK cliente para añadir información al segmento y crear subsegmentos para rastrear las llamadas posteriores. SDKTambién registra automáticamente las excepciones que la aplicación lanza mientras el segmento está abierto.

En el caso de las funciones de Lambda llamadas por una aplicación o un servicio instrumentados, Lambda lee el encabezado de rastreo y rastrea automáticamente las solicitudes muestreadas. Para otras funciones, puede configurar Lambda con el fin de muestrear y rastrear las solicitudes entrantes. En cualquier caso, Lambda crea el segmento y lo proporciona al X-Ray. SDK

nota

En Lambda, el X-Ray SDK es opcional. Si no lo usa en su función, el mapa de servicio seguirá incluyendo un nodo para el servicio de Lambda y uno para cada función de Lambda. Al añadir elSDK, puede instrumentar el código de función para añadir subsegmentos al segmento de función registrado por Lambda. Para obtener más información, consulte AWS Lambda y AWS X-Ray.

A continuación, utilice X-Ray SDK para Node.js para instrumentar su lugar AWS SDK JavaScript en los clientes de Node.js. Cada vez que realizas una llamada a un canal intermedio Servicio de AWS o a un recurso con un cliente instrumentado, este SDK graba la información sobre la llamada en un subsegmento. Servicios de AWS y los recursos a los que accedes dentro de los servicios aparecen como nodos descendentes en el mapa de rastreo para ayudarte a identificar los errores y los problemas de limitación en las conexiones individuales.

X-Ray SDK for Node.js también proporciona instrumentación para consultas APIs y SQL llamadas posteriores a la HTTP web. Incluya a su HTTP cliente en el método SDK de captura para registrar la información sobre las llamadas salientesHTTP. Para SQL los clientes, usa el método de captura para tu tipo de base de datos.

El middleware aplica reglas de muestreo a las solicitudes entrantes para determinar qué solicitudes se deben rastrear. Puede configurar X-Ray SDK para Node.js para ajustar el comportamiento del muestreo o para registrar información sobre los recursos AWS informáticos en los que se ejecuta la aplicación.

Registre información adicional acerca de las solicitudes y el trabajo que la aplicación realiza en anotaciones y metadatos. Las anotaciones son pares sencillos de clave-valor que se indexan para su uso con expresiones de filtro para poder buscar rastros que contengan datos específicos. Las entradas de metadatos son menos restrictivas y pueden registrar objetos y matrices enteros, es decir, cualquier elemento en el que se pueda serializar. JSON

Anotaciones y metadatos

Las anotaciones y los metadatos son texto arbitrario que se añade a los segmentos con el X-RaySDK. Las anotaciones se indexan para su uso con expresiones de filtro. Los metadatos no están indexados, pero se pueden ver en el segmento sin procesar con la consola X-Ray oAPI. Cualquier persona a la que conceda acceso de lectura a X-Ray puede ver estos datos.

Cuando tenga muchos clientes instrumentados en su código, un único segmento de solicitud puede contener un gran número de subsegmentos, uno para cada llamada realizada con un cliente instrumentado. Puede organizar y agrupar los subsegmentos incluyendo las llamadas del cliente en subsegmentos personalizados. Puede crear un subsegmento personalizado para una función completa o para cualquier sección de código, y registrar los metadatos y las anotaciones en el subsegmento en lugar de escribirlo todo en el segmento principal.

Para obtener documentación de referencia sobre SDK sus clases y métodos, consulte la APIreferencia AWS X-Ray SDK de Node.js.

Requisitos

X-Ray SDK para 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

SDKExtrae estas bibliotecas cuando se instala conNPM.

Para rastrear AWS SDK los clientes, X-Ray SDK for Node.js requiere una versión mínima del AWS SDK for JavaScript de Node.js.

• aws-sdk: 2.7.15

Administración de dependencias

El X-Ray SDK para Node.js está disponible enNPM.

• Paquete: aws-xray-sdk

Para el desarrollo local, instálelo SDK en el directorio de su proyecto con npm.

~/nodejs-xray$ npm install aws-xray-sdk
aws-xray-sdk@3.3.3
  ├─┬ aws-xray-sdk-core@3.3.3
  │ ├── @aws-sdk/service-error-classification@3.15.0
  │ ├── @aws-sdk/types@3.15.0
  │ ├─┬ @types/cls-hooked@4.3.3
  │ │ └── @types/node@15.3.0
  │ ├── atomic-batcher@1.0.2
  │ ├─┬ cls-hooked@4.2.2
  │ │ ├─┬ async-hook-jl@1.7.6
  │ │ │ └── stack-chain@1.3.7
  │ │ └─┬ emitter-listener@1.1.2
  │ │   └── shimmer@1.2.1
  │ └── semver@5.7.1
  ├── aws-xray-sdk-express@3.3.3
  ├── aws-xray-sdk-mysql@3.3.3
  └── aws-xray-sdk-postgres@3.3.3

Utilice la --save opción para guardarla SDK como una dependencia en la de package.json su aplicación.

~/nodejs-xray$ npm install aws-xray-sdk --save
aws-xray-sdk@3.3.3

Si la aplicación tiene dependencias cuyas versiones entran en conflicto con las SDK de los X-Ray, se instalarán ambas versiones para garantizar la compatibilidad. Para obtener más información, consulta la NPMdocumentación oficial sobre la resolución de dependencias.

Ejemplos de Node.js

Trabaje con el archivo Node.js AWS X-Ray SDK para end-to-end ver las solicitudes a medida que pasan por sus aplicaciones de Node.js.

• Node.js aplicación de ejemplo activada GitHub.