opentelemetry-exporter-datadog
    TypeScript icon, indicating that this package has built-in type declarations

    0.2.0 • Public • Published

    dd-opentelemetry-exporter-js

    OpenTelemetry Datadog Trace Exporter

    [BETA]

    Apache License

    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

    License

    Apache 2.0 - See LICENSE for more information.

    Install

    npm i opentelemetry-exporter-datadog

    DownloadsWeekly Downloads

    861

    Version

    0.2.0

    License

    Apache-2.0

    Unpacked Size

    67.6 kB

    Total Files

    23

    Last publish

    Collaborators

    • datadog