Logging

The Basics

Logging with Clog is simple. Simply pick your logging priority and call that static method with the data you want to log. Clog will figure out the rest. The most basic log looks like this:

Clog.log("Hello World");

Clog has six built-in priorities, but can support as many or as few as you need. Those six priorities, from lowest to highest, are listed in the table below. In addition to those six priorities, there is a default logger which will be used in the case that a logger for a priority is not defined, and you can define your own custom logging priorities and refere to them by their key.

For each of the above priorities, there are six logging methods that can be used, described below. Here, I use all with the 'log' priority, but all priorities and custom loggers support the same API:

log(Throwable throwable)

log(String tag, Throwable throwable)

log(String message, Object... args)

log(String tag, String message, Object... args)

log(String formatString, Throwable throwable, Object... args)

log(String tag, String formatString, Throwable throwable, Object... args)

Default Tag

Each message will be logged with a tag. If no tag is supplied to the logging method, then Clog will use a default tag. Any string can be used as a tag, but it should be kept short. The Android Log, which this library is inspired by, puts a strict limit of 26 characters on a tag, but no such limit is used with Clog. The default tag can be set with setDefaultTag(String), but if the default tag is null, Clog will attempt to find the caller's simple class name and use that as the tag.

Custom Loggers

By default, Clog has only a single logger implemented, which is a wrapper around System.out.println() which concatenates the tag and message. For any large applications, you will want to replace this basic logger with wrappers around your standard or more powerful logging libraries.

See Clog for Android and Clog4j for specialized Clog implementations

The simple way to use your custom loggers is to add it directly to Clog. You can also set up multiple profiles, each with their own set of loggers (see below for more on profiles). A custom logger is any class that implements the ClogLogger interface, which has the following methods:

boolean isActive()

int log(String tag, String message)

int log(String tag, String message, Throwable throwable)

To add your custom logger to Clog, call addLogger with your key and an instance of your custom logger, or set it as the default with setDefaultLogger. Loggers can be removed with removeLogger. Below is an example of how to add and use your custom loggers.

MyLogger myLogger = new MyLogger();

// set it as a fully custom logger
Clog.addLogger("loggerKey", myLogger);
Clog.logger("loggerKey", "Hello world");

// set it as a priority logger
Clog.addLogger(KEY_I, myLogger);
Clog.i("Hello world");

// set it as the default logger
Clog.setDefaultLogger(myLogger);
// OR
Clog.addLogger(null, myLogger);
Clog.log("loggerKey", "Hello world");

Multiple Environments

Under the hood, the String formatter and all loggers are held within instances of Clog objects, which are then access through a static hashmap of all available instances. This means you can set up a profile with all your desired loggers and parsers, and switch between profiles at will. Below is an example of setting up and using a custom profile, which is based on the Android Clog library's implementation.

// Create your clog profile with its loggers and chosen String formatter (see below)
ClogFormatter formatter = new Parseltongue();
Map<String, ClogLogger> loggers = new HashMap<String, ClogLogger>();
loggers.put(null, new ClogI());
loggers.put("d", new ClogD());
loggers.put("e", new ClogE());
loggers.put("i", new ClogI());
loggers.put("v", new ClogV());
loggers.put("w", new ClogW());
loggers.put("wtf", new ClogWTF());

Clog dev = new Clog(loggers, formatter);

Clog.addProfile("dev", dev); //add the profile to clog
Clog.setCurrentProfile("dev"); //sets the current profile to "dev"
Clog.setCurrentProfile(dev, "dev"); //Adds the profile to clog and switch to use it

Formatters

Clog is designed to make logging easier by allowing messages to be formatted with various arguments. It comes with my custom formatting language, Parseltongue, but the formatter implementation is separated out as in interface so you can use any formatter you wish. A custom formatter is any class that implements the ClogFormatter interface, which has the following method:

String format(String message, Object... params)

Custom formatters can be supplied to the profile as shown above, or added directly to the current profile with the setFormatter(ClogFormatter) method.