npm package: @pager/logger
Description: Logging library
Latest version: 7.12.0

# @pager/logger

Structured logging for your verbose projects. Provides a [pino](https://github.com/pinojs/pino) logger with standard
Pager defaults and redactions.

As of [v7.0.0](https://github.com/pagerinc/logger/releases/tag/v7.0.0), no hapi plugin is exposed in this library.
Hapi-based projects should use [@pager/hapi-logger](https://github.com/pagerinc/hapi-logger) instead of this library.
For an explanation of the split, see [ADR-0015](https://pagerinc.atlassian.net/wiki/spaces/EN/pages/3008200714/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](https://github.com/pinojs/pino) or see [configuration](#Configuration) below for the setup details.

> [!IMPORTANT]  
> Not for use in [hapi](https://hapi.dev/) projects, if your project uses hapi use
> [@pager/hapi-logger](https://github.com/pagerinc/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](https://github.com/pinojs/pino-pretty#pino-pretty) |


### pino options
Pino default overrides per [Pino's documentation](https://github.com/pinojs/pino/blob/master/docs/api.md#options-object).

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

### pino (Object)
Pino configuration object per [Pino's documentation](https://github.com/pinojs/pino/blob/master/docs/api.md#options-object)

### instance (pino object)
Already configured pino object

## Installation and Usage

```javascript
// 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](https://github.com/pinojs/pino-std-serializers/blob/master/lib/err.js). 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:

```javascript

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"
  }
*/
```