@pager/logger

@pager/logger

Structured logging for your verbose projects. Provides a pino logger with standard Pager defaults and redactions.

As of v7.0.0, no hapi plugin is exposed in this library. Hapi-based projects should use @pager/hapi-logger instead of this library. For an explanation of the split, see ADR-0015.

Basic usage

Provides a logger with standardized formatting and redaction configuration. For more details on how to work with Pino, take a look at its documentation or see configuration below for the setup details.

[!IMPORTANT]
Not for use in hapi projects, if your project uses hapi use @pager/hapi-logger instead of this library

Redacting

This library has been set up with an array of standard redactions based on current usage. Each app should explicitly append and detail all potential leaks. There are no wildcard defaults because there are large associated performance issues with wildcards, particularly intermediate wildcards. Please do your part in log security to ensure no PHI or secrets are leaked into the logs; defaults provided in the code are append only.

Environment

Name	Default	Description
LOG_LEVEL	info	Lowest level to log in this order: trace, debug, info, warn, error, fatal
LOG_ERROR_THRESHOLD	error	Lowest error to send to error transport
LOG_PRETTY_PRINT	none	Set to 1 to enable pretty print - this is not json and follows the configuration for prettyPrint docs

pino options

Pino default overrides per Pino's documentation.

{
  "level": "warn", // any pino default option overrides
  "redact": ['redactKey']
}

pino (Object)

Pino configuration object per Pino's documentation

instance (pino object)

Already configured pino object

Installation and Usage

// injecting a logger is best practice for most cases, defaulting to singleton is acceptable
const Logger = require('@pager/logger');

module.exports = (logger = Logger) => {

    Logger.info('Worker log');

    // .. worker works ...
    try {
        // do work
    }
    catch (err) {
        logger.error(err);
    }
};

Error handling

Under the hood we are using pino's default error serializer. This means it will add extra keys on the error object if present, and are not already used by one of pino's preset keys (e.g. data, message, type, etc.).

For example, see the custom field context within the error and it's expected log output:

const entity = { id: '6025827b568bb78e64b83ba2' };
const error = new Error('my error title');
error.context = { entityId: entity.id };
Logger.error(error);
/* Prints something like:
  {
    "level": 50,
    "time": 1613070971891,
    "pid": 58541,
    "hostname": "hostMBP",
    "context": {
      "entityId": "6025827b568bb78e64b83ba2"
    },
    "stack": "Error: my error title\n    at /projects/edge-api-cc/test/custom-error.js:19:23\n    at Immediate._onImmediate (/projects/edge-api-cc/node_modules/@hapi/lab/lib/runner.js:661:35)\n    at processImmediate (internal/timers.js:461:21)",
    "type": "Error",
    "data": "my error title"
  }
*/

Prereleases

New versions are published automatically via the package-prerelease github workflow. If you add the package-alpha github label to a PR, at least one commit on your branch has a prefix that semantic-release recognizes as needing a new version (i.e., fix or feat), and your branch differs from master for at least one file in the root directory, an appropriate release will be generated and published to the alpha tag on NPM.

Alpha versions should never be merged into master, so another workflow will prevent merge while the package-alpha label is present. Once you remove the label, you should be able to merge your PR.

[!NOTE]
This workflow uses semantic-release which inspects commit messages to determine whether or not a new release is needed. This means if your branch contains only chore-prefixed commits, no release will be triggered. If you want to trigger a prerelease, you should push a commit prefixed with package-fix, package-feat, fix, or feat.

[!WARNING]
Changes made to CHANGELOG.md and package.json are not committed to git. This means the CHANGELOG.md is unmaintained, and the version in package.json is not accurate. Instead, we rely on git tags to indicate what version the SDK is at for a given commit SHA

The tl;dr is that to publish an alpha, you must meet the following requirements:

1. Your branch differs from master for at least one file within the root directory
2. At least one commit on your branch has the appropriate format for semantic-release to recognize
3. Your branch has the package-alpha label

If these things are true, a release should be created when you add the label, as well as after pushing new commits to the remote branch. You can also add and remove the label to re-trigger the workflow.

Troubleshooting Prereleases

1. Does your branch have at least one commit with an appropriate prefix? You must have a commit with one of the default semantic-release commit formats that trigger a release, or one configured in our shared semantic-release config

2. Look at the history for the package pre-release github workflow for any errors during runs on your PR, or if the workflow is erroring for all PRs. The error messages may help reveal the problem, otherwise you can ask for help on slack in #eng-architecture