easy-log

One debugging logger to rule them all

Usage no npm install needed!

<script type="module">
  import easyLog from 'https://cdn.skypack.dev/easy-log';
</script>

README

easy-log

basic_example

A debugging module that grew out of a dissatisfaction of all other current modules for logging and debugging. Features all other dubugging features I could find, and some additional configurations, stack tracing, and options.

Notice that this package is still not officially released, and is under heavy development. All releases should be stable, but are currently only tested on a Mac, use at your own risk, currently

Installation

npm i easy-log

Usage

Using const logger = require('easy-log')('app') exposes a function that will name-space a logging function, which means the specified logger will only output when that name-space is specified, either in code or in the run script. Each logger is highly customizable, individually of each other. You can set, change, and toggle colors, formatting, stack tracing, and even the entire logger itself. Read on for specific syntax and example of how to do so.

Base Example

A basic use case with a few different name-spaced loggers, and a couple different files

Example app.js

const express = require('express')
    , basicLogger = require('easy-log')('app:basic', { colorCode: 199 })
    , dbLogger = require('easy-log')('app:db:', { colorCode: 226 })
    , mongoose = require('mongoose');

const app = express();
const name = "Example Application";

basicLogger(`Booting ${name}`);

mongoose.connect("mongodb://localhost/example", { useNewUrlParser: true })
    .then(() => { dbLogger(`Mongod DB connected successfully`); })
    .catch((err) => { dbLogger(`Mongo DB could not connect: ${err}`); });

const port = process.env.PORT || 3000;

app.listen(port, () => { basicLogger(`App listening on port ${port}`); });

// Use some imaginary worker file
require('./worker');

Example worker.js

const dbLogger = require('easy-log')('app:db', { colorCode: 40 })
    , basicLogger = require('easy-log')('app:basic', { colorCode: 45 });

function dbWork() {
    dbLogger('doing lots of uninteresting database work');
    setTimeout(dbWork, Math.random() * 1000);
}

dbWork();

function basicWork() {
    basicLogger('doing some basic work:b');
    setTimeout(basicWork, Math.random() * 2000);
}

basicWork();

run DEBUG=app:* node app.js

Result

basic_example

Features

Name Spaces

When you create a logger, simple pass it a namespace as well, and it will only output when that namespace is specified either in code or in the run script.

const logger = require('easy-log')(); // Will default to '' and will always work
const logger2 = require('easy-log')('debugging') // Now will only output when the 'debugging' namespace is enabled

Note that a logger without a namespace will always output, and in fact, cannot be turned off.

Enabling/Disabling namespaces

When you want to enable or disable a namespace you currently have two options.

In code:

logger.enable();
logger.disable();

With run script

Enabling a namespace

DEBUG=debugging

// OR

DEBUG=debugging,other-namespace

// OR

DEBUG=debugging other-namespace

Notice the runs script can set the DEBUG environmental variable(s) with commas, or spaces.

Specifically Disabling a namespace

DEBUG=debugging,-other-namespace

The - tells the logger to disable. If you put DEBUG=debugging,-debugging, the last one gets run last and so the debugging namespace logger will not work. This works really well in conjunction with wildcards.

Wildcards

Instead of enabling every namespace, or listing every one in the run script, you can use wildcards. Wildcards can only be added in the run scripts

DEBUG=* // Will run every namespace (including some global node ones you might not want)

DEBUG=app:* // Will run every namespace that is a child of `app` (`app:db`, `app:error`, etc)

DEBUG=app:*,-app:db // Will run every namespace that is a child of `app` EXCEPT `app:db`

Stack Tracing

You may have noticed that each logger almost looks like a error stack trace. This is intentional and the default behaviour, although it can be overridden. This is to give the developer more information about the program and where each output log is coming from, allowing them to trace through the program with ease.

stack_tracing

Formatting

You also may have noticed that every logger lines up, right aligned. This makes it easier to ready, and currently is the default and only behaviour, but if it is not suitable for your use case, please submit a feature request on github and I will make a way to configure it.

Options (colors and stack tracing)

When a logger is created, you can also pass it a set of options that will change how the logger acts. Right now these can only be configures when the logger is created. Below is a list of current options and what they do.

const logger = require('easy-log')('app', { colorCode: 201, includeLineNumber: false });
colorCodeInteger (supported ones)Specify a color for the logger{ colorCode: 201 }Calculated from namespace string
includeFunctionBooleanWhether to list the function where the logger was called{ includeFunction: false }true
includeFileBooleanWhether to list the file where the logger was called{ includeFunction: false }`true`
includeLineNumberBooleanWhether to list the line where the logger was called{ includeFunction: false }true

**That's it! So far this is what I have. Beware, this is not yet tested on windows, linux, or browsers, and I may need to tweak things to make those all work. Once I do, I will realease the first 'real' version (1.0.0). Until then, it should be stable, at least on Mac and in Node.js.

If you have a feature suggestion PLEASE let me know so I can incorporate it as quickly as possible. You can do so on my github, by following the Collaborating Guidelines I have and using the issue template I created: Ask for a new feature

Color Codes

Below is a table of supported color codes for you to choose from when configuring colors

20 21 26 27 32 33 38
39 40 41 42 43 44 45
56 57 62 63 68 69 74
75 76 77 78 79 80 81
92 93 98 99 112 113 128
129 134 135 148 149 160 161
162 163 164 165 166 167 168
169 170 171 172 173 178 179
184 226 185 196 197 198 199
200 201 202 203 204 205 206
207 208 209 214 215 220 221