You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@felix.apache.org by ro...@apache.org on 2018/07/06 20:26:57 UTC
svn commit: r1835279 - /felix/trunk/logback/logback/README.md
Author: rotty3000
Date: Fri Jul 6 20:26:57 2018
New Revision: 1835279
URL: http://svn.apache.org/viewvc?rev=1835279&view=rev
Log:
[logback] sync README with the CMS page
Signed-off-by: Raymond Auge <ro...@apache.org>
Modified:
felix/trunk/logback/logback/README.md
Modified: felix/trunk/logback/logback/README.md
URL: http://svn.apache.org/viewvc/felix/trunk/logback/logback/README.md?rev=1835279&r1=1835278&r2=1835279&view=diff
==============================================================================
--- felix/trunk/logback/logback/README.md (original)
+++ felix/trunk/logback/logback/README.md Fri Jul 6 20:26:57 2018
@@ -6,33 +6,30 @@ With **OSGi R7** the **Log Service Speci
This project is intended to help bridge the last frontier of OSGi logging by leveraging many capabilities of [Logback](https://logback.qos.ch/), the new **Log 1.4** features to provide a **unified backend** where:
-1. all logging is configured in one place
+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
-The LICENSE is of course [Apache License Version 2.0](./LICENSE).
-
## Depedencies
-First, to add Logback to an OSGi framework include the following dependencies
+To add Logback to an OSGi framework include the following dependencies
-```xml
-<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>
-```
+ :::xml
+ <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.
@@ -42,9 +39,9 @@ Configuring logback is most easily handl
This is an example using a *bndrun* file:
-```properties
--runproperties: logback.configurationFile=file:${.}/logback.xml
-```
+ :::properties
+ -runproperties: logback.configurationFile=file:${.}/logback.xml
+
where in bnd `${.}` gives the path to the directory of the bndrun file.
@@ -65,16 +62,15 @@ The **standard approach** is to install
**cons**:
-- due to the fact that logging APIs are most comonly static there is an inevitable race condition which is exacerbated by aspects such as:
+- due to the fact that logging APIs are most commonly static there is an inevitable race condition which is exacerbated by aspects such as:
- the order in which the bundles are started
- which bundle makes the first call the static API that most-likely has the side effect of binding an implementation
- - it's not possible to ensure that all log records are temporaly recieved when they are made which means that some form of queue[*](*) is required to temporarily store records until the log engine is ready or, as in the vast majority of cases, simply fail outright.
-
-[^*]: *(In the case of the OSGi Log Service this is handled by implementations that support Log 1.4, or perhaps earlier through proprietary means. Most logging frameworks simply do not support this type of feature.)*
+ - buffering is required to collect the complete set of logs, but configuring the buffer to hold that many logs can cause memory issues, or if too small to lose records. Also, some logging frameworks simply don't provide such buffering, and some actually simply fail in this scenario.
+ In the case of the OSGi Log Service this is handled by implementations that support Log 1.4, or perhaps earlier through proprietary means.
-### The RunPath Approach
+### The Immediate Approach
-The **runpath approach** is intended overcome the **cons** of *the standard approach*; to initialize the log engine and allow APIs to bind to implementations as early as possible in order to capture all records without resorting to a queues, being worried about binding issues, or having to be concerned with missed logs due to start ordering.
+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**:
@@ -83,13 +79,13 @@ The **runpath approach** is intended ove
**cons**:
-- bundles on the runpath are not installed into the framework and so they cannot be managed through regular means. *On the other hand, logging is one of those infrastructural aspects that trancends the application and for which there are very few scenarios under which one would want to manage logging API or implementation bundles this way. Configuration? Sure!*
+- bundles on the framework class path are not installed into the framework so they cannot be managed through regular means. *On the other hand, logging is one of those infrastructural aspects that transcends the application and for which there are very few scenarios under which one would want to manage logging API or implementation bundles this way. Configuration? Sure!*
## Unified Backend
-Of course adding Logback does not magically result in all logs being funnelled 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.
+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 setting up the various logging APIs can be found in the integration tests of the project.
+Many examples of setting up the various logging APIs can be found in the integration tests of the project.
The following APIs are tested:
@@ -103,48 +99,48 @@ The following APIs are tested:
## Mapping of OSGi Events
-The OSGi Log specification describes events resulting in log records. **Log 1.4** defines logger names mapping to these 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<br />`STARTED` - BundleEvent STARTED<br />`STOPPED` - BundleEvent STOPPED<br />`UPDATED` - BundleEvent UPDATED<br />`UNINSTALLED` - BundleEvent UNINSTALLED<br />`RESOLVED` - BundleEvent RESOLVED<br />`UNRESOLVED` - BundleEvent UNRESOLVED |
-| Service event | `Events.Service` | `REGISTERED` - ServiceEvent REGISTERED<br /> `MODIFIED` - ServiceEvent MODIFIED<br /> `UNREGISTERING` - ServiceEvent UNREGISTERING |
-| Framework event | `Events.Framework` | `STARTED` - FrameworkEvent STARTED<br />`ERROR` - FrameworkEvent ERROR<br />`PACKAGES_REFRESHED` - FrameworkEvent PACKAGES REFRESHED<br />`STARTLEVEL_CHANGED` - FrameworkEvent STARTLEVEL CHANGED<br />`WARNING` - FrameworkEvent WARNING<br />`INFO` - FrameworkEvent INFO |
-| Legacy Log Service events | `LogService` | any log events originating from bundles that used the original `LogService` logging API |
+Event | Logger Name | Events types
+------------------------- | ------------------ | ------------------------------------------------------------
+Bundle event | `Events.Bundle` | `INSTALLED` - BundleEvent INSTALLED<br />`STARTED` - BundleEvent STARTED<br />`STOPPED` - BundleEvent STOPPED<br />`UPDATED` - BundleEvent UPDATED<br />`UNINSTALLED` - BundleEvent UNINSTALLED<br />`RESOLVED` - BundleEvent RESOLVED<br />`UNRESOLVED` - BundleEvent UNRESOLVED
+Service event | `Events.Service` | `REGISTERED` - ServiceEvent REGISTERED<br /> `MODIFIED` - ServiceEvent MODIFIED<br /> `UNREGISTERING` - ServiceEvent UNREGISTERING
+Framework event | `Events.Framework` | `STARTED` - FrameworkEvent STARTED<br />`ERROR` - FrameworkEvent ERROR<br />`PACKAGES_REFRESHED` - FrameworkEvent PACKAGES REFRESHED<br />`STARTLEVEL_CHANGED` - FrameworkEvent STARTLEVEL CHANGED<br />`WARNING` - FrameworkEvent WARNING<br />`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** makes it possible to refer to these mappings per bundle by appending a period (`.`) and segments of the `Bundle-SymbolicName` of the originating bundle(s) to the logger names. This greatly improves the configurability.
+**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:
-```xml
-<configuration>
- <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"/>
-
- <!-- WARN framework service events, because we can -->
- <logger name="Events.Service.org.eclipse.osgi" level="WARN"/>
-
- <!-- turn OFF legacy Log Service records from bundles with BSN `org.baz.*` -->
- <logger name="LogService.org.baz" level="OFF"/>
-
- <!-- DEBUG service events for bundles with BSN `org.fum.*` -->
- <logger name="Events.Service.org.fum" level="DEBUG"/>
-
- <!-- DEBUG custom project -->
- <logger name="org.my.foo" level="DEBUG"/>
-
- <root level="ERROR">
- <appender-ref ref="STDOUT" />
- </root>
-</configuration>
-```
+ :::xml
+ <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