Nouvelles annonces sur les technologies sans serveur et réseau ainsi que sur le RUM (Real-User Monitoring) dévoilées à la conférence Dash ! Nouvelles annonces dévoilées à la conférence Dash !

Tracer des applications Node.js

Installation et démarrage

Si vous avez déjà un compte Datadog, vous trouverez des instructions détaillées dans nos guides intégrés à l'application pour les configurations basées sur un host et basées sur un conteneur.

Pour connaître la définition des termes utilisés dans l’APM, consultez la documentation officielle.

Pour obtenir des détails sur la configuration et l’utilisation de l’API, consultez la documentation relative à l’API de Datadog.

Pour en savoir plus sur les contributions, consultez le guide de développement.

Prise en main

Cette bibliothèque DOIT être importée et initialisée avant tous les autres modules instrumentés. Lors de l'utilisation d'un transcompilateur, vous DEVEZ importer et initialiser la bibliothèque de tracing dans un fichier externe, puis importer ce fichier en entier pendant la compilation de votre application. Cela empêche l'accès aux variables avant leur définition et garantit que la bibliothèque de tracing est importée et initialisée avant l'importation des autres modules instrumentés.

Pour commencer le tracing d’applications Node.js, commencez par installer et configurer l’Agent Datadog, puis consultez la documentation supplémentaire relative au tracing d’applications Docker ou au tracing d’applications Kubernetes.

Installez ensuite la bibliothèque de tracing Datadog avec npm :

npm install --save dd-trace

Enfin, importez et initialisez le traceur :

JavaScript
// Cette ligne doit précéder l'importation des modules instrumentés.
const tracer = require('dd-trace').init()
TypeScript
// server.js
import "./tracer"; // doit précéder l'importation des modules instrumentés.

// tracer.js
import tracer from "dd-trace";
tracer.init(); // initialisé dans un fichier différent pour empêcher l'accès aux variables avant leur définition.
export default tracer;

Consultez les paramètres du traceur pour obtenir la liste des options d’initialisation.

Configuration

Les réglages du traceur peuvent être configurés en tant que paramètre de la méthode init() ou en tant que variables d’environnement.

ConfigurationVariable d’environnementValeur par défautDescription
enabledDD_TRACE_ENABLEDtrueIndique si le traceur doit être activé.
debugDD_TRACE_DEBUGfalseActive la journalisation de debugging dans le traceur.
serviceDD_SERVICE_NAMEnullLe nom du service à utiliser pour ce programme.
urlDD_TRACE_AGENT_URLnullL’URL de l’Agent de trace auquel le traceur transmet des données. Lorsque ce paramètre est défini, il est utilisé à la place du hostname et du port.
hostnameDD_TRACE_AGENT_HOSTNAMElocalhostL’adresse de l’Agent auquel le traceur transmet des données.
portDD_TRACE_AGENT_PORT8126Le port de l’Agent de trace auquel le traceur transmet des données.
dogstatsd.portDD_DOGSTATSD_PORT8125Le port de l’Agent DogStatsD auquel les métriques sont transmises.
envDD_ENVnullDéfinit l’environnement de l’application, p. ex. prod, pre-prod ou encore stage.
logInjectionDD_LOGS_INJECTIONfalseActive l’injection automatique d’ID de trace dans les logs, pour les bibliothèques de journalisation prises en charge.
tagsDD_TAGS{}Définit des tags globaux qui doivent être appliqués à l’ensemble des spans et métriques. Lorsque ce paramètre est transmis en tant que variable d’environnement, son format correspond à key:value, key:value.
sampleRate-1Pourcentage de spans à échantillonner. Valeur flottante comprise entre 0 et 1.
flushInterval-2000Intervalle (en millisecondes) de transmission par le traceur des traces à l’Agent.
runtimeMetricsDD_RUNTIME_METRICS_ENABLEDfalseIndique si l’enregistrement des métriques de runtime doit être activé. Le port 8125 (ou le port configuré avec dogstatsd.port) doit être ouvert sur l’Agent pour le transport UDP.
reportHostnameDD_TRACE_REPORT_HOSTNAMEfalseIndique si le hostname du système doit être transmis pour chaque trace. Lorsque cette option est désactivée, le hostname de l’Agent est transmis à la place.
experimental-{}Les fonctionnalités expérimentales peuvent toutes être activées simultanément à l’aide de la valeur booléenne « true », ou individuellement à l’aide de paires key/value. Contactez l’assistance pour en savoir plus sur les fonctionnalités expérimentales disponibles.
plugins-trueIndique si l’instrumentation automatique des bibliothèques externes à l’aide des plug-ins intégrés doit être activée.
clientTokenDD_CLIENT_TOKENnullToken client pour le tracing sur navigateur. Peut être généré dans Datadog en accédant à Integrations -> APIs.
logLevelDD_TRACE_LOG_LEVELdebugChaîne de caractères indiquant le niveau minimum des logs du traceur à utiliser lorsque la journalisation de debugging est activée. Exemple : error ou debug.

Modifier le hostname de l’Agent

Configurez vos traceurs d’applications de façon à envoyer des traces à un hostname d’Agent personnalisé :

Le module de tracing NodeJS recherche automatiquement les variables ENV DD_AGENT_HOST et DD_TRACE_AGENT_PORT et s’initialise avec celles-ci.

DD_AGENT_HOST=<HOSTNAME> DD_TRACE_AGENT_PORT=<PORT> node server

Pour utiliser un autre protocole (tel qu’UDS), spécifiez l’URL complète en tant que variable ENV DD_TRACE_AGENT_URL unique.

DD_TRACE_AGENT_URL=unix:<CHEMIN_SOCKET> node server

Compatibilité

Les versions >=8 de Node sont prises en charge par cette bibliothèque. Seules les versions paires telles que 8.x et 10.x sont officiellement prises en charge. Les versions impaires telles que 9.x et 11.x devraient fonctionner, mais elles ne sont pas officiellement prises en charge.

Les versions 4 et 6 de Node sont prises en charge par la version 0.13 du traceur dd-trace-js. Cette version sera prise en charge jusqu’au 30 avril 2020, mais aucune fonctionnalité ne sera ajoutée.

Remarque : de manière générale, chaque version de Node est prise en charge par le traceur JS Datadog (corrections de bugs uniquement) jusqu’à 1 an après la fin de son cycle de vie.

Intégrations

L’APM intègre une solution d’instrumentation pour de nombreux frameworks et bibliothèques populaires via un système de plug-ins. Si vous souhaitez la prise en charge d’un module qui ne fait pas partie de la liste ci-dessous, contactez l’assistance pour en faire la demande.

Pour découvrir comment activer et configurer des plug-ins, consultez la documentation de l’API.

Compatibilité des frameworks Web

ModuleVersionsType de prise en chargeRemarques
connect>=2Prise en charge complète
express>=4Prise en charge complètePrend en charge Sails, Loopback et plus encore
fastify>=1Prise en charge complète
graphql>=0.10Prise en charge complètePrend en charge Apollo Server et express-graphql
gRPC>=1.13Prise en charge complète
hapi>=2Prise en charge complète
koa>=2Prise en charge complète
paperplane>=2.3Prise en charge complèteNon pris en charge en mode sans serveur
restify>=3Prise en charge complète

Compatibilité des modules natifs

ModuleType de prise en charge
dnsPrise en charge complète
httpPrise en charge complète
httpsPrise en charge complète
netPrise en charge complète

Compatibilité des datastores

ModuleVersionsType de prise en chargeRemarques
cassandra-driver>=3Prise en charge complète
couchbase^2.4.2Prise en charge complète
elasticsearch>=10Prise en charge complètePrend en charge @elastic/elasticsearch versions >=5
ioredis>=2Prise en charge complète
knex>=0.8Prise en charge complèteCette intégration est uniquement pour la propagation en contexte
memcached>=2.2Prise en charge complète
mongodb-core>=2Prise en charge complètePrend en charge Mongoose
mysql>=2Prise en charge complète
mysql2>=1Prise en charge complète
pg>=4Prise en charge complètePrend en charge pg-native en cas d’utilisation conjointe avec pg
redis>=0.12Prise en charge complète
tedious>=1Prise en charge complètePilote SQL Server pour mssql et sequelize

Compatibilité des workers

ModuleVersionsType de prise en chargeRemarques
amqp10>=3Prise en charge complètePrend en charge les agents AMQP 1.0 (p. ex. ActiveMQ, Apache Qpid)
amqplib>=0.5Prise en charge complètePrend en charge les agents AMQP 0.9 (p. ex. RabbitMQ, Apache Qpid)
generic-pool>=2Prise en charge complète
kafka-nodeDisponible prochainement
rheaDisponible prochainement

Compatibilité des bibliothèques Promise

ModuleVersionsType de prise en charge
bluebird>=2Prise en charge complète
promise>=7Prise en charge complète
promise-js>=0.0.3Prise en charge complète
q>=1Prise en charge complète
when>=3Prise en charge complète

Compatibilité des loggers

ModuleVersionsType de prise en charge
bunyan>=1Prise en charge complète
paperplane>=2.3.2Prise en charge complète
pino>=2Prise en charge complète
winston>=1Prise en charge complète

Pour aller plus loin