npm package: @openfin/snog
Description: Simple node logger
Author: Nigel Edwards
Latest version: 2.0.8

# snog

A simple strutured logging library for node. Heavily inspired by Logrus.

`npm i @openfin/snog`

Latest Stable: 2.0.0

## Usage

You can use snog directly aka the default global logger.

```javascript
import log from "@openfin/snog";
log.debug("hello");
```

Or clone / create a new one

```javascript
import log, { Snog } from "@openfin/snog";
const clonedLogger = log.clone();
const newLogger = new Snog();
```

See snog.clone for the difference between clone and new.

You can log with fields

```javascript
import log from "@openfin/snog";
log
  .addField("I love", "pizza")
  .addField("I love", "grits")
  .addFields({ like: "oranges" })
  .info("food i love");
// Note: Fields with the same name will override previous fields
```

### `log.silly(...values)`

### `log.debug(...values)`

### `log.info(...values)`

### `log.warn(...values)`

### `log.error(...values)`

Logs the given values at the respective level

### `log.sillyF(format, ...values)`

### `log.debugF(format, ...values)`

### `log.infoF(format, ...values)`

### `log.warnF(format, ...values)`

### `log.errorF(format, ...values)`

Logs the given values after formatting with `util.format`. See documentation on [util.format](https://nodejs.org/dist/latest-v8.x/docs/api/util.html#util_util_format_format_args) for more information.

### `log.addField(fieldName:string, value:any)`

Adds a field to be logged when a logging method is called. Fields can over write each other, the latest one taking precendence. Also nothing is logged until a log method(eg log.info) is called

### `log.addFields(fields:Object)`

Similar to `.addField` but takes an object instead of a key/value pair

### `log.setLevel(logLevel:int|string)`

Set the log level using either the logLevel enum integer or a log level string(silly, debug, info, warn, error). If you pass something invalid it will not change the level. It will print a error message. Returns false if the level was not changed otherwise true.

### `log.clone(snogOptions)`

Takes the same options as creating a new Snog instance directly, only difference is that clone will merge defaultFields and keep custom formater, writer and previous level. Just a small convience function for those who want "child logger" like functionality.

## Configuration

Both <snogInstance>.clone and new Snog take the same options object.

* `colorize` OPTIONAL: Colorize the terminal output. If the environment variable `NODE_ENV` is set to `production` colorize is set to false, otherwise it defaults to true.
* `defaultFields` OPTIONAL: Fields to always log.
* `level` OPTIONAL: Log level. If the environment variable `NODE_DEBUG` is set to a valid level(see Log Levels), it will use that otherwise defaults to `INFO`
* `date` OPTIONAL: A function that returns a date object. This is used for testing and should never be set.
* `writer` OPTIONAL: The log writer, defaults to `console.log`.
* `formatter` OPTIONAL: The log formatter. Defaults to built in text formatter. See formatter section for more details

## Format and Formatters

You can customize the output of Snog by using a custom formatter. Snog comes with two formatters, `textFormatter` and `jsonFormatter`. Snog defaults to `textFormatter`.

Text formatter output

`2018-04-28T04:00:00.000Z INFO msg=Single added field I have='a field'`

JSON formatter output

`{"I have":"a field","msg":"Overriden","timestamp":"2018-04-28T04:00:00.000Z","level":"INFO","Field 1":1,"Field 2":"another field","im":"an object fields\\n","snog":"true","thisGetsOverriden":"YES"}`

You can create your own formatter and pass it to snog provided it matches the formatter interface. For example here is the `jsonFormatter`

```typescript
//Snog fields contain the log message(msg), timestamp and level
// fields is the fields the caller added to the log using .addField and/or .addFields
export interface Formatter {
  (snog: Snog, snogFields: SnogFields, fields: Map<string, any>): any;
}

export function jsonFormatter(
  snog: Snog,
  snogFields: SnogFields,
  fields: Map<string, any>
) {
  const k = Object.assign(snog.defaultFields, mapToObject(fields), snogFields, {
    timestamp: snogFields.timestamp.toISOString(),
    level: levelText[snogFields.level]
  });
  return JSON.stringify(k, null, 0) + "\n";
}
```

## Writers

You can change where snog writes to by passing in a custom writer. The writer must be a function that takes a single value and can return anything(prefer void). By default snog uses `console.log`

Example custom writer

```typescript
function myAwesomeWriter(input) {
  myCustomStream.write(input);
}
const logger = new Snog({ writer: myAwesomeWriter });
```

## License

Apache 2.0 See LICENSE for more details