User manual

First steps

Download the tinylog JAR
Add the JAR to your classpath

Use the logger:

import org.pmw.tinylog.Logger;
 
public class Application {
 
   public static void main(final String[] args) {
      Logger.info("My first log entry");
   }
 
}

Logging methods

tinylog supports five logging levels: TRACE < DEBUG < INFO < WARNING < ERROR. By default only log entries with the logging level INFO and higher (INFO, WARNING and ERROR) are output and all other log entries (TRACE and DEBUG) ignored.

Examples for the logging methods:

try {
   Logger.info("Try to divide {0} by {1}", a, b);
   int d = a / b;
   Logger.trace("Division was successful");
} catch (ArithmeticException ex) {
   Logger.error(ex, "Div {0} by {1} failed", a, b);
} catch (Exception ex) {
   Logger.error(ex);
}

There are three logging methods for each logging level:

One for a message string(-pattern) with optional arguments
One for an exception
And finally a mixed one for an exception with a message string(-pattern) and optional arguments

A message string pattern is compatible with MessageFormat.format(String, Object...).

	Methods
TRACE	Logger.trace(String message, Object... arguments) Logger.trace(Throwable exception) Logger.trace(Throwable exception, String message, Object... arguments)
DEBUG	Logger.debug(String message, Object... arguments) Logger.debug(Throwable exception) Logger.debug(Throwable exception, String message, Object... arguments)
INFO	Logger.info(String message, Object... arguments) Logger.info(Throwable exception) Logger.info(Throwable exception, String message, Object... arguments)
WARNING	Logger.warn(String message, Object... arguments) Logger.warn(Throwable exception) Logger.warn(Throwable exception, String message, Object... arguments)
ERROR	Logger.error(String message, Object... arguments) Logger.error(Throwable exception) Logger.error(Throwable exception, String message, Object... arguments)

Configuration

tinylog can be configured by code statements, properties and/or a property file. Properties can be set as VM argument with the "-D" prefix as it's usual in Java. A property file must have the filename "tinylog.properties" and be placed in the default package.

Locale

The locale is used e.g. for formatting numbers and dates. If not set or set to "null", the default locale of the JVM is used.

	Definition	Example
Java code	Logger.setLocale(Local locale)	Logger.setLocale(Locale.US);
Property	tinylog.locale=<locale>	tinylog.locale=en_US
VM argument	-Dtinylog.locale=<locale>	-Dtinylog.locale=en_US

Logging format

The logging format is a pattern that describes the format of log entries. The default pattern is "{date:yyyy-MM-dd HH:mm:ss} [{thread}] {class}.{method}()\n{level}: {message}".

Placeholder	Description
{class}	Fully-qualified class name where the logging request is issued
{date}	Date and time of the logging request Optionally there can be a date format pattern like "{date:yyyy-MM-dd HH:mm:ss}". This pattern is compatible with SimpleDateFormat.
{file}	Filename of the Java source file from where the logging request is issued
{level}	Logging level of the created log entry
{line}	Line number from where the logging request is issued
{message}	Associated message of the created log entry
{method}	Method name from where the logging request is issued
{thread}	Name of the current thread

	Definition	Example
Java code	Logger.setLoggingFormat(String format)	Logger.setLoggingFormat("{level}: {class}.{method}()\t{message}");
Property	tinylog.format=<format pattern>	tinylog.format={level}: {class}.{method}()\t{message}
VM argument	-Dtinylog.format=<format pattern>	"-Dtinylog.format={level}: {class}.{method}()\t{message}"

Logging level

tinylog supports five logging levels: TRACE < DEBUG < INFO < WARNING < ERROR. The default logging level is INFO. This means that only log entries with the logging level INFO and higher (INFO, WARNING and ERROR) are output and all other log entries (TRACE and DEBUG) ignored. To disable the logging set the logging level to OFF.

	Definition	Example
Java code	Logger.setLoggingLevel(LoggingLevel level)	Logger.setLoggingLevel(LoggingLevel.DEBUG);
Property	tinylog.level=<logging level>	tinylog.level=debug
VM argument	-Dtinylog.level=<logging level>	-Dtinylog.level=debug

Logging level depending on package

If required special logging levels for packages can be set. This overrides the default logging level for the package.

	Definition	Example
Java code	Logger.setLoggingLevel(String packageName, LoggingLevel level)	Logger.setLoggingLevel("org.pmw.tinylog", LoggingLevel.TRACE);
Property	tinylog.level:<package name>=<logging level>	tinylog.level:org.pmw.tinylog=trace
VM argument	-Dtinylog.level:<package namel>=<logging level>	-Dtinylog.level:org.pmw.tinylog=trace

Max. number of stack trace elements

Limit the number of lines of output stack traces from exceptions. The default is "40" and can be set to "0" to disable stack traces and to "-1" for no limitation.

	Definition	Example
Java code	Logger.setMaxStackTraceElements(int maxStackTraceElements)	Logger.setMaxStackTraceElements(100);
Property	tinylog.stacktrace=<limit>	tinylog.stacktrace=100
VM argument	-Dtinylog.stacktrace=<limit>	-Dtinylog.stacktrace=100

Writer

A writer outputs created log entries (e.g. to a log file or to the console). All log entries are written by default into the console. tinylog contains already three writers.

Writer	Name	Description
ConsoleWriter	console	Writes log entries into the console (uses System.err for warnings and errors and System.out for other logging levels)
FileWriter	file	Writes log entries into a file
RollingFileWriter	rollingfile	Like FileWriter but it uses multiple files by rotating them
null	null	Discards all log entries

You can program your own writer by implementing the interface LoggingWriter.

	Definition	Example
Java code	Logger.setWriter(LoggingWriter writer)	Logger.setWriter(new FileWriter("log.txt"));
Property	tinylog.writer=<name> tinylog.writer.filename=<log file>	tinylog.writer=file tinylog.writer.filename=log.txt
VM argument	-Dtinylog.writer=<name> -Dtinylog.writer.filename=<log file>	-Dtinylog.writer=file -Dtinylog.writer.filename=log.txt

Policies

The RollingFileWriter supports policies, which can be used to define when the RollingFileWriter has to start a new log file. You can use one policy as well as multiple policies.

Policy	Name	Description
StartupPolicy	startup	Creates a new log file at every startup of the application (e.g. "startup")
SizePolicy	size	Creates a new log file when the current log file reaches the defined file size (e.g. "size: 32KB")
HourlyPolicy	hourly	Creates hourly a new log file (e.g. "hourly" after each hour uptime, or "hourly: true" for each full hour)
DailyPolicy	daily	Creates daily a new log file (e.g. "daily" after each day uptime, or "daily: 00:00" for each day at midnight)
WeeklyPolicy	weekly	Creates weekly a new log file (e.g. "weekly" after each week uptime, or "weekly: monday" starts a new log file each Monday morning at 00:00 clock)
MonthlyPolicy	monthly	Creates monthly a new log file (e.g. "monthly" after each month uptime, or "monthly: true" for each first of a month)
YearlyPolicy	yearly	Creates yearly a new log file (e.g. "yearly" after each year uptime, oder "yearly: january" starts always a new log file at the beginning of a new year)

It is also possible to program own policies by implementing the interface Policy.

Labellers

The RollingFileWriter supports labellers to name archived log files by a specified schema.

Labeller	Name	Description
CountLabeller	count	Numbers the backups sequentially (e.g. "log.0.txt" for the newest, "log.1.txt" for the second newest etc.)
TimestampLabeller	timestamp	Adds a timestamp to the filename (e.g. "log.2012-08-20 08-22-31.txt") The timestamp can be defined by a date pattern (e.g. "timestamp: yyyy-MM-dd HH-mm-ss"). The date pattern is compatible with SimpleDateFormat.

Own labellers are supported and have just to implement the interface Labeller.

	Definition	Example
Java code	Logger.setWriter(LoggingWriter writer)	Logger.setWriter(new RollingFileWriter( "log.txt", // Verwende die Datei "log.txt" 2, // Behalte zwei Backups new CountLabeller(), new StartupPolicy(), new SizePolicy(10 * 1024) ));
Property	tinylog.writer=<name> tinylog.writer.filename=<log file> tinylog.writer.backups=<number of backups> tinylog.writer.label=<name of labeller> tinylog.writer.policies=<policies>	tinylog.writer=rollingfile tinylog.writer.filename=log.txt tinylog.writer.backups=2 tinylog.writer.label=count tinylog.writer.policies=startup, size: 10KB
VM argument	-Dtinylog.writer=<name> -Dtinylog.writer.filename=<log file> -Dtinylog.writer.backups=<number of backups> -Dtinylog.writer.label=<name of labeller> -Dtinylog.writer.policies=<policies>	-Dtinylog.writer=rollingfile -Dtinylog.writer.filename=log.txt -Dtinylog.writer.backups=2 -Dtinylog.writer.label=count -Dtinylog.writer.policies=startup, size: 10KB

Writing Thread

Writers can be executed in a separate thread. This has the advantage that the application itself is not blocked by slow IO operations. By default the writing thread is running with low priority (2) and terminates automatically when the main thread is finished.

	Definition	Example
Java code	Logger.startWritingThread() Logger.startWritingThread(String threadName, int priority)	Logger.startWritingThread(); Logger.startWritingThread("main", 2);
Property	tinylog.writingthread=<true or false> tinylog.writingthread.observe=<thread to wait for> tinylog.writingthread.priority=<priority of the writing thread>	tinylog.writingthread=true tinylog.writingthread.observe=main tinylog.writingthread.priority=2
VM argument	-Dtinylog.writingthread=<true or false> -Dtinylog.writingthread.observe=<thread to wait for> -Dtinylog.writingthread.priority=<priority of the writing thread>	-Dtinylog.writingthread=true -Dtinylog.writingthread.observe=main -Dtinylog.writingthread.priority=2