El último rastreador de Node.js es compatible con las versiones de Node.js >=18. Para una lista completa de las versiones de Node.js y el soporte de frameworks de Datadog (incluidas las versiones heredadas y de mantenimiento), consulta la página de Requisitos de compatibilidad.
Comenzando
Antes de comenzar, asegúrate de haber instalado y configurado el agente. Luego, completa los siguientes pasos para agregar el SDK de Datadog a tu aplicación Node.js para instrumentarla.
Instala el SDK de Datadog
Para instalar el SDK de Datadog usando npm para Node.js 18+, ejecuta:
npm install dd-trace
Para instalar el SDK de Datadog (versión 4.x de dd-trace) para la versión de Node.js 16 que ha llegado al final de su vida útil, ejecuta:
npm install dd-trace@latest-node16
Para más información sobre las etiquetas de distribución de Datadog y el soporte de versiones de tiempo de ejecución de Node.js, consulta la página de Requisitos de compatibilidad.
Si estás actualizando desde una versión principal anterior de la biblioteca (0.x, 1.x, 2.x, 3.x o 4.x) a otra versión principal, lee la Guía de migración para evaluar cualquier cambio que rompa la compatibilidad.
En entornos sin servidor o al usar Instrumentación de un solo paso, la biblioteca ya está preinstalada, por lo que no es necesario agregarla como una dependencia. En su lugar, agréguela como una dependencia de desarrollo para obtener trazas localmente:
npm install dd-trace -D # instead of `npm install dd-trace`
Instale la API pública de Datadog (opcional)
Este paso solo es necesario al realizar instrumentación personalizada en entornos sin servidor o con Instrumentación de un solo paso. Para otros casos de uso de instrumentación personalizada, es opcional. Para información sobre cuándo usar la API pública de Datadog, consulte Instrumentación personalizada usando la API de Datadog.
npm install dd-trace-api
Luego puede importar dd-trace-api en lugar de dd-trace en cualquier código que realice instrumentación personalizada.
Importar e inicializar el rastreador
Importe e inicialice el rastreador ya sea en el código o con argumentos de línea de comandos. El SDK de Node.js debe ser importado e inicializado antes de cualquier otro módulo.
Con frameworks como Next.js y Nest.js debe proporcionar una variable de entorno o agregar una bandera adicional de Node.js. Consulte Uso de frameworks complejos para más información.
Después de completar la configuración, si no está recibiendo trazas completas, incluyendo rutas URL faltantes para solicitudes web, o tramos desconectados o faltantes, confirme que el SDK ha sido importado e inicializado correctamente. Es necesario que el SDK se inicialice primero para que el SDK pueda parchear correctamente todas las bibliotecas requeridas para la instrumentación automática.
Al utilizar un transpilador como TypeScript, Webpack, Babel u otros, importa e inicializa el SDK en un archivo externo y luego importa ese archivo completo al construir tu aplicación.
Agrega el SDK con argumentos de línea de comandos
Utiliza la opción --require de Node.js para cargar e inicializar el SDK en un solo paso.
node --require dd-trace/init app.js
El enfoque anterior requiere el uso de variables de entorno para toda la configuración del SDK. Si necesitas usar una configuración programática, inicializa dd-trace en un archivo dedicado y requiérelo en su lugar:
Para los casos en que no es posible controlar los argumentos de la CLI, puedes usar una variable de entorno en su lugar:
DD_TRACE_ENABLED es true por defecto, lo que significa que se realiza cierta instrumentación en el momento de la importación, antes de la inicialización. Para deshabilitar completamente la instrumentación, puedes hacer una de las siguientes acciones:
Importa el módulo condicionalmente
Establecer DD_TRACE_ENABLED=false (si, por ejemplo, las importaciones estáticas o de nivel superior de ESM impiden la carga condicional)
Aplicaciones ESM solamente: Importa el cargador
Las aplicaciones de ECMAScript Modules (ESM) requieren un argumento adicional de línea de comandos. Agrega este argumento sin importar cómo se importe e inicialice el SDK:
Node.js < v20.6:--loader dd-trace/loader-hook.mjs
Node.js >= v20.6:--import dd-trace/register.js
Por ejemplo, en Node.js 22, si inicializas el SDK utilizando la opción uno de arriba, lo iniciarías así:
node --import dd-trace/register.js app.js
Esto también se puede combinar con el --require dd-trace/init argumento de línea de comandos:
Existe una forma abreviada para combinar ambos argumentos de línea de comandos en Node.js v20.6 y versiones posteriores:
node --import dd-trace/initialize.mjs app.js
Agrupación
dd-trace funciona interceptando las llamadas require() que una aplicación de Node.js realiza al cargar módulos. Esto incluye módulos que están integrados en Node.js, como el módulo fs para acceder al sistema de archivos, así como módulos instalados desde el registro de NPM, como el módulo de base de datos pg.
Los agrupadores rastrean todas las llamadas require() que una aplicación realiza a archivos en el disco. Reemplaza las llamadas require() con código personalizado y combina todo el JavaScript resultante en un solo archivo “agrupado”. Cuando se carga un módulo integrado, como require('fs'), esa llamada puede permanecer igual en el archivo agrupado resultante.
Las herramientas APM como dd-trace dejan de funcionar en este punto. Pueden continuar interceptando las llamadas para módulos integrados, pero no interceptan llamadas a bibliotecas de terceros. Esto significa que cuando agrupas una aplicación dd-trace con un agrupador, es probable que capture información sobre el acceso al disco (a través de fs) y solicitudes HTTP salientes (a través de http), pero omita llamadas a bibliotecas de terceros. Por ejemplo:
Extrayendo información de la ruta de la solicitud entrante para el marco express.
Mostrando qué consulta se ejecuta para el cliente de base de datos mysql.
Una solución común es tratar todos los módulos de terceros que el APM necesita instrumentar como “externos” al agrupador. Con esta configuración, los módulos instrumentados permanecen en el disco y continúan cargándose con require() mientras que los módulos no instrumentados son agrupados. Sin embargo, esto resulta en una construcción con muchos archivos superfluos y comienza a derrotar el propósito de la agrupación.
Datadog recomienda que tengas complementos de agrupador personalizados. Estos complementos pueden instruir al agrupador sobre cómo comportarse, inyectar código intermedio e interceptar las llamadas “traducidas” require(). Como resultado, se incluyen más paquetes en el archivo JavaScript agrupado.
Nota: Algunas aplicaciones pueden tener el 100% de los módulos agrupados, sin embargo, los módulos nativos aún deben permanecer externos al paquete agrupado.
Agrupando con esbuild
Esta biblioteca proporciona soporte experimental para esbuild en forma de un plugin de esbuild, y requiere al menos Node.js v16.17 o v18.7. Para usar el plugin, asegúrate de tener dd-trace@3+ instalado, y luego requiere el módulo dd-trace/esbuild al construir tu paquete.
Aquí hay un ejemplo de cómo se podría usar dd-trace con esbuild:
constddPlugin=require('dd-trace/esbuild')constesbuild=require('esbuild')esbuild.build({entryPoints:['app.js'],bundle:true,outfile:'out.js',plugins:[ddPlugin],platform:'node',// allows built-in modules to be required
target:['node16'],external:[// required if you use native metrics
'@datadog/native-metrics',// required if you use profiling
'@datadog/pprof',// required if you use Datadog security features
'@datadog/native-appsec','@datadog/native-iast-taint-tracking','@datadog/native-iast-rewriter',]}).catch((err)=>{console.error(err)process.exit(1)})
Agrupando con Next.js
Si estás usando Next.js u otro marco que dependa de webpack para agrupar tu aplicación, agrega una declaración
similar a la de webpack dentro de tu archivo de configuración next.config.js:
/** @type {import('next').NextConfig} */constnextConfig={// ... non-relevant parts omitted, substitute your own config ...
// this custom webpack config is required for Datadog tracing to work
webpack:(config,{buildId,dev,isServer,defaultLoaders,nextRuntime,webpack})=>{constexternals=[// required if you use native metrics
'@datadog/native-metrics',// required if you use profiling
'@datadog/pprof',// required if you use Datadog security features
'@datadog/native-appsec','@datadog/native-iast-taint-tracking','@datadog/native-iast-rewriter',];config.externals.push(...externals);returnconfig;},};exportdefaultnextConfig;
Características no soportadas de Datadog
Las siguientes características están desactivadas por defecto en el rastreador de Node.js. No soportan agrupamiento y no pueden ser utilizadas si tu aplicación está agrupada.
APM: Dynamic Instrumentation
Observaciones generales sobre agrupamiento
Nota: Debido al uso de módulos nativos en el SDK, que son código C++ compilado, (generalmente terminando con una extensión de archivo .node), necesitas agregar entradas a tu lista external. Actualmente, los módulos nativos utilizados en el rastreador de Node.js viven dentro de paquetes con prefijo @datadog. Esto también requerirá que envíes un directorio node_modules/ junto a tu aplicación agrupada. No necesitas enviar todo tu directorio node_modules/ ya que contendría muchos paquetes superfluos que deberían estar contenidos en tu paquete.
Para generar un directorio node_modules/ más pequeño con solo los módulos nativos requeridos, (y sus dependencias) primero puedes determinar las versiones de los paquetes que necesitas, luego crear un directorio temporal para instalarlos, y copiar el directorio node_modules/ resultante desde allí. Por ejemplo:
Nota: En el caso de Next.js, el path/to/bundle suele ser el directorio .next/standalone de tu aplicación.
En esta etapa deberías poder desplegar tu paquete, (que es tu código de aplicación y la mayoría de tus dependencias), con el directorio node_modules/, que contiene los módulos nativos y sus dependencias.
Configuración
Si es necesario, configura el SDK para enviar datos de telemetría de rendimiento de la aplicación según lo requieras, incluyendo la configuración de Unified Service Tagging. Lea Configuración de la Biblioteca para más detalles.
Lea tracer settings para una lista de opciones de inicialización.
