Server Logging


This page summarizes Alluxio’s logging system for servers, such as the master and worker processes. We include tips for modifying Alluxio’s log4j properties file to best suit deployment needs. If you are a user of Alluxio looking for logging information about clients that are utilizing the Alluxio API, we recommend looking at the client logging documentation

Alluxio’s logging behavior can be fully configured through the file found in the conf folder.

Log Location

Default Location

By default Alluxio processes’ log files can be found under ${ALLUXIO_HOME}/logs/.

Configuring the Log Location

The location of the logs is determined by the alluxio.logs.dir property. This can only be set via JVM property; it cannot be set in the file. See the configuration settings page for more information on how to set JVM properties for Alluxio.

Each Alluxio process (master, worker, FUSE, proxy) will log to a separate file within the alluxio.logs.dir directory

Log Levels

Modifying Logging with

You can modify the found under the ${ALLUXIO_HOME}/conf/ to modify logging levels.

For example, if you would like to modify the level for all logs, then you can change the rootLogger level by modifying the following line:

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

If you wish to have DEBUG logging, then you would make the first line

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

Modifying 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

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:

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

Remote Logging


Alluxio supports sending logs to a remote log server over the network. This feature can be useful to system administrators who have to perform the task of log collection. With remote logging, the log files, e.g. master.log, worker.log, etc. on all Alluxio servers will be readily available on a designated and configurable directory on the log server.

Deploying the Log Server

Configuring the Log Server

You can choose the directory that the log server will write logs to by setting the ALLUXIO_LOGSERVER_LOGS_DIR environment variable or adding it to ${ALLUXIO_HOME}/conf/

Start the Log Server

On the log server, execute the following command.

./bin/ logserver

Stop the Log Server

./bin/ logserver

Configuring Alluxio Processes to use the Log Server

By default, remote logging is not enabled. There are two options which can enable remote logging. One option is to set environment variables within ${ALLUXIO_HOME}/conf/ The other is to modify Alluxio’s file under ${ALLUXIO_HOME}/conf/

There is no requirement on where the log server can be run, as long as the other Alluxio servers have network access to it. In our example, we run the log server on the same machine as a master.

Enable Remote Logging with Environment Variables

The two environment variables ALLUXIO_LOGSERVER_HOSTNAME and ALLUXIO_LOGSERVER_PORT control the logging behavior of masters and workers in an Alluxio cluster.

Suppose the hostname of the log server is AlluxioLogServer, and the port is 45010. The following lines would need to be added to conf/ to enable the correct :


These variables propagate their values to the alluxio.logserver.hostname and alluxio.logserver.port system properties when set via which are then referenced within

Enable Remote Logging with

You can also choose to modify the ${ALLUXIO_HOME}/conf/ file on the machines where your masters or workers reside to add an appender which will send log entries to the log server. A sample configuration is provided below:

log4j.appender.MASTER_LOGGER_SOCKET.layout.ConversionPattern=%d{ISO8601} %-5p %c{1} - %m%n

Note that on the line containing log4j.rootLogger you may add multiple appenders in order to log locally to a file on the system and remotely over a network. For example:


Restart Alluxio and the Log Server

After making the modification to configuration, you need to restart the log server first. Then you can start Alluxio. This ensures that the logs that Alluxio generates during start-up phase will also go to the log server.

Verify the Log Server has Started

SSH to the machine on which log server is running.

Go to the directory where the log server has been configured to store logs received from other Alluxio servers. In the above example, the directory is /tmp/alluxio_remote_logs.

cd /tmp/alluxio_remote_logs
master          proxy           secondary_master    worker
ls -l master/
-rw-r--r--  1 alluxio  alluxio  26109 Sep 13 08:49

You can see that the log files are put into different folders according to their type. Master logs are put in the folder master, worker logs are put in folder worker, etc. Within each folder, log files from different workers are distinguished by the IP/hostname of the machine on which the server has been running.

Configuration Properties

You can find the properties related to logging in the table of configuration properties