Skip to content
Utility functions to help integrate Datadog's APM with a Node.js client
TypeScript JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Datadog APM Helpers

A lightweight wrapper over Datadog's dd-trace library, adding utility functions to make it easier to trace, tag, and search for your functions.


dd-trace offers power and flexibility, but with that comes complexity. This wrapper adds helpers to simplify with:

  • Tracing functions (including async)
  • Tracing class methods
  • Adding tags to the active span
  • Adding tags to the root span (Required to enable filtering and searching in Trace Search and Analytics)
  • Marking a span as an error without throwing


npm install --save @gamechanger/datadog-apm


yarn add @gamechanger/datadog-apm


Your observability code should stay out of the way of your business logic, and should be easy to add and remove. Decorators are a great way to accomplish that.

// Trace a function
async function foo() {}

// Trace *all* methods of a class
class GameChanger {
    public foo() {}
    private bar() {}

// Trace *individual* methods of a class
class GameChanger {
    public foo() {}
    private bar() {}

// The decorator can be configured to override the defaults
class EmailQueue {
    @APM.trace({ serviceName: 'queue', spanName: 'queue.message' })
    public async pop() {}


Adding tags happens throughout the code, and so ideally adds as few lines as possible.

With vanilla dd-trace, you must always check if the active span exists:

const span = tracer.scope().active();

if (span !== null) {
        'http.method': req.method

This wrapper helps clean things up for you:

APM.addTags({ 'http.method': req.method })

Root Span Access

If you're using koa or express, you can use APM.getRootSpanFromContext to get the root span. This can be used to add tags to the root span, which are then accessible in the Trace Search & Analytics screens in datadog.

APM.addTags({ teamId: context.params.teamId }, APM.getRootSpanFromContext(context));

NOTE: This uses undocumented properties and is not guaranteed to work. However, if the underlying dd-trace code were to change, it will safely fall back to adding the tags to the current span rather than the root span.

Marking Spans as Errors

APM.markAsError(new Error('I am not thrown'))


All publishing is done through the CI pipeline.

To trigger a new deploy, simply update the version number using npm version <version> and then push the package.json change and related tag to the repo with git push --follow-tags.

You can’t perform that action at this time.