Flattr tinylog GitHub
  1. Configuration
    1. Properties file
    2. System properties
    3. Fluent API
  2. Settings
    1. Locale
    2. Logging format
    3. Logging level
    4. Stack traces
    5. Writers
      1. ConsoleWriter
      2. FileWriter
      3. JdbcWriter
      4. LogcatWriter
      5. RollingFileWriter
        1. Labelers
        2. Policies
      6. SharedFileWriter
    6. Writing thread

Configuration

There are three ways to configure tinylog: by a properties file, by system properties (can be set as "-D" parameter) and programmatically by a fluent API.

Properties file

In productive environments the recommended way to configure tinylog is the configuration of the logger by a properties file. The properties file should be named "tinylog.properties" and placed in the default package. In common IDEs like Eclipse and Netbeans, it is sufficient to put "tinylog.properties" into the "src/" folder or for Maven based projects into "src/main/resources".

If the properties file has another name or is placed somewhere else, the location can be set by the system property "tinylog.configuration" (e.g. "-Dtinylog.configuration=c:\conf\tinylog.properties"). Instead of a path to a local file, also a URL can be specify to load the configuration via network or internet since tinylog 1.2. An alternative way is to load properties files programmatically using the Configurator.

Example for a properties file:

tinylog.writer = file
tinylog.writer.filename = log.txt
tinylog.level = warning

If desired, tinylog can observe a properties file and apply changes automatically at runtime. For this purpose the property "tinylog.configuration.observe" must be set to "true". The property can easily be set in the properties file or passed as system property at startup.

In OSGi applications, such as Eclipse RCP, the easiest way is to create a fragment for the tinylog bundle and to put "tinylog.properties" in the default package of this fragment.

System properties

System properties are especially interesting for developers, because this way the configuration from a properties file can be overridden. In common IDEs, such as Eclipse and Netbeans, system properties can be easily passed as a "-D" parameter at startup. For example, system properties provide an easy way to activate trace and debug log entries in a productive environment and thus simplify finding a bug.

Example:

-Dtinylog.writer=file -Dtinylog.writer.filename=log.txt -Dtinylog.level=trace

Fluent API

In special cases it may be useful to configure tinylog programmatically or to change the configuration at runtime. For this purpose, there is a fluent API. This ensures that new configurations are always set atomically. This means that all changes will be activated at once, even in multithreaded programs. The class to configure tinylog is the Configurator.

Example:

Configurator.defaultConfig() .writer(new FileWriter("log.txt")) .level(Level.WARNING) .activate();

Configurator.defaultConfig() takes the default configuration and Configurator.currentConfig() the current configuration as basis.

Settings

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.

Properties Parameters Java Code

Definition:

tinylog.locale = <locale>

Example:

tinylog.locale = en_US

Definition:

-Dtinylog.locale=<locale>

Example:

-Dtinylog.locale=en_US

Method signature:

Configurator.locale(Locale locale)

Example:

Configurator.currentConfig() .locale(Locale.US) .activate();

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
{class_name} Class name (without package) where the logging request is issued
{context:key} Value from logging context ("key" should be replaced by the real key of the mapping)
{date} Date and time of the logging request
Optionally there can be a date format pattern such as "{date:yyyy-MM-dd HH:mm:ss}". This pattern is compatible with SimpleDateFormat. Since tinylog 1.3, you can also output microseconds and nanosecons on Java 9 in the same way as DateTimeFormatter does.
{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
{package} Package where the logging request is issued
{pid} Process ID of the application
{thread} Name of the current thread
{thread_id} ID of the current thread

Properties Parameters Java Code

Definition:

tinylog.format = <format pattern>

Example:

tinylog.format = {level}: {class}.{method}()\t{message}

Definition:

-Dtinylog.format=<format pattern>

Example:

"-Dtinylog.format={level}: {class}.{method}()\t{message}"

Method signature:

Configurator.formatPattern(String format)

Example:

Configurator.currentConfig() .formatPattern("{level}: {class}.{method}()\t{message}") .activate();

Optionally the minimum size of placeholders or group of placeholders can be defined. This is for example useful to format placeholders as columns.

Properties Parameters Java Code

Example:

tinylog.format = {{level}:|min-size=8} {message}

Example:

"-Dtinylog.format={{level}:|min-size=8} {message}"

Example:

Configurator.currentConfig() .formatPattern("{{level}:|min-size=8} {message}") .activate();

Since tinylog 1.1, it is possible to define the indentation level after new lines. This can be used for example to indent stack traces of exceptions by a defined number of spaces. Each tabulator at the beginning of a line will be replaced by the defined number of spaces, too. Thereby stack traces will be indented twice by the defined number of spaces and the description of (cause) exceptions once.

Properties Parameters Java Code

Example:

tinylog.format = {level}: {message|indent=4}

Example:

"-Dtinylog.format={level}: {message|indent=4}"

Example:

Configurator.currentConfig() .formatPattern("{level}: {message|indent=4}") .activate();

If multiple writers are used, it is possible to define particular logging formats for them.

Properties Parameters Java Code

Definition:

tinylog.writer* = <name>
tinylog.writer*.format = <format pattern>

Example:

tinylog.writer1 = console
tinylog.writer1.format = {level}: {message}

tinylog.writer2 = file
tinylog.writer2.filename = log.txt
tinylog.writer2.format = {class}.{method}()\t{message}

Definition:

-Dtinylog.writer*=<name>
-Dtinylog.writer*.format=<format pattern>

Example:

-Dtinylog.writer1=console
"-Dtinylog.writer1.format={level}: {message}"

-Dtinylog.writer2=file
-Dtinylog.writer2.filename=log.txt
"-Dtinylog.writer2.format={class}.{method}()\t{message}"

Method signature:

Configurator.writer(Writer writer, String formatPattern).addWriter(Writer writer, String formatPattern)

Example:

Configurator.currentConfig() .writer(new ConsoleWriter(), "{level}: {message}") .addWriter(new FileWriter("log.txt"), "{class}.{method}()\t{message}") .activate();

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) are ignored. The logging level OFF disables all kinds of logging.

Properties Parameters Java Code

Definition:

tinylog.level = <logging level>

Example:

tinylog.level = debug

Definition:

-Dtinylog.level=<logging level>

Example:

-Dtinylog.level=debug

Method signature:

Configurator.level(Level level)

Example:

Configurator.currentConfig() .level(Level.DEBUG) .activate();

If required, particular logging levels for packages or classes can be set. This overrides the default logging level.

Properties Parameters Java Code

Definition:

tinylog.level@<package or class> = <logging level>

Example:

tinylog.level@org.pmw.tinylog = trace

Definition:

-Dtinylog.level@<package or class>=<logging level>

Example:

-Dtinylog.level@org.pmw.tinylog=trace

Method signature:

Configurator.level(String packageOrClass, Level level)

Example:

Configurator.currentConfig() .level("org.pmw.tinylog", Level.TRACE) .activate();

If multiple writers are used, it is possible to define particular logging formats for them. In that case, these writers will only output log entries with the defined logging level or higher.

Properties Parameters Java Code

Definition:

tinylog.writer* = <name>
tinylog.writer*.level = <logging level>

Example:

tinylog.writer1 = console
tinylog.writer1.level = trace

tinylog.writer2 = file
tinylog.writer2.filename = log.txt
tinylog.writer2.level = info

Definition:

-Dtinylog.writer*=<name>
-Dtinylog.writer*.level=<logging level>

Example:

-Dtinylog.writer1=console
-Dtinylog.writer1.level=trace

-Dtinylog.writer2=file
-Dtinylog.writer2.filename=log.txt
-Dtinylog.writer2.level=info

Method signature:

Configurator.writer(Writer writer, Level level).addWriter(Writer writer, Level level)

Example:

Configurator.currentConfig() .writer(new ConsoleWriter(), Level.TRACE) .addWriter(new FileWriter("log.txt"), Level.INFO) .activate();

Stack traces

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

Properties Parameters Java Code

Definition:

tinylog.stacktrace = <limit>

Example:

tinylog.stacktrace = 100

Definition:

-Dtinylog.stacktrace=<limit>

Example:

-Dtinylog.stacktrace=100

Method signature:

Configurator.maxStackTraceElements(int maxStackTraceElements)

Example:

Configurator.currentConfig() .maxStackTraceElements(100) .activate();

Writers

A writer outputs created log entries (e.g. to a log file or to the console). All log entries are written to the console by default. Out of the box tinylog contains five different writers.

Writer Name Description
ConsoleWriter console Writes log entries to the console
FileWriter file Writes log entries to a defined file
JdbcWriter jdbc Stores log entries in a SQL database
LogcatWriter logcat Forwards log entries to Android's native logging system
RollingFileWriter rollingfile Like FileWriter but uses multiple files by rotating them
SharedFileWriter sharedfile Supports writing of multiple instances of a program to the same file
null null Discards all log entries

Properties Parameters Java Code

Definition:

tinylog.writer = <name or null>

Example:

tinylog.writer = console

Definition:

-Dtinylog.writer=<name or null>

Example:

-Dtinylog.writer=console

Method signature:

Configurator.writer(Writer writer)

Example:

Configurator.currentConfig() .writer(new ConsoleWriter()) .activate();

Multiple writers can be used in parallel. For example, it is possible to write log entries to the console and to a log file simultaneously.

Properties Parameters Java Code

Definition:

tinylog.writer* = <name>

Example:

tinylog.writer1 = console

tinylog.writer2 = file
tinylog.writer2.filename = log.txt

Definition:

-Dtinylog.writer*=<name>

Example:

-Dtinylog.writer1=console

-Dtinylog.writer2=file
-Dtinylog.writer2.filename=log.txt

Method signature:

Configurator.writer(Writer writer).addWriter(Writer writer)

Example:

Configurator.currentConfig() .writer(new ConsoleWriter()) .addWriter(new FileWriter("log.txt")) .activate();

Optionally, particular logging formats and/or logging levels can be defined for (some) writers.

ConsoleWriter

The ConsoleWriter is the default writer of tinylog and writes log entries to the console. By default, warnings and errors will be written to the error stream (System.err) and all other logging levels to the default output stream (System.out). Since tinylog 1.3, the console writer can also be configured to write all log entries to the same stream regardless of the logging level.

Properties Parameters Java Code

Definition:

tinylog.writer = <name>
tinylog.writer.stream = <stream> (optional)

Example:

tinylog.writer = console
tinylog.writer.stream = err

Definition:

-Dtinylog.writer=<name>
-Dtinylog.writer.stream=<stream> (optional)

Beispiel:

-Dtinylog.writer=console
-Dtinylog.writer.stream=err

Method signature:

Configurator.writer(Writer writer)

Example:

Configurator.currentConfig() .writer(new ConsoleWriter()) .activate();

FileWriter

The FileWriter writes log entries to a defined file. Optionally, the writing can be buffered. This will be significantly faster, especially in connection with activation of the writing thread. But buffered writing has the disadvantage that possibly the last - and thus the most important - log entries are lost after a crash of the JVM.

An already existing log file will be overwritten at startup by default. Since tinylog 1.1, it is possible to continue existing log files by enabling the append mode.

Properties Parameters Java Code

Definition:

tinylog.writer = <name>
tinylog.writer.filename = <log file>
tinylog.writer.buffered = <true/false> (default: false)
tinylog.writer.append = <true/false> (default: false)

Example:

tinylog.writer = file
tinylog.writer.filename = log.txt
tinylog.writer.buffered = true
tinylog.writer.append = false

Definition:

-Dtinylog.writer=<name>
-Dtinylog.writer.filename=<log file>
-Dtinylog.writer.buffered=<true/false> (default: false)
-Dtinylog.writer.append=<true/false> (default: false)

Example:

-Dtinylog.writer=file
-Dtinylog.writer.filename=log.txt
-Dtinylog.writer.buffered=true
-Dtinylog.writer.append=false

Method signature:

Configurator.writer(Writer writer)

Example:

Configurator.currentConfig() .writer(new FileWriter("log.txt", true, false)) .activate();

JdbcWriter

The JdbcWriter writes log entries to a SQL database. Optionally, the inserts can be done in a batch mode. This will be significantly faster, especially in connection with activation of the writing thread. But the batch mode has the disadvantage that possibly the last - and thus the most important - log entries are lost after a crash of the JVM.

Since tinylog 1.2, the JdbcWriter supports Java EE data sources and reestablishing database connections automatically in case of connection losses. The seconds between two reconnecting tries have to be defined to enable reestablishing. URLs of data sources can be configured in the same way as JDBC URLs. tinylog detects on the basis of the URL if it is a data source or JDBC. User name and password haven't been to configured for data sources in tinylog as they are usually already defined in the data source itself.

PreparedStatements are used to avoid security vulnerability by SQL injections.

Properties Parameters Java Code

Definition:

tinylog.writer = <name>
tinylog.writer.url = <JDBC or data source URL>
tinylog.writer.reconnect = <seconds> (default: disabled)
tinylog.writer.table = <table name>
tinylog.writer.columns = <columns> (default: from table)
tinylog.writer.values = <Values to log>
tinylog.writer.batch = <true/false> (default: false)
tinylog.writer.username = <user name> (if necessary)
tinylog.writer.password = <password> (if necessary)

Example:

tinylog.writer = jdbc
tinylog.writer.url = jdbc:h2:mem:mydb
tinylog.writer.table = LOG_ENTRIES_TABLE
tinylog.writer.columns = COLUMN_A, COLUMN_B
tinylog.writer.values = LEVEL, MESSAGE

Definition:

-Dtinylog.writer=<name>
-Dtinylog.writer.url=<JDBC or data source URL>
-Dtinylog.writer.reconnect=<seconds> (default: disabled)
-Dtinylog.writer.table=<table name>
-Dtinylog.writer.columns=<columns> (default: from table)
-Dtinylog.writer.values=<Values to log>
-Dtinylog.writer.batch=<true/false> (default: false)
-Dtinylog.writer.username=<user name> (if necessary)
-Dtinylog.writer.password=<password> (if necessary)

Example:

-Dtinylog.writer=jdbc
-Dtinylog.writer.url=jdbc:h2:mem:mydb
-Dtinylog.writer.table=LOG_ENTRIES_TABLE
-Dtinylog.writer.columns=COLUMN_A, COLUMN_B
-Dtinylog.writer.values LEVEL, MESSAGE

Method signature:

Configurator.writer(Writer writer)

Example:

Configurator.currentConfig() .writer(new JdbcWriter("jdbc:h2:mem:mydb", "LOG_ENTRIES_TABLE", Arrays.asList("COLUMN_A", "COLUMN_B"), Arrays.asList(Value.LEVEL, Value.MESSAGE))) .activate();

The following values can be logged:

Name Description
CLASS Fully-qualified class name where the logging request is issued
CLASS_NAME Class name (without package) where the logging request is issued
CONTEXT All set values from logging context (new in tinylog 1.1)
DATE Date and time of the logging request
EXCEPTION Thrown exception (null, if none has been thrown)
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
PACKAGE Package where the logging request is issued
PROCESS_ID Process ID of the application
RENDERED_LOG_ENTRY Final rendered log entry as it would be used for text based outputs
THREAD_ID ID of the current thread
THREAD_NAME Name of the current thread

LogcatWriter

The LogcatWriter forwards log entries to Android's native logging system (known as logcat). This writer is only available on Android and new in tinylog 1.2. The class name excluding package, where the logging request is issued, is used as tag for logcat by default.

Properties Parameters Java Code

Definition:

tinylog.writer = <name>
tinylog.writer.tag = <tag> (default: class name)

Example:

tinylog.writer = logcat
tinylog.writer.tag = MyApp

Definition:

-Dtinylog.writer=<name>
-Dtinylog.writer.tag=<tag> (default: class name)

Example:

-Dtinylog.writer=logcat
-Dtinylog.writer.tag=MyApp

Method signature:

Configurator.writer(Writer writer)

Example:

Configurator.currentConfig() .writer(new LogcatWriter()) .activate();

RollingFileWriter

The RollingFileWriter writes log entries to a defined file. Thereby new log files can be started in regular intervals. Old log files are kept as backups. A labeler manages the naming of the log files to ensure unique filenames. By default, the log file will be numbered consecutively. By policies can be defined, when to start a new log file. If nothing else has been configured, a new log file will be started at every startup.

Optionally, the writing can be buffered. This will be significantly faster, especially in connection with activation of the writing thread. But buffered writing has the disadvantage that possibly the last - and thus the most important - log entries are lost after a crash of the JVM.

Properties Parameters Java Code

Definition:

tinylog.writer = <name>
tinylog.writer.filename = <log file>
tinylog.writer.buffered = <true/false> (default: false)
tinylog.writer.backups = <number of backups>
tinylog.writer.label = <labeler> (default: count)
tinylog.writer.policies = <policies> (default: startup)

Example:

tinylog.writer = rollingfile
tinylog.writer.filename = log.txt
tinylog.writer.backups = 10
tinylog.writer.label = timestamp
tinylog.writer.policies = startup, size: 10KB

Definition:

-Dtinylog.writer=<name>
-Dtinylog.writer.filename=<log file>
-Dtinylog.writer.buffered=<true/false> (default: false)
-Dtinylog.writer.backups=<number of backups>
-Dtinylog.writer.label=<labeler> (default: count)
-Dtinylog.writer.policies=<policies> (default: startup)

Example:

-Dtinylog.writer=rollingfile
-Dtinylog.writer.filename=log.txt
-Dtinylog.writer.backups=10
-Dtinylog.writer.label = timestamp
"-Dtinylog.writer.policies=startup, size: 10KB"

Method signature:

RollingFileWriter(String filename, int backups, Policy... policies)

Example:

Configurator.currentConfig() .writer(new RollingFileWriter("log.txt", 10, new TimestampLabeler(), new StartupPolicy(), new SizePolicy(10 * 1024))) .activate();

Labelers

The RollingFileWriter supports labelers to name archived log files by a specified schema. By default, the CountLabeler is active.

Labeler Name Description
CountLabeler count Numbers the backups sequentially (e.g. "log.0.txt" for the newest, "log.1.txt" for the second newest etc.)
ProcessIdLabeler pid Adds the process ID of the application to the filename (e.g. "log.1836.txt", if the process ID is 1836) and ensures that every active instance of the application gets an own log file
TimestampLabeler 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 and under tinylog 1.3 on Java 9 also with DateTimeFormatter.

Policies

Policies define when the RollingFileWriter has to start a new log file. Any number of policies can be concatenated.

Policy Name Beschreibung
CountPolicy count Starts a new log file when the current log file reaches the defined number of log entries (e.g. "count: 1000")
StartupPolicy startup Starts a new log file at every startup of the application (e.g. "startup")
SizePolicy size Starts a new log file when the current log file reaches the defined file size (e.g. "size: 32KB")
HourlyPolicy hourly Starts a new log file at every full hour (e.g. "hourly")
DailyPolicy daily Starts daily a new log file (e.g. "daily: 03:00" or just "daily" for daily at midnight)
WeeklyPolicy weekly Starts weekly a new log file (e.g. "weekly: monday" for every Monday morning at 00:00 clock)
MonthlyPolicy monthly Starts monthly a new log file (e.g. "monthly" for every first day of a month)
YearlyPolicy yearly Starts yearly a new log file (e.g. "yearly: july" for every year at the 1st July or just "yearly" for yearly at the 1st January)

SharedFileWriter

The SharedFileWriter writes log entries to a defined file. Thereby multiple instances of an application can write to the same log file simultaneously. An alternative is using the RollingFileWriter with the ProcessIdLabeler to create an own log file for every active instance of the application. For single instance applications, the FileWriter will be much faster.

An already existing log file will be overwritten at startup by default, if the file is not in use. Additional processes will always join without overwriting any existing log entry. Since tinylog 1.1, it is possible to disable overwriting at all by enabling the append mode. Due to limitations of the JVM, disabling the append mode works only on Windows. If tinylog detects another OS, the append mode will be automatically enabled.

Properties Parameters Java Code

Definition:

tinylog.writer = <name>
tinylog.writer.filename = <log file>
tinylog.writer.append = <true/false> (default: false)

Example:

tinylog.writer = sharedfile
tinylog.writer.filename = log.txt
tinylog.writer.append = true

Definition:

-Dtinylog.writer=<name>
-Dtinylog.writer.filename=<log file>
-Dtinylog.writer.append=<true/false> (default: false)

Example:

-Dtinylog.writer=sharedfile
-Dtinylog.writer.filename=log.txt
-Dtinylog.writer.append=true

Method signature:

Configurator.writer(Writer writer)

Example:

Configurator.currentConfig() .writer(new SharedFileWriter("log.txt", true)) .activate();

Writing thread

Writers can be executed in a separate thread. The advantage is that the application itself will not be blocked by slow IO operations. By default, the writing thread is running with low priority (2) and shuts down automatically together with the main thread.

In standard Java applications, it is common to let the writing thread observe the main thread or another long running thread. The writing thread terminates automatically when the observed thread is shut down. As there is no reliable long running thread in Java EE applications, it is recommended to disable any observing and to shut down the writing thread via a ServletContextListener manually. For this purpose, the static method Configurator.shutdownWritingThread() can be called. Observing can be disabled by setting the thread to null.

Properties Parameters Java Code

Definition:

tinylog.writingthread = <true/false>
tinylog.writingthread.observe = <thread> (default: main)
tinylog.writingthread.priority = <priority> (default: 2)

Example:

tinylog.writingthread = true
tinylog.writingthread.observe = null
tinylog.writingthread.priority = 1

Definition:

-Dtinylog.writingthread=<true/false>
-Dtinylog.writingthread.observe=<thread> (default: main)
-Dtinylog.writingthread.priority=<priority> (default: 2)

Example:

-Dtinylog.writingthread=true
-Dtinylog.writingthread.observe=null
-Dtinylog.writingthread.priority=1

Method signature:

Configurator.writingThread(String threadToObserve, int priority)

Example:

Configurator.currentConfig() .writingThread("main", 1) .activate();