Overview

The Node.js integration allows you to collect and monitor your Node.js application logs, traces, and custom metrics.

Setup

Metric collection

The Node.js tracer can send custom metrics to the Datadog Agent in two ways: using an HTTP proxy (default) or using UDP (fallback).

By default, the tracer attempts to send metrics to an HTTP endpoint within the Datadog Agent. This is the preferred and most reliable method, as HTTP is a connection-oriented protocol that ensures delivery. If the Agent’s HTTP endpoint is unavailable, the tracer automatically falls back to sending metrics using UDP to the DogStatsD server on port 8125.

Note: You can’t force the tracer to use UDP if the HTTP endpoint is available.

For example, you can instrument your code to increment a counter for page views:

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

// Increment a counter
tracer.dogstatsd.increment('page.views');

Agent configuration

You must ensure the Agent is configured to accept incoming metrics.

• HTTP (Default): Metric submission over HTTP uses the same endpoint as trace collection. If you have already configured your application for tracing, no additional Agent configuration is needed. The Agent listens for HTTP traffic on port 8126 by default.

• UDP (Fallback): For the UDP fallback to work, you must enable DogStatsD on the Agent. To allow metrics from containers or other hosts, set dogstatsd_non_local_traffic to true.

  DD_USE_DOGSTATSD=true # default
  DD_DOGSTATSD_PORT=8125 # default
  DD_DOGSTATSD_NON_LOCAL_TRAFFIC=true # if expecting external metrics
  

  use_dogstatsd: true # default
  dogstatsd_port: 8125 # default
  dogstatsd_non_local_traffic: true # if expecting external metrics
  

Application configuration

By default, the tracer attempts to connect to the Agent at localhost. To specify a different agent host, use the DD_AGENT_HOST environment variable.

When DD_AGENT_HOST is set, the tracer automatically targets the correct ports for both HTTP and UDP.

# The tracer will attempt to send metrics to http://your-agent-host:8126
# If that fails, it will fall back to UDP on your-agent-host:8125
DD_AGENT_HOST=your-agent-host node app.js

For additional information about the Node.js integration, see the Metrics Submission page.

Trace collection

See the dedicated documentation for instrumenting your Node.js application for sending traces to Datadog.

Log collection

Available for Agent v6.0+

See the dedicated documentation to set up Node.js log collection for forwarding your logs to Datadog.

Profile collection

See the dedicated documentation for enabling the Node.js profiler.

Data Collected

Metrics

Troubleshooting

Need help? Contact Datadog support.

Further Reading

Additional helpful documentation, links, and articles:

How to collect, customize, and centralize Node.js logsBLOG Node.js monitoring with Datadog APM and distributed tracingBLOG