# @commercetools/express-request-correlator
> Express middleware to help tracing correlation IDs
Latest version **4.0.0** (published 2025-12-18) · MIT license · 0 weekly downloads
## Install
```sh
npm install @commercetools/express-request-correlator
pnpm add @commercetools/express-request-correlator
yarn add @commercetools/express-request-correlator
bun add @commercetools/express-request-correlator
```
## Health
**Score 70/100 (B)** — status: stable.
Positive: has types; esm support; no vulnerabilities; has provenance; high maintenance score; high quality score.
Warnings: low downloads.
## Facts
| | |
|---|---|
| Version | 4.0.0 |
| Published | 2025-12-18 |
| First published | 2019-11-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=24 |
| Dependencies | 5 |
| Unpacked size | 27.1 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 4 |
| Author | Tobias Deekens |
| Maintainers | commercetools-admin, emmenko, hajoeichler, tdeekens, jenschude, chukwuemeka |
| Keywords | express, devops, logs, tracing |
## Links
- npm: https://www.npmjs.com/package/@commercetools/express-request-correlator
- Repository: https://github.com/commercetools/express-request-correlator
- Homepage: https://github.com/commercetools/express-request-correlator#readme
- Issues: https://github.com/commercetools/express-request-correlator/issues
- npm.io page: https://npm.io/package/@commercetools/express-request-correlator
## Dependencies (5)
- [uuid](https://npm.io/package/uuid.md) 9.0.1
- [@types/uuid](https://npm.io/package/@types/uuid.md) 9.0.8
- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.22.5
- [@types/express](https://npm.io/package/@types/express.md) 5.0.6
- [@babel/runtime-corejs3](https://npm.io/package/@babel/runtime-corejs3.md) ^7.22.5
## Alternatives
- [cli-color](https://npm.io/package/cli-color.md) — 3.4M weekly downloads
- [log](https://npm.io/package/log.md) — 1.3M weekly downloads
- [logstash-client](https://npm.io/package/logstash-client.md) — 4.5K weekly downloads
- [@nocobase/plugin-logger](https://npm.io/package/@nocobase/plugin-logger.md) — 2.0K weekly downloads
- [child-process-debug](https://npm.io/package/child-process-debug.md) — 695 weekly downloads
## Recent versions
- 4.0.0 (latest) — 2025-12-18
- 0.0.0-canary-20251218120608 (canary) — 2025-12-18
- 1.0.0-beta.3 (next) — 2019-11-29
- 3.0.3 — 2025-12-15
- 3.0.2 — 2024-06-17
- 0.0.0-canary-20240617072046 — 2024-06-17
- 0.0.0-canary-20240617072026 — 2024-06-17
- 0.0.0-canary-20240614075255 — 2024-06-14
- 0.0.0-canary-20240614075230 — 2024-06-14
- 0.0.0-canary-20240614075206 — 2024-06-14
- 0.0.0-canary-20240614074935 — 2024-06-14
- 0.0.0-canary-20240614074838 — 2024-06-14
- 0.0.0-canary-20240614074525 — 2024-06-14
- 0.0.0-canary-20240614074419 — 2024-06-14
- 0.0.0-canary-20240614073621 — 2024-06-14
- … 27 more at https://npm.io/package/@commercetools/express-request-correlator/versions
## README
🧷 Express middleware to help tracing correlation IDs ⚙️
## ❯ 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:
1. 🎨 **Customized** correlation ids: sometimes correlation ids need customization. For instance adding prefix based on the incoming request's origin.
2. 🍕 **Forwarding** correlation ids: oftentimes an incoming correlation id needs to be forwarded as a header to another request (e.g. a `fetch` call).
3. 🏄🏻 **Opting out** of correlation ids: cases exist where a correlation id can or should not be generated while the fact should be logged
4. 👌🏼 **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 to `X-Correlation-Id`.
- `generateId`: a function called whenever an incoming request does not have a correlation id. Receives the `request` within its options argument.
An example configuration would be:
```js
import { createRequestCorrelatorMiddleware } from '@commercetools/express-request-correlator';
app.use(createRequestCorrelatorMiddleware());
```
1. 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
2. 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`.
1. If for instance you need to retrieve the current request's correlation id invoke `request.correlator.getCorrelationId()`
2. 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:
```js
{
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.
```js
import { createRequestCorrelatorMock } from '@commercetools/express-request-correlator/test-utils';
createRequestCorrelatorMock();
```
---
_Source: https://npm.io/package/@commercetools/express-request-correlator · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._