File: README.md

package info (click to toggle)
libminlog-java 1.3.0-1.1
  • links: PTS, VCS
  • area: main
  • in suites: bookworm, bullseye, sid
  • size: 100 kB
  • sloc: java: 157; xml: 116; makefile: 4
file content (128 lines) | stat: -rw-r--r-- 4,589 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
![](https://raw.github.com/wiki/EsotericSoftware/minlog/images/logo.png)

## MinLog

Please use the [MinLog discussion group](http://groups.google.com/group/minlog-users) for support.

## Overview

MinLog is a tiny Java logging library which features:

- **Zero overhead** Logging statements below a given level can be automatically removed by javac at compile time. This means applications can have detailed trace and debug logging without having any impact on the finished product.

- **Extremely lightweight** The entire project consists of a [single Java file](https://github.com/EsotericSoftware/minlog/blob/master/src/com/esotericsoftware/minlog/Log.java) with ~100 non-comment lines of code.

- **Simple and efficient** The API is concise and the code is very efficient at runtime.

Also see [this](https://github.com/jdanbrown/minlog-slf4j) drop-in replacement for minlog which logs to slf4j.

## Usage

Messages are logged using static methods:

```java
    Log.info("Some message.");
    Log.debug("Error reading file: " + file, ex);
```

A static import can be used to make the logging more concise:

```java
    import static com.esotericsoftware.minlog.Log.*;
    // ...
    info("Some message.");
    debug("Error reading file: " + file, ex);
```

While optional, for brevity the rest of this documentation assumes this static import is in place.

If log statements from different libraries or areas of an application need to be differentiated, a category can be specified as the first argument:

```java
    info("some lib", "Some message.");
    debug("some lib", "Error reading file: " + file, ex);
```

## Log level

Setting the level will log that level, as well as all higher levels. There are multiple ways to set the current level:

```java
    Log.set(LEVEL_INFO);
    Log.INFO();
    INFO();
```

The levels are:

- NONE disables all logging.
- ERROR is for critical errors. The application may no longer work correctly.
- WARN is for important warnings. The application will continue to work correctly.
- INFO is for informative messages. Typically used for deployment.
- DEBUG is for debug messages. This level is useful during development.
- TRACE is for trace messages. A lot of information is logged, so this level is usually only needed when debugging a problem.


## Conditional logging

If a logging method below the current level is called, it will return without logging the message. In order to avoid string concatenation, the current log level can be checked before the message is logged:

```java
    if (ERROR) error("Error reading file: " + file, ex);
    if (TRACE) {
    	StringBuilder builder = new StringBuilder();
    	// Do work, append to the builder.
    	trace(builder);
    }
```

## Fixed logging levels

MinLog users can choose from the regular "minlog.jar" or from from a JAR file like "minlog-info.jar" which has a fixed logging level that cannot be changed at runtime. When a fixed level JAR is used, code that changes the level will have no affect. During compilation, any conditional logging statements below the fixed level will be automatically removed by the Java compiler. This means they will have absolutely no impact on the application.

## Output customization

The default logger outputs messages in this format:

```
    time level: [category] message
```

Where "time" is the time elapsed since the application started. For example:

```
    00:00 TRACE: [kryo] Wrote string: moo
    00:00 TRACE: [kryo] Wrote object: NonNullTestClass
    00:01 TRACE: [kryo] Wrote string: this is some data
    00:01 TRACE: [kryo] Compressed to 7.97% using: DeflateCompressor
    00:12 TRACE: [kryo] Decompressed using: DeflateCompressor
    00:12 TRACE: [kryo] Read string: this is some data
```

The output can be customized:

```java
    static public class MyLogger extends Logger {
    	public void log (int level, String category, String message, Throwable ex) {
    		StringBuilder builder = new StringBuilder(256);
    		builder.append(new Date());
    		builder.append(' ');
    		builder.append(level);
    		builder.append('[');
    		builder.append(category);
    		builder.append("] ");
    		builder.append(message);
    		if (ex != null) {
    			StringWriter writer = new StringWriter(256);
    			ex.printStackTrace(new PrintWriter(writer));
    			builder.append('\n');
    			builder.append(writer.toString().trim());
    		}
    		System.out.println(builder);
    	}
    }
    // ...
    Log.setLogger(new MyLogger());
```

Using this mechanism, log messages can be filtered (eg, by category), written to a file, etc.