Migration guide for @dotcom-reliability-kit/logger

This document outlines how to migrate to the latest version of the Reliability Kit logger. Throughout this guide we use the following emoji and labels to indicate the level of change required:

Emoji	Label	Meaning
🔴	Breaking	A breaking change which will likely require code or config changes to resolve
🟠	Possibly Breaking	A breaking change that is unlikely to require code changes but things outside of the code (e.g. logs) may have changed
🟡	Deprecation	A deprecated feature which will require code changes in the future

Migrating from n-logger
Migrating from n-mask-logger
Migrating from n-serverless-logger
Migrating from v1 to v2
- Node.js 14 is no longer supported
Migrating from v2 to v3
- Node.js 16 is no longer supported
- Log times are now ISO 8601 timestamps

Migrating from n-logger

We tried to maintain as much compatibility with n-logger as possible to make switching relatively easy. This guide covers the differences and how to migrate your application. This guide assumes you're using the latest major version of n-logger.

n-logger: where logs get sent

🟠 Possibly Breaking: The Splunk HEC Logger has been removed. @dotcom-reliability-kit/logger does not directly log to Splunk, it logs to process.stdout and relies on your application forwarding these errors to Splunk. This is the same behaviour as n-logger with the MIGRATE_TO_HEROKU_LOG_DRAINS environment variable set.

If your app is on Heroku and you've migrated to use Heroku Log Drains, then this change will not impact you. If you haven't migrated to Heroku Log Drains yet then you'll need to do that before using this package.

If your app runs on AWS Lambda then you need to ensure that logs are forwarded to Splunk.

n-logger: error serialization changes

🟠 Possibly Breaking: The format of errors has changed in the log outputs between n-logger and @dotcom-reliability-kit/logger. We now run instances of Error through the serialize-error package which enriches the logs a lot more.

This is technically not a backwards-compatible change, if you have dashboards which are based on the old error properties (error_name, error_message, error_stack) then you'll need to update these after migrating.

The differences are:

logger.info(new TypeError('Example Error'));

{
-    "error_name": "TypeError",
-    "error_message": "Example Error",
-    "error_stack": "..."
+    "error": {
+        "name": "TypeError",
+        "code": "UNKNOWN",
+        "message": "Example Error",
+        "stack": "...",
+        "isOperational": false,
+       // ...all other serialized properties
+    }
}

n-logger: log timestamps

🟠 Possibly Breaking: Because Pino (the default underlying log transport) logs asynchronously, the time that it takes logs to reach process.stdout isn't predictable. That means that the time captured alongside logs may be slightly inaccurate, though they will all still be in the correct order.

Now, by default, a time property is sent on every log to capture the exact time that a log method was called. If your app is already using a time property then this may be a breaking change.

It's possible to switch off this behaviour for backwards-compatibility, set the withTimestamps option to false in order to not capture log timestamps.

n-logger: log level changes

🟡 Deprecation: The log levels which this logger supports are different to n-logger, we've reduced and simplified the number of levels and made it clear what each is for. The older log level methods have been deprecated or removed as follows:

data: This level is now an alias of debug and any logs sent with this method will be changed to have a level of debug. A warning will also be logged to explain the deprecation. While it's not essential yet, it's worth switching from data to debug explicitly in your code.
silly: This level is now an alias of debug and any logs sent with this method will be changed to have a level of debug. A warning will also be logged to explain the deprecation. While it's not essential yet, it's worth switching from silly to debug explicitly in your code.
verbose: This level is now an alias of debug and any logs sent with this method will be changed to have a level of debug. A warning will also be logged to explain the deprecation. While it's not essential yet, it's worth switching from verbose to debug explicitly in your code.

n-logger: method changes

🟡 Deprecation: The logger.addContext method has been deprecated and will be removed in a later version of Reliability Kit logger. It currently works in exactly the same way as n-logger, so migration isn't strictly necessary but you'll get warning logs. The README documents some alternatives.

We want to avoid making modifications to a global logger as this can have unexpected consequences. It's better to create a new logger for your specific purpose, and you can now do so by creating child loggers:

// The old way
const logger = require('@dotcom-reliability-kit/logger').default;
logger.addContext({ example: true });
logger.info('Hello');
// { "level": "info", "message": "Hello", "example": true }

// The new way (#1): not modifying the default logger
const logger = require('@dotcom-reliability-kit/logger').default;
const childLogger = logger.createChildLogger({ example: true });
childLogger.info('Hello');
// { "level": "info", "message": "Hello", "example": true }

// The new way (#2): creating a brand new logger with base data
const { Logger } = require('@dotcom-reliability-kit/logger');
const logger = new Logger({
    baseLogData: { example: true }
});
logger.info('Hello');
// { "level": "info", "message": "Hello", "example": true }

n-logger: environment variable changes

🟡 Deprecation: The following environment variables no longer do anything:

MIGRATE_TO_HEROKU_LOG_DRAINS: This is no longer required as the Reliability Kit logger doesn't not work without log drains.
SPLUNK_HEC_TOKEN: This is no longer required as the Reliability Kit logger does not directly connect to Splunk.
CONSOLE_LOG_LEVEL: This has been replaced with a more generic LOG_LEVEL environment variable. This means that in local development you might see more logs until you reconfigure. This removal has no impact on production environments.
CONSOLE_LOG_UNCOLORIZED: This is no longer required as the Reliability Kit logger does not colourize logs by default. See the local development usage guide if you want colourized logs when running locally.

The following environment variables have been deprecated.

SPLUNK_LOG_LEVEL: This environment variable will be used if a LOG_LEVEL environment variable is not present, however it may be removed in a later version of the Reliability Kit logger. It's best to migrate to LOG_LEVEL early.

n-logger: proxy incompatibility

🔴 Breaking: due to our use of private class features in the new logger, using Proxy objects is no longer possible. This is a known JavaScript incompatibility between private fields and proxies.

We decided to continue using private fields because Proxy use at the FT is uncommon and private fields allow us to ensure internal APIs aren't used in places that they shouldn't be.

Migrating from n-mask-logger

We tried to maintain as much compatibility with n-mask-logger as possible to make switching relatively easy. This guide covers the differences and how to migrate your application. This guide assumes you're using the latest major version of n-mask-logger.

n-mask-logger: API changes

🔴 Breaking: n-mask-logger's public API has been completely revised, and you'll need to make code changes in order to migrate to the Reliability Kit logger. We've tried to keep this as minimal as possible. For basic n-mask-logger usage, you'll need to replace as follows:

- const MaskLogger = require('@financial-times/n-mask-logger');
+ const { Logger, transforms } = require('@dotcom-reliability-kit/logger');

- const logger = new MaskLogger();
+ const logger = new Logger({
+     transforms: [
+         transforms.legacyMask()
+     ]
+ });

If you're using arguments to configure n-mask-logger, you'll need to switch those to named options on the legacy mask transform:

- const logger = new MaskLogger(
-     ['example', 'deny', 'list'],
-     ['example', 'allow', 'list'],
-     'example mask string'
- );
+ const logger = new Logger({
+     transforms: [
+         transforms.legacyMask({
+             denyList: ['example', 'deny', 'list'],
+             allowList: ['example', 'allow', 'list'],
+             maskString: 'example mask string'
+         })
+     ]
+ });

n-mask-logger: where logs get sent

🟠 Possibly Breaking: n-mask-logger uses n-logger under the hood, so the same breaking changes potentially apply. As with n-logger, if your app is on Heroku and you've migrated to use Heroku Log Drains, then this change will not impact you.

n-mask-logger: log timestamps

🟠 Possibly Breaking: As with n-logger, we now add a time property to logs. This is potentially a breaking change. See the migration guide for n-logger for more information.

n-mask-logger: method changes

🔴 Breaking: The logger.mask method has been removed and is no longer available. We could not find any use of this method across our systems so you should be safe, but check just in case.

n-mask-logger: environment variable changes

🟡 Deprecation: n-mask-logger reads the same environment variables as n-logger, please refer to the n-logger migration guide for more information.

Migrating from n-serverless-logger

We tried to maintain as much compatibility with n-serverless-logger as possible to make switching relatively easy. This guide covers the differences and how to migrate your application. This guide assumes you're using the latest major version of n-serverless-logger.

n-serverless-logger: where logs get sent

🔴 Breaking: The Splunk logger has been removed. @dotcom-reliability-kit/logger does not directly log to Splunk, it logs to process.stdout and relies on your application forwarding these errors to Splunk. This is a breaking change.

Your logs will still be sent to CloudWatch, but you'll need to ensure that these logs are forwarded to Splunk.

n-serverless-logger: error serialization changes

🟠 Possibly Breaking: The format of errors has changed in the log outputs between n-serverless-logger and @dotcom-reliability-kit/logger. We now run instances of Error through the serialize-error package which enriches the logs a lot more.

See the error serialization changes for n-logger for more information.

n-serverless-logger: property changes

🔴 Breaking: The logger.withTimestamps property is no longer accessible as it's no longer a trivial task to change the timestamp settings after a logger is constructed. Timestamps are included by default, if you need to disable them then you should create a new Logger instance with the configuration set:

const { Logger } = require('@dotcom-reliability-kit/logger');
const logger = new Logger({
    withTimestamps: false
});

n-serverless-logger: method changes

🟡 Deprecation: The logger.setContext and logger.clearContext methods have been deprecated and will be removed in a later version of Reliability Kit logger. They currently work in exactly the same way as n-serverless-logger, so migration isn't strictly necessary but you'll get warning logs. The README documents some alternatives.

We want to avoid making modifications to a global logger as this can have unexpected consequences. It's better to create a new logger for your specific purpose, and you can now do so by creating child loggers:

// The old way
const logger = require('@dotcom-reliability-kit/logger').default;
logger.setContext({ example: true });
logger.info('Hello');
// { "level": "info", "message": "Hello", "context": { "example": true } }

// The new way (#1): not modifying the default logger
const logger = require('@dotcom-reliability-kit/logger').default;
const childLogger = logger.createChildLogger({ context: { example: true } });
childLogger.info('Hello');
// { "level": "info", "message": "Hello", "context": { "example": true } }

// The new way (#2): creating a brand new logger with base data
const { Logger } = require('@dotcom-reliability-kit/logger');
const logger = new Logger({
    baseLogData: { context: { example: true } }
});
logger.info('Hello');
// { "level": "info", "message": "Hello", "context": { "example": true } }

n-serverless-logger: environment variable changes

🟡 Deprecation: The following environment variables no longer do anything:

AWS_LAMBDA_FUNCTION_NAME: This is no longer required as the Reliability Kit logger does not directly connect to Splunk.
SPLUNK_HEC_TOKEN: This is no longer required as the Reliability Kit logger does not directly connect to Splunk.
SPLUNK_HEC_URL: This is no longer required as the Reliability Kit logger does not directly connect to Splunk.

The following environment variables have been deprecated.

SPLUNK_LOG_LEVEL: This environment variable will be used if a LOG_LEVEL environment variable is not present, however it may be removed in a later version of the Reliability Kit logger. It's best to migrate to LOG_LEVEL early.

Migrating from v1 to v2

Node.js 14 is no longer supported

🔴 Breaking: this version drops support for Node.js v14. If your app is already using Node.js v16 or above then you can migrate with no code changes.

Migrating from v2 to v3

Node.js 16 is no longer supported

🔴 Breaking: this version drops support for Node.js v16. If your app is already using Node.js v18 or above then you can migrate with no code changes.

Log times are now ISO 8601 timestamps

🟠 Possibly Breaking: The time property of all logs is now an ISO 8601 representation of the time that the log was sent rather than a timestamp. There are two ways this could be a breaking change in your app:

If you have saved searches or dashboards that rely on the time property being a number.
If you're using the withTimestamps or useIsoTimeFormat options with TypeScript, because these options have now been removed from the code and the type definitions.

If neither of the above is true, this should be a safe update with no code changes.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

migration.md

migration.md

Migration guide for @dotcom-reliability-kit/logger

Migrating from n-logger

n-logger: where logs get sent

n-logger: error serialization changes

n-logger: log timestamps

n-logger: log level changes

n-logger: method changes

n-logger: environment variable changes

n-logger: proxy incompatibility

Migrating from n-mask-logger

n-mask-logger: API changes

n-mask-logger: where logs get sent

n-mask-logger: log timestamps

n-mask-logger: method changes

n-mask-logger: environment variable changes

Migrating from n-serverless-logger

n-serverless-logger: where logs get sent

n-serverless-logger: error serialization changes

n-serverless-logger: property changes

n-serverless-logger: method changes

n-serverless-logger: environment variable changes

Migrating from v1 to v2

Node.js 14 is no longer supported

Migrating from v2 to v3

Node.js 16 is no longer supported

Log times are now ISO 8601 timestamps

Files

migration.md

Latest commit

History

migration.md

File metadata and controls

Migration guide for @dotcom-reliability-kit/logger

Migrating from n-logger

n-logger: where logs get sent

n-logger: error serialization changes

n-logger: log timestamps

n-logger: log level changes

n-logger: method changes

n-logger: environment variable changes

n-logger: proxy incompatibility

Migrating from n-mask-logger

n-mask-logger: API changes

n-mask-logger: where logs get sent

n-mask-logger: log timestamps

n-mask-logger: method changes

n-mask-logger: environment variable changes

Migrating from n-serverless-logger

n-serverless-logger: where logs get sent

n-serverless-logger: error serialization changes

n-serverless-logger: property changes

n-serverless-logger: method changes

n-serverless-logger: environment variable changes

Migrating from v1 to v2

Node.js 14 is no longer supported

Migrating from v2 to v3

Node.js 16 is no longer supported

Log times are now ISO 8601 timestamps