Async Tracer

This is a general purpose async tracer to trace the execution data, timing and relation between async calls etc.

Table of Contents

1. Install
2. Initialize
3. Inject
4. Tags/Logs
5. Remote
6. Exceptions
7. Debug
8. Example Trace

Install

Install with npm:

npm install git://github.com/sahnisarbjit/AsyncTracer.git

Install with yarn:

yarn add git://github.com/sahnisarbjit/AsyncTracer.git

Initialize

To initalize the library, we need to setup a collector first. Whose interface must have write method as the entry point to accept the incoming data. Use following code to initialize:

const { Tracer, NoopCollector } = require('AsyncTracer');

const tracer = new Tracer(NoopCollector);

Please note that NoopCollector is just a blank collector which only do STDOUT writes whenever a data stream is written.

Inject

Inject is the wrapper function whose async calls you want to trace. For example:

tracer.inject('simple.method', () => {
    // Any async code here
});

In the example above, first argument is label you want to give to this trace and second argument is the piece of code you want to trace with this tracer.

Tags/Logs

Tags and logs could be added to any sub-segment using tag & log method available on tracer. The difference is that tag could be used to filter traces inside collector UI. We can add these using the following syntax in the context where we want to tag the data.

// setTimeout is just example
setTimeout(() => {
    tracer
        .tag('cart-items', 5)
        .log('sub-total', '$50');
}, 500);

Remote

If you are dealing with some remote calls in any context. You can mark that segment as remote by using following:

setTimeout(() => {
    tracer
        .markRemote()
        .tag('url', 'https://api.host.com')
        .tag('status', 200);
}, 500);

Exceptions

Exception handling is absolute necessary steps to every piece of software. If you missed thrown exception then tracer won't be able to trace it. You can use tracer as following:

// Normal exception
try {
    throw new Error('Example exception!!');
} catch (e) {
    tracer.error(e);

    // Handling this as per requirements.
}

// Promise rejection
task
    .then(() => {
        res.send('Success!!');
    })
    .catch((error) => {
        tracer.error(error);
        res.send('Failed!!');
    });

Debug

Debugging could be enabled using:

Tracer.debug();

Please note that this is static method not an instance method.

Example Trace

{
    "id": "53b376bd-8f63-408b-aeec-a5de908ce9ed",
    "start_time": 1591556797177,
    "end_time": 1591556797178,
    "children": [
        {
            "id": "f3c86cbd-01a5-436e-8834-509a1f772cc1",
            "parent_id": "53b376bd-8f63-408b-aeec-a5de908ce9ed",
            "type": "TickObject",
            "start_time": 1591556797177,
            "end_time": 1591556797179
        },
        {
            "id": "f4b12c59-5267-41c5-94be-c5f524c774f2",
            "parent_id": "53b376bd-8f63-408b-aeec-a5de908ce9ed",
            "type": "Timeout",
            "start_time": 1591556797178,
            "end_time": 1591556797685,
            "logs": {
                "Author": "admin"
            },
            "stack": {
                "type": "Error",
                "message": "This must be caught!!",
                "stack": [
                    "Error: This must be caught!!",
                    "at Timeout._onTimeout (/Users/sahni/code/personal/AsyncTracer/tests/basic.js:20:19)",
                    "at listOnTimeout (internal/timers.js:531:17)",
                    "at processTimers (internal/timers.js:475:7)"
                ]
            }
        }
    ],
    "tags": {
        "level": 0
    }
}