Overview

There are a few reasons to manually instrument your applications with the OpenTelemetry API:

• You are not using Datadog supported library instrumentation.
• You want to extend the ddtrace library’s functionality.
• You need finer control over instrumenting your applications.

The ddtrace library provides several techniques to help you achieve these goals. The following sections demonstrate how to use the OpenTelemetry API for custom instrumentation to use with Datadog.

Setup

To configure OpenTelemetry to use the Datadog trace provider:

1. Add your desired manual OpenTelemetry instrumentation to your Node.js code following the OpenTelemetry Node.js Manual Instrumentation documentation. Note: Where those instructions indicate that your code should call the OpenTelemetry SDK, call the Datadog tracing library instead.

2. Add the dd-trace module to your package.json:

   npm install dd-trace
   

3. Initialize the dd-trace module in your application:

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

4. Get TracerProvider from tracer:

   const { TracerProvider } = tracer
   

5. Construct and register a TracerProvider:

   const provider = new TracerProvider()
   provider.register()
   

6. Import the OpenTelemetry API and create an OpenTelemetry tracer instance:

   const ot = require('@opentelemetry/api')
   const otelTracer = ot.trace.getTracer(
     'my-service'
   )
   

7. Run your application.

Datadog combines these OpenTelemetry spans with other Datadog APM spans into a single trace of your application. It also supports integration instrumentation and OpenTelemetry automatic instrumentation.

Adding span tags

Add custom attributes to your spans to provide additional context:

function processData(i, param1, param2) {
  return tracer.startActiveSpan(`processData:${i}`, (span) => {
    const result = someOperation(param1, param2);

    // Add an attribute to the span
    span.setAttribute('app.processedData', result.toString());
    span.end();
    return result;
    });
}

Creating spans

To create a new span and properly close it, use the startActiveSpan method:

function performTask(iterations, param1, param2) {
  // Create a span. A span must be closed.
  return tracer.startActiveSpan('performTask', (span) => {
    const results = [];
    for (let i = 0; i < iterations; i++) {
      results.push(processData(i, param1, param2));
    }
    // Be sure to end the span!
    span.end();
    return results;
  });
}

Adding span events

Minimum SDK version: 5.17.0 & 4.41.0.

You can add span events using the addEvent API. This method requires a name parameter and optionally accepts attributes and timestamp parameters. The method creates a new span event with the specified properties and associates it with the corresponding span.

• Name [required]: A string representing the event’s name.
• Attributes [optional]: Zero or more key-value pairs with the following properties:
  • The key must be a non-empty string.
  • The value can be either:
    • A primitive type: string, Boolean, or number.
    • A homogeneous array of primitive type values (for example, an array of strings).
  • Nested arrays and arrays containing elements of different data types are not allowed.
• Timestamp [optional]: A UNIX timestamp representing the event’s occurrence time, expects a TimeInput object.

The following examples demonstrate different ways to add events to a span:

span.addEvent('Event With No Attributes')
span.addEvent('Event With Some Attributes', {"int_val": 1, "string_val": "two", "int_array": [3, 4], "string_array": ["5", "6"], "bool_array": [true, false]})

Read the OpenTelemetry specification for more information.

Recording exceptions

To record exceptions, use the recordException API. This method requires an exception parameter and optionally accepts a UNIX timestamp parameter. It creates a new span event that includes standardized exception attributes and associates it with the corresponding span.

The following examples demonstrate different ways to record exceptions:

span.recordException(new TestError())

Read the OpenTelemetry specification for more information.

Filtering requests

In some cases, you may want to exclude certain requests from being instrumented, such as health checks or synthetic traffic. You can use the blocklist or allowlist option on the http plugin to ignore these requests.

To exclude requests at the application level, add the following after initializing the tracer:

// at the top of the entry point right after tracer.init()
tracer.use('http', {
  blocklist: ['/health', '/ping']
})

You can also split the configuration between client and server if needed:

tracer.use('http', {
  server: {
    blocklist: ['/ping']
  }
})

Additionally, you can exclude traces based on their resource name to prevent the Agent from sending them to Datadog. For more information on security and fine-tuning Agent configurations, read the Security or Ignoring Unwanted Resources.

Further Reading

Additional helpful documentation, links, and articles:

Explore your services, resources, and tracesDOCUMENTATION Interoperability of OpenTelemetry API and Datadog instrumented tracesDOCUMENTATION