README.md

@imqueue/dd-trace

---

Integration package with Datadog tracing for @imqueue

---

What Is This?

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

Install

As easy as:

npm i --save @imqueue/dd-trace

Usage & API

Importing, instantiation and connecting

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

import tracer  from '@imqueue/dd-trace';
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.

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/dd-trace 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/dd-trace';

// ... 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/dd-trace';

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/dd-trace 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

ISC

Happy Coding!