Apache
Home » Documentation » Apache Felix Subproject Documentation

Apache Felix Logback

Apache Felix Logback is a small integration of the Logback backend with OSGi.

With OSGi R7 the Log Service Specification 1.4 (Log 1.4) brings a slew of new features designed to improve the developer experience with logging, the details of which can be read about here.

This project is intended to help bridge the last frontier of OSGi logging by leveraging many capabilities of Logback, the new Log 1.4 features to provide a unified backend where:

  1. all logging can be configured in one place
  2. all log records are appended together (or at least all appenders are setup in one place)
  3. support as many logging APIs as possible

Depedencies

To add Logback to an OSGi framework include the following dependencies

<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>1.2.x</version>
</dependency>
<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-core</artifactId>
    <version>1.2.x</version>
</dependency>
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-api</artifactId>
    <version>1.7.x</version>
</dependency>

These provide the slf4j logging API over the Logback backend.

Basic Configuration

Configuring logback is most easily handled by setting the system property logback.configurationFile to point to a file on the file system.

This is an example using a bndrun file:

-runproperties: logback.configurationFile=file:${.}/logback.xml

where in bnd ${.} gives the path to the directory of the bndrun file.

Logback offers many features from it's configuration file, so make sure to look through the documentation.

Deployment Options

There are at least two possible deployment scenarios.

The Standard Approach

The standard approach is to install all bundles into the OSGi runtime.

pros:

cons:

The Immediate Approach

The immediate approach overcomes the cons of the standard approach and initializes the log engine as early as possible in order to avoid buffering, binding issues, or losing records.

pros:

cons:

Unified Backend

Of course adding Logback does not magically result in all logs being funneled into the same appenders, particularly the OSGi logs. However, it is quite common to assemble an OSGi application from a variety of bundles which use a variety of logging APIs. Many of these can already be mapped onto Logback.

Many examples of setting up the various logging APIs can be found in the integration tests of the project.

The following APIs are tested:

Mapping of OSGi Events

The OSGi Log specification 1.4 describes events resulting in log records. Log 1.4 defines logger names mapping to these events.

Event Logger Name Events types
Bundle event Events.Bundle INSTALLED - BundleEvent INSTALLED
STARTED - BundleEvent STARTED
STOPPED - BundleEvent STOPPED
UPDATED - BundleEvent UPDATED
UNINSTALLED - BundleEvent UNINSTALLED
RESOLVED - BundleEvent RESOLVED
UNRESOLVED - BundleEvent UNRESOLVED
Service event Events.Service REGISTERED - ServiceEvent REGISTERED
MODIFIED - ServiceEvent MODIFIED
UNREGISTERING - ServiceEvent UNREGISTERING
Framework event Events.Framework STARTED - FrameworkEvent STARTED
ERROR - FrameworkEvent ERROR
PACKAGES_REFRESHED - FrameworkEvent PACKAGES REFRESHED
STARTLEVEL_CHANGED - FrameworkEvent STARTLEVEL CHANGED
WARNING - FrameworkEvent WARNING
INFO - FrameworkEvent INFO
Legacy Log Service events LogService any log events originating from bundles that used the original LogService logging API

Note: In order to improve the granularity of the logging associated with these events, Apache Felix Logback allows appending a period (.) followed by any number of segments (separated by periods) of the Bundle-SymbolicName for the logger names used in configuring the levels. This greatly improves the configurability.

Consider the following logback.xml example:

<configuration>

    <!-- defined a console append -->
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%.15thread] %-5level %logger{36}:%line - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- log all Bundle events -->
    <logger name="Events.Bundle" level="TRACE"/>

    <!-- log WARN Framework service events of bundles whose BSN starts with `org.eclipse.osgi` (guess who that is?) -->
    <logger name="Events.Service.org.eclipse.osgi" level="WARN"/>

    <!-- turn OFF legacy Log Service records from bundles whose BSN starts with `org.baz` -->
    <logger name="LogService.org.baz" level="OFF"/>

    <!-- log DEBUG Service events for bundles whose BSN starts with `org.fum` -->
    <logger name="Events.Service.org.fum" level="DEBUG"/>

    <!-- log DEBUG from any log API using a logger name starting with `org.my.foo` -->
    <logger name="org.my.foo" level="DEBUG"/>

    <root level="ERROR">
        <appender-ref ref="STDOUT" />
    </root>
</configuration>

Notes

Rev. 1835281 by rotty3000 on Fri, 6 Jul 2018 20:50:28 +0000
Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.