== why another logging library?

This one is geared specifically towards k8s deployed applications. That means it needs to self configure from external configuration, it always writes to the console, it always handles context, and log priorities are whatever the hell i want them to be and are not restricted to numbers (really bunyan? that is so utterly daft) or some arbitrary enforced step-grade (aka winston and everything else).

• connect-logging always logs to the console.
• the you tell it the log priority names you want to turn off, not the ones you want to turn on
• log priorities are arbitrary but several are set up for you
• each logger stores context, you create loggers, store context in them and then let them disappear when you have finished.
• for convenience you get three modes, pretty print, pretty json or json, with json being the default
• we expect the format of java loggers - i.e. {} in place of values because then we don't bother evaluation it and writing it if we aren't writing that log priority. aka: don't use the back-tilde format or other such malarky.
• works in javascript or typescript (first class).

==== getting a logger

[source,typescript]

const x = ConnectLogger.createLogger(path);

path is the name you wish to give to your logger, it allows the logging to be excluded and gives more information when trying to find logs relating to a specific issue. It turns up as 'path' in your JSON logs.

==== adding context

calling context will merge with what is there. it returns the logger so you can log in chain mode.

x.context({someValue: 'hello})

calling context with null will wipe it out (why else would you call with null? that would be silly.)

x.context(null)

==== logging

trace/debug/info/warn/error/rest - and priority('name', ....)

Loggers can now be chained, which is useful for push/pop below.

x.info('there is a {} at the end of my ${} {}', 'fish', 300, 'hook');

==== logging exceptions

We expect the last parameter to be an exception if there is one. It will always be checked to see even if it matches the number of parameters. e.g. if you have the following

x.error('there is an error! {}', e)

then toString() will be called on e to make up the string, but the last parameter will always be checked to see if it is an exception, and if so, it will add an extra field called "stack_trace".

==== undefined, null, etc

The library will deal with parameters that are undefined or null by inserting them in \<<undefined>>, etc tags. If it cannot "toString" the exception is caught and a sensible value inserted.

==== push/pop contexts

Sometimes you may wish to create a local version of your unit's logger, so you can now do

push({'request-id': '12344'}).debug('some thing').pop()

This avoids having to create a new logger each time.

==== configuration

As connect-config-loader uses this for logging, config is by environment variable only.

• CONNECT_LOG_STYLE = pretty, pretty-json, json with json being default.
• CONNECT_LOG_EXCLUDES = any of the priorities, comma separated to exclude those priorities
• CONNECT_LOG_PATH = any of the names that get passed when creating a logger.

e.g.

in your environment:

CONNECT_LOG_STYLE=pretty CONNECT_LOG_EXCLUDES=trace,rest CONNECT_LOG_PATHS=this-library,that-library

vs (in your yml config)

connect-logging: style: "pretty" exclude: "trace,rest"