@leaflink/snitch

@leaflink/snitch

Simple and extensible browser logging, inspired by Winston.

Installation

$ npm i @leaflink/snitch

Transports

Transports are a way of routing log messages to multiple destinations, with the ability to pre-process or format the message. @leaflink/snitch includes two transports by default (console and Sentry), but they can be extended using the Transport type exported by the logger.

Log Levels

Transports can be created with a log level to only handle messages with a certain severity. Log levels supported by @leaflink/snitch, in decreasing order by severity, are:

• error
• warn
• info
• debug

These levels cascade up, so a transport created with level debug will handle logs with that level as well as info, warn, and error, but a transport created with level error will not handle logs with the levels warn, info, or debug.

The level a log was called at is passed to transports to help determine how a message should be handled (for example, logging with console.<level> in the console transport).

Usage

The default export exposed by @leaflink/snitch is a singleton logger instance with no initial transports, which can be shared between modules easily. It does not include any transports by default to allow flexibility in per-environment transports.

import logger from '@leaflink/snitch';

In other situations, you may want to have a logger instance (or multiple instances) created and managed inside your application. To support this, @leaflink/snitch also exports a Logger class that can be used to create logger instances, optionally with predefined transports.

import { Logger } from '@leaflink/snitch';
import { ConsoleTransport } from '@leaflink/snitch/transports/console';

const loggerInstance = new Logger({
  transports: [new ConsoleTransport()],
});

// `logger.log` is an alias for `logger.info` for convenience
loggerInstance.log('Example log message');

Console Transport

main.ts

import logger from '@leaflink/snitch';
import { ConsoleTransport } from '@leaflink/snitch/transports/console';

logger.addTransport(new ConsoleTransport());

call in component file

import logger from '@leaflink/snitch';

try {
  await someErroringMethod()
} catch (err) {
  logger.error(err)
}

Sentry Transport

main.ts

import * as Sentry from '@sentry/vue';
import logger from '@leaflink/snitch';
import { SentryTransport } from '@leaflink/snitch/transports/sentry';

// Important: init Sentry instance before creating transport
Sentry.init({
  // ...
});
logger.addTransport(new SentryTransport({
  sentryInstance: Sentry,
}));

call in component file

import logger from '@leaflink/snitch';

try {
  await someErroringMethod()
} catch (err) {
  // optional error context object
  const errorContext: Record<string, any> = getErrorContext();
  // `err` is Error | string
  logger.error(err, errorContext);
}

With Log Level

main.ts

import logger from '@leaflink/snitch';
import { ConsoleTransport } from '@leaflink/snitch/transports/console';

logger.addTransport(new ConsoleTransport({
  level: 'info'
}));

Custom Transports

custom-transport.ts

import { LogLevel, Transport } from '@leaflink/snitch';
// imagine this has a `report(options<{message, context}>)` method
import CustomDestinationInstance from '@example/destination';

interface CustomTransportOptions {
  level?: LogLevel;
}

export class CustomTransport implements Transport {
  level: LogLevel;
  log: (message: string | object, meta: Record<string, unknown> | undefined, level: LogLevel) => void;

  constructor(opts?: ConsoleTransportOptions) {
    this.level = opts?.level || 'debug';
    this.log = (message, meta) => {
      CustomDestinationInstance.report({
        message,
        context: 'meta',
      })
    };
  }
}

main.ts

import logger from '@leaflink/snitch';
import { CustomTransport } from './custom-transport';

logger.add(new CustomTransport());

Note: You can add a custom transport in your project, but consider opening a PR in this repo instead!