Pax Logging - OPS4J

The current release is 1.1.1 - available from the OPS4J Maven repository

Also see the [official docs|http://www.ops4j.org/projects/pax/logging].

Purpose

The logging support in the standard Log Service of the OSGi specification is minimalistic and not entirely suitable for enterprise applications. This project tries to address this by extending the standard interface with additional interfaces and using a strong logging backend, the Apache Log4J. Pax Logging defines its own API, but more importantly it supports the Log4J and Jakarta Commons Logging APIs as well, making it easy to create bundles that use these common APIs, either directly in new code or indirectly from inside 3rd party libraries.

Features

Log4J driving the backend implementation.
Log4J API supported.
Jakarta Commons Logging API supported.
Pax Logging Service implements the standard OSGi Log Service API.
JDK Logging API support.
Avalon Logger API support.
SLF4J API support.
Knopflerfish Log service support.
Tomcat Juli API support.

Roadmap

We are getting closer and closer to a final release of Pax Logging. The main features missing for a 1.0 release at this point are;

Full support of packaging Appender and Layout implementations in installable bundles.
Full OSGi Log Service spec compliance in Pax Logging Service. Missing right now is the LogReader service.
A PaxLogger factory class for the API bundle to make the usage of the native Pax Logging API simpler.

Any help in these areas are greatly appreciated.

Installation

Manual installation

Download the latest version from http://repository.ops4j.org/maven2/org/ops4j/pax/logging/.
- pax-logging-api (1.1.0)
- pax-logging-service (1.1.0)
Deploy the downloaded bundle to your prefered OSGi framework

Using Pax Runner profile option

You can automatically include pax logging in your deployed installed bundles when using Pax Runner by using the profile option. Following is the most simple example to include a log profile:

pax-run "--profiles=log"

Using Pax Runner provisioning

You can automatically provision the pax logging bundles by using any of the scanners. Here are some examples:

Using the dir scanner
- Download the pax logging bundles (see above) and place them in a folder
- Start a command line
- cd to that folder
- start pax runner: pax-run

Using the pom scanner

...
    <dependency>
      <groupId>org.ops4j.pax.logging</groupId>
      <artifactId>pax-logging-api</artifactId>
      <version>1.1.0</version>
    </dependency>
    <dependency>
      <groupId>org.ops4j.pax.logging</groupId>
      <artifactId>pax-logging-service</artifactId>
      <version>1.1.0</version>
    </dependency>
...

Using the file scanner

...
mvn:org.ops4j.pax.logging/pax-logging-api/1.1.0
mvn:org.ops4j.pax.logging/pax-logging-service/1.1.0

Using Pax Construct

Install Pax Construct http://www.ops4j.org/projects/pax/construct/
Create a project using pax-create-project (if you do not already have one)

Ensure that you have the following repository:

<repository>
  <id>ops4j.releases</id>
  <url>http://repository.ops4j.org/maven2/</url>
</repository>

Import pax logging api bundle using pax-import-bundle -g org.ops4j.pax.logging -a pax-logging-api -v 1.1.0
Import pax logging service bundle using pax-import-bundle -g org.ops4j.pax.logging -a pax-logging-service -v 1.1.0
Start mvn pax:provision

A more detailed example is shown below:

# this assumes you are using Pax-Construct v1.1
# ---------------------------------------------

pax-create-project -g mygroup -a project

cd project

# add the OPS4J release repository, as Pax-Logging is not on central yet...
pax-add-repository -i ops4j.releases -u http://repository.ops4j.org/maven2/

pax-create-bundle -p mygroup.mybundle -n mybundle

# import the Pax-Logging bundles for the global project
pax-import-bundle -g org.ops4j.pax.logging -a pax-logging-api -v 1.1.0
pax-import-bundle -g org.ops4j.pax.logging -a pax-logging-service -v 1.1.0

# NOTE that by default this global set of imported bundles is NOT added to
# the classpath of individual bundles (this is to avoid potential clashes)
# but you can edit the pom.xml of individual bundles to add this classpath
# ... see example below ...

# BTW, the directory is 'mybundle' not 'mygroup.mybundle' because you chose
# a specific name using the -n option, and the directory comes from the name

cd mybundle

# here you have a choice if you want to compile against the Log4J API

# ==either==

# 1) import the Pax-Logging API bundle for this particular local bundle
pax-import-bundle -g org.ops4j.pax.logging -a pax-logging-api -v 1.1.0

# ==OR==

# 2) uncomment the following entry from the generated local bundle pom:

#    <!--
#     | uncomment to add all imported (non-local) bundles to your compilation classpath
#    <dependency>
#      <type>pom</type>
#      <groupId>${parent.groupId}</groupId>
#      <artifactId>provision</artifactId>
#      <optional>true</optional>
#    </dependency>
#    -->

# to get the global classpath, including the logging bundles you just imported

# ==OR==

# 3) manually add the Log4J artifact to your bundle as a *compile* dependency

#    <dependency>
#      <groupId>log4j</groupId>
#      <artifactId>log4j</artifactId>
#      <version>1.2.13</version>
#      <scope>compile</scope>
#      <optional>true</optional>
#    </dependency>

# do NOT add the Log4J artifact using pax-import-bundle, or add it using provided
# scope, as it will then be deployed onto the OSGi framework and potentially cause
# problems. Instead rely on the Pax-Logging API bundle at deploy time, even if you
# decide the compile against the real Log4J artifact at compile time.

# You can now add your Log4J call to the bundle activator and it should compile ok:
#
#    org.apache.log4j.Logger.getLogger(this.getClass()).info("LOG4J message");
#

cd ..

# head back to the project root and let's try to build and deploy...

mvn clean install pax:provision

Configuration

By default, there is a Root logger created in the Pax Logging Service, which is set to DEBUG level and a fairly extensive output format to the ConsoleAppender.
This configuration may be suitable for the initial startup, and by using the Config Admin Service you can configure logging as you need. The configuration pid used by Pax Logging is org.ops4j.pax.logging. The Dictionary object provided from the Config Admin Service must be the log4j.properties file itself (keys starting with "log4j"). This configuration will be applied across all Loggers.

Deprecation: Pax Logging used to support for each Bundle that it defines two manifest entries, which will provide some default configuration for such client bundle.

Log4J-LoggerName : Defines the Logger name to be used for the Bundle. If not defined, the Bundle location will be used instead.
Log4J-ConfigFile : Defines the name of the Log4J configuration file, which contains the default configuration for this bundle. The configuration file is resolved relative to the Bundle classloader, which means that it is typically part of the Bundle itself. Recommended name is log4j.properties sitting in the Bundle jar's root.

Deprecation: Pax Logging used to support that a Pax Logging client connected to the standard OSGi Log Service. This is no longer supported. We will work to improve the the Pax Logging Service to the full spec of the standard OSGi Log Service. This may however still take some time.

Deprecation: Pax Logging used to support Log4J-ConfigFile entry in Dictionary object provided from the Config Admin Service. This is no longer supported. Only entries starting with "log4j" in Dictionary object are used for configuration.

Change Log

Check out the following page to find out what is changed in each version of Pax Logging.

FAQ

If the above description did not anwer what you are looking for you may checkout the FAQ page.

Labels