Configuration
There are three ways to configure tinylog: by a properties file, by system properties (can be set as
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
| 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 levels 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 six 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(); |