refcodes-logger: Fancy runtime-logs and highly scalable cloud logging

README

“The REFCODES.ORG codes represent a group of artifacts consolidating parts of my work in the past years. Several topics are covered which I consider useful for you, programmers, developers and software engineers.”

Update [2018-06-09@10:41]: The RuntimeLogger is now configured with a runtimelogger.* file (where * stands for the ini, toml, yaml, json, xml or properties suffixes) instead of the runtimelogger-config.xml files used by previous versions of the refcodes-logger artifact. This applies when using the RuntimeLoggerFactoryImpl or the RuntimeLoggerFactorySingleton factory to create your RuntimeLogger instances. The article has been updated accordingly.

What is this repository for?

“… An introduction to the refcodes-logger framework; let’s start with giving your logs some color and tidy them up! Then let’s take over spring-boot’s log output …” [Logging like the nerds log, 04/04/2015]

The refcodes-logger artifact provides the refcodes-logging framework for flexible logging of any data to any data sink (including files, databases or the console provided as alternate implementations).

The refcodes-logger artifact supports straight forward, composite (clustering) or partitioning functionality as implementations of the Logger type. The REFCODES.ORG runtime logger RuntimeLogger integrates with SLF4J seamlessly and also acts as an alternative to to SLF4J.

The RuntimeLogger implementations are being configured with a Logger implementation. In your code, you use the RuntimeLogger type which, depending on you configuring it, logs to a SimpleDB cluster, the console (with ANSI escape sequence support) or any I/O device as well as to an SLF4J logger.

Being an alternative to SLF4J, the RuntimeLogger’s architecture settles upon the much more generic Logger; which actually can be used to log high volume logs of any data type and not being restricted to runtime logs. The RuntimeLogger implementations add functionality not found in other logging frameworks (logging out the class- and method-names of the logging methods without any configuration or additional lines of code)

How do I get set up?

To get up and running, include the following dependency (without the three dots “…”) in your pom.xml:

1
2
3
4
5
6
7
8
9
<dependencies>
	...
	<dependency>
		<artifactId>refcodes-logger</artifactId>
		<groupId>org.refcodes</groupId>
		<version>2.1.1</version>
	</dependency>
	...
</dependencies>

The artifact is hosted directly at Maven Central. Jump straight to the source codes at Bitbucket. Read the artifact’s javadoc at javadoc.io.

How do I get started?

You configure your RuntimeLoggerFactoryImpl (and the RuntimeLoggerFactorySingleton sub-class) by providing a runtimelogger.ini file (also supported are *.toml, *.yaml, *.xml, *.properties or *.json notations) in one of those locations relative to your main class’s location:

.
./config
./etc
./settings
./.config
./.settings
../config
../etc
../settings
../.config
../.settings

Given your main class’s JAR file resides in the folder /opt/app/lib, then the valid locations for the runtimelogger.ini file are:

/opt/app/lib
/opt/app/lib/config
/opt/app/lib/etc
/opt/app/lib/settings
/opt/app/lib/.config
/opt/app/lib/.settings
/opt/app/config
/opt/app/etc
/opt/app/settings
/opt/app/.config
/opt/app/.settings

(see also the class ConfigLocator.ALL which is used to identify the configuration’s location)

In case you pass a JVM argument via -Dconfig.dir=path_to_your_config_dir (where path_to_your_config_dir stands for the path to the directory where you placed configuration files such as the runtimelogger.ini file), then your path_to_your_config_dir is placed first in the list of configuration directories to look at (in case the directory exists). See SystemProperty.CONFIG_DIR as well as ConfigLocator.ALL.

Use the JVM argument -Dconfig.dir=path_to_your_config_dir for your custom runtimelogger.ini configuration folder.

The runtimelogger.ini configuration is deadly simple:

1
2
3
4
5
6
7
8
9
10
11
12
[root]

runtimelogger=org.refcodes.logger.RuntimeLoggerImpl
runtimelogger/logPriority=INFO
runtimelogger/logger=org.refcodes.logger.SystemLogger

[com.acme]

runtimelogger=org.refcodes.logger.RuntimeLoggerImpl
runtimelogger/logPriority=INFO
runtimelogger/name=com.acme
runtimelogger/logger=org.refcodes.logger.SystemLogger

The sections in squared braces (e.g. [com.acme]) represent the Java package for which the afterwards configured RuntimeLogger is responsible; e.g. a log issued from inside a class located in the package com.acme (or in one of its sub-packages) will be handled by the com.acme logger. In case no logger is found for a given package, then the root logger found below the [root] section is used. Useful to know that a logger for a package namespace is only created once.

If you like logs colored nicely with ANSI escape codes, then you will love the ConsoleLoggerSingleton:

1
2
3
4
5
[root]

runtimelogger=org.refcodes.logger.RuntimeLoggerImpl
runtimelogger/logPriority=INFO
runtimelogger/logger=org.refcodes.logger.alt.cli.ConsoleLoggerSingleton

Make sure to include the refcodces-logger-alt-console dependency in your build setup to include the ConsoleLoggerSingleton logger.

Supported notations

Below find the various supported notations by example. We configure a root logger as well as a logger for the package com.acme, both using the fancy ConsoleLoggerSingleton logger.

Please note that some notations use the this keyword to denote the value of the enclosing element as some notations do not support (or make it hard) to assign a value to an element which has child elements.