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',
agentUrl: 'http://localhost:8126',
tags: 'example_key:example_value,example_key_two:value_two',
env: 'production',
version: '1.0'
}
const exporter = new DatadogExporter(exporterOptions);
provider.addSpanProcessor(new DatadogSpanProcessor(exporter));
provider.register({
propagator: new DatadogPropagator(),
})
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({
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.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:
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',
agentUrl: 'http://localhost:8126'
tags: 'example_key:example_value,example_key_two:value_two',
env: 'production',
version: '1.1'
});
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
License
Apache 2.0 - See LICENSE for more information.