6.2. Creating the Logging Configuration File

Documentation

VoltDB Home » Documentation » Administrator's Guide

6.2. Creating the Logging Configuration File

VoltDB ships with a default Log4J configuration file, voltdb/log4j.xml, in the installation directory. The VoltDB shell commands use this file to configure logging and it is recommended for new application development. This default Log4J file lists all of the VoltDB-specific logging categories and can be used as a template for any modifications you wish to make. Or you can create a new file from scratch.

The following is an example of a Log4J configuration file:

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">

<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">

<appender name="Async" class="org.apache.log4j.AsyncAppender">
  <param name="Blocking" value="true" />
  <appender-ref ref="Console" />
  <appender-ref ref="File" />
</appender>

<appender name="Console" class="org.apache.log4j.ConsoleAppender">
  <param name="Target" value="System.out" />
  <layout class="org.apache.log4j.TTCCLayout" />
</appender>

<appender name="File" class="org.apache.log4j.FileAppender">
  <param name="File" value="/tmp/voltdb.log" />
  <param name="Append" value="true" />
  <layout class="org.apache.log4j.TTCCLayout" />
</appender>

<logger name="AUTH"> 
<!-- Print all VoltDB authentication messages -->
  <level value="trace" />
</logger>

<root>
      <priority value="debug" />
      <appender-ref ref="Async" />
</root>
</log4j:configuration>

The preceding configuration file defines three destinations, or appenders, called Async, Console, and File. The appenders define the type of output (whether to the console, to a file, or somewhere else), the location (such as the file name), as well as the layout of the messages sent to the appender. See the log4J documentation for more information about layout.

Note that the appender Async is a superset of Console and File. So any messages sent to Async are routed to both Console and File. This is important because for logging of VoltDB, you should always use an asynchronous appender as the primary target to avoid the processing of the logging messages from blocking other execution threads.

More importantly, you should not use any appenders that are susceptible to extended delays, blockages, or slow throughput, This is particularly true for network-based appenders such as SocketAppender and third-party log infrastructures including logstash and JMS. If there is any prolonged delay in writing to the appenders, messages can end up being held in memory causing performance degradation and, ultimately, generating out of memory errors or forcing the database into read-only mode.

The configuration file also defines a root class. The root class is the default logger and all loggers inherit the root definition. So, in this case, any messages of severity "debug" or higher are sent to the Async appender.

Note

This example is for demonstration purposes only. Normally, do not set the severity to either "debug" or "trace" for production systems unless instructed to by VoltDB Support. Trace and debug logging generate a significant number of messages that can negatively impact performance. They contain internal information for debugging purposes and provide no additional value otherwise.

Finally, the configuration file defines a logger specifically for VoltDB authentication messages. The logger identifies the class of messages to log (in this case "AUTH"), as well as the severity ("trace"). VoltDB defines several different classes of messages you can log. Table 6.1, “VoltDB Components for Logging” lists the loggers you can invoke.

Table 6.1. VoltDB Components for Logging

LoggerDescription
ADHOCExecution of ad hoc queries
AUTHAuthentication and authorization of clients
COMPILERInterpretation of SQL in ad hoc queries
CONSOLEInformational messages intended for display on the console
DRDatabase replication sending data
DRAGENTDatabase replication receiving data
EXPORTExporting data
GCJava garbage collection
HOSTHost specific events
IMPORTImporting data
ELASTICElastic addition of nodes to the cluster
LOADERBulk loading of data (including as part of import)
NETWORKNetwork events related to the database cluster
REJOINNode recovery and rejoin
SNAPSHOTSnapshot activity
SQLExecution of SQL statements
TMTransaction management
TOPICSStreaming data in topics