@dotcom-reliability-kit/middleware-log-errors

Express middleware to consistently log errors. This module is part of FT.com Reliability Kit.

• Usage
  • createErrorLogger
  • Configuration options
    • options.filter
    • options.includeHeaders
    • options.logger
    • options.logUserErrorsAsWarnings
• Migrating
• Contributing
• License

Usage

Install @dotcom-reliability-kit/middleware-log-errors as a dependency:

1npm install --save @dotcom-reliability-kit/middleware-log-errors

Include in your code:

1import createErrorLogger from '@dotcom-reliability-kit/middleware-log-errors';
2// or
3const createErrorLogger = require('@dotcom-reliability-kit/middleware-log-errors');

createErrorLogger

The createErrorLogger function can be used to generate Express middleware which logs errors to the console and Splunk via Reliability Kit logger.

[!CAUTION]
This middleware must be added to your Express app after all your application routes – you won't get error logs for any routes which are mounted after this middleware.

1const app = express();
2// App routes go here
3app.use(createErrorLogger());

This will automatically serialize error objects and log them along with a serialized HTTP request which lead to the error being thrown. The information logged looks like this:

1{
2    event: 'HANDLED_ERROR',
3    message: 'Error: something went wrong',
4
5    error: {
6        code: 'EXAMPLE_CODE',
7        message: 'Something went wrong'
8        // etc. (see `@dotcom-reliability-kit/serialize-error` linked above
9        // for information about the logged properties
10    },
11
12    request: {
13        id: 'abc123',
14        method: 'GET',
15        url: '/'
16        // etc. (see `dotcom-reliability-kit/serialize-request` linked above
17        // for information about the logged properties)
18    },
19
20    app: {
21        commit: '137da65185397a7d699ed54c3052d10d83e82137',
22        name: 'example-app',
23        nodeVersion: '22.13.0',
24        region: 'EU',
25        releaseDate: '2022-07-25T01:37:00Z'
26    }
27}

Configuration options

Config options can be passed into the createErrorLogger function as an object with any of the keys below.

1app.use(createErrorLogger({
2    // Config options go here
3}));

options.filter

A function used to determine whether a particular error or request should be logged. This must be a Function which returns a Boolean and accepts both an error object and an Express Request object:

1type ErrorLoggingFilter = (error: any, request: express.Request) => boolean;

If the function returns true then the error and request details will be logged. Otherwise no logs will be output.

[!WARNING]
This option can be dangerous, misconfiguring it can result in a loss of log information. Consider whether you definitely need to filter logs before using, sometimes it's better to have a few too many logs than miss an important one.

Example of usage:

1app.use(createErrorLogger({
2    filter: (error, request) => {
3        if (request.url === '/deliberate-erroring-endpoint') {
4            return false;
5        }
6        if (error?.code === 'ERROR_WE_DO_NOT_CARE_ABOUT') {
7            return false;
8        }
9        return true;
10    }
11}));

options.includeHeaders

An array of request headers to include in the serialized request object. This must be an Array of Strings, with each string being a header name. It's important that you do not include headers which include personally-identifiable-information, API keys, or other privileged information. This option gets passed directly into dotcom-reliability-kit/serialize-request which has further documentation.

This option defaults to:

1[
2    'accept',
3    'accept-encoding',
4    'accept-language',
5    'content-type',
6    'referer',
7    'user-agent'
8]

Example of usage:

1app.use(createErrorLogger({
2    includeHeaders: [
3        'accept',
4        'content-length',
5        'content-type',
6        'user-agent'
7    ]
8}));

The default set of headers is also available to use, so that you don't need to repeat them if you want to add new included headers. You'll need to import @dotcom-reliability-kit/serialize-request, then these headers are available:

1const { DEFAULT_INCLUDED_HEADERS } = require('@dotcom-reliability-kit/serialize-request');
2
3app.use(createErrorLogger({
4    includeHeaders: [
5        ...DEFAULT_INCLUDED_HEADERS,
6        'my-custom-header'
7    ]
8}));

[!NOTE]
There's no need to include the x-request-id header in this array, as this is automatically included as request.id in the logs.

options.logger

A logger object which implements two methods, error and warn, which have the following permissive signature:

1type LogMethod = (...logData: any) => any;

This is passed directly onto the relevant log-error method, see the documentation for that package for more details.

options.logUserErrorsAsWarnings

A boolean indicating whether to log user errors (those with a 400–499 status property) with a level of warn rather than error. This helps to reduce the amount of error-level logs that you need to focus on.

This option defaults to false.

Migrating

Consult the Migration Guide if you're trying to migrate to a later major version of this package.

Contributing

See the central contributing guide for Reliability Kit.

License

Licensed under the MIT license.
Copyright © 2022, The Financial Times Ltd.