What Is This?

This library provides a clean way to integrate @imqueue/rpc with Datadog tracing.

Renamed

This package was called @imqueue/dd-trace up to and including 3.1.0. The old name is deprecated on npm and receives no further releases; there is no compatibility shim. To migrate, change the dependency and every import specifier.

Nothing Datadog sees changed: the integration is still tracer.use('imq', …), spans are still imq.request and imq.response, the component tag is still imq, and DD_TRACE_IMQ_ENABLED still switches it off. Your dashboards and monitors keep working untouched.

Do not install both packages at once — they patch the same @imqueue/rpc option singletons, so only one set of hooks can be live.

@imqueue/datadog is an unofficial community integration. It is not published by or affiliated with Datadog, Inc.; dd-trace below refers to Datadog's own tracer, which this package wraps.

Install

As easy as:

npm i --save @imqueue/datadog

This package is an ES module, as is @imqueue/rpc from version 3 on, so it is imported and not required. It needs @imqueue/rpc 3.x and dd-trace 6.x.

Usage & API

Importing, instantiation and connecting

At the top of your entry file (service or client):

import tracer  from '@imqueue/datadog';
tracer.init();
export default tracer;

This does not differ of original dd-trace and exposes the whole functionality from it. To learn more about dd-trace API and features, follow this link.

Importing this package installs the tracing hooks, and init() enables the imq integration. Both halves of a call are traced: imq.request on the calling side, imq.response on the handling side, and the two are linked into one trace through the request metadata. Every client and service created after init() is traced, with no change to application code.

Either half can be switched off, and any dd-trace plugin option applies to both:

tracer.use('imq', { client: false });     // trace incoming calls only
tracer.use('imq', { service: 'my-api' }); // report both halves as `my-api`

Tracing Redis

Redis is traced by dd-trace's own Redis integration. Earlier releases of this package replaced that integration to tag the @imqueue broker's connections with a service.name of imq-broker-redis; it targeted internals dd-trace no longer has, and since it replaced the built-in one, Redis ended up not being traced at all. It is gone — Redis spans now come from dd-trace itself, without that tag.

Extended API

This module also provides possibility to disable Datadog self-traces (enabled by default as standard dd-trace behavior), using environment configuration variable:

export DISABLE_DD_SELF_TRACES=1

This option will disable datadog agent to trace it's own HTTP calls about traces, but still keeping http/https requests to other domains to be traced.

Withing the package @imqueue/datadog provides also some valuable functions, giving the ability to instrument and send traces manually inside your code.

For example, if you need to trace some specific block of code, do it as:

import { trace, traceEnd } from '@imqueue/datadog';

// ... whenever you want to trace a block of code do as:

trace('block-of-code-trace-name');

// ... code comes here

traceEnd('block-of-code-trace-name');

Please, note that trace name given to trace() function must be unique in your code or it will produce exception.

There is also a way to decorate any non-exposed service or client methods, using @traced() decorator factory.

For example:

import { traced } from '@imqueue/datadog';

class MySpecificClassOrService {

    @traced()
    private doSomething() {
        console.log('Something...');
    }

    @traced()
    protected doAnotherThing() {
        console.log('Another thing!');
    }

    @traced()
    public doCoolStuff() {
        this.doHidden();
        console.log('Cool stuff!');
    }
    
    private doHidden() {
        console.log('Hidden stuff!');
    }
}

With this example, only doSomething, doAnotherThing and doCoolStuff methods will be traced, but doHidden remain un-traced.

Please, note, that every method on client and server, which are decorated with @expose will be automatically traced if @imqueue/datadog was set-up and initialized (and enabled via DD trace env config). Plugin name for DD trace config is imq.

Contributing

Any contributions are greatly appreciated. Feel free to fork, propose PRs, open issues, do whatever you think may be helpful to this project. PRs which passes all tests and do not brake tslint rules are first-class candidates to be accepted!

License

This project is licensed under the GNU General Public License v3.0. See the LICENSE

Happy Coding!