[![*nix build status][nix-build-image]][nix-build-url]
[![Windows build status][win-build-image]][win-build-url]
[![Tests coverage][cov-image]][cov-url]
![Transpilation status][transpilation-image]
[![npm version][npm-image]][npm-url]

# log

## Universal logging utility

**Configurable, environment and presentation agnostic, with log levels and namespacing ([debug](https://github.com/visionmedia/debug#debug) style) support**

### Usage

#### Writing logs

```javascript
// Default logger writes at 'info' level
const log = require("log");

// Log 'info' level message:
log("some info message %s", "injected string");

// Get namespaced logger (debug lib style)
log = log.get("my-lib");

// Log 'info' level message in context of 'my-lib' namespace:
log("some info message in 'my-lib' namespace context");

// Namespaces can be nested
log = log.get("func");

// Log 'info' level message in context of 'my-lib:func' namespace:
log("some info message in 'my-lib:func' namespace context");

// Log 'error' level message in context of 'my-lib:func' namespace:
log.error("some error message");

// log output can be dynamically enabled/disabled during runtime
const { restore } = log.error.disable();
log.error("error message not really logged");
// Restore previous logs visibiity state
restore();
log.error("error message to be logged");
```

#### Available log levels

Mirror of applicable syslog levels (in severity order):

-   `debug` - debugging information (hidden by default)
-   `info` - a purely informational message (hidden by default)
-   `notice` - condition normal, but significant
-   `warning` (also aliased as `warn`) - condition warning
-   `error` - condition error - to notify of errors accompanied with recovery mechanism (hence reported as log and not as uncaught exception)

_Note: `critical`, `alert`, `emergency` are not exposed as seem to not serve a use case in context of JS applications,
such errors should be exposed as typical exceptions_

#### Output message formatting

`log` doesn't force any specific arguments handling. Still it is recommended to assume [printf-like](https://en.wikipedia.org/wiki/Printf_format_string) message
format, as all currently available writers are setup to support it. Placeholders support reflects one implemented in Node.js [format](https://nodejs.org/api/util.html#util_util_format_format_args) util

Excerpt from Node.js documentation:

_The first argument is a string containing zero or more placeholder tokens. Each placeholder token is replaced with the converted value from the corresponding argument. Supported placeholders are:_

-   _`%s` - String._
-   _`%d` - Number (integer or floating point value)._
-   _`%i` - Integer._
-   _`%f` - Floating point value._
-   _`%j` - JSON. Replaced with the string '[Circular]' if the argument contains circular references._
-   _`%o` - Object. A string representation of an object with generic JavaScript object formatting. Similar to util.inspect() with options { showHidden: true, depth: 4, showProxy: true }. This will show the full object including non-enumerable symbols and properties._
-   _`%O` - Object. A string representation of an object with generic JavaScript object formatting. Similar to util.inspect() without options. This will show the full object not including non-enumerable symbols and properties._
-   _`%%` - single percent sign ('%'). This does not consume an argument._

_Note to log writer configuration developers: For cross-env compatibility it is advised to base implementation on [sprintf-kit](https://github.com/medikoo/sprintf-kit)_

#### Enabling log writing

`log` on its own doesn't write anything to the console or any other means (it just emits events to be consumed by preloaded log writers).

To have logs written, the pre-chosen log writer needs to be initialized in the main (starting) module of a process.

##### List of available log writers

-   [`log-node`](https://github.com/medikoo/log-node) - For typical Node.js processes
-   [`log-aws-lambda`](https://github.com/medikoo/log-aws-lambda) - For AWS lambda environment

_Note: if some writer is missing, propose a PR_

#### Logs Visibility

Default visibility depends on the enviroment (see chosen log writer for more information), and in most cases is setup through the following environment variables:

###### `LOG_LEVEL`

(defaults to `notice`) Lowest log level from which (upwards) all logs will be exposed.

###### `LOG_DEBUG`

Eventual list of namespaces to expose at levels below `LOG_LEVEL` threshold

List is comma separated as e.g. `foo,-foo:bar` (expose all `foo` but not `foo:bar`).

It follows convention configured within [debug](https://github.com/visionmedia/debug#windows-note). To ease eventual migration from [debug](https://github.com/visionmedia/debug), configuration fallbacks to `DEBUG` env var if `LOG_DEBUG` is not present.

#### Timestamps logging

Writers are recommended to to expose timestamps aside each log when following env var is set

###### `LOG_TIME`

-   `rel` (default) - Logs time elapsed since logger initialization
-   `abs` - Logs absolute time in ISO 8601 format

### Tests

    $ npm test

Project cross-browser compatibility supported by:

<a href="https://browserstack.com"><img src="https://bstacksupport.zendesk.com/attachments/token/Pj5uf2x5GU9BvWErqAr51Jh2R/?name=browserstack-logo-600x315.png" height="150" /></a>

[nix-build-image]: https://semaphoreci.com/api/v1/medikoo-org/log/branches/master/shields_badge.svg
[nix-build-url]: https://semaphoreci.com/medikoo-org/log
[win-build-image]: https://ci.appveyor.com/api/projects/status/jmw8p7g98x83itr0?svg=true
[win-build-url]: https://ci.appveyor.com/project/medikoo/log
[cov-image]: https://img.shields.io/codecov/c/github/medikoo/log.svg
[cov-url]: https://codecov.io/gh/medikoo/log
[transpilation-image]: https://img.shields.io/badge/transpilation-free-brightgreen.svg
[npm-image]: https://img.shields.io/npm/v/log.svg
[npm-url]: https://www.npmjs.com/package/log