opentelemetry-exporter-datadog

dd-opentelemetry-exporter-js

OpenTelemetry Datadog Trace Exporter

[BETA]

OpenTelemetry Datadog Trace Exporter allows the user to send collected traces to a Datadog Trace-Agent.

Datadog APM, is a distributed tracing system. It is used for monitoring and troubleshooting microservices-based distributed systems.

Prerequisites

The OpenTelemetry Datadog Trace Exporter requires a Datadog Agent that it can send exported traces to. This Agent then forwards those traces to a Datadog API intake endpoint. To get up and running with Datadog in your environment follow the Getting Started Instructions for Installing and configuring a Datadog Agent which the exporter can send traces to. By default, the Agent listens for Traces at localhost:8126.

Installation

To install:

npm install --save opentelemetry-exporter-datadog

Usage

Install the datadog processor and datadog exporter on your application and pass the options. It should contain a service name (default is dd-service).

Furthermore, the agentUrl option (which defaults to http://localhost:8126), can instead be set by the DD_TRACE_AGENT_URL environment variable to reduce in-code config. If both are set, the value set by the option in code is authoritative.

import { NodeTracerProvider } from '@opentelemetry/node';
import { DatadogSpanProcessor, DatadogExporter, DatadogPropagator, DatadogProbabilitySampler } from 'opentelemetry-exporter-datadog';

const provider = new NodeTracerProvider();

const exporterOptions = {
  serviceName: 'my-service', // optional
  agentUrl: 'http://localhost:8126', // optional
  tags: 'example_key:example_value,example_key_two:value_two', // optional
  env: 'production', // optional
  version: '1.0' // optional
}

const exporter = new DatadogExporter(exporterOptions);

//  Now, register the exporter.

provider.addSpanProcessor(new DatadogSpanProcessor(exporter));

// Next, add the Datadog Propagator for distributed tracing

provider.register({
  propagator: new DatadogPropagator(),
  // while datadog suggests the default ALWAYS_ON sampling, for probability sampling,
  // to ensure the appropriate generation of tracing metrics by the datadog-agent,
  // use the `DatadogProbabilitySampler`
  // sampler: new DatadogProbabilitySampler(0.75)  
})

It's recommended to use the DatadogSpanProcessor

• DatadogSpanProcessor: The implementation of SpanProcessor that passes ended complete traces to the configured SpanExporter.

Probability Based Sampling Setup

• By default, the OpenTelemetry tracer will sample and record all spans. This default is the suggest sampling approach to take when exporting to Datadog. However, if you wish to use Probability Based sampling, we recommend that, in order for the Datadog trace-agent to collect trace related metrics effectively, to use the DatadogProbabilitySampler. You can enabled Datadog Probability based sampling with the code snippet below when registering your tracer provider.

provider.register({
  // while datadog suggests the default ALWAYS_ON sampling, for probability sampling,
  // to ensure the appropriate generation of tracing metrics by the datadog-agent,
  // use the `DatadogProbabilitySampler`
  sampler: new DatadogProbabilitySampler(0.75)  
})

Distributed Tracing Context Propagation

• In order to connect your OpenTelemetry Instrumentation Application with other Datadog Instrumented Applications, you must propagate the distribute tracing context with Datadog specific headers. To accomplish this we recommend configuring to use DatadogPropagator. You can enabled Datadog Propagation with the below code snippet below when registering your tracer provider.

provider.register({
  propagator: new DatadogPropagator(),
})

• To propagator multiple header formats to downstream application, use a CompositePropogator. For example, to use both B3 and Datadog formatted distributed tracing headers for Propagation, you can enable a Composite Propagator with the below code snippet when registering your tracer provider.

import { CompositePropagator, B3Propagator } from '@opentelemetry/core';
import { DatadogPropagator } from '@opentelemetry/exporter-datadog';

const provider = new NodeTracerProvider();
// ... provider setup with appropriate exporter

provider.register({
  propagator: new CompositePropagator({
    propagators: [new B3Propagator(), new DatadogPropagator()]
  }),
});

Configuration Options

Configuration Options - Datadog Agent URL

By default the OpenTelemetry Datadog Exporter transmits traces to http://localhost:8126. You can configure the application to send traces to a diffent URL using the following environmennt variables:

• DD_TRACE_AGENT_URL: The <host>:<port: where you Datadog Agent is listening for traces. (e.g. agent-host:8126)

These values can also be overridden at the trace exporter level:

// Configure the datadog trace agent url
new DatadogExporter({agentUrl: 'http://dd-agent:8126'});

Configuration Options - Tagging

You can configure the application to automatically tag your Datadog exported traces, using the following environment variables:

• DD_ENV: Your application environment (e.g. production, staging, etc.)
• DD_SERVICE: Your application's default service name (e.g. billing-api)
• DD_VERSION: Your application version (e.g. 2.5, 202003181415, 1.3-alpha, etc.)
• DD_TAGS: Custom tags in value pairs separated by , (e.g. layer:api,team:intake)
• If DD_ENV, DD_SERVICE or DD_VERSION are set, it will override any respective env/service/version tag defined in DD_TAGS.
• If DD_ENV, DD_SERVICE or DD_VERSION are NOT set, tags defined in DD_TAGS will be used to populate env/service/version respectively.

These values can also be overridden at the trace exporter level:

new DatadogExporter({
  serviceName: 'my-service', // optional
  agentUrl: 'http://localhost:8126' // optional
  tags: 'example_key:example_value,example_key_two:value_two', // optional
  env: 'production', // optional
  version: '1.1' // optional
});

This enables you to set this value on a per application basis, so you can have for example several applications reporting for different environments on the same host.

Tags can also be set directly on individual spans, which will supersede any conflicting tags defined at the application level.

Useful links

• To know more about Datadog, visit: https://www.datadoghq.com
• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For more about OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js
• Learn more about OpenTelemetry on gitter

License

Apache 2.0 - See LICENSE for more information.