# Getting started

# Installation

The library oddlog should be added to the package.json file of your projects:

npm install --save oddlog

In order to beautify the output, you might want to install @oddlog/cli either globally or project-specific (e.g. for use within npm scripts).

npm install --save @oddlog/cli
# or
npm install -g @oddlog/cli # you probably need to run this as root

Import oddlog according to your module system:

// ES6 modules
import * as oddlog from "oddlog";
// CommonJS
const oddlog = require("oddlog");
// AMD
require(["oddlog"], (oddlog) => { /* ... */ });

# Logger creation

Call oddlog.createLogger with your desired options like this:

const myLogger = oddlog.createLogger("my-app", {transports: [{type: "stream"}]}, {some: "global payload"});

When using multiple loggers for an application, it is recommended to give all loggers the same prefix such as my-app:root, my-app:http.

# Logger storage

If you'd like to use the built-in logger storage, you can replace oddlog.createLogger with oddlog.defineLogger and use oddlog.getLogger("my-app") (within ES6 modules the default export is an alias for getLogger) to retrieve the previously defined logger:

oddlog.defineLogger("my-app", {transports: [{type: "stream"}]}, {some: "global payload"});

const myLogger = oddlog("my-app");

If you prefer to separate the logger name from the storage name, you can do so like this:

// 1. create logger
const myHTTPLogger = oddlog.createLogger("my-app:http", {transports: [{type: "stream"}]}, {some: "global payload"});
// 2. register logger to the store
oddlog.defineLogger("http", myHTTPLogger);
// 3. retrieve logger from anywhere in your application
const httpLogger = oddlog("http");

# CLI

When you use oddlog within your project, the raw output looks like this (one line per log record):

[1,"_type",["4.14.15-1-ARCH","zerg","26032"],"app",1,"2018-02-15T18:04:33.100Z",3,null,"server listening",{"host":"127.0.0.1","port":8128,"package":"oddlog-example-file-server@0.1.0","production":false}]

Pipe it through the oddlog binary that is provided by @oddlog/cli to get human readable output instead:

Run oddlog --help for parameter information.

# Process exit

Especially in production it is highly important for all logs to be flushed on application exit - especially if caused by errors that are not catched otherwise.

Oddlog provides some methods for this: