README.md

@seek/logger

@seek/logger is a JSON logger for Node.js applications. It implements several SEEK customisations over Pino, including:

• Human-readable timestamps for Splunk compatibility
• Redaction of sensitive data
• Trimming deep objects to reduce cost and unintended disclosure

Table of contents

• Usage
  • Standardised fields
  • Typed fields
• Features
  • Redaction
  • Omitting Headers
  • Trimming
  • Pino customisation
  • Pretty printing

Usage

import createLogger, { createDestination } from '@seek/logger';

const { destination, stdoutMock } = createDestination({
  mock: config.environment === 'test',
});

// Initialize the logger.
// This will log to stdout if `createDestination` is not mocked.
const logger = createLogger(
  {
    name: 'my-app',
  },
  destination,
);

// Write an informational (`level` 30) log with a `msg`.
logger.info('Something good happened');

// Create a child logger that automatically includes the `requestId` field.
const childLogger = logger.child({ requestId });

// Write an error (`level` 50) log with `err`, `msg` and `requestId`.
childLogger.error({ err }, 'Something bad happened');

// Introspect mocked calls in your test environment.
// See the Testing section for more information.
stdoutMock.calls;

Standardised fields

@seek/logger bundles custom req, res and headers serializers along with Pino's standard set. User-defined serializers will take precedence over predefined ones.

Use the following standardised logging fields to benefit from customised serialization:

• err for errors.

  The Error is serialized with its message, name, stack and additional properties. Notice that this is not possible with e.g. JSON.stringify(new Error()).

• req for HTTP requests.

  The request object is trimmed to a set of essential fields.
  Certain headers are omitted by default; see Omitting Headers for details.

• res for HTTP responses.

  The response object is trimmed to a set of essential fields.

• headers for tracing headers.

  Certain headers are omitted by default; see Omitting Headers for details.

All other fields will be logged directly.

Typed fields

You can type common sets of fields to enforce consistent logging across your application(s). Compatibility should be maintained with the existing serializer functions.

// Declare a TypeScript type for your log fields.
interface Fields {
  activity: string;
  err?: Error;
}

// Supply it as a type parameter for code completion and compile-time checking.
logger.trace<Fields>(
  {
    activity: 'Getting all the things',
  },
  'Request initiated',
);

logger.error<Fields>(
  {
    activity: 'Getting all the things',
    err,
  },
  'Request failed',
);

Features

Redaction

Bearer tokens are redacted regardless of their placement in the log object.

Some property paths are redacted by default. See defaultRedact in src/redact/index.ts for the path list.

Additional property paths can be redacted using the redact logger option as per pino redaction.

Note that pino only supports either redaction or removal of the properties, not redaction of some properties and removal of other properties.

If you would like to redact some properties and remove others, you are recommended to configure redact with the list of paths to redact and provide a custom serializer to omit specific properties from the logged object.

Custom serializers can be provided with the serializers logger option as described in pino serializers and is the strategy used for omitting default headers.

Omitting Headers

Specific headers defined in DEFAULT_OMIT_HEADER_NAMES are omitted from the following properties:

• headers
• req.headers

This behaviour can be configured with the omitHeaderNames option.

• Opt out by providing an empty list.
• Only omit specific headers by providing your own list.
• Extend the defaults by spreading the DEFAULT_OMIT_HEADER_NAMES list and appending your own list.

Example of extending the default header list:

-import createLogger from '@seek/logger';
+import createLogger, { DEFAULT_OMIT_HEADER_NAMES } from '@seek/logger';

const logger = createLogger({
  name: 'my-app',
+ omitHeaderNames: [...DEFAULT_OMIT_HEADER_NAMES, 'dnt' , 'sec-fetch-dest']
});

Trimming

The following trimming rules apply to all logging data:

• All log structures deeper than 4 levels (default) will be omitted from output.
• All log structures (objects/arrays) with size bigger/longer than 64 will be trimmed.
• All strings that are longer than 512 will be trimmed.
• All buffers will be substituted with their string representations, eg. "Buffer(123)".

Avoid logging complex structures such as buffers, deeply nested objects and long arrays. Trimming operations are not cheap and may lead to significant performance issues of your application.

While log depth is configurable via loggerOptions.maxObjectDepth, we strongly discourage a log depth that exceeds the default of 4 levels. Consider flattening the log structure for performance, readability and cost savings.

Pino customisation

@seek/logger uses Pino under the hood. You can customise your logger by providing Pino options like so:

import createLogger, { pino } from '@seek/logger';

const logger = createLogger(
  {
    name: 'my-app',
    ...myCustomPinoOptions,
  },
  myDestination,
);

const extremeLogger = createLogger({ name: 'my-app' }, pino.extreme());

Note: createLogger mutates the supplied destination in order to redact sensitive data.

Pretty printing

@seek/logger supports Pino-compatible pretty printers. For example, you can install pino-pretty as a devDependency:

yarn add --dev pino-pretty

Then selectively enable pretty printing when running your application locally:

import createLogger from '@seek/logger';

const logger = createLogger({
  name: 'my-app',
  transport:
    process.env.ENVIRONMENT === 'local' ? { target: 'pino-pretty' } : undefined,
});

Testing

See docs/testing.md.