Title: Logging
## WebTail
The Web Console Plugin also supports tailing of the current active log files.
It generates link to all active log files which can be used to see there content
from within the browser. The url used is like
```
http://localhost:8080/system/console/slinglog/tailer.txt?tail=1000&grep=lucene&name=%2Flogs%2Ferror.log
```
It supports following parameters
* `name` - Appender name like _/logs/error.log_
* `tail` - Number of lines to include in dump. -1 to include whole file
* `grep` - Filter the log lines based on `grep` value which can be
* Simple string phrase - In this case search is done in case insensitive way via String.contains
* regex - In this case the search would be done via regex pattern matching
## Initial Configuration
The `org.apache.sling.commons.log` bundle gets its initial configuration from the following `BundleContext` properties:
| Property | Default | Description |
|--|--|--|
| `org.apache.sling.commons.log.level` | `INFO` | Sets the initial logging level of the root logger. This may be any of the defined logging levels `DEBUG`, `INFO`, `WARN`, `ERROR` and `FATAL`. |
| `org.apache.sling.commons.log.file` | undefined | Sets the log file to which log messages are written. If this property is empty or missing, log messages are written to `System.out`. |
| `org.apache.sling.commons.log.file.number` | 5 | The number of rotated files to keep. |
| `org.apache.sling.commons.log.file.size` | '.'yyyy-MM-dd | Defines how the log file is rotated (by schedule or by size) and when to rotate. See the section *Log File Rotation* below for full details on log file rotation. |
| `org.apache.sling.commons.log.pattern` | \{0,date,dd.MM.yyyy HH:mm:ss.SSS\} \*\{4\}\* \[\{2\}\]({{ refs.-2.path }}) \{3\} \{5\} | The `MessageFormat` pattern to use for formatting log messages with the root logger. |
| `org.apache.sling.commons.log.julenabled` | n/a | Enables the `java.util.logging` support. |
| `org.apache.sling.commons.log.configurationFile` | n/a | Path for the Logback config file which would be used to configure logging. If the path is not absolute then it would be resolved against Sling Home |
| `org.apache.sling.commons.log.packagingDataEnabled` | true | Boolean property to control packaging data support of Logback. See [Packaging Data][11] section of Logback for more details |
| `org.apache.sling.commons.log.numOfLines` | 1000 | Number of lines from each log files to include while generating the dump in 'txt' mode. If set to -1 then whole file would be included |
| `org.apache.sling.commons.log.maxOldFileCountInDump` | 3 | Maximum number of old rolled over files for each active file to be included while generating the dump as part of Status zip support |
| `sling.log.root` | Sling Home | The directory, which is used to resolve relative path names against. If not specified it would map to sling.home. Since [4.0.2](https://issues.apache.org/jira/browse/SLING-4225)|
## User Configuration - OSGi Based
User Configuration after initial configuration is provided by the Configuration Admin Service. To this avail two
`org.osgi.services.cm.ManagedServiceFactory` services are registered under the PIDs `org.apache.sling.commons.log.LogManager.factory.writer`
and `org.apache.sling.commons.log.LogManager.factory.config` to receive configurations.
### Logger Configuration
Loggers (or Categories) can be configured to log to specific files at specific levels using configurable patterns.
To this avail factory configuration instances with factory PID `org.apache.sling.commons.log.LogManager.factory.config`
may be created and configured with the Configuration Admin Service.
The following properties may be set:
| Property | Type | Default | Description |
|--|--|--|--|
| `org.apache.sling.commons.log.level` | `String` | `INFO` | Sets the logging level of the loggers. This may be any of the defined logging levels `DEBUG`, `INFO`, `WARN`, `ERROR` and `FATAL`. |
| `org.apache.sling.commons.log.file` | `String` | undefined | Sets the log file to which log messages are written. If this property is empty or missing, log messages are written to `System.out`. This property should refer to the file name of a configured Log Writer (see below). If no Log Writer is configured with the same file name an implicit Log Writer configuration with default configuration is created. |
| `org.apache.sling.commons.log.pattern` | `String` | \{0,date,dd.MM.yyyy HH:mm:ss.SSS\} \*\{4\}\* \[\{2\}\]({{ refs.-2.path }}) \{3\} \{5\} | The `java.util.MessageFormat` pattern to use for formatting log messages with the root logger. This is a `java.util.MessageFormat` pattern supporting up to six arguments: \{0\} The timestamp of type `java.util.Date`, \{1\} the log marker, \{2\} the name of the current thread, \{3\} the name of the logger, \{4\} the log level and \{5\} the actual log message. If the log call includes a Throwable, the stacktrace is just appended to the message regardless of the pattern. |
| `org.apache.sling.commons.log.names` | `String\[\]` | -- | A list of logger names to which this configuration applies. |
| `org.apache.sling.commons.log.additiv` | `Boolean` | false | If set to false then logs from these loggers would not be sent to any appender attached higher in the hierarchy |
Note that multiple Logger Configurations may refer to the same Log Writer Configuration. If no Log Writer Configuration
exists whose file name matches the file name set on the Logger Configuration an implicit Log Writer Configuration
with default setup (daily log rotation) is internally created. While the log level configuration is case insensitive, it
is suggested to always use upper case letters.
### Log Writer Configuration
Log Writer Configuration is used to setup file output and log file rotation characteristics for log writers used by the Loggers.
The following properties may be set:
| Property | Default | Description |
|--|--|--|
| `org.apache.sling.commons.log.file` | undefined | Sets the log file to which log messages are written. If this property is empty or missing, log messages are written to `System.out`. |
| `org.apache.sling.commons.log.file.number` | 5 | The number of rotated files to keep. |
| `org.apache.sling.commons.log.file.size` | '.'yyyy-MM-dd | Defines how the log file is rotated (by schedule or by size) and when to rotate. See the section *Log File Rotation* below for full details on log file rotation. |
See the section *Log File Rotation* below for full details on the `org.apache.sling.commons.log.file.size` and
`org.apache.sling.commons.log.file.number` properties.
#### Log File Rotation
Log files can grow rather quickly and fill up available disk space. To cope with this growth log files may be rotated in
two ways: At specific times or when the log file reaches a configurable size. The first method is called *Scheduled Rotation*
and is used by specifying a `SimpleDateFormat` pattern as the log file "size". The second method is called *Size Rotation*
and is used by setting a maximum file size as the log file size.
As of version 2.0.6 of the Sling Commons Log bundle, the default value for log file scheduling is `'.'yyyy-MM-dd`
causing daily log rotation. In previous version, log rotation defaults to a 10MB file size limit.
##### Scheduled Rotation
The rolling schedule is specified by setting the `org.apache.sling.commons.log.file.size` property to a
`java.text.SimpleDateFormat` pattern. Literal text (such as a leading dot) to be included must be *enclosed* within a
pair of single quotes. A formatted version of the date pattern is used as the suffix for the rolled file name. Internally
the Log bundle configures a `TimeBasedRollingPolicy` for the appender. Refer to [TimeBasedRollingPolicy][10] for
more details around the pattern format
For example, if the log file is configured as `/foo/bar.log` and the pattern set to `'.'yyyy-MM-dd`, on
2001-02-16 at midnight, the logging file `/foo/bar.log` will be renamed to `/foo/bar.log.2001-02-16` and logging for
2001-02-17 will continue in a new `/foo/bar.log` file until it rolls over the next day.
It is possible to specify monthly, weekly, half-daily, daily, hourly, or minutely rollover schedules.
| DatePattern | Rollover schedule | Example |
|--|--|--|
| `'.'yyyy-MM` | Rollover at the beginning of each month | At midnight of May 31st, 2002 `/foo/bar.log` will be copied to `/foo/bar.log.2002-05`. Logging for the month of June will be output to `/foo/bar.log` until it is also rolled over the next month. |
| `'.'yyyy-ww` | Rollover at the first day of each week. The first day of the week depends on the locale. | Assuming the first day of the week is Sunday, on Saturday midnight, June 9th 2002, the file `/foo/bar.log` will be copied to `/foo/bar.log.2002-23`. Logging for the 24th week of 2002 will be output to `/foo/bar.log` until it is rolled over the next week. |
| `'.'yyyy-MM-dd` | Rollover at midnight each day.| At midnight, on March 8th, 2002, `/foo/bar.log` will be copied to `/foo/bar.log.2002-03-08`. Logging for the 9th day of March will be output to `/foo/bar.log` until it is rolled over the next day.|
| `'.'yyyy-MM-dd-a` | Rollover at midnight and midday of each day.| at noon, on March 9th, 2002, `/foo/bar.log` will be copied to `/foo/bar.log.2002-03-09-AM`. Logging for the afternoon of the 9th will be output to `/foo/bar.log` until it is rolled over at midnight.|
| `'.'yyyy-MM-dd-HH` | Rollover at the top of every hour.| At approximately 11:00.000 o'clock on March 9th, 2002, `/foo/bar.log` will be copied to `/foo/bar.log.2002-03-09-10`. Logging for the 11th hour of the 9th of March will be output to `/foo/bar.log` until it is rolled over at the beginning of the next hour.|
| `'.'yyyy-MM-dd-HH-mm` | Rollover at the beginning of every minute.| At approximately 11:23,000, on March 9th, 2001, `/foo/bar.log` will be copied to `/foo/bar.log.2001-03-09-10-22`. Logging for the minute of 11:23 (9th of March) will be output to `/foo/bar.log` until it is rolled over the next minute.|
Do not use the colon ":" character in anywhere in the pattern option. The text before the colon is interpreted as the
protocol specification of a URL which is probably not what you want.
Note that Scheduled Rotation ignores the `org.apache.sling.commons.log.file.number` property since the old log files are
not numbered but "dated".
##### Size Rotation
Log file rotation by size is specified by setting the `org.apache.sling.commons.log.file.size` property to a plain number
or a number plus a size multiplier. The size multiplier may be any of `K`, `KB`, `M`, `MB`, `G`, or `GB` where the case
is ignored and the meaning is probably obvious.
When using Size Rotation, the `org.apache.sling.commons.log.file.number` defines the number of old log file generations
to keep. For example to keep 5 old log files indexed by 0 through 4, set the `org.apache.sling.commons.log.file.number`
to `5` (which happens to be the default).
## Logback Integration
Logback integration provides following features
* LogBack configuration can be provided via Logback config xml
* Supports Appenders registered as OSGi Services
* Supports Filters and TurboFilters registered as OSGi Services
* Support providing Logback configuration as fragments through OSGi Service Registry
* Support for referring to Appenders registered as OSGi services from with Logback config
* Exposes Logback runtime state through the Felix WebConsole Plugin
The following sections provide more details.
### TurboFilters as OSGi Services
[Logback TurboFilters][3] operate globally and are invoked for every Logback call. To register an OSGi `TurboFilter`,
just to register an service that implements the `ch.qos.logback.classic.turbo.TurboFilter` interface.
:::java
import import ch.qos.logback.classic.turbo.MatchingFilter;
SimpleTurboFilter stf = new SimpleTurboFilter();
ServiceRegistration sr = bundleContext.registerService(TurboFilter.class.getName(), stf, null);
private static class SimpleTurboFilter extends MatchingFilter {
@Override
public FilterReply decide(Marker marker, Logger logger, Level level, String format,
Object[] params, Throwable t) {
if(logger.getName().equals("turbofilter.foo.bar")){
return FilterReply.DENY;
}
return FilterReply.NEUTRAL;
}
}
As these filters are invoked for every call they must execute quickly.
### Filters as OSGi services
[Logback Filters][1] are attached to appenders and are used to determine if any LoggingEvent needs to
be passed to the appender. When registering a filter the bundle needs to configure a service property
`appenders` which refers to list of appender names to which the Filter must be attached
:::java
import ch.qos.logback.core.filter.Filter;
SimpleFilter stf = new SimpleFilter();
Dictionary