@eastsideco/escshopify/manual/utils/log.md

WIP JS library for Shopify, containing a variety of useful functionality.

# Utilities/Log

The Log util module provides a very basic logging framework for level and module-based logging. The log utility support custom loggers (i.e. to send logs via AJAX or to the DOM), and level-based muting (i.e. ignoring debug-level messages).

## Using SALVO
If you're using SALVO, a logger has already been configured for you - simple use salvo.log:

**ES6**:
```js
import salvo from 'salvo';

salvo.log.send(salvo.log.WARN, 'Example', 'This is an example message.');
```

## Log levels and tags
The log interface accepts three arguments: log level, tag, and message.

The log level is a description of the purpose and importance of the log message: DEBUG, INFO, WARN, ERROR, or FATAL. These constants are defined on the log instance, i.e. `log.DEBUG`, `log.WARN`, etc.

The log tag is a description of where the log message comes from. Typically, it should be the name of a component or class. Log tags help find track down log messages, or filter messages in the debugger. A common pattern is to have a TAG constant in your classes like so:

**ES6**:
```js
import log from 'log';

const TAG = 'ExampleComponent';

class ExampleComponent {
    constructor() {
        log.send(log.DEBUG, TAG, 'Created a new thing!');
    }
}
```

## Getting started
### Create a logging module
Create a module in your application which bootstraps logging like so:

**ES6**:
```js
// log.js
import {Log} from '@eastsideco/esc-shopify';
import ConsoleLogger from '@eastsideco/esc-shopify/src/utils/loggers/ConsoleLogger.js';

const log = new Log;
const defaultLogger = new ConsoleLogger();

log.addLogger(logger);

export default log;
```

You can then use the log like so:
```js
import log from 'log';

log.send(log.WARN, 'Example', 'This is an example message');
log.sendObject(log.DEBUG, 'Example', 'This is an example object', {
    test: 123
});
```

### Setting a log level
You can mute logging below a given level by calling `Log#setLogLevel`:
```js
if (!config.debug) {
    log.setLogLevel(log.WARN);
}
```



## Writing new loggers

A single log instance can write to multiple loggers. By default, the library provides a ConsoleLogger, which simply passes the log arguments on to window.console, but you can extend this if you need to display logs elsewhere for some reason.

**ES6**:
```js
// DOMLogger.js
import Logger from '@eastsideco/escshopify/src/utils/loggers/Logger.js';

export default class DOMLogger extends Logger {
    constructor(element) {
        this._element = element;
    }

    send(level, tag, text) {
        var child = document.createElement('p');
        child.classList.add('level-'+level);
        child.innerText = tag + ': ' + text;
        this._element.appendChild(child);
    }

    sendObject(level, tag, text, object) {
        this.send(level, tag, text + ' -- ' + JSON.stringify(object);
    }
}

// log.js
import {Log} from '@eastsideco/shopify';
import ConsoleLogger from '@eastsideco/shopify/src/utils/loggers/ConsoleLogger.js';
import DOMLogger from './DomLogger';

const log = new Log;
const defaultLogger = new ConsoleLogger;
const customLogger = new DOMLogger;

log.addLogger(defaultLogger);
log.addLogger(customLogger);

export default log;
```