Twig

Opinionated minimal logging inspired by and compatible with node-bunyan

---

Features

• JSON formatted, bunyan-conformant log entries
• asynchronous logging, powered by Kovenant and Disruptor
• console only by default
• easily extendable and customisable via simple Appender interface
• startup configuration via optional environment variables

Basic

Having a TestObject

object TestObject {
    val logger: Logger = Logger(this)

    fun dummyFunction() {
        logger.info("dummy")
    }
}

and calling its dummyFunction will result in a log entry similar to

{"hostname":"vyo-pc","pid":6484,"thread":"Thread[main,5,]","time":"2015-11-30T18:55:35.092Z","level":30,"name":"io.github.vyo.twig.TestObject@12aba81","msg":"dummy","v":0}

Custom Fields

You may pass in an arbitrary number of Pair<String, Any> to create additional custom log entry fields

logger.info("dummy", Pair("my custom field", "my custom content"), Pair("my logger", logger))

{"hostname":"vyo-pc","pid":6156,"thread":"Thread[main,5,]","time":"2015-11-30T19:09:58.507Z","level":30,"name":"io.github.vyo.twig.TestObject@16e898f","msg":"dummy","my custom field":"my custom content","my logger":"io.github.vyo.twig.logger.Logger@1a97992","v":0}

Auto-expanded Throwables

You may pass throwables, i.e. exceptions and errors, and they will be automatically expanded to both a short message and an accompanying stacktrace.

Stacktraces will only be logged out at DEBUG level (configurable) or below. They will be put into a custom field called 'stacktrace' in the form of an array.

val logger = Logger("twig")

try {
    Integer.parseInt("not an int")
} catch (e: Exception) {
    logger.error(e)
    logger.debug(e)
}

will lead to

{"hostname":"vyo-pc"","pid":6580,"thread":"Thread[main,5,]","time":"2015-11-30T19:38:45.037Z","level":50,"name":"twig","msg":"java.lang.NumberFormatException: For input string: \"not an int\"","v":0}
{"hostname":"vyo-pc"","pid":6580,"thread":"Thread[main,5,]","time":"2015-11-30T19:38:45.037Z","level":20,"name":"twig","msg":"java.lang.NumberFormatException: For input string: \"not an int\"","stacktrace":["java.lang.NumberFormatException.forInputString(NumberFormatException.java:65)","java.lang.Integer.parseInt(Integer.java:580)","java.lang.Integer.parseInt(Integer.java:615)"],"v":0}

Bunyan CLI

Piped into the bunyan cli the preceding log entry will be pretty-printed like this

[2015-11-30T19:09:58.507Z]  INFO: io.github.vyo.twig.TestObject@16e898f/6156 on vyo-pc: dummy (thread=Thread[main,5,], my custom field="my custom content", my logger=io.github.vyo.twig.logger.Logger@1a97992)

Configuration

Note: You may configure global options by referencing either Logger.* or Logger.global.*.

The configuration is logged on startup; by default

• the global log level will be INFO,
• the worker amount will be set to the system's available processors,
• the log queue size will be set to 1024,
• throwables will be auto-expanded at DEBUG level or below,
• and auto-expanded throwables will come with a stacktrace of 50 lines at most.

{"hostname":"vyo-pc","pid":1144,"thread":"Thread[main,5,]","time":"2015-11-30T19:36:28.220Z","level":30,"name":"twig","msg":"logging worker count: 4","v":0}
{"hostname":"vyo-pc","pid":1144,"thread":"Thread[main,5,]","time":"2015-11-30T19:36:28.220Z","level":30,"name":"twig","msg":"logging work queue size: 1024","v":0}
{"hostname":"vyo-pc","pid":1144,"thread":"Thread[main,5,]","time":"2015-11-30T19:36:28.220Z","level":30,"name":"twig","msg":"global log level: INFO","v":0}
{"hostname":"vyo-pc"","pid":6580,"thread":"Thread[main,5,]","time":"2015-11-30T19:38:45.037Z","level":30,"name":"twig","msg":"throwable expansion level: DEBUG","v":0}
{"hostname":"vyo-pc"","pid":6580,"thread":"Thread[main,5,]","time":"2015-11-30T19:38:45.037Z","level":30,"name":"twig","msg":"throwable expansion depth: 50","v":0}

Setting up the following environment variables in advance

TWIG_LEVEL=TRACE
TWIG_QUEUE=64
TWIG_WORKERS=1
TWIG_EXPANSION_LEVEL=TRACE
TWIG_EXPANSION_DEPTH=100

{"hostname":"vyo-pc"","pid":6580,"thread":"Thread[main,5,]","time":"2015-11-30T19:38:45.037Z","level":30,"name":"twig","msg":"global log level TRACE","v":0}
{"hostname":"vyo-pc"","pid":6580,"thread":"Thread[main,5,]","time":"2015-11-30T19:38:45.037Z","level":30,"name":"twig","msg":"logging work queue size: 64","v":0}
{"hostname":"vyo-pc"","pid":6580,"thread":"Thread[main,5,]","time":"2015-11-30T19:38:45.037Z","level":30,"name":"twig","msg":"logging worker count: 1","v":0}
{"hostname":"vyo-pc"","pid":6580,"thread":"Thread[main,5,]","time":"2015-11-30T19:38:45.037Z","level":30,"name":"twig","msg":"throwable expansion level: TRACE","v":0}
{"hostname":"vyo-pc"","pid":6580,"thread":"Thread[main,5,]","time":"2015-11-30T19:38:45.037Z","level":30,"name":"twig","msg":"throwable expansion depth: 100","v":0}

Re-assigning the global log level or appender will also be logged

Logger.global.appender = ConsoleAppender()
Logger.global.level = Level.WARN

{"hostname":"vyo-pc"","pid":6364,"thread":"Thread[main,5,]","time":"2015-11-30T19:40:36.876Z","level":30,"name":"twig","msg":"global appender io.github.vyo.twig.appender.ConsoleAppender@1ae6ba4","v":0}
{"hostname":"vyo-pc"","pid":6364,"thread":"Thread[main,5,]","time":"2015-11-30T19:40:36.876Z","level":30,"name":"twig","msg":"global log level WARN","v":0}

You may also specify your own serialiser function if the built in JSON-serialiser does not fit your needs.

####Default (built in):

Logger.global.serialiser = Logger.global.simpleSerialiser

####Jodd:

val jodd = JsonSerializer()
Logger.global.serialiser = { any: Any -> jodd.serialize(any) }

####Jackson:

val jackson = ObjectMapper()
Logger.global.serialiser = { any: Any -> jackson.writeValueAsString(any) }

####Custom function:

fun customToJson( any: Any) : String {
    return any.toString()
}
Logger.global.serialiser = { any: Any -> customToJson(any) }

// or:

val lambdaJson = { any: Any -> any.toString() }
Logger.global.serialiser = { any: Any -> lambdaJson(any) }

// or:
Logger.global.serialiser = { any: Any -> any.toString() }

Note: You should ensure that your custom function produces valid JSON. You may also want to have arrays and collections be automatically expanded, especially when making use of Twig's auto-expanded throwables.

Note: Google's GSON seems to be unable to handle cyclic references, making it unsuitable for Twig for the time being.

Per-logger settings:

Log level, appender and serialiser can be set globally, as well as individually for each logger:

val loggerOne = Logger("one")
val loggerTwo = Logger("two")

loggerOne.level = Level.WARN
loggerTwo.level = Level.INFO

loggerOne.appender = FileAppender()
loggerTwo.appender = ConsoleAppender()

loggerOne.serialiser = Logger.simpleSerialiser
loggerTwo.serialiser = { any: Any -> any.toString() }

Exception Behaviour

If an exception occurs during the actual logging process, e.g. because the underlying Appender fails, we try to log a diagnostic entry to STDERR

logger.fatal("exceptional")

{"hostname":"vyo-pc","pid":3092,"thread":"Thread[main,5,]","time":"2015-11-30T19:47:15.128Z","level":60"name":"io.github.vyo.twig.logger.Logger@50ea2a","msg":"logging failed: null","original level":30,"original name":"io.github.vyo.twig.TestObject@970b10","original message":"exceptional","v":0

Notes

This project adheres to the semantic versioning and change log guidelines.

Author

Manuel Weidmann (@vyo)

License

ISC License