Basic Logging

Slack Docker Pulls GitHub edit source


This page describes the basic logging function provided by Alluxio server processes (e.g., masters, workers and etc) and application processes utilizing Alluxio clients (e.g., Spark or MapReduce jobs running on Alluxio). Note that there is an experimental feature that streams server-side and client-side logs to separate Alluxio logservers (see remote logging for more details).

Alluxio logging is implemented using log4j and thus most of the configuration is done through modifying

Log Location

Server Logs

Log files for each individual Alluxio server process (e.g., master, worker, FUSE, proxy) can be found under ${ALLUXIO_HOME}/logs/. Files suffixed with .log like master.log or worker.log are generated by log4j, logging the events that Alluxio system is recording through JVM. These files are typically the main target for users to investigate logs. Files suffixed with .out like master.out or worker.out are the redirection of stdout and stderr of the corresponding process, typically empty unless fatal error happens (e.g., killed by operating system).

The log location can be customized by setting environment variable ALLUXIO_LOGS_DIR or appending alluxio.logs.dir property through JVM properties (e.g. ALLUXIO_JAVA_OPTS+=" -Dalluxio.logs.dir=/foo") See the configuration settings page for more information.

Application Logs

Log files for the Alluxio client utilized by different applications are located with their respective application logs. Please check out particular compute frameworks on where their logs may be found.

Here are the documentation to configure individual application logs including Apache Hadoop, Apache HBase, Apache Hive, Apache Spark.

Configuring Log Levels

Alluxio uses the following four logging levels:

  • DEBUG: fine-grained information, most useful for debugging purpose.
  • INFO: messages that highlight the status of progress.
  • WARN: potentially harmful events that users may need to know but the process will still continue running.
  • ERROR: system errors that users should pay attention to.

By default, Alluxio server processes write logs at level INFO, which includes all events at level INFO, WARN and ERROR.

Modifying Logging with

You can modify ${ALLUXIO_HOME}/conf/ to customize logging levels and restart corresponding server processes.

For example, to modify the level for all logs to DEBUG, change the rootLogger level by modifying the first line of as the following:

log4j.rootLogger=DEBUG, ${alluxio.logger.type}, ${alluxio.remote.logger.type}

To modify the logging level for a particular Java class (e.g., set alluxio.client.file.AlluxioFileInStream to DEBUG), add a new line in the end of this file:


Modifying Server Logging at Runtime

It is recommended to modify the file, however if there is a need to modify logging parameters without stopping nodes in the cluster, then you may modify some parameters at runtime.

The Alluxio shell comes with a logLevel command that returns the current value of or updates the log level of a particular class on specific instances. Users are able to change Alluxio server-side log levels at runtime.

The command follows the format alluxio logLevel --logName=NAME [--target=<master|worker|host:port>] [--level=LEVEL], where:

  • --logName <arg> indicates the logger’s class (e.g. alluxio.master.file.DefaultFileSystemMaster)
  • --target <arg> lists the Alluxio master or workers to set. The target could be of the form <master|workers|host:webPort> and multiple targets can be listed as comma-separated entries. The host:webPort format can only be used when referencing a worker. The default target value is all masters and workers.
  • --level <arg> If provided, the command changes to the given logger level, otherwise it returns the current logger level.

For example, the following command sets the logger level of the class alluxio.heartbeat.HeartbeatContext to DEBUG on master as well as a worker at

$ ./bin/alluxio logLevel --logName=alluxio.heartbeat.HeartbeatContext \
  --target=master, --level=DEBUG

And the following command returns the log level of the class alluxio.heartbeat.HeartbeatContext among all the workers:

$ ./bin/alluxio logLevel --logName=alluxio.heartbeat.HeartbeatContext --target=workers

For more information, refer to the help text of the logLevel command by running ./bin/alluxio logLevel

Enabling Advanced Logging

Logging JVM GC (Garbage Collection) events

Add the following line to conf/ to enable logging GC events for server processes in log files with .out suffix like master.out and worker.out:

ALLUXIO_JAVA_OPTS+=" -XX:+PrintGCDetails -XX:+PrintTenuringDistribution -XX:+PrintGCTimeStamps"

ALLUXIO_JAVA_OPTS is included in Java VM options for all Alluxio server processes. Alternatively, modify ALLUXIO_MASTER_JAVA_OPTS, ALLUXIO_WORKER_JAVA_OPTS to turn on GC for each individual process.

Logging RPC Calls Received by Masters

On the master, debug-level RPC logging for File System level RPC calls can be turned on (e.g., creating/reading/writing/removing files, updating file attributions) using the logLevel command:

$ ./bin/alluxio logLevel \
--logName=alluxio.master.file.FileSystemMasterClientServiceHandler \
--target master --level=DEBUG

Similarly, turn on the debug-level logging for block related RPC calls (e.g., adding/removing blocks):

$ ./bin/alluxio logLevel \
--logName=alluxio.master.block.BlockMasterClientServiceHandler \
--target master --level=DEBUG