Configuration

Owned by Grzegorz Grzybek
Last updated: Feb 23, 2022

When selected backend is available (pax-logging-service, pax-logging-logback or pax-logging-log4j2) and Configuration Admin is working, configuration may be done using org.ops4j.pax.logging PID.

Typically in Apache Karaf, it’s done through Felix Fileinstall and etc/org.ops4j.pax.logging.cfg file.

Configuration of particular logging backends are described in dedicated pages:

What if org.ops4j.pax.logging PID is not available?

All 3 backends may successfully start without specific configuration. In this scenario, default configuration is used.

Default configuration for Log4j1

Default Log4J1 configuration uses:

  • root logger configured with level specified as org.ops4j.pax.logging.DefaultServiceLog.level system/context property

  • org.apache.log4j.ConsoleAppender appender

  • org.apache.log4j.TTCCLayout layout with pattern [thread] level category - message

Default configuration for Log4j2

Default Log4J2 configuration uses org.apache.logging.log4j.core.config.DefaultConfiguration and has:

  • root logger configured with level specified as org.ops4j.pax.logging.DefaultServiceLog.level system/context property

  • org.apache.logging.log4j.core.appender.ConsoleAppender appender

  • pattern layout with org.apache.logging.log4j.core.config.DefaultConfiguration#DEFAULT_PATTERNpattern, which is %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n

Default configuration for Logback

Default Logback configuration uses ch.qos.logback.classic.BasicConfigurator and has:

  • root logger configured with level specified as org.ops4j.pax.logging.DefaultServiceLog.level system/context property

  • ch.qos.logback.core.ConsoleAppender appender

  • ch.qos.logback.core.encoder.LayoutWrappingEncoder with ch.qos.logback.classic.layout.TTLLLayout, which is %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n

What if Configuration Admin is not available at all?

PAXLOGGING-308 allows to use any backend without Configuration Admin service available. This means that the backend will never be configured asynchronously with CM update. Without special configuration, the above rules are effective. However there’s a way to specify external configuration file. It differs a bit between backends though.

Generally there are two options that can be used (some of them are kept for backward compatibility):

  • Use org.ops4j.pax.logging.property.file system or bundle context property to specify a file name (not URL) with configuration that would normally reside in Karaf’s etc/org.ops4j.pax.logging.cfg. This file should contain the same properties that normally are processed by Configuration Admin (e.g., should be prefixed by log4j2. for Log4j2 configuration). This file may contain full properties-based configuration, but can also specify org.ops4j.pax.logging.logback.config.file or org.ops4j.pax.logging.log4j2.config.file to point to native configuration for Logback or Log4j2 respectively).

  • Use org.ops4j.pax.logging.property.file system or bundle context property to specify a file name (not URL) with native configuration specific to given backend. It can be for example Log4j2’s log4j2.xml configuration file.

Log4j1

In case of Log4j1, this property should point to a file with log4j. prefixed properties. Remember - these properties are handled directly by Log4j1. This convention was also used with pax-logging-log4j2, where properties are prefixed by log4j2., but this prefix is removed before passing the properties to Log4j2 configuration parser!

Log4j2

In case of Log4j2, this property can point to properties file with log4j2. prefixed properties. In such case the prefix is removed and configuration is performed as if Configuration Admin service was available.

This property can also point to native configuration (in any supported format, however JSON and YAML formats require additional bundles for parsing). Also (see https://github.com/ops4j/org.ops4j.pax.logging/pull/39/files) Log4j2 supports composite configuration, where configuration is split between many files. To leverage this mechanism, org.ops4j.pax.logging.property.file property can specify a comma-separated list of locations.

Logback

In case of Logback, there’s no native properties-based file format. However we still can point to a file containing single property:

org.ops4j.pax.logging.logback.config.file = /path/to/logback.xml

We can also directly point to native Logback configuration using -Dorg.ops4j.pax.logging.property.file=/path/to/logback.xml.

For backward compatibility, pax-logging-logback supports a system or bundle context property named org.ops4j.pax.logging.StaticLogbackFile which should point to native Logback XML file.