nodejs.md

title	Enabling the Node.js Profiler
code_lang	nodejs
type	multi-code-lang
code_lang_weight	50
further_reading	link tag text getting_started/profiler Documentation Getting Started with Profiler link tag text profiler/profile_visualizations Documentation Learn more about available profile visualizations link tag text profiler/profiler_troubleshooting Documentation Fix problems you encounter while using the profiler
aliases	/tracing/profiler/enabling/nodejs/

The profiler is shipped within Datadog tracing libraries. If you are already using APM to collect traces for your application, you can skip installing the library and go directly to enabling the profiler.

Requirements

For a summary of the minimum and recommended runtime and tracer versions across all languages, read Supported Language and Tracer Versions.

The Datadog Profiler requires at least Node.js 18.

Continuous Profiler support is in Preview for some serverless platforms, such as AWS Lambda.

Continuous Profiler support is in Preview for Google Cloud Run.

Installation

To begin profiling applications:

1. Ensure Datadog Agent v6+ is installed and running. Datadog recommends using Datadog Agent v7+.

2. Run npm install --save dd-trace@latest to add a dependency on the dd-trace module which includes the profiler.

3. Enable the profiler using one of the following approaches:

   {{< tabs >}} {{% tab "Environment variables" %}}

export DD_PROFILING_ENABLED=true
export DD_ENV=prod
export DD_SERVICE=my-web-app
export DD_VERSION=1.0.3

Note: If you're already using Datadog APM, you are already calling init and don't need to do so again. If you are not, ensure the tracer and the profiler are loaded together:

node -r dd-trace/init app.js

{{% /tab %}} {{% tab "In code" %}}

const tracer = require('dd-trace').init({
  profiling: true,
  env: 'prod',
  service: 'my-web-app',
  version: '1.0.3'
})

Note: If you're already using Datadog APM, you are already calling init and don't need to do so again. If you are not, ensure the tracer and the profiler are loaded together:

const tracer = require('dd-trace/init')

{{% /tab %}} {{< /tabs >}}

4. A couple of minutes after you start your application, your profiles appear on the APM > Profiler page. If they do not, refer to the Troubleshooting guide.

5. Optional: Set up Source Code Integration to connect your profiling data with your Git repositories.

6. Optional: Upload Source Maps (in Preview.) If you use source maps and you deploy them with your application the profiler will read them and produce mapped locations in profiles. Source maps in .map files as well as inline source maps are both supported. If you want to reduce deployment sizes (typically in serverless environments) you can choose to not deploy source maps and instead upload them to Datadog. You need to use dd-trace version 5.93.0 or newer for uploaded source maps to work, and your deployed source files still must contain the @sourceMappingURL annotation as an indication that they need to be mapped using the uploaded maps.

Not sure what to do next?

The Getting Started with Profiler guide takes a sample service with a performance problem and shows you how to use Continuous Profiler to understand and fix the problem.

Further Reading

{{< partial name="whats-next/whats-next.html" >}}