thekid/rfc — Issue #192: RFC 0192: Logging API enhancements
Author: thekid
Created: 2011-10-09 15:42:35+00:00
State: closed
Labels: implemented, rfc

Scope of Change
====
The logging API util.log will be internally refactored and support new log
format tokens.
At the same time, the generation of the filename of a LogAppender will become
the appender's duty - it will be able to generate updated filenames after a
day turnaround.

Rationale
====

Tokens
----

The token format was changed to support more tokens, some of which require
rather expensive calculations at runtime. As the old sprintf() approach was
simple, it required calculating all possible values every time, regardless of
whether they were used or not.
The new approach implements an on-demand calculation of parameters and is
easier from human readability perspective.

Configuration evaluation
----

Evaluation of configuration settings will be delegated on to the instance
that actually makes use of the configuration.

Functionality
====
The refactoring is composed of the following:

- Creating a new LoggingEvent class which will carry information about
the date, level, pid, category and message.
- Changing the LogAppender::append() method's signature from varargs
to this new class
- Creating a new LogLayout object that will take care of formatting
this event.

LoggingEvent
----
The event class is a value object which captures a single log entry:

```php

```

LogLayout
----
The layout class

```php

```

The placeholder tokens used for `util.log.PatternLayout` are:
. {DATE} => prints the current date in datefmt format
. {PID} => prints process id of current process
. {LEVEL} => prints level of log message
. {CATEGORY} => prints category
. {MESSAGE} => prints message

The old tokens will still be supported for BC until XP 5.8.

Configuration
----

Eg. the FileAppender will be given the original config setting for its filename
so it will be enabled to generate a new filename once the an external event
(eg. midnight) will lead to a newly generated filename.

Security considerations
====
n/a

Speed impact
====
n/a

Dependencies
====
n/a

Related documents
====
* xp-framework/rfc #64 - RollingFileAppender
* http://logging.apache.org/log4net/release/sdk/log4net.Layout.PatternLayout.html

Comments
====