Marlowe, Your Request Sleuth

Description

Marlowe is a Rack
middleware that extracts or creates a request ID using a pre-defined
header, permitting request correlation across multiple services.

When using Rails, Marlowe automatically adds itself to the middleware
before Rails::Rack::Logger.

Upgrading from Marlowe 1.x

In Marlowe 1.0, the correlation header was called Correlation-Id;
since then, Rails 5 and other tools and frameworks (such as Phoenix) have
standardized on the header X-Request-Id. Marlowe 2.0 changes to
this header by default.

To keep complete compatibility with Marlowe 1.0, the following should be
used:

Configuration

Marlowe has three main configuration options: the request ID header, the
request ID handler, and the request ID return. The options may be provided
to the Rack use command as a keyword option, or set in a
corresponding marlowe_option configuration variable in
Rails.

Request ID Header

Specifies the header to be used for the request correlation ID. Defaults to
X-Request-Id.

Marlowe will convert this to an appropriate HTTP header (in the Rack
env parameter, the above header would be represented as
env['HTTP_CORRELATION_ID']).

Request ID Handler

Specifies the method for sanitizing or generating the request correlation
ID. Values can be :clean (the default, which limits incoming
correlation IDs to 255 alphanumeric-or-dash characters), :simple
(does not limit incoming correlation IDs), or a proc to transform or
generate a correlation ID.

In all cases, if a correlation request ID is not handled, a UUID will be
generated.

Using Marlowe with Rails 5

Rails 5 includes the ActionDispatch::RequestId middleware,
reducing the need for Marlowe. Marlowe is more configurable than the Rails
5 default, so set marlowe_replace_action_dispatch_request_id to
true to have Marlowe::Middleware will replace
ActionDispatch::RequestId:

# Rails only
config.marlowe_replace_action_dispatch_request_id=true

Accessing the Correlation ID

The correlation id can be accessed throughout the application by accessing
the RequestStore
storage.

RequestStore[:correlation_id]

Logging

For a Rails application, you simply need to change the log formatter to one
of the provided ones. Correlated versions of both the SimpleFormatter and
Formatter are included.

Clients

Catching and creating the correlation ID is a great all on its own, but to
really take advantage of the correlation in a service based architecture
you'll need to pass the request ID to the next service in the change.