Configuración del SDK de X-Ray para Node.js

Puede configurar el SDK de X-Ray para Node.js el uso de complementos a fin de incluir información sobre el servicio que sus aplicaciones ejecutan, modificar la conducta predeterminada de muestreo o agregar reglas de muestreo que se aplican a las solicitudes dirigidas a rutas específicas.

Complementos del servicio

Utilice plugins para registrar información sobre el servicio que aloja la aplicación.

Complementos

• Amazon EC2: EC2Plugin añade el ID de instancia, la zona de disponibilidad y el grupo de registros de CloudWatch.

• Elastic Beanstalk: ElasticBeanstalkPlugin añade el nombre de entorno, la etiqueta de versión y el ID de implementación.

• Amazon ECS: ECSPlugin agrega el ID de contenedor.

Para utilizar un complemento, configure el cliente del SDK de X-Ray para Node.js mediante el método config.

ejemplo app.js: complementos

var AWSXRay = require('aws-xray-sdk');
AWSXRay.config([AWSXRay.plugins.EC2Plugin,AWSXRay.plugins.ElasticBeanstalkPlugin]);

El SDK también usa la configuración del complemento para establecer el campo origin en el segmento. Eso indica el tipo de recurso de AWS que ejecuta la aplicación. Cuando utiliza varios complementos, el SDK utiliza el siguiente orden de resolución para determinar el origen: ElasticBeanstalk > EKS > ECS > EC2.

Reglas de muestreo

El SDK utiliza las reglas de muestreo que define el usuario en la consola de X-Ray para determinar qué solicitudes registrar. La regla predeterminada rastrea la primera solicitud cada segundo y el 5 % de las solicitudes adicionales de todos los servicios que envían rastros a X-Ray. Cree reglas adicionales en la consola de X-Ray para personalizar la cantidad de datos registrados para cada una de sus aplicaciones.

El SDK aplica las reglas personalizadas en el orden en que se definen. Si una solicitud coincide con varias reglas personalizadas, el SDK solo aplica la primera regla.

nota

Si el SDK no puede comunicarse con X-Ray para obtener las reglas de muestreo, vuelve a una regla local predeterminada de la primera solicitud cada segundo y del 5 % de las solicitudes adicionales por host. Eso puede ocurrir si el host no tiene permiso para llamar a las API de muestreo o no puede conectarse al daemon de X-Ray, que actúa como proxy TCP para las llamadas a las API realizadas por el SDK.

También puedes configurar el SDK para que cargue las reglas de muestreo desde un documento JSON. El SDK puede usar las reglas locales como respaldo para los casos en que el muestreo de X-Ray no esté disponible, o puede usar las reglas locales exclusivamente.

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

En este ejemplo se define una regla personalizada y una regla predeterminada. La regla personalizada aplica un porcentaje de muestreo del 5 % sin un número mínimo de solicitudes de rastreo para las rutas incluidas bajo /api/move/. La regla predeterminada rastrea la primera solicitud cada segundo y el 10 % de las solicitudes adicionales.

La desventaja de definir las reglas localmente es que el objetivo establecido lo aplica cada instancia de la grabadora de forma independiente, en lugar de ser administrado por el servicio de X-Ray. A medida que se implementan más hosts, el porcentaje establecido se multiplica, lo que dificulta el control de la cantidad de datos registrados.

En AWS Lambda no puede modificar el porcentaje de muestreo. Si un servicio instrumentado llama a su función, Lambda registrará las llamadas que generaron solicitudes muestreadas por ese servicio. Si el rastreo activo está activado y no hay ningún encabezado de rastreo, Lambda toma la decisión de muestreo.

Para configurar reglas de respaldo, indique al SDK de X-Ray para Node.js que cargue reglas de muestreo desde un archivo con setSamplingRules.

ejemplo 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.

ejemplo 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

Para registrar la salida del SDK, llame a AWSXRay.setLogger(logger), donde logger es un objeto que proporciona métodos de registro estándar (warn, info, etc.).

De forma predeterminada, el SDK registrará los mensajes de error en la consola mediante los métodos estándar del objeto de la consola. El nivel de registro del registrador integrado se puede configurar mediante las variables de entorno AWS_XRAY_DEBUG_MODE o AWS_XRAY_LOG_LEVEL. Para obtener una lista de valores de nivel de registro válidos, consulte Variables de entorno.

Si desea proporcionar un formato o destino diferente para los registros, puede proporcionar al SDK su propia implementación de la interfaz del registrador, como se muestra a continuación. Se puede utilizar cualquier objeto que implemente esta interfaz. Eso significa que muchas bibliotecas de registro, por ejemplo, Winston, podrían usarse y pasarse directamente al SDK.

ejemplo app.js: registro

var AWSXRay = require('aws-xray-sdk');

// Create your own logger, or instantiate one using a library.
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 de capturar la salida de estas operaciones.

Dirección del daemon de X-Ray

Si el daemon de X-Ray escucha en un puerto o host que no sea 127.0.0.1:2000, puede configurar el SDK de X-Ray para Node.js con el fin de 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.

ejemplo 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 especificar ambos en la configuración de dirección del demonio.

ejemplo 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 AWS_XRAY_DAEMON_ADDRESSvariable de entornoVariables de entorno.

Variables de entorno

Puede usar variables de entorno para configurar el SDK de X-Ray para Node.js. El SDK admite las siguientes variables.

• AWS_XRAY_CONTEXT_MISSING: establezca esta opción en RUNTIME_ERROR para generar excepciones cuando el código instrumentado intente registrar datos sin que haya ningún segmento abierto.

  Valores válidos

  • RUNTIME_ERROR: lance una excepción de tiempo de ejecución.

  • LOG_ERROR: registre un error y continúe (predeterminado).

  • IGNORE_ERROR: ignore el error y continúe.

  Se pueden producir errores relativos a segmentos o subsegmentos inexistentes al intentar usar un cliente instrumentado en el código de inicio que se ejecuta cuando no hay ninguna solicitud abierta o en el código que inicia un nuevo subproceso.

• AWS_XRAY_DAEMON_ADDRESS: establezca el host y el puerto del oyente del daemon de X-Ray. De forma predeterminada, el SDK utiliza 127.0.0.1:2000 tanto para rastrear datos (UDP) como para el muestreo (TCP). Use esta variable si ha configurado el daemon para que escuche en un puerto diferente o si se ejecuta en un host diferente.

  Formato

  • El mismo puerto: address:port

  • Puertos diferentes: tcp:address:port udp:address:port

• AWS_XRAY_DEBUG_MODE: establezca este valor en TRUE para configurar el SDK de manera que envíe los registros a la consola, a nivel de debug.

• AWS_XRAY_LOG_LEVEL : establezca un nivel de registro para el registrador predeterminado. Los valores válidos son debug, info, warn, error y silent. Este valor se omite cuando AWS_XRAY_DEBUG_MODE se establece en TRUE.

• AWS_XRAY_TRACING_NAME: establezca 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.