npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@seek/logger

v9.0.0

Published

Standardized logging

Downloads

28,595

Readme

@seek/logger

GitHub Release GitHub Validate Node.js version npm package

@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

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.