dd-trace: Datadog APM Tracer for Node.js

Common errors

• Error: dd-trace requires Node.js >=18

  cause Attempting to run dd-trace v5 on an unsupported Node.js version.
  fix Upgrade Node.js to version 18 or higher. Alternatively, if upgrading Node.js is not possible, install an older, compatible major version of `dd-trace` (e.g., `npm install dd-trace@4` for Node.js >=16).

• [dd-trace] No agent could be found. Traces will be dropped.

  cause The Datadog Agent is not running, is not accessible at the configured host/port, or firewall rules are blocking communication.
  fix Start the Datadog Agent. Ensure `DD_AGENT_HOST` and `DD_AGENT_PORT` environment variables are correctly set, pointing to the agent's location. Verify network connectivity and firewall rules between your application and the agent.

• TypeError: Cannot read properties of undefined (reading 'startSpan')

  cause `tracer.init()` was not called before attempting to use tracing methods, or the `tracer` object was not correctly imported/referenced.
  fix Ensure `tracer.init()` is called once at the very beginning of your application's entry point, preferably before any other modules are loaded, and that the `tracer` object is properly imported and available where `startSpan` is invoked.

Warnings

• breaking Older `dd-trace` major versions (v1, v2, v3, v4) are End-of-Life (EOL). Continuing to use these versions means no new features, bug fixes, or critical security updates.
  Fix: Upgrade to the latest `v5` release line to ensure continued support and access to the latest features. Review the migration guide for any breaking changes between major versions.
• breaking `dd-trace` v5 requires Node.js version 18 or higher. Using it with older Node.js versions will result in immediate startup errors or unpredictable runtime behavior due to reliance on modern Node.js APIs.
  Fix: Ensure your application environment uses Node.js version 18 or newer. If you must use an older Node.js version, you will need to install a compatible EOL version of `dd-trace` (e.g., v4 for Node.js >=16, v3 for Node.js >=14).
• gotcha The `dd-trace` library critically depends on a running and accessible Datadog Agent to send traces. If the agent is not available at the configured host and port, traces will be buffered for a short period and then dropped, leading to missing APM data.
  Fix: Verify that the Datadog Agent is running and network accessible from your application. Configure `DD_AGENT_HOST` and `DD_AGENT_PORT` environment variables if the agent is not on `localhost:8126`.
• gotcha Careless or excessive manual instrumentation, especially in performance-critical code paths, can introduce noticeable overhead. Similarly, enabling `debug: true` or very verbose logging in production environments can severely impact performance.
  Fix: Profile your application to identify performance bottlenecks before and after adding manual instrumentation. Enable debug logging only during development or for targeted troubleshooting, and avoid overly granular manual spans in high-throughput loops.
• gotcha Automatic instrumentation may conflict with other APM agents or custom module patching, leading to unexpected behavior or incomplete traces. This is particularly true in environments with multiple observability tools.
  Fix: If conflicts arise, try disabling specific plugins in `dd-trace.init({ plugins: false })` or using `DD_TRACE_DISABLED_PLUGINS` environment variables. Consult the Datadog documentation for advanced plugin configuration and troubleshooting.

Install

• npm install dd-trace npm
• yarn add dd-trace yarn
• pnpm add dd-trace pnpm

Imports

• tracer.init
  wrong:

  const tracer = require('dd-trace');
  // Forget to call .init()

  correct:

  import tracer from 'dd-trace';
  tracer.init();

  The tracer must be initialized once at the application's entry point before any other modules are imported to ensure proper automatic instrumentation. For ESM, use `import tracer from 'dd-trace';`.
• tracer.startSpan
  wrong:

  import { startSpan } from 'dd-trace';

  correct:

  import tracer from 'dd-trace';
  const span = tracer.startSpan('my.operation');

  Manual span creation methods are accessed directly from the initialized `tracer` instance, not as named exports from the package root. Type imports for `Span` or `SpanOptions` are separate.
• Span
  wrong:

  import { Span } from 'dd-trace';

  correct:

  import type { Span, SpanOptions } from 'dd-trace';

  Types like `Span` or `SpanOptions` should be imported using `import type` for TypeScript projects to prevent runtime bundling issues and clearly distinguish them from runtime values.

Quickstart

This quickstart initializes the Datadog tracer, sets up a basic Express.js server, and demonstrates both automatic (Express request) and manual (`custom.db.query`) span creation with custom tags and error handling. It highlights the importance of `tracer.init()` and provides guidance on checking the Datadog Agent connectivity.

import tracer from 'dd-trace';
import express from 'express';

// Initialize the Datadog tracer early in your application lifecycle.
// Configuration can also be done via environment variables (DD_SERVICE, DD_ENV, DD_VERSION).
tracer.init({
  service: process.env.DD_SERVICE || 'my-node-app',
  env: process.env.DD_ENV || 'development',
  version: process.env.DD_VERSION || '1.0.0',
  logInjection: true,
  debug: false // Set to true for verbose logging
});

const app = express();
const port = process.env.PORT || 3000;

app.get('/', async (req, res) => {
  // Automatic instrumentation will create a span for the Express request.
  // We can also create a custom span manually within it.
  const customSpan = tracer.startSpan('custom.db.query', {
    tags: { 'db.name': 'users_db', 'db.statement': 'SELECT * FROM users' }
  });

  try {
    await new Promise(resolve => setTimeout(resolve, 100)); // Simulate async DB call
    customSpan.addTags({ 'db.row_count': 5, 'http.status_code': 200 });
    res.send('Data retrieved successfully via Datadog Tracing!');
  } catch (error) {
    customSpan.setTag('error', true);
    customSpan.log({ 'event': 'error', 'error.message': error.message });
    res.status(500).send('Error during data retrieval!');
  } finally {
    customSpan.finish();
  }
});

app.listen(port, () => {
  console.log(`Server listening on port ${port}`);
  console.log(`Datadog Tracer initialized for service: ${tracer.dogstatsd.service}`);
  console.log(`Ensure a Datadog Agent is running and accessible at DD_AGENT_HOST:${process.env.DD_AGENT_PORT || 8126}`);
});