gtlo
v0.9.1
Published
Get The Logs Out
Downloads
3
Maintainers
Readme
gtlo
A no-frills logging Typescript/Javascript library for NodeJs, because most of the times you just need to Get The Logs Out for something else to pick them up.
Features:
- log levels
- configurable level thresholds and formats
- lazy message string formatting, compatible with
console
methods - hierarchical named loggers, statically instantiated
- automatic configuration via environment and hot reconfiguration
- zero runtime npm dependencies
Getting started
Install gtlo
from npm.
Instantiate loggers via the static LoggerFactory
, giving a name string, or
even a class or function:
import { loggerFactory } from "gtlo";
class MyImportantClass {
private readonly logger = loggerFactory.getLogger(MyImportantClass);
// ...
}
Then log using format strings:
const answer = 42;
this.logger.info("The answers is %d.", answer);
With the builtin simple
format, this will print:
INFO MyImportantClass The answer is 42.
Lazy message interpolation is reasonably efficent, but it's also possible to actively check the level and avoid doing anything too expensive if it is going to be thrown away:
if (this.logger.level <= LogLevels.DEBUG) {
this.logger.debug("The details are %j", computeDetails());
}
Good logs take dedication, but that's 95% of the story. The rest is configuring things to get the desired output.
There's more that one way to provide configuration so that it will be picked up automatically.
The easiest is the GTLO
environment variable:
export GTLO='{"default": {"level": "INFO", "format": "simple", "output": "stderr"}}'
Using a GTLO_MODS
environment variable you can load json or javascript files:
export GTLO_MODS="mynpm/gtlo,$PWD/gtlo.json"
All configurations are merged in order (GTLO_MODS
, then GTLO
). If you
don't configure anything, loggers will behave exacly like the console
.
In the browser, global window
attributes serve in place of the environment.
Why another logging library?
Because we could not find a library that already had this set of features and not a lot more.
In the modern infrastructure the only thing you need to do is print to standard facilities. This code is meant to rely on the log management solution to store the logs and just be small and fast.
When running in a container, the log driver will probably add a timestamp on
each line, so the simple
format and stderr
output are enough.
When running in AWS Lambda, named
and console
will give great integration
with Cloudwatch.
Furthermore, we did not completely reinvent the wheel but took after the
designs of Slf4j, Python's logging
module and the javascript console
.
Advanced usage
Loggers hierarchy
Loggers can have a tree-like hierarchical structure, defined by dots in the name:
const logger = loggerFactory.getLogger("mypackage.mymodule");
const other = loggerFactory.getLogger("mypackage.myothermodule");
The loggers will use the most specific configuration provided at any level or ultimately use the defaults for the root logger.
Handlers
Log records are passed to a chain of handlers, usually made of two functions: one for formatting and the other for printing.
The available built in format handlers are:
none
named
: adds the logger namesimple
: adds the level and logger nametimed
: adds a timestamp, level and logger name
The built in outputs handlers are:
stdout
stderr
console
: default, uses stardard output or error depending on level
More configuration
An example of advanced setup that uses a javascript module to specify custom handlers is the following:
module.exports = {
handlers: {
utcTime: record => {
record.message = `[${new Date().toISOString().substring(11, 23)}] ${record.message}`
}
},
default: {
level: "DEBUG",
format: "utcTime", // handlers are referenced by name
output: "stdout"
},
loggers: {
mypackage: "WARNING", // the level can be configured very simply
"mypackage.important": { // more settings are available with an object
level: "INFO",
output: "stderr",
// if any handler is set, others are not inherited, so the format here becomes "none"
}
}
};
For very specific use cases it is also possible to add more handlers, either class or function based, but that's for people who look at the source code.
For unit tests, it makes sense to disable all logging:
export GTLO_MODS="" # If you are using mods
export GTLO='{"default": "DISABLED"}'
In production, configured levels can also be manipulated at runtime, but it will take some coding:
const loggers = loggerFactory.getAllLoggers(); // what's the situation?
loggerFactory.getLogger('please.stop').level = LogLevels.DISABLED);
loggerFactory.configure() // reapply previous configuration
Contributing
We are happy with how things are working now, but PRs are welcome, provided they keep with minimalist nature of the project.