The NodeJS Tracer officially supports versions >=8. Only even versions like 8.x and 10.x are officially supported. Odd versions like 9.x and 11.x should work but are not officially supported. For a full list of supported libraries, visit the Compatibility Requirements page.
To add the Datadog tracing library to your Node.js applications, follow these steps:
npm install dd-trace --save
Import and initialize the tracer either in code or via command line arguments. The Node.js tracing library needs to be imported and initialized before any other module.
Once you have completed setup, if you are not receiving complete traces, including missing URL routes for web requests, or disconnected or missing spans, confirm step 2 has been correctly done. The tracing library being initialized first is necessary for the tracer to properly patch all of the required libraries for automatic instrumentation.
When using a transpiler such as TypeScript, Webpack, Babel, or others, import and initialize the tracer library in an external file and then import that file as a whole when building your application.
Add any desired configuration to the tracer, such as service, env, and version for Unified Service Tagging.
// This line must come before importing any instrumented module.
const tracer = require('dd-trace').init();
For TypeScript and bundlers that support EcmaScript Module syntax, initialize the tracer in a separate file in order to maintain correct load order.
// server.ts
import './tracer'; // must come before importing any instrumented module.
// tracer.ts
import tracer from 'dd-trace';
tracer.init(); // initialized in a different file to avoid hoisting.
export default tracer;
If the default config is sufficient, or all configuration is done
via environment variables, you can also use dd-trace/init, which loads and
initializes in one step.
import `dd-trace/init`;
Use the --require option to Node.js to load and initialize the tracer in one
step.
node --require dd-trace/init app.js
Note: This approach requires using environment variables for all configuration of the tracer.
Install and configure the Datadog Agent to receive traces from your now instrumented application. By default the Datadog Agent is enabled in your datadog.yaml file under apm_enabled: true and listens for trace traffic at localhost:8126. For containerized environments, follow the links below to enable trace collection within the Datadog Agent.
Set apm_non_local_traffic: true in your main datadog.yaml configuration file
See the specific setup instructions to ensure that the Agent is configured to receive traces in a containerized environment:
localhost:8126 by default. If this is not the correct host and port change it by setting the below env variables:DD_AGENT_HOST and DD_TRACE_AGENT_PORT.
DD_AGENT_HOST=<HOSTNAME> DD_TRACE_AGENT_PORT=<PORT> node server
To use a different protocol such as UDS, specify the entire URL as a single ENV variable DD_TRACE_AGENT_URL.
DD_TRACE_AGENT_URL=unix:<SOCKET_PATH> node server
To set up Datadog APM in AWS Lambda, see the Tracing Serverless Functions documentation.
Tracing is available for a number of other environments, such as Heroku, Cloud Foundry, AWS Elastic Beanstalk, and Azure App Services Extension.
For other environments, please refer to the Integrations documentation for that environment and contact support if you are encountering any setup issues.
See the tracer settings for the list of initialization options.
Tracer settings can be configured as the following parameters to the init() method, or as environment variables.
envDD_ENVnullprod, pre-prod, stage, etc. Available for versions 0.20+serviceDD_SERVICEnullversionDD_VERSIONnulltagsDD_TAGS{}key:value,key:value. When setting this programmatically: tracer.init({ tags: { foo: 'bar' } }) Available for versions 0.20+It is recommended that you use DD_ENV, DD_SERVICE, and DD_VERSION to set env, service, and version for your services. Review the Unified Service Tagging documentation for recommendations on how to configure these environment variables.
enabledDD_TRACE_ENABLEDtruedebugDD_TRACE_DEBUGfalseurlDD_TRACE_AGENT_URLnullapm_config.receiver_socket in your datadog.yaml file, or the DD_APM_RECEIVER_SOCKET environment variable.hostnameDD_TRACE_AGENT_HOSTNAMElocalhostportDD_TRACE_AGENT_PORT8126dogstatsd.portDD_DOGSTATSD_PORT8125logInjectionDD_LOGS_INJECTIONfalsesampleRate10 and 1.flushInterval2000runtimeMetricsDD_RUNTIME_METRICS_ENABLEDfalse8125 (or configured with dogstatsd.port) must be opened on the Agent for UDP.experimental{}pluginstrueDD_TRACE_DISABLED_PLUGINSDD_TRACE_DISABLED_PLUGINS=express,dns.logLevelDD_TRACE_LOG_LEVELdebugerror, debug.Additional helpful documentation, links, and articles:
