Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés. # Configuración del SDK de X-Ray para Node.js **nota** Aviso de SDK/Daemon mantenimiento de X-Ray: el 25 de febrero de 2026, el AWS X-Ray SDKs/Daemon entrará en modo de mantenimiento, donde AWS se limitarán las versiones de X-Ray SDK y Daemon para abordar únicamente los problemas de seguridad. Para obtener más información sobre la cronología del soporte, consulte [Cronología de X-Ray SDK y Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar a. OpenTelemetry Para obtener más información sobre la migración a OpenTelemetry, consulte [Migración de una instrumentación de rayos X a una instrumentación](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry 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. **Topics** + [Complementos del servicio](#xray-sdk-nodejs-configuration-plugins) + [Reglas de muestreo](#xray-sdk-nodejs-configuration-sampling) + [Registro](#xray-sdk-nodejs-configuration-logging) + [Dirección del daemon de X-Ray](#xray-sdk-nodejs-configuration-daemon) + [Variables de entorno](#xray-sdk-nodejs-configuration-envvars) ## Complementos del servicio Utilice `plugins` para registrar información sobre el servicio que aloja la aplicación. **Plugins** + Amazon EC2 : `EC2Plugin` agrega el ID de la instancia, la zona de disponibilidad y el grupo de CloudWatch registros. + 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`. **Example 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. Esto indica el tipo de AWS recurso que ejecuta la aplicación. Cuando utilizas 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](xray-console-sampling.md) 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. Esto puede ocurrir si el host no tiene permiso para llamar al muestreo APIs o no puede conectarse al daemon X-Ray, que actúa como proxy TCP 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. 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. **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 } } ``` 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. Sí AWS Lambda, no puedes modificar la frecuencia 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`. **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 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](#xray-sdk-nodejs-configuration-envvars). 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. **Example 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 nombre o IPv4 dirección. **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 especificar ambos 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 `AWS_XRAY_DAEMON_ADDRESS`variable de entorno[Variables de entorno](#xray-sdk-nodejs-configuration-envvars). ## 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 los datos de rastro (UDP) como para el muestreo (TCP). Use esta variable si ha configurado el daemon para que [escuche en un puerto diferente](xray-daemon-configuration.md) 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 ignora cuando AWS\$1XRAY\$1DEBUG\$1MODE se establece en`TRUE`. + `AWS_XRAY_TRACING_NAME`: establezca el nombre de servicio que el SDK utiliza para los segmentos. Anula el nombre de segmento que se ha [establecido en el middleware de Express](xray-sdk-nodejs-middleware.md).