@commercetools/express-request-correlator
v3.0.2
Published
Express middleware to help tracing correlation IDs
Downloads
1,348
Readme
❯ Why another middleware for express to work with correlation ids?
This packages is a combination of observations and experiences we have had with other middlewares upon whose ideas we build:
- 🎨 Customized correlation ids: sometimes correlation ids need customization. For instance adding prefix based on the incoming request's origin.
- 🍕 Forwarding correlation ids: oftentimes an incoming correlation id needs to be forwarded as a header to another request (e.g. a
fetch
call). - 🏄🏻 Opting out of correlation ids: cases exist where a correlation id can or should not be generated while the fact should be logged
- 👌🏼 Inspecting correlation ids: the correlation id of a request should be easy to extract without knowing the specific header it is passed under
❯ Installation
Depending on the preferred package manager:
yarn add @commercetools/express-request-correlator
or
npm i @commercetools/express-request-correlator --save
❯ Concepts
A correlation id, can be referred to as a unique identifier that is attached to requests that allow grouping them as a transaction or event chain. In the case of multiple microservices it is used to correlate an incoming request to other resulting requests to other services. As a result a correlation ids should be passed on when found on an incoming request. If not found they should be generated early to have a correlatable request/transaction chain as soon as possible. Ultimately, this helps enabling a concept called distributed tracing in a distributed systems by for instance graphing a sequence diagram of multiple requests across various services.
Usually correlation ids are passed as a header. The specific name of that header differs. Often X-Correlation-Id
is used. Generally multiple services should agree on a shared name and location (e.g. header) of the id. However, it is possible that service A
makes a request with a correlation id named (X-Request-Id
) to service B
which forwards it as X-Correlation-Id
.
❯ Documentation
The express-request-correlator
comes with a couple of options it can be configured with:
headerName
: the name of the header on which a new correlation id will be set on. Defaults toX-Correlation-Id
.generateId
: a function called whenever an incoming request does not have a correlation id. Receives therequest
within its options argument.
An example configuration would be:
import { createRequestCorrelatorMiddleware } from '@commercetools/express-request-correlator';
app.use(createRequestCorrelatorMiddleware());
- The middleware adds a correlation id to each response as a header for debugging
- The previously received id is forwarded/used or a new id is generated
- The middleware itself exposes a property called
correlator
(more below) onto each incoming request- This object allows receiving the correlation id in other parts of the request chain
Configuring the middleware on your express application exposes a correlator
property on each request. See type TRequestCorrelator
.
- If for instance you need to retrieve the current request's correlation id invoke
request.correlator.getCorrelationId()
- If you want to forward the correlation id to another request's headers run
request.correlator.forwardCorrelationId({ headers })
- This will mutate the passed in headers to contain the previous request's correlation id
Note, that getCorrelationId
and forwardCorrelationId
both accept a object with configuration:
{
ifNotDefined: () => TCorrelationId;
}
Whenever ifNotDefined
is passed it can be used as a last resort to generate a new correlation id given the request does not already have one. Another use case is logging. Whenever ifNotDefined
is not passed the "globally" configured generate
function will be used if no correlation id is present on the request.
❯ Testing
In case you want to create a test correlator you can use the createRequestCorrelatorMock
function on the testUtils
object. It will create a mocked correlator with the same API as the actual correlator.
import { createRequestCorrelatorMock } from '@commercetools/express-request-correlator/test-utils';
createRequestCorrelatorMock();