Manual · Appenders · Appenders: Console and File

Appenders: Console and File

This page continues the Appenders chapter. The overview introduces the Appender interface, AppenderBase, and OutputStreamAppender (including its encoder and immediateFlush properties and the class diagram of its subclasses).

Here we turn to the concrete stream-oriented appenders that most applications configure first: ConsoleAppender, JansiConsoleAppender, and FileAppender. All three build on OutputStreamAppender. Rolling files are covered separately under Rolling file.

ConsoleAppender

The ConsoleAppender, as the name indicates, appends on the console, or more precisely on System.out or System.err, the former being the default target. ConsoleAppender formats events with the help of an encoder specified by the user. Encoders will be discussed in a subsequent chapter. Both System.out and System.err are of type java.io.PrintStream. Consequently, they are wrapped inside an OutputStreamWriter which buffers I/O operations.

WARNING Please note the console is comparatively slow, even very slow. You should avoid logging to the console in production, especially in high volume systems.

Here is a sample configuration that uses ConsoleAppender.

Example: ConsoleAppender configuration (logback-examples/​src/main/resources/​chapters/appenders/​conf/logback-Console.​xml)

<configuration>

  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <!-- encoders are assigned the type
         ch.qos.logback.classic.encoder.PatternLayoutEncoder by default -->
    <encoder>
      <pattern>%-4relative [%thread] %-5level %logger{35} -%kvp- %msg %n</pattern>
    </encoder>
  </appender>

  <root level="DEBUG">
    <appender-ref ref="STDOUT" />
  </root>
  </configuration>
    

After you have set your current path to the logback-examples directory and set up your class path, you can give the above configuration file a whirl by issuing the following command:

java chapters.appenders.​ConfigurationTester src/main/java/chapters/​appenders/conf/​logback-Console.xml

JansiConsoleAppender

since 1.6.3 The JansiConsoleAppender is a ConsoleAppender that always writes through JLine's org.jline.jansi.AnsiConsole. It is the recommended way to enable ANSI sequences on platforms that need Jansi (notably Windows). Unlike the deprecated withJansi path on ConsoleAppender, this class talks to AnsiConsole directly and does not use reflection.

You must place org.jline:jansi-core on the class path. On start, the appender calls AnsiConsole.systemInstall() and routes output to AnsiConsole.out() or AnsiConsole.err() according to the target property. On stop, if this appender performed the install, it pairs that call with AnsiConsole.systemUninstall(). As with ConsoleAppender, stop flushes the console stream but does not close process-wide stdout or stderr.

JansiConsoleAppender admits the same encoder and target properties as ConsoleAppender. You do not set withJansi; Jansi wrapping is always applied.

Here is a sample configuration that uses JansiConsoleAppender instead of a plain ConsoleAppender with <withJansi>true</withJansi>:

DEPRECATED

<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
  <withJansi>true</withJansi>
  <encoder>
    <pattern>%highlight(%-5level) %logger{35} - %msg%n</pattern>
  </encoder>
</appender>

RECOMMENDED

<appender name="STDOUT" class="ch.qos.logback.core.JansiConsoleAppender">
  <encoder>
    <pattern>%highlight(%-5level) %logger{35} - %msg%n</pattern>
  </encoder>
</appender>

FileAppender

The FileAppender, a subclass of OutputStreamAppender, appends log events into a file. The target file is specified by the File option. If the file already exists, it is either appended to, or truncated depending on the value of the append property.

Immediate Flush By default, each log event is immediately flushed to the underlying output stream. This default approach is safer in the sense that logging events are not lost in case your application exits without properly closing appenders. However, for significantly increased logging throughput, you may want to set the immediateFlush property to false.

Below is an example of a configuration file for FileAppender:

Example: FileAppender configuration (logback-examples/​src/main/resources/​chapters/appenders/​conf/logback-fileAppender.​xml)

<configuration>

  <appender name="FILE" class="ch.qos.logback.core.FileAppender">
    <file>testFile.log</file>
    <append>true</append>
    <!-- set immediateFlush to false for much higher logging throughput -->
    <immediateFlush>true</immediateFlush>
    <!-- encoders are assigned the type
         ch.qos.logback.classic.encoder.PatternLayoutEncoder by default -->
    <encoder>
      <pattern>%-4relative [%thread] %-5level %logger{35} -%kvp- %msg%n</pattern>
    </encoder>
  </appender>

  <root level="DEBUG">
    <appender-ref ref="FILE" />
  </root>
</configuration>

After changing the current directory to logback-examples, run this example by launching the following command:

java chapters.appenders.​ConfigurationTester src/main/java/chapters/​appenders/conf/​logback-fileAppender.​xml

Uniquely named files (by timestamp)

During the application development phase or in the case of short-lived applications, e.g. batch applications, it is desirable to create a new log file at each new application launch. This is fairly easy to do with the help of the <timestamp> element. Here's an example.

Example: Uniquely named FileAppender configuration by timestamp (logback-examples/​src/main/resources/​chapters/appenders/​conf/logback-timestamp.​xml)

<configuration>

  <!-- Insert the current time formatted as "yyyyMMdd'T'HHmmss" under
       the key "bySecond" into the logger context. This value will be
       available to all subsequent configuration elements. -->
  <timestamp key="bySecond" datePattern="yyyyMMdd'T'HHmmss"/>

  <appender name="FILE" class="ch.qos.logback.core.FileAppender">
    <!-- use the previously created timestamp to create a uniquely
         named log file -->
    <file>log-${bySecond}.txt</file>
    <encoder>
      <pattern>%logger{35} -%kvp- %msg%n</pattern>
    </encoder>
  </appender>

  <root level="DEBUG">
    <appender-ref ref="FILE" />
  </root>
     </configuration>

The timestamp element takes two mandatory attributes key and datePattern and an optional timeReference attribute. The key attribute is the name of the key under which the timestamp will be available to subsequent configuration elements as a variable. The datePattern attribute denotes the date pattern used to convert the current time (at which the configuration file is parsed) into a string. The date pattern should follow the conventions defined in SimpleDateFormat. The timeReference attribute denotes the time reference for the time stamp. The default is the interpretation/parsing time of the configuration file, i.e. the current time. However, under certain circumstances it might be useful to use the context birth time as time reference. This can be accomplished by setting the timeReference attribute to "contextBirth".

Experiment with the <timestamp> element by running the command:

java chapters.appenders.​ConfigurationTester src/main/resources/​chapters/appenders/​conf/logback-timestamp.​xml

To use the logger context birthdate as time reference, you would set the timeReference attribute to "contextBirth" as shown below.

Example: Timestamp using context birthdate as time reference (logback-examples/​src/main/resources/​chapters/appenders/​conf/logback-timestamp-contextBirth.​xml)

<configuration>
  <timestamp key="bySecond" datePattern="yyyyMMdd'T'HHmmss" 
             timeReference="contextBirth"/>
  ...
</configuration>