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.

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

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.

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.

{
  "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.

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.

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.

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.

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.

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.