feat: add a logUserErrorsAsWarnings option

This adds a `logUserErrorsAsWarnings` option which allows you to change
the log level for handled errors. If this option is set to `true` then:

  * Errors with a `status` or `statusCode` property of `400`-`499` will
    be logged with a level of "warn"

  * All other errors will still be logged with a level of "error"

I think in future we'll switch this to be the default behaviour and
remove the option.

Author: rowanmanning

docs/getting-started/logging-errors.md

@@ -108,6 +108,8 @@ When logging errors it's important to consider the level of the log you send. Th
     }
     ```
 
+    You may also want to differentiate between `4xx` and `5xx` errors by logging them with a level of "warn" or "error" respectively to indicate the different criticality of these types of errors.
+
   * If an error is not recoverable at all and throws the app into an unstable state, e.g. an initial database connection cannot be established, then consider a level of "fatal" or "critical" if your logger supports it (currently [n-logger](https://github.com/Financial-Times/n-logger) does not support critical logs but we'll be investigating adding this in future).
 
 

packages/log-error/README.md

@@ -11,6 +11,7 @@ A method to consistently log error object with optional request information. Thi
     * [`options.error`](#optionserror)
     * [`options.includeHeaders`](#optionsincludeheaders)
     * [`options.logger`](#optionslogger)
+    * [`options.logUserErrorsAsWarnings`](#optionslogusererrorsaswarnings)
     * [`options.request`](#optionsrequest)
 * [Migrating](#migrating)
 * [Contributing](#contributing)
@@ -213,6 +214,15 @@ Though it's best if they can accept a single object and output results as JSON.
 
 This option defaults to [Reliability Kit logger](https://github.com/Financial-Times/dotcom-reliability-kit/tree/main/packages/logger).
 
+#### `options.logUserErrorsAsWarnings`
+
+> [!NOTE]<br />
+> This option is only available in the [`logHandledError`](#loghandlederror) function.
+
+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`.
+
 #### `options.request`
 
 A request object (e.g. an instance of `Express.Request` or an object with `method` and `url` properties) to include alongside the error in the log. This will be [automatically serialized with `@dotcom-reliability-kit/serialize-request`](https://github.com/Financial-Times/dotcom-reliability-kit/tree/main/packages/serialize-request#readme).

packages/log-error/lib/index.js

@@ -82,13 +82,22 @@ function extractErrorMessage(serializedError) {
  *
  * @type {typeof import('@dotcom-reliability-kit/log-error').logHandledError}
  */
-function logHandledError({ error, includeHeaders, logger, request }) {
+function logHandledError({
+	error,
+	includeHeaders,
+	logger,
+	logUserErrorsAsWarnings = false,
+	request
+}) {
 	const serializedError = serializeError(error);
 	logError({
 		error: serializedError,
 		event: 'HANDLED_ERROR',
 		includeHeaders,
-		level: 'error',
+		level:
+			logUserErrorsAsWarnings && isUserError(serializedError)
+				? 'warn'
+				: 'error',
 		logger,
 		request
 	});
@@ -128,6 +137,18 @@ function logUnhandledError({ error, includeHeaders, logger, request }) {
 	});
 }
 
+/**
+ * @param {SerializedError} error
+ * @returns {boolean}
+ */
+function isUserError(error) {
+	return (
+		error.statusCode !== null &&
+		error.statusCode >= 400 &&
+		error.statusCode < 500
+	);
+}
+
 exports.logHandledError = logHandledError;
 exports.logRecoverableError = logRecoverableError;
 exports.logUnhandledError = logUnhandledError;

packages/log-error/test/unit/lib/index.spec.js

@@ -293,6 +293,99 @@ describe('@dotcom-reliability-kit/log-error', () => {
 			});
 		});
 
+		describe('when the logUserErrorsAsWarnings option is set to true', () => {
+			describe('and the serialized error has a status code in the 4xx range', () => {
+				beforeEach(() => {
+					serializeError.mockClear();
+					serializeError.mockReturnValueOnce({
+						name: 'MockError',
+						message: 'mock error',
+						statusCode: 456
+					});
+					logger.error.mockReset();
+					logger.warn.mockReset();
+					logHandledError({
+						error,
+						request,
+						logUserErrorsAsWarnings: true
+					});
+				});
+
+				it('logs with a level of "warn" rather than "error"', () => {
+					expect(logger.error).toHaveBeenCalledTimes(0);
+					expect(logger.warn).toHaveBeenCalledWith(
+						expect.objectContaining({
+							error: {
+								name: 'MockError',
+								message: 'mock error',
+								statusCode: 456
+							}
+						})
+					);
+				});
+			});
+
+			describe('and the serialized error has a status code in the 5xx range', () => {
+				beforeEach(() => {
+					serializeError.mockClear();
+					serializeError.mockReturnValueOnce({
+						name: 'MockError',
+						message: 'mock error',
+						statusCode: 500
+					});
+					logger.error.mockReset();
+					logger.warn.mockReset();
+					logHandledError({
+						error,
+						request,
+						logUserErrorsAsWarnings: true
+					});
+				});
+
+				it('still logs with a level of "error"', () => {
+					expect(logger.warn).toHaveBeenCalledTimes(0);
+					expect(logger.error).toHaveBeenCalledWith(
+						expect.objectContaining({
+							error: {
+								name: 'MockError',
+								message: 'mock error',
+								statusCode: 500
+							}
+						})
+					);
+				});
+			});
+
+			describe('and the serialized error does not have a status code', () => {
+				beforeEach(() => {
+					serializeError.mockClear();
+					serializeError.mockReturnValueOnce({
+						name: 'MockError',
+						message: 'mock error'
+					});
+					logger.error.mockReset();
+					logger.warn.mockReset();
+					logHandledError({
+						error,
+						request,
+						logUserErrorsAsWarnings: true
+					});
+				});
+
+				it('still logs with a level of "error"', () => {
+					expect(logger.warn).toHaveBeenCalledTimes(0);
+					expect(logger.error).toHaveBeenCalledWith(
+						expect.objectContaining({
+							error: {
+								name: 'MockError',
+								message: 'mock error'
+							}
+						})
+					);
+				});
+			});
+		});
+
 		describe('when logging fails', () => {
 			let loggingError;
 

packages/log-error/types/index.d.ts

@@ -16,7 +16,11 @@ declare module '@dotcom-reliability-kit/log-error' {
 		request?: string | Request;
 	};
 
-	export function logHandledError(options: ErrorLoggingOptions): void;
+	export type HandledErrorLoggingOptions = ErrorLoggingOptions & {
+		logUserErrorsAsWarnings?: boolean;
+	};
+
+	export function logHandledError(options: HandledErrorLoggingOptions): void;
 
 	export function logRecoverableError(options: ErrorLoggingOptions): void;
 

packages/middleware-log-errors/README.md

@@ -9,6 +9,7 @@ Express middleware to consistently log errors. This module is part of [FT.com Re
     * [`options.filter`](#optionsfilter)
     * [`options.includeHeaders`](#optionsincludeheaders)
     * [`options.logger`](#optionslogger)
+    * [`options.logUserErrorsAsWarnings`](#optionslogusererrorsaswarnings)
 * [Migrating](#migrating)
 * [Contributing](#contributing)
 * [License](#license)
@@ -167,6 +168,12 @@ type LogMethod = (...logData: any) => any;
 
 This is passed directly onto the relevant log-error method, [see the documentation for that package for more details](../log-error/README.md#optionslogger).
 
+#### `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
 

packages/middleware-log-errors/lib/index.js

@@ -15,6 +15,8 @@ const {
  * @returns {ExpressErrorHandler}
  */
 function createErrorLoggingMiddleware(options = {}) {
+	const { logUserErrorsAsWarnings } = options;
+
 	// Validate the included headers (this stops the request serializer from erroring
 	// on every request if the included headers are invalid)
 	const includeHeaders = options?.includeHeaders;
@@ -67,6 +69,7 @@ function createErrorLoggingMiddleware(options = {}) {
 				error,
 				includeHeaders,
 				logger: options.logger,
+				logUserErrorsAsWarnings,
 				request
 			});
 		} catch (_) {

packages/middleware-log-errors/test/unit/lib/index.spec.js

@@ -217,6 +217,27 @@ describe('@dotcom-reliability-kit/middleware-log-errors', () => {
 			});
 		});
 
+		describe('when the logUserErrorsAsWarnings option is set', () => {
+			beforeEach(() => {
+				middleware = createErrorLoggingMiddleware({
+					logUserErrorsAsWarnings: true
+				});
+				middleware(error, request, response, next);
+			});
+
+			it('it passes the option down to the error logging function', () => {
+				expect(logHandledError).toBeCalledWith({
+					error,
+					request,
+					logUserErrorsAsWarnings: true
+				});
+			});
+
+			it('calls `next` with the original error', () => {
+				expect(next).toBeCalledWith(error);
+			});
+		});
+
 		describe('when logging fails', () => {
 			beforeEach(() => {
 				logHandledError.mockImplementation(() => {

packages/middleware-log-errors/types/index.d.ts

@@ -11,6 +11,7 @@ declare module '@dotcom-reliability-kit/middleware-log-errors' {
 		filter?: ErrorLoggingFilter;
 		includeHeaders?: string[];
 		logger?: Logger & { [key: string]: any };
+		logUserErrorsAsWarnings?: boolean;
 	};
 
 	declare function createErrorLoggingMiddleware(