Logging

CrateDB provides two types of logging:

  1. Application logging – Managed by Log4j 2, which handles CrateDB-specific events and messages.

  2. Java Virtual Machine (JVM) garbage collection (GC) logging – Native JVM logging for memory management events.

We use the term application logging here to distinguish between:

  • CrateDB itself (running as a Java application), and

  • The JVM process that runs CrateDB.

Because garbage collection logging is a JVM feature, it is configured and behaves differently from application logging.

Table of contents

Application logging

Log4j

CrateDB uses Log4j for application logging.

Configuration file

Log4j is configured via the log4j2.properties file located in the CrateDB configuration directory.

This file:

  • Uses a simplified syntax (similar to YAML) to reduce repetition of the log4j prefix.

  • Allows quick configuration via the PropertyConfigurator without verbose XML.

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

📚 See also:

Log levels

Log4j supports the following log levels, in order of increasing severity:

TRACE < DEBUG < INFO < WARN < ERROR

  • Log levels must be set as string literals in SET statements.

  • TRACE is extremely verbose and can quickly fill disks — use it only for short-term debugging.

Run-time configuration

You can change log levels without restarting nodes using the SET statement:

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

  • "logger.action" targets a specific logger (org.crate.action.sql in this example).

  • Use logger._root to configure the root logger.

  • Changes are applied cluster-wide and override the log4j2.properties startup configuration.

Inspect current configuration:

SELECT * FROM sys.cluster;

Run-time configuration is useful for debugging issues in production without downtime.

Caution: Using RESET reverts configuration only after a full cluster restart.

JVM logging

Garbage collection

CrateDB relies on the JVM’s built-in garbage collection logging to record GC times and related metrics.

Environment variables

You can control GC logging behavior using the following environment variables:

Variable
Type / Default
Description

CRATE_DISABLE_GC_LOGGING

boolean int (default: 0)

Set to 1 to disable GC logging.

CRATE_GC_LOG_DIR

path (default: varies)

Directory for GC log files. - Basic installations: CRATE_HOME/logs - Linux packages: /var/log/crate

CRATE_GC_LOG_SIZE

size (default: 64m)

Max size of a GC log file before rotation.

CRATE_GC_LOG_FILES

number (default: 16)

Number of rotated GC log files to keep.

With the default settings (16 × 64m), GC logs can consume up to 1 GB of disk space. Ensure sufficient free space.

PreviousSession settingsNextEnvironment Variables

Last updated