npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@commercetools/express-request-correlator

v3.0.2

Published

Express middleware to help tracing correlation IDs

Downloads

1,771

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:

  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:

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:

{
  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();