Rastreo de aplicaciones de Node.js
Requisitos de compatibilidad
La última versión del rastreador Node.js es compatible con las versiones de Node.js >=18
. Para ver la lista completa de versiones de Node.js y de compatibilidad de marcos de trabajo de Datadog (incluidas las versiones heredadas y de mantenimiento), consulta la página de requisitos de compatibilidad.
Para empezar
Antes de empezar, asegúrate de haber instalado y configurado el Agent. A continuación, sigue los siguientes pasos para añadir la biblioteca de rastreo de Datadog a tu aplicación Node.js para instrumentarla.
Instalación de la biblioteca de rastreo de Datadog
Para instalar la biblioteca de rastreo de Datadog utilizando npm para Node.js v18 y superiores, ejecuta:
npm install dd-trace --save
Para instalar la biblioteca de rastreo de Datadog (v4. y superiores de dd-trace
) para la versión 16 de Node.js, ejecuta:
npm install dd-trace@latest-node16
Para obtener más información sobre las etiquetas (tags) de distribución y la compatibilidad con las versiones de tiempos de ejecución Node.js de Datadog, consulta la página de requisitos de compatibilidad.
Si estás actualizando desde una versión principal anterior de biblioteca (0., 1., 2., 3. 4. o superiores) a otra versión principal, consulta la guía para migraciones, para evaluar cualquier cambio de última hora.
Para importar e inicializar el rastreador
Importa e inicializa el rastreador ya sea en código o con argumentos de línea de comandos. La biblioteca de rastreo de Node.js debe importarse e inicializarse antes que cualquier otro módulo.
Una vez que hayas completado la configuración, si no estás recibiendo trazas (traces) completas, incluyendo rutas URL faltantes para solicitudes web, o tramos (spans) desconectados o faltantes, confirma que el rastreador ha sido importado e inicializado correctamente. La biblioteca de rastreo que se inicializa en primer lugar es necesaria para que el rastreador corrija correctamente a través de parches todas los bibliotecas requeridas para la instrumentación automática.
Cuando utilices un transpilador como TypeScript, Webpack, Babel u otros, importa e inicializa la biblioteca de rastreo en un archivo externo y luego importa ese archivo como un todo cuando crees tu aplicación.
Opción 1: Añadir el rastreador en el código
JavaScript
// Esta línea debe venir antes de importar cualquier módulo instrumentado.
const tracer = require('dd-trace').init();
TypeScript y bundlers (empaquetadores)
Para TypeScript y bundlers compatibles con la sintaxis EcmaScript Module, inicializa el rastreador en un archivo separado para mantener el orden de carga correcto.
// server.ts
import './tracer'; // debe venir antes de importar cualquier módulo instrumentado.
// tracer.ts
import tracer from 'dd-trace';
tracer.init(); // inicializado en un archivo diferente para evitar el hoisting.
export default tracer;
Si la configuración por defecto es suficiente o si toda la configuración se realiza
a través de variables de entorno, también puedes utilizar dd-trace/init
, que se carga e
inicializa en un solo paso.
Opción 2: Añadir el rastreador con argumentos de línea de comandos
Utiliza la opción --require
de Node.js para cargar e inicializar el rastreador en un solo paso.
node --require dd-trace/init app.js
Nota: Esta estrategia requiere el uso de variables de entorno para todas las configuraciones del rastreador.
Sólo aplicaciones ESM: Importar el cargador
Las aplicaciones EcmaScript Modules (ESM) requieren un argumento de línea de comandos adicional. Ejecuta este comando independientemente de cómo se importa e inicializa el rastreador.
Node.js v20.6 o anteriores
node --loader dd-trace/loader-hook.mjs entrypoint.js
Node.js v20.6 o superiores
node --import dd-trace/register.js entrypoint.js
Agrupación
dd-trace
funciona interceptando las llamadas require()
que una aplicación 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 NPM, como el módulo de base de datos pg
.
Los bundlers rastrean todas las llamadas require()
que una aplicación realiza a los archivos del disco. Sustituye las llamadas require()
por código personalizado y combina todos los JavaScript resultantes en un archivo “empaquetado”. Cuando se carga un módulo incorporado, como require('fs')
, esa llamada puede seguir siendo la misma en el paquete resultante.
Las herramientas APM como dd-trace
dejan de funcionar en este punto. Pueden seguir interceptando las llamadas a módulos incorporados, pero no interceptan las llamadas a bibliotecas de terceros. Esto significa que cuando empaquetas una aplicación dd-trace
utilizando un bundler, es probable que capture información sobre el acceso al disco (a través de fs
) y las solicitudes HTTP salientes (a través de http
), pero que omita las llamadas a bibliotecas de terceros. Por ejemplo:
- Extracción de información entrante de rutas de solicitudes para el marco de trabajo
express
. - Muestra qué consulta se ejecuta para el cliente de base de datos
mysql
.
Una solución común es tratar como “externos” al bundler todos los módulos de terceros que APM necesita para la instrumentación. Con esta configuración, los módulos instrumentados permanecen en el disco y continúan siendo cargados con require()
, mientras que los módulos no instrumentados se empaquetan. Sin embargo, esto resulta en una compilación con muchos archivos extraños y comienza a hacer fracasar el propósito de la agrupación.
Datadog recomienda disponer de complementos de bundler personalizados. Estos complementos son capaces de dar instrucciones al bundler sobre cómo comportarse, inyectar código intermediario e interceptar las llamadas “traducidas” a require()
. Como resultado, se incluyen más paquetes en el archivo empaquetado JavaScript.
Nota: Algunas aplicaciones pueden tener el 100% de los módulos empaquetados, sin embargo los módulos nativos deben permanecer externos al paquete.
Compatibilidad Esbuild
Esta biblioteca proporciona compatibilidad esbuild experimental en forma de un complemento esbuild y requiere al menos Node.js v16.17 o v18.7. Para utilizar el complemento, asegúrate de tener instalado dd-trace@3+
y luego solicita el módulo dd-trace/esbuild
al compilar el paquete.
El siguiente es un ejemplo de cómo se puede utilizar dd-trace
con esbuild:
const ddPlugin = require('dd-trace/esbuild')
const esbuild = require('esbuild')
esbuild.build({
entryPoints: ['app.js'],
bundle: true,
outfile: 'out.js',
plugins: [ddPlugin],
platform: 'node', // permite que los módulos incorporados sean requeridos
target: ['node16'],
external: [
// esbuild no puede empaquetar módulos nativos
'@datadog/native-metrics',
// requerido si utilizas la creación de perfiles
'@datadog/pprof',
// requerido si utilizas funciones de seguridad de Datadog
'@datadog/native-appsec',
'@datadog/native-iast-taint-tracking',
'@datadog/native-iast-rewriter',
// requerido si encuentras errores graphql en el paso de compilación
'graphql/language/visitor',
'graphql/language/printer',
'graphql/utilities'
]
}).catch((err) => {
console.error(err)
process.exit(1)
})
Nota: Debido al uso de módulos nativos en el rastreador, que son código C++ compilado, (normalmente terminan con una extensión de archivo .node
), necesitas añadir entradas a tu lista external
. Actualmente los módulos nativos utilizados en el rastreador Node.js viven dentro de paquetes prefijados @datadog
. Esto también requerirá que envíes un directorio node_modules/
junto con tu aplicación empaquetada. No necesitas enviar tu directorio node_modules/
completo, ya que contendría muchos paquetes innecesarios que deberían estar contenidos en tu bundle.
Para generar un directorio node_modules/
más pequeño con sólo los módulos nativos requeridos, (y sus dependencias), puedes determinar primero las versiones de los paquetes que necesitas, luego crear un directorio temporal para instalarlos y copiar el directorio node_modules/
resultante a partir de aquel. Por ejemplo:
cd path/to/project
npm ls @datadog/native-metrics
# dd-trace@5.4.3-pre ./dd-trace-js
# └── @datadog/native-metrics@2.0.0
$ npm ls @datadog/pprof
# dd-trace@5.4.3-pre ./dd-trace-js
# └── @datadog/pprof@5.0.0
mkdir temp && cd temp
npm init -y
npm install @datadog/native-metrics@2.0.0 @datadog/pprof@5.0.0
cp -R ./node_modules path/to/bundle
En esta etapa, debes ser capaz de desplegar tu paquete (que es el código de la 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 la biblioteca de rastreo para que envíe datos de telemetría sobre el rendimiento de la aplicación, según sea necesario, incluida la configuración del etiquetado unificado de servicios. Para ver más detalles, consulta la configuración de bibliotecas.
Para ver lista de opciones de inicialización, lee los parámetros del rastreador.
Leer más
Additional helpful documentation, links, and articles: