exp-correlator


Keep track of correlation id through a series of async operations. Either using a handler or an Express middleware. Uses
async_hooks.

Table of contents

- exp-correlator
- Table of contents
- Installation
- Usage
- Async handler
- Express middleware
- Logging with pino
- Making requests with exp-fetch
- Known issues
- Changelog
- License

Installation

``bash
npm install exp-correlator
`

Usage

If an execution is started using either attachCorrelationIdHandler or occurs after the middleware is attached (when
the execution is part of the call chain of a Express request) any call to getId during that execution will return the
same correlation id. Example of use-cases may be to pass a correlation-id onto subsequent requests to other systems or
to be able to group log messages during the same request without passing on a correlation id between each function call.

$3

The async handler will set the correlation id to the supplied or generate a new uuid v4 if not supplied.

`js
const { attachCorrelationIdHandler, getId } = require("exp-correlator");
const logThis = async function (msg) {
const correlationId = getId();
console.log({correlationId, msg});
}
const f = async function () {
...
logThis("epic message");
logThis("epic message2");
...
};

await attachCorrelationIdHandler(f);
`

In the example above all the log messages produced by logThis can be grouped together by the correlation id without having
to pass the correlation id as an argument every time.

$3

The Express middleware will set the correlation id from the correlation-id or x-correlation-id header if available. Otherwise a
new uuid v4 will be generated. The middleware also assigns the correlation-id to the response, matching the header of incoming correlation-id if
it's available.

`js
const { middleware, getId } = require("exp-correlator");
const express = require("express");
const app = express();
const logThis = async function (msg) {
const correlationId = getId();
console.log({correlationId, msg});
}

const callToExternalSystem () {
const correlationId = getId();
await ... // call to an external system setting correlationId as a header
}

app.use(middleware);
app.get("/", (req, res) => {
const correlationId = getId();
await callToExternalSystem();
logThis("epic message");
res.json({ correlationId });
...
});
`

In the example above the middleware set the correlation id based on the incoming header, it will then
be passed on when doing calls to callToExternalSystem and logThis without being explicitly passed.

$3

To add correlationId when logging using pino do the following:

`js
const { getId } = require("exp-correlator");
const pino = require("pino");
const logger = pino({mixin: () => {return { correlationId: getId() };}});
`

In the example above the correct correlation id will be added each time a log function is called when
the express middleware or the async handler is used.

$3

To add a correlation id when fetching using exp-fetch do the
following:

`js
const { getId } = require("exp-correlator");
const fetchBuilder = require("exp-fetch);
const fetch = fetchBuilder({ getCorrelationId: getId }).fetch;
await fetch("http://foo.bar");
`

In the example above the correlation id will be added to the outgoing requests headers as correlation-id.

Known issues

Using bodyParser after using correlation middleware will cause the async local storage to be undefined.
This applies to any middleware that is derived from bodyParser as well (i.e. urlencoded).

`js
const { middleware, getId } = require("exp-correlator");
const express = require("express");
const bodyParser = require("body-parser");
const app = express();
const logThis = async function (msg) {
const correlationId = getId(); // correlationId will be null here
console.log({correlationId, msg});
}

app.use(middleware);

// this won't work, bodyParser is used after correlation middleware for this route
app.post("/", bodyParser.json(), (req, res) => {
const correlationId = getId();
await callToExternalSystem();
logThis("epic message");
res.json({ correlationId });
...
});

// workaround add the correlation middleware after the bodyParser
app.post("/", bodyParser.json(), middleware, (req, res) => {
const correlationId = getId();
await callToExternalSystem();
logThis("epic message");
res.json({ correlationId });
...
});

``

Changelog

Can be found here.

License

Released under the MIT license.