lumberjack

It logs.

You can configure lumberjack to log to the console (multiple formats), files, and Loki. It uses winston for logging and axios for http transport.

This package has a custom Loki integration to specifically integrate with the Grafana Cloud API (winston-loki has problems with authenticating to Grafana Cloud). The Loki integration also includes a cache that holds messages and sends them in groups to the Grafana endpoint. Being a cloud native, I haven't checked this against a local Loki instance 😭.

usage

installation

npm i @sndwrks/lumberjack

configuration

The logger can be configured only once. Once configureLogger() is called the subsequent configuration object is frozen. Additionally, configureLogger() should be called before you call beginLogging() to return a logger instance.

Configuration is passed as an object to configureLogger(). None of the parameters are explicitly required, but you should specify at least one option as true. If you don't specify at least one winston will store the logs in memory which may not be what you wanted.

If lokiConfig.apiKey, lokiConfig.host, or lokiConfig.username are not included, Loki Transport is turned off.

There are a few formats for the console logging: pretty, google cloud (gcp), or string. pretty is all fancy-like most useful for development, but terrible in production. gcp uses the google cloud log format. string is a single line json string for more generic production use if you logging to the console.

parameters

| name | type | required | description | | -------------------------- | ------- | -------- | -------------------------------------------------- | | logToConsole | Object | No | Console configuration object | | logToConsole.enable | Boolean | No | Should lumberjack log to the console? | | logToConsole.type | Enum | No | What format should log to the console? 'pretty', 'gcp', 'string'| | logToFiles | Boolean | No | Should lumberjack log to the file system? It logs to two files any error messages to ./error.log and any other messages (less sever than error) to ./combined.log. | | logLevel | Enum | No | 'error','warn', 'info', 'http', 'verbose', 'debug', 'silly' The default is silly| | service | String | No | The name of the service to include this is included in the metadata that is sent to Loki so it is queryable. Default is my-saucy-logger | | -------------------------- | ------- | -------- | -------------------------------------------------- | | lokiConfig | Object | No | Configuration for Loki. | | lokiConfig.apiKey | String | Yes | The API you receive from Grafana. | | lokiConfig.host | String | Yes | The URL of the host lumberjack should send the logs to. | | lokiConfig.username | String | Yes | The username to receive from Grafana. | | lokiConfig.sendLogs | Boolean | No | Should the transport send logs to Loki? Default is false | | lokiConfig.logCacheLimit | Number | No | Sets how many logs are stored before the transport sends them. Default is 10 |

example

Logger Configuration

import { configureLogger } from '@sndwrks/lumberjack';

// full configuration or "whole hog" as they say in the biz
configureLogger({
  logToConsole: {
    enabled: true,
    type: 'pretty', // <pretty | gcp | string>
  },
  logToFiles: true,
  lokiConfig: {
    sendLogs: true,
    host: process.env.LOKI_HOST,
    username: process.env.LOKI_USERNAME,
    apiKey: process.env.LOKI_API_KEY,
    logCacheLimit: 10,
  },
  logLevel: 'silly',
  service: 'lumberjack-dev-test',
});

Logging

import { beginLogging } from '@sndwrks/lumberjack';

const logger = beginLogging({ name: 'myImportantFile.js' });

logger.error();
logger.warn();
logger.info();
logger.http();
logger.verbose();
logger.debug();
logger.silly();

contributing

If you like this and want to contribute, well sweet. Just slap up a pr.

to-do & desires

• Moar Tests
• Typescript
• Handle shutdown in some fashion
• More formats