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.

What is this repository for?

This artifact provides flexible logging of any data to any data sink (including files, databases or the console). It supports straight forward, composite (clustering) or partitioning functionality provided by different implementations of the Logger type. The RuntimeLogger type harnesses the Logger type for logging your runtime log messages and integrates with SLF4J seamlessly (and may also act as an alternative data sink to log to when using SLF4J.

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>3.3.8</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.

Introduction

The RuntimeLogger implementations are being configured with a Logger implementation. You may 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 or to an SLF4J logger. Being an alternative data sink for SLF4J, the RuntimeLogger type’s architecture settles upon a generic Logger type, which actually can be used to log high volume logs of any data type and not being restricted to runtime logs. Furthermore, the RuntimeLogger type adds functionality not found in other logging frameworks such as logging out the class- and method-names of the logging source without any configuration or additional lines of code.

See also Logging like the nerds log for a quick start on how to do fancy console logging of your application’s runtime logs!

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.console.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.