npm add diary makes logging simple

---

⚡ Features

• No dependencies
• Outstanding performance
• Support for debug's filter
• Browser compatible through localStorage

⚙️ Install

npm add diary

🚀 Usage

import { info, diary } from 'diary';

info('this important thing happened');
// ~> ℹ info  this important thing happened

const scopedDiary = diary('my-module', (event) => {
  if (event.level === 'error') {
    Sentry.captureException(event.error);
  }
});

scopedDiary.info('this other important thing happened');
// ~> ℹ info  [my-module] this other important thing happened

Controlling runtime emission of logs, using the code below as an example:

// example.js
import { diary } from 'diary';

const scopeA1 = diary('scopeA:one');
const scopeA2 = diary('scopeA:two');
const scopeB1 = diary('scopeB:one');
const scopeB2 = diary('scopeB:two');

scopeA1.info('message'); // won't log ✗
scopeA2.info('message'); // will log ✔
scopeB1.info('message'); // will log ✔
scopeB2.info('message'); // will log ✔

browser

localStorage.setItem('DEBUG', 'scopeA:two,scopeB:*');

// then your scripts

💡 Tip - Set this via the DevTools, then hit refresh. Saves you having to re-bundle.

node

DEBUG=scopeA:two,scopeB:* node example.js

workers

As of version v0.3.0 to enable log events you must use the enable programmatic api, this is due to Module Workers no longer offering global environment variables, and instead they are injected through an api.

Ambiant logs do however need to be statically enabled. (put a enable() in module scope).

import { diary, enable } from 'diary';

const logger = diary('my-worker');

export default {
  async fetch(req, env, context) {
    enable(env.DEBUG);

    logger.info('request for', req.url);
  },
};

programmatic

import { diary, enable } from 'diary';

enable('scopeA:two,scopeB:*');

const scopeA1 = diary('scopeA:one');
const scopeA2 = diary('scopeA:two');
const scopeB1 = diary('scopeB:one');
const scopeB2 = diary('scopeB:two');

scopeA1.info('message'); // won't log ✗
scopeA2.info('message'); // will log ✔
scopeB1.info('message'); // will log ✔
scopeB2.info('message'); // will log ✔

enable('scopeA:*');

scopeA1.info('message'); // will log ✔
scopeA2.info('message'); // will log ✔
scopeB1.info('message'); // won't log ✗
scopeB2.info('message'); // won't log ✗

🔎 API

diary(name: string, onEmit?: Reporter)

Returns: log functions

A default diary is exported, accessible through simply importing any log function.

Example of default diary

import { info } from 'diary';

info("i'll be logged under the default diary");

name

Type: string

The name given to this diary—and will also be available in all logEvents.

onEmit (optional)

Type: Reporter

A reporter is run on every log message (provided its enabled). A reporter gets given the LogEvent interface:

interface LogEvent {
  name: string;
  level: LogLevels;

  message: string;
  extra: unknown[];
}

Errors (for error and fatal) there is also an error: Error property.

log functions

A set of functions that map to console.error, console.warn, console.debug, console.info and console.info. Aptly named;

• fatal(message: string | Error, ...extra: any[])

• error(message: string | Error, ...extra: any[])

  If an Error instance is sent, the error object will be accessible with the error property on the context, this is for both fatal and error.

• warn(message: string, ...extra: any[])

• debug(message: string, ...extra: any[])

• info(message: string, ...extra: any[])

• log(message: string, ...extra: any[])

All extra parameters are simply spread onto the console function, so node/browser's built-in formatters will format any objects etc.

diary (optional)

Type: Diary

The result of a calling diary;

enable(query: string)

Type: Function

Opts certain log messages into being output. See more here.

💨 Benchmark

via the /bench directory with Node v16.2.0

Validation
  ✔ @graphile/logger
  ✔ bunyan
  ✔ debug
  ✔ diary
  ✔ pino
  ✔ roarr
  ✔ ulog
  ✔ winston

Benchmark
  @graphile/logger     x 20,198,944 ops/sec ±1.15% (89 runs sampled)
  bunyan               x    120,302 ops/sec ±0.63% (94 runs sampled)
  debug                x    211,486 ops/sec ±1.95% (88 runs sampled)
  diary                x  6,682,958 ops/sec ±1.79% (90 runs sampled)
  pino                 x     40,994 ops/sec ±2.15% (83 runs sampled)
  roarr                x    812,015 ops/sec ±1.87% (84 runs sampled)
  ulog                 x     24,878 ops/sec ±24.93% (19 runs sampled)
  winston              x      9,499 ops/sec ±14.17% (67 runs sampled)

Related

• workers-logger — fast and effective logging for Cloudflare Workers

License

MIT © Marais Rossouw