Apache Ignite Documentation

GridGain Developer Hub - Apache Ignitetm

Welcome to the Apache Ignite developer hub run by GridGain. Here you'll find comprehensive guides and documentation to help you start working with Apache Ignite as quickly as possible, as well as support if you get stuck.

 

GridGain also provides Community Edition which is a distribution of Apache Ignite made available by GridGain. It is the fastest and easiest way to get started with Apache Ignite. The Community Edition is generally more stable than the Apache Ignite release available from the Apache Ignite website and may contain extra bug fixes and features that have not made it yet into the release on the Apache website.

 

Let's jump right in!

 

Documentation     Ask a Question     Download

 

Javadoc     Scaladoc     Examples

Ignite supports a variety of logging libraries and frameworks - Log4j, Log4j2, JCL, and SLF4J out-of-the-box. This documentation will show you how to set up a logger in Ignite.

Common Configuration

When an Ignite node starts, it outputs start-up information to the console, including the information about the configured logging library. Each logging library has its own configuration parameters and should be set up according to its official documentation. Besides library-specific configuration, there is a number of system properties that allow you to tune logging. These properties are presented in the following table.

System Property
Description
Default

IGNITE_LOG_INSTANCE_NAME

If the property is present, Ignite will include its instance name in log messages.

Not set

IGNITE_QUIET

Set to "false" to disable the quiet mode and enable the verbose mode. In the verbose mode, Ignite will log a lot more information.

true

IGNITE_LOG_DIR

This property allows you to specify the directory where Ignite will write log files.

$IGNITE_HOME/
work/log

IGNITE_DUMP_THREADS_ON_FAILURE

Set to "true" to output thread dumps to the log when a critical error is caught.

true

Default Logging

By default, Ignite uses java.util.logging.Logger (JUL) with the $IGNITE_HOME/config/java.util.logging.properties file for logging and logs all messages in the $IGNITE_HOME/work/log directory. To override the logging directory that has been set in the logger configuration, use the IGNITE_LOG_DIR environment variable.

Additionally, Ignite starts in quiet mode suppressing INFO and DEBUG log output. To turn off quiet mode, use the -DIGNITE_QUIET=false system property. Note that all output in quiet mode is done through standard output (STDOUT).

Default Log Directory

When Ignite is started from a Java application, the log directory is set to $IGNITE_HOME/work, which defaults to '/tmp/ignite/work/log/'. Make sure to set your log directory to a more reliable location.

Ensure Logging is Correctly Set up if jul-to-slf4j Bridge is Used

If you use the jul-to-slf4j bridge, you may want to pay particular attention to the JUL log-level for Ignite. If you have org.apache at DEBUG level, you may have your final logger at INFO. This means that Ignite will spend 10x overhead generating log messages that will be subsequently thrown away once they cross the bridge. JUL has a default level of INFO out of the box. Setting a quick breakpoint in org.apache.ignite.logger.java.JavaLogger#isDebugEnabled should show if your JUL subsystem is producing debug level logs.

The default logger can be reconfigured in runtime via LoggingMXBean.

<bean class="org.apache.ignite.configuration.IgniteConfiguration">
  
  <!-- uncomment the following section to set, e.g., log4j as the logging library to be used-->
  <!--property name="gridLogger">
    <bean class="org.apache.ignite.logger.log4j.Log4JLogger">
      <constructor-arg type="java.lang.String" value="log4j.xml"/>
    </bean>
  </property-->
  
   <!-- how frequently Ignite will output basic node metrics into the log-->
  <property name="metricsLogFrequency" value="#{60 * 10 * 1000}"/>
  
</bean>

Log4j

To enable the Log4J module when starting a standalone node, move the optional/ignite-log4j folder to the libs folder of your Ignite distribution before running the ignite.{sh|bat} script. The content of the module folder will be added to the classpath in this case.

If you are using Maven to manage the dependencies of your project, you can add the Log4J module dependency like this:

<dependency>
  <groupId>org.apache.ignite</groupId>
  <artifactId>ignite-log4j</artifactId>
  <version>${ignite.version}</version>
</dependency>        

Replace ${ignite.version} with the actual Ignite version you are interested in.

To enable Log4j logger in Ignite, you need to set the gridLogger property of IgniteConfiguration, as shown below:

<bean class="org.apache.ignite.configuration.IgniteConfiguration">
  <property name="gridLogger">
    <bean class="org.apache.ignite.logger.log4j.Log4JLogger">
      <constructor-arg type="java.lang.String" value="log4j.xml"/>
    </bean>
  </property>
  <!-- Other Ignite configurations -->
  ...
</bean>
IgniteConfiguration cfg = new IgniteConfiguration();

IgniteLogger log = new Log4JLogger("log4j.xml");

cfg.setGridLogger(log);

// Start Ignite node.
Ignite ignite = Ignition.start(cfg);

ignite.log().info("Info Message Logged!");

In the above configuration, the path to log4j.xml should be either absolute or a relative local file system path, relative to META-INF in classpath, or relative to IGNITE_HOME. An example log4j.xml file can be found in the config directory of the Ignite binary package.

Log4j supports runtime reconfiguration, i.e. changes in the configuration file will be applied without the need to restart the application.

Log4j2

To enable the Log4J2 module when starting a standalone node, move the optional/ignite-log4j2 folder to the libs folder of your Ignite distribution before running the ignite.{sh|bat} script. The content of the module folder will be added to the classpath in this case.

If you are using Maven to manage dependencies of your project, you can add the Log4J2 module dependency like this:

<dependency>
  <groupId>org.apache.ignite</groupId>
  <artifactId>ignite-log4j2</artifactId>
  <version>${ignite.version}</version>
</dependency>

Replace ${ignite.version} with the actual Ignite version you are interested in.

To enable Log4j2 logger in Ignite, you need to set the gridLogger property of IgniteConfiguration, as shown below:

<bean class="org.apache.ignite.configuration.IgniteConfiguration">
  <property name="gridLogger">
    <bean class="org.apache.ignite.logger.log4j2.Log4J2Logger">
      <constructor-arg type="java.lang.String" value="log4j2.xml"/>
    </bean>
  </property>
  <!-- Other Ignite configurations -->
  ...
</bean>
IgniteConfiguration cfg = new IgniteConfiguration();

IgniteLogger log = new Log4J2Logger("log4j2.xml");

cfg.setGridLogger(log);

// Start Ignite node.
Ignite ignite = Ignition.start(cfg);

ignite.log().info("Info Message Logged!");

In the above configuration, the path to log4j2.xml should be either absolute or a relative local file system path, relative to META-INF in classpath, or relative to IGNITE_HOME. An example log4j2.xml file can be found in the config directory of the Ignite binary package.

Log4j2 supports runtime reconfiguration, i.e. changes in the configuration file will be applied without the need to restart the application.

JCL

To enable the JCL module when starting a standalone node, move the optional/ignite-jcl folder to the libs folder of your Ignite distribution before running the ignite.{sh|bat} script. The content of the module folder will be added to the classpath in this case.

If you are using Maven to manage dependencies of your project, you can add the JCL module dependency like this:

<dependency>
  <groupId>org.apache.ignite</groupId>
  <artifactId>ignite-jcl</artifactId>
  <version>${ignite.version}</version>
</dependency>

Replace ${ignite.version} with the actual Ignite version you are interested in.

To enable JCL logger in Ignite, you need to set the gridLogger property of IgniteConfiguration, as shown below:

<bean class="org.apache.ignite.configuration.IgniteConfiguration">
  <property name="gridLogger">
    <bean class="org.apache.ignite.logger.jcl.JclLogger">
    </bean>
  </property>
  <!-- Other Ignite configurations -->
  ...
</bean>
IgniteConfiguration cfg = new IgniteConfiguration();

IgniteLogger log = new JclLogger();

cfg.setGridLogger(log);

// Start Ignite node.
Ignite ignite = Ignition.start(cfg);

ignite.log().info("Info Message Logged!");

Note that JCL simply forwards logging messages to an underlying logging system, which needs to be properly configured. Refer to JCL official documentation for more information. For example, if you want to use Log4j, make sure you add the required libraries to your classpath.

SLF4J

To enable the SLF4J module when starting a standalone node, move the optional/ignite-slf4j folder to the libs folder of your Ignite distribution before running the ignite.{sh|bat} script. The content of the module folder will be added to the classpath in this case.

If you are using Maven to manage dependencies of your project, you can add the SLF4J module dependency like this:

<dependency>
  <groupId>org.apache.ignite</groupId>
  <artifactId>ignite-slf4j</artifactId>
  <version>${ignite.version}</version>
</dependency>

Replace ${ignite.version} with the actual Ignite version you are interested in.

To enable SLF4J logger in Ignite, you need to set the gridLogger property of IgniteConfiguration, as shown below:

<bean class="org.apache.ignite.configuration.IgniteConfiguration">
  <property name="gridLogger">
    <bean class="org.apache.ignite.logger.slf4j.Slf4jLogger"/>
  </property>
  
  <!-- Other Ignite configurations -->
 
</bean>
IgniteConfiguration cfg = new IgniteConfiguration();

IgniteLogger log = new Slf4jLogger();

cfg.setGridLogger(log);

// Start Ignite node.
Ignite ignite = Ignition.start(cfg);

ignite.log().info("Info Message Logged!");

Refer to SLF4J user manual for more information.

Logging Configuration Example

The following steps will guide you through the process of configuring logging. This should be suitable for most cases.

  1. Use either Log4j or Log4j2 as the logging framework. To enable it, follow the instructions provided in the corresponding section above.
  2. If you use the default configuration file (either ignite-log4j.xml or ignite-log4j2.xml), uncomment the CONSOLE appender.
  3. In the log4j configuration file, set the path to the log file. The default location is ${IGNITE_HOME}/work/log/ignite.log.
  4. Start Ignite in verbose mode:
    • If you use ignite.sh, specify the -v option.
    • If you start Ignite from Java code, use system variable IGNITE_QUIET=false.

Log Management Tips

Logs play an important role when it comes to troubleshooting and finding what went wrong. Here are a few general tips on how to manage your log files:

  • Do not store log files in the /tmp folder. This folder is cleared up every time the server is restarted.
  • Make sure that there is enough space available on the storage where the log files are stored.
  • Archive old log files periodically to save on storage space.

Updated 8 months ago

Logging


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.