@seek/logger

@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
  • Trimming
  • Pino customisation
  • Pretty printing

Usage

import createLogger from '@seek/logger';

// Initialize the logger. By default, this will log to stdout.
const logger = createLogger({
  name: 'my-app',
});

// 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');

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 (e.g. x-envoy-peer-metadata).
  To opt out of this behavior, set the omitHeaderNames logger option to an empty list [] or provide your own list.

• 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 (e.g. x-envoy-peer-metadata).
  To opt out of this behavior, set the omitHeaderNames logger option to an empty list [] or provide your own list.

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.

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,
});

Changelog

6.2.0

Minor Changes

• Omit request headers (#92)

  @seek/logger now omits the following properties from headers and req.headers by default:

  • x-envoy-attempt-count
  • x-envoy-decorator-operation
  • x-envoy-expected-rq-timeout-ms
  • x-envoy-external-address
  • x-envoy-internal
  • x-envoy-peer-metadata
  • x-envoy-peer-metadata-id
  • x-envoy-upstream-service-time

  To opt out of this behaviour, provide an empty list or your own list of omissible request headers to omitHeaderNames:

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

  You can also extend the default list like so:

  - 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']
  });