Logging

CrateDB supports two kinds of logging:

  • Application logging with Log4j

  • Java Virtual Machine (JVM) garbage collection logging

We use “application” here to distinguish between CrateDB running as a Java application and the JVM itself, which runs CrateDB.

Because garbage collection logging is a native feature of the JVM it behaves differently and is configured differently.

Table of contents

Application logging

Log4j

CrateDB uses Log4j.

Configuration file

You can configure Log4j with the log4j2.properties file in the CrateDB configuration directory.

The log4j2.properties file is formatted using YAML and simplifies Log4j configuration by allowing you to use the PropertyConfigurator but without having to tediously repeat the log4j prefix.

Here’s one example:

rootLogger.level = info
rootLogger.appenderRef.console.ref = console

# log query execution errors for easier debugging
logger.action.name = org.crate.action.sql
logger.action.level = debug

appender.console.type = Console
appender.console.name = console
appender.console.layout.type = PatternLayout
appender.console.layout.pattern = [%d{ISO8601}][%-5p][%-25c{1.}] %marker%m%n

And here is a snippet of the generated properties ready for use with log4j. You get the point.

See also

Consult the PropertyConfigurator documentation or the configuration section of the Log4j documentation for more information.

Log levels

Possible log levels are the same as for Log4j, in order of increasing importance:

  • TRACE

  • DEBUG

  • INFO

  • WARN

  • ERROR

Log levels must be provided as string literals in the SET statement.

Note

Be careful using the TRACE log level because it’s extremely verbose, can obscure other important log messages and even fill up entire data disks in some cases.

Run-time configuration

It’s possible to set the log level of loggers at runtime using SET, like so:

SET GLOBAL TRANSIENT "logger.action" = 'INFO';

In this example, the log level INFO is applied to the action logger.

In addition to being able to configure any of the standard loggers, you can configure the root (i.e. default) logger using logger._root.

As with any setting, you can inspect the current configuration by querying the sys.cluster table.

Tip

Run-time logging configuration is particularly useful if you are debugging a problem and you want to increase the log level without restarting nodes.

Run-time logging configuration is applied across the whole cluster, and overrides the start-up configuration defined in each respective log4j2.properties file.

Caution

The RESET statement is supported but logging configuration is only reset when the whole cluster is restarted.

JVM logging

CrateDB exposes some native JVM logging functionality.

Garbage collection

CrateDB logs JVM garbage collection times using the built-in garbage collection logging of the JVM.

Environment variables

The following environment variables can be used to configure garbage collection logging.

CRATE_DISABLE_GC_LOGGING: boolean integer (default: 0)

Whether to disable garbage collection logging.

Set to 1 to disable.

Note

Since since CrateDB 3.0, Garbage collection logging is enabled by default.

CRATE_GC_LOG_DIR: path to logs directory (default: varies)

The log file directory.

For a basic installation, the logs directory in the CRATE_HOME directory is default.

If you have installed a CrateDB Linux package, the default directory is /var/log/crate instead.

CRATE_GC_LOG_SIZE: file size (default: 64m)

Maximum file size of log files before they are rotated.

CRATE_GC_LOG_FILES: number (default: 16)

The amount of files kept in rotation.

Caution

With the default configuration of 16 rotated 64 megabyte log files, garbage collection logs will grow to occupy one gigabyte on disk.

Make sure you have enough available disk space for configuration.