You are viewing a plain text version of this content. The canonical link for it is here.
Posted to log4php-dev@logging.apache.org by ih...@apache.org on 2011/01/08 15:28:57 UTC
svn commit: r1056712 [1/2] - in /logging/log4php/trunk/src/site: ./ apt/
apt/docs/ apt/docs/appender/
Author: ihabunek
Date: Sat Jan 8 14:28:56 2011
New Revision: 1056712
URL: http://svn.apache.org/viewvc?rev=1056712&view=rev
Log:
Updated the site documentation, added XML examples everywhere, rewrote a fair amount of it to make it easier to understand.
Added:
logging/log4php/trunk/src/site/apt/docs/appender/
logging/log4php/trunk/src/site/apt/docs/appender/appender.apt
logging/log4php/trunk/src/site/apt/docs/appender/filter.apt
logging/log4php/trunk/src/site/apt/docs/appender/layout.apt
logging/log4php/trunk/src/site/apt/docs/appender/threshold.apt
logging/log4php/trunk/src/site/apt/docs/loggers.apt
Removed:
logging/log4php/trunk/src/site/apt/docs/appender-filter.apt
logging/log4php/trunk/src/site/apt/docs/appender-layout.apt
logging/log4php/trunk/src/site/apt/docs/appender-threshold.apt
logging/log4php/trunk/src/site/apt/docs/appenders.apt
logging/log4php/trunk/src/site/apt/usage.apt
Modified:
logging/log4php/trunk/src/site/apt/contributingpatches.apt
logging/log4php/trunk/src/site/apt/docs/configuration.apt
logging/log4php/trunk/src/site/apt/docs/introduction.apt
logging/log4php/trunk/src/site/apt/docs/performance.apt
logging/log4php/trunk/src/site/apt/docs/renderer.apt
logging/log4php/trunk/src/site/apt/download.apt
logging/log4php/trunk/src/site/apt/index.apt
logging/log4php/trunk/src/site/apt/install.apt
logging/log4php/trunk/src/site/apt/quickstart.apt
logging/log4php/trunk/src/site/apt/roadmap.apt
logging/log4php/trunk/src/site/apt/showcase.apt
logging/log4php/trunk/src/site/apt/upgrading.apt
logging/log4php/trunk/src/site/apt/volunteering.apt
logging/log4php/trunk/src/site/site.xml
Modified: logging/log4php/trunk/src/site/apt/contributingpatches.apt
URL: http://svn.apache.org/viewvc/logging/log4php/trunk/src/site/apt/contributingpatches.apt?rev=1056712&r1=1056711&r2=1056712&view=diff
==============================================================================
--- logging/log4php/trunk/src/site/apt/contributingpatches.apt (original)
+++ logging/log4php/trunk/src/site/apt/contributingpatches.apt Sat Jan 8 14:28:56 2011
@@ -13,7 +13,7 @@
~~ See the License for the specific language governing permissions and
~~ limitations under the License.
------
- Apache log4php
+ Contributing Patches
------
------
------
Added: logging/log4php/trunk/src/site/apt/docs/appender/appender.apt
URL: http://svn.apache.org/viewvc/logging/log4php/trunk/src/site/apt/docs/appender/appender.apt?rev=1056712&view=auto
==============================================================================
--- logging/log4php/trunk/src/site/apt/docs/appender/appender.apt (added)
+++ logging/log4php/trunk/src/site/apt/docs/appender/appender.apt Sat Jan 8 14:28:56 2011
@@ -0,0 +1,819 @@
+~~ Licensed to the Apache Software Foundation (ASF) under one or more
+~~ contributor license agreements. See the NOTICE file distributed with
+~~ this work for additional information regarding copyright ownership.
+~~ The ASF licenses this file to You under the Apache License, Version 2.0
+~~ (the "License"); you may not use this file except in compliance with
+~~ the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing, software
+~~ distributed under the License is distributed on an "AS IS" BASIS,
+~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+~~ See the License for the specific language governing permissions and
+~~ limitations under the License.
+ ------
+Appenders
+ ------
+ ------
+ ------
+
+Appenders
+
+ Logging requests can be sent to multiple destinations, such as files, databases, syslog and others. Such destinations are called appenders. Appenders are attached to {{{../loggers.html}loggers}} and each logger can have one or more attached appenders.
+
+* Configuring appenders
+
+ An appender can be configured in the configuration file. The following example shows how to configure an appender which logs to a file:
+
++--
+<appender name="myAppender" class="LoggerAppenderFile">
+ <layout class="LoggerLayoutSimple" />
+ <param name="file" value="/var/log/my.log" />
+ <param name="append" value="true" />
+</appender>
++--
+
+ From this configuration you can see that an appender has the following settings:
+
+ * A <<name>> which uniquely identifies it, in this case <myAppender>.
+
+ * A <<class>> which specifies which appender class will be used to handle the requests. Since we wish to log to a file, <LoggerAppenderFile> is used in this case.
+
+ * Most appenders have an associated {{{layout.html}layout}}, which governs how the message is formatted.
+
+ * An appender can have zero or more <<parameters>> which configure it's behaviour. In our example, the <file> parameter governs the path to the file which will be used for logging, and <append> defines that log messages should be appended to the file, instead of truncating it.
+
+ []
+
+ The same configuration via an ini file:
+
++--
+log4php.appender.myAppender = LoggerAppenderFile
+log4php.appender.myAppender.layout = LoggerLayoutSimple
+log4php.appender.myAppender.file = /var/log/my.log
+log4php.appender.myAppender.append = true
++--
+
+* Linking appenders to loggers
+
+ Appenders are linked to loggers in the configuration file.
+
+ Example XML configuration:
+
++--
+<log4php:configuration xmlns:log4php="http://logging.apache.org/log4php/">
+ <appender name="primus" class="LoggerAppenderConsole" />
+ <appender name="secundus" class="LoggerAppenderFile">
+ <param name="file" value="/var/log/my.log" />
+ </appender>
+ <logger name="main">
+ <appender_ref ref="primus" />
+ <appender_ref ref="secundus" />
+ </logger>
+</log4php:configuration>
++--
+
+ Equivalent ini configuration:
+
++--
+log4php.appender.primus = LoggerAppenderEcho
+log4php.appender.secundus = LoggerAppenderFile
+log4php.appender.secundus.file = /var/log/my.log
+log4php.logger.main = DEBUG, primus, secundus
++--
+
+ This configuration file defines two appenders: <primus> and <secundus>, and links them to a logger named <main>.
+
+ Now, when a logging request is issued to the <main> logger:
+
++--
+$logger = Logger::getLogger('main');
+$logger->info("Log this.");
++--
+
+ The logger will forward this logging requests to all appenders which are linked with it. In our example, the output will be written both to console and to the file.
+
+* {Appender Reference}
+
+ The following appenders are included with log4php.
+
+*------------------------------+--------------+
+|| Name || Destination
+*------------------------------+--------------+
+| {{LoggerAppenderEcho}} | Console, using the PHP <<echo>> command.
+*------------------------------+--------------+
+| {{LoggerAppenderConsole}} | STDOUT or STDERR
+*------------------------------+--------------+
+| {{LoggerAppenderFile}} | A file.
+*------------------------------+--------------+
+| {{LoggerAppenderDailyFile}} | A file (new file each day).
+*------------------------------+--------------+
+| {{LoggerAppenderRollingFile}}| A file (new file when a specified size has been reached).
+*------------------------------+--------------+
+| {{LoggerAppenderMail}} | Sends the log via email. The entire log is sent in one email.
+*------------------------------+--------------+
+| {{LoggerAppenderMailEvent}} | Sends the log via email. Each log entry is sent in individual emails.
+*------------------------------+--------------+
+| {{LoggerAppenderNull}} | Ignores all log events.
+*------------------------------+--------------+
+| {{LoggerAppenderPDO}} | Database.
+*------------------------------+--------------+
+| {{LoggerAppenderPhp}} | Creates a PHP user-level message using the PHP <<trigger_error>> function.
+*------------------------------+--------------+
+| {{LoggerAppenderSocket}} | A network socket.
+*------------------------------+--------------+
+| {{LoggerAppenderSyslog}} | Syslog.
+*------------------------------+--------------+
+
+
+** {LoggerAppenderEcho}
+
+ The LoggerAppenderEcho appender writes logging events using PHP's {{{http://php.net/manual/en/function.echo.php}echo}} function. Echo outputs may be buffered.
+
+*** Configurable parameters
+
+*-------------------+--------------*--------------------+------------------------+
+|| Parameter || Required || Default value || Description
+*-------------------+--------------*--------------------+------------------------+
+| htmlLineBreaks | No | false | If set to true, a \<br /\> element will be inserted before each line break in the logged message.
+*-------------------+--------------*--------------------+------------------------+
+
+*** Examples
+
+ Configuration via XML file:
+
++--
+<appender name="default" class="LoggerAppenderEcho">
+ <layout class="LoggerLayoutTTCC" />
+ <param name="htmlLineBreaks" value="true" />
+</appender>
++--
+
+ Configuration via ini file:
+
++--
+log4php.appender.default = LoggerAppenderEcho
+log4php.appender.default.layout = LoggerLayoutTTCC
+log4php.appender.default.htmlLineBreaks = "true"
++--
+
+** {LoggerAppenderConsole}
+
+ The LoggerAppenderConsoler appender writes logging events to the STDOUT (php://stdout) or STDERR (php://stderr) stream. Defaults to STDOUT.
+
+*** Configurable parameters
+
+*-------------------+--------------*--------------------+------------------------+
+|| Parameter || Required || Default value || Description
+*-------------------+--------------*--------------------+------------------------+
+| target | No | stdout | Sets the otuput stream to which this appender should write to. Possible values are "stdout" for standard output stream and "stderr" for standard error stream.
+*-------------------+--------------*---------------------------------------------*
+
+*** Examples
+
+ Configuration via XML file:
+
++--
+<appender name="default" class="LoggerAppenderConsole">
+ <layout class="LoggerLayoutTTCC" />
+ <param name="target" value="STDOUT" />
+</appender>
++--
+
+ Configuration via ini file:
+
++--
+log4php.appender.console = LoggerAppenderConsole
+log4php.appender.console.target = STDOUT
+log4php.appender.console.layout = LoggerLayoutTTCC
++--
+
+
+** {LoggerAppenderFile}
+
+ The LoggerAppenderFile writes logging events to a file.
+
+*** Configurable parameters
+
+*-------------------+--------------*--------------------+------------------------+
+|| Parameter || Required || Default value || Description
+*-------------------+--------------*--------------------+------------------------+
+| file | <<Yes>> | - | Path to the target file.
+*-------------------+--------------*--------------------+------------------------+
+| append | No | true | Defines if the appender should append to the end of the file ("true") or truncate the file before writing ("false").
+*-------------------+--------------*--------------------+------------------------+
+
+*** Examples
+
+ Configuration via XML file:
+
++--
+<appender name="default" class="LoggerAppenderFile">
+ <layout class="LoggerLayoutTTCC" />
+ <param name="file" value="target/examples/file.log" />
+</appender>
++--
+
+ Configuration via ini file:
+
++--
+log4php.appender.default = LoggerAppenderFile
+log4php.appender.default.file = target/examples/file.log
+log4php.appender.default.layout = LoggerLayoutTTCC
++--
+
+
+** {LoggerAppenderDailyFile}
+
+ The LoggerAppenderDailyFile writes logging events to a specified file.
+ The file is rolled over once a day. That means, for each day a new file
+ is created.
+
+ The path specified in the <file> parameter should contain
+ the string '%s' which will be substituted with the current date when logging.
+ The <datePattern> parameter determines how the date will be formatted. It
+ follows the formatting rules used by {{{http://php.net/manual/en/function.date.php}PHP's date function}}.
+
+*** Configurable parameters
+
+*-------------------+--------------*--------------------+------------------------+
+|| Parameter || Required || Default value || Description
+*-------------------+--------------*--------------------+------------------------+
+| file | <<Yes>> | - | Path to the target file. Should contain a '%s' which gets substituted by the date.
+*-------------------+--------------*--------------------+------------------------+
+| append | No | true | Defines if the appender should append to the end of the file ("true") or truncate the file before writing ("false").
+*-------------------+--------------*--------------------+------------------------+
+| datePattern | No | Ymd | Date format for the date in the file path.
+*-------------------+--------------*--------------------+------------------------+
+
+*** Examples
+
+ Configuration via XML file:
+
++--
+<appender name="default" class="LoggerAppenderDailyFile">
+ <layout class="LoggerLayoutTTCC" />
+ <param name="datePattern" value="Y-m-d" />
+ <param name="file" value="/var/log/daily_%s.log" />
+</appender>
++--
+
+ Configuration via ini file:
+
++--
+log4php.appender.default = LoggerAppenderDailyFile
+log4php.appender.default.layout = LoggerLayoutTTCC
+log4php.appender.default.datePattern = Y-m-d
+log4php.appender.default.file = /var/log/daily_%s.log
++--
+
+ Let's say, for example, that today is May 5th 2010. Using the above configuration, LoggerAppenderDailyFile will log to
+ </var/log/daily_2010-05-05.log>
+
+** {LoggerAppenderRollingFile}
+
+ The LoggerAppenderDailyFile appender writes logging events to a file.
+ The file is rolled over after a specified size has been reached.
+
+*-------------------+--------------*--------------------+------------------------+
+|| Parameter || Required || Default value || Description
+*-------------------+--------------*--------------------+------------------------+
+| file | <<Yes>> | - | Path to the target file.
+*-------------------+--------------*--------------------+------------------------+
+| append | No | true | Defines if the appender should append to the end of the file ("true") or truncate the file before writing ("false").
+*-------------------+--------------*--------------------+------------------------+
+| datePattern | No | Ymd | Date format for the date in the file path.
+*-------------------+--------------*--------------------+------------------------+
+| maxBackupIndex | No | 1 | Maximum number of backup files to keep.
+*-------------------+--------------*--------------------+------------------------+
+| maxFileSize | No | 10MB | Maximum allowed file size (in bytes) before rolling over. Suffixes "KB", "MB" and "GB" are allowed. 10KB = 10240 bytes, etc.
+*-------------------+--------------*--------------------+------------------------+
+
+*** Examples
+
+ Configuration via XML file:
+
++--
+<appender name="default" class="LoggerAppenderRollingFile">
+ <layout class="LoggerLayoutTTCC" />
+ <param name="file" value="target/examples/appender_rollingfile.log" />
+ <param name="maxFileSize" value="10MB" />
+ <param name="maxBackupIndex" value="3" />
+</appender>
++--
+
+ Configuration via ini file:
+
++--
+log4php.appender.default = LoggerAppenderRollingFile
+log4php.appender.default.layout = LoggerLayoutTTCC
+log4php.appender.default.file = target/examples/appender_rollingfile.log
+log4php.appender.default.maxFileSize = 10MB
+log4php.appender.default.maxBackupIndex = 3
++--
+
+ The resulting filenames are appender_rollingfile.log, appender_rollingfile.log.1, appender_rollingfile.log.2 and so on.
+
+** {LoggerAppenderMail}
+
+ The LoggerAppenderMail appends log events via email.
+
+ This appender will not send individual emails for each logging requests, but will collect them in a buffer
+ and send them all in a single email once the appender is closed.
+
+*** Configurable parameters
+
+*-------------------+--------------*--------------------+------------------------+
+|| Parameter || Required || Default value || Description
+*-------------------+--------------*--------------------+------------------------+
+| to | <<Yes>> | - | Email address to which the log will be sent
+*-------------------+--------------*--------------------+------------------------+
+| from | <<Yes>> | - | Email address of the sender
+*-------------------+--------------*--------------------+------------------------+
+| subject | <<Yes>> | - | Subject of the mail
+*-------------------+--------------*--------------------+------------------------+
+
+*** Examples
+
+ Configuration via XML file:
+
++--
+<appender name="default" class="LoggerAppenderMail">
+ <layout class="LoggerLayoutTTCC" />
+ <param name="from" value="someone@example.com" />
+ <param name="to" value="root@localhost" />
+ <param name="subject" value="log4php test" />
+</appender>
++--
+
+ Configuration via ini file:
+
++--
+log4php.appender.default = LoggerAppenderMail
+log4php.appender.default.layout = LoggerLayoutTTCC
+log4php.appender.default.from = someone@example.com
+log4php.appender.default.to = root@localhost
+log4php.appender.default.subject = log4php test
++--
+
+
+** {LoggerAppenderMailEvent}
+
+ The LoggerAppenderMailEvent appends log events to mail.
+
+ This appender is similar to the LoggerAppenderMail appender, except that it
+ sends each each log event in an individual email message at the time when
+ it occurs.
+
+*** Configurable parameters
+
+*-------------------+--------------*--------------------+------------------------+
+|| Parameter || Required || Default value || Description
+*-------------------+--------------*--------------------+------------------------+
+| to | <<Yes>> | - | Email address to which the log will be sent
+*-------------------+--------------*--------------------+------------------------+
+| from | <<Yes>> | - | Email address of the sender
+*-------------------+--------------*--------------------+------------------------+
+| subject | <<Yes>> | - | Subject of the mail
+*-------------------+--------------*--------------------+------------------------+
+| smtpHost | No | ini_get('SMTP') | Used to override the SMTP server used for sending the email. <<Only works on Windows>>
+*-------------------+--------------*--------------------+------------------------+
+| port | No | 25 | Used to override the default SMTP server port. <<Only works on Windows>>
+*-------------------+--------------*--------------------+------------------------+
+
+*** Examples
+
+ Configuration via XML file:
+
++--
+<appender name="default" class="LoggerAppenderMailEvent">
+ <layout class="LoggerLayoutTTCC" />
+ <param name="from" value="someone@example.com" />
+ <param name="to" value="root@localhost" />
+ <param name="subject" value="log4php test" />
+</appender>
++--
+
+ Configuration via ini file:
+
++--
+log4php.appender.default = LoggerAppenderMailEvent
+log4php.appender.default.layout = LoggerLayoutTTCC
+log4php.appender.default.from = someone@example.com
+log4php.appender.default.to = root@localhost
+log4php.appender.default.subject = log4php test
++--
+
+
+** {LoggerAppenderNull}
+
+ The LoggerAppenderNull appender ignores all log events.
+
+ This appender does not use a layout and has no configurable parameters.
+
+ Configuration via XML file:
+
++--
+<appender name="default" class="LoggerAppenderNull" />
++--
+
+ Configuration via ini file:
+
++--
+log4php.appender.default = LoggerAppenderNull
++--
+
+** {LoggerAppenderPDO}
+
+ The LoggerAppenderPDO appender logs to a database using the PHP's {{{http://php.net/manual/en/book.pdo.php}PDO extension}}.
+
+*-------------------+--------------*--------------------+------------------------+
+|| Parameter || Required || Default value || Description
+*-------------------+--------------*--------------------+------------------------+
+| dsn | <<Yes>> | - | The Data Source Name (DSN) used to connect to the database.
+*-------------------+--------------*--------------------+------------------------+
+| user | <<Yes>> | - | Username used to connect to the database.
+*-------------------+--------------*--------------------+------------------------+
+| password | <<Yes>> | - | Password used to connect to the database.
+*-------------------+--------------*--------------------+------------------------+
+| createTable | No | true | Create the table if it does not exist? ("true" or "false")
+*-------------------+--------------*--------------------+------------------------+
+| table | No | log4php_log | Name of the table to which log entries should be inserted.
+*-------------------+--------------*--------------------+------------------------+
+| insertSql | No | <see below> | SQL query used to insert a log event.
+*-------------------+--------------*--------------------+------------------------+
+| insertPattern | No | <see below> | A comma separated list of <LoggerPatternLayout> format strings used in <insertSql> parameter.
+*-------------------+--------------*--------------------+------------------------+
+
+ Parameters <dsn>, <user> and <password> are used by PDO to connect to the
+ database which will be used for logging. For available database drivers
+ and corresponding DSN format, please see the {{{http://www.php.net/manual/en/pdo.drivers.php}PDO driver documentation}}.
+
+*** Advanced configuration
+
+ Parameters <insertSql> and <insertPattern> can be used to change how events
+ are inserted into the database. By manipulating them, it is possible to use
+ a custom table structure to suit your needs.
+
++--
+ WARNING: Change these settings only if you are sure what you are doing.
++--
+
+ By default their values are:
+
+*--------------+--------+
+| insertSql | INSERT INTO __TABLE__ (timestamp, logger, level, message, thread, file, line) VALUES (?, ?, ?, ?, ?, ?, ?)
+*--------------+--------+
+| insertPattern| %d,%c,%p,%m,%t,%F,%L
+*--------------+--------+
+
+ The string <__TABLE__> in <insertSql> will be replaced with the table name
+ defined in the <table> parameter. Question marks in the <insertSql>
+ will be replaced by evaluated <LoggerPatternLayout> format strings defined
+ in <insertPattern>. See LoggerPatternLayout documentation for format
+ string description.
+
+*** Example 1
+
+ The simplest example is connecting to an SQLite database which does not
+ require any authentication.
+
+ Configuration via XML file:
+
++--
+<appender name="default" class="LoggerAppenderPDO">
+ <param name="dsn" value="sqlite:target/appender_pdo.sqlite" />
+</appender>
++--
+
+ Configuration via ini file:
+
++--
+log4php.appender.default = LoggerAppenderPDO
+log4php.appender.default.dsn = "sqlite:target/appender_pdo.sqlite"
++--
+
+ In this example, a database table named log4php_log will automatically be
+ created the first time the appender is used.
+
+*** Example 2
+
+ A slightly more complex example is connecting to a MySQL database which
+ requires user credentials to be provided. Additionally, a user-specified
+ table name is used.
+
+ Configuration via xml file:
+
++--
+<appender name="default" class="LoggerAppenderPDO">
+ <param name="dsn" value="mysql:host=localhost;dbname=test" />
+ <param name="user" value="root" />
+ <param name="password" value="secret" />
+ <param name="table" value="my_log" />
+</appender>
++--
+
+ Configuration via ini file:
+
++--
+log4php.appender.default = LoggerAppenderPDO
+log4php.appender.default.dsn = "mysql:host=localhost;dbname=test"
+log4php.appender.default.user = root
+log4php.appender.default.password = secret
+log4php.appender.default.table = my_log
++--
+
+*** Sample output
+
+ This is some sample output retrieved from a MySQL database.
+
++--
+ mysql> desc log4php_log;
+ +-----------+-------------+------+-----+---------+-------+
+ | Field | Type | Null | Key | Default | Extra |
+ +-----------+-------------+------+-----+---------+-------+
+ | timestamp | varchar(32) | YES | | NULL | |
+ | logger | varchar(32) | YES | | NULL | |
+ | level | varchar(32) | YES | | NULL | |
+ | message | varchar(64) | YES | | NULL | |
+ | thread | varchar(32) | YES | | NULL | |
+ | file | varchar(64) | YES | | NULL | |
+ | line | varchar(4) | YES | | NULL | |
+ +-----------+-------------+------+-----+---------+-------+
+
+ mysql> SELECT * FROM log4php_log;
+ +-------------------------+--------+-------+--------------+--------+------------------------------------------------------------------+------+
+ | timestamp | logger | level | message | thread | file | line |
+ +-------------------------+--------+-------+--------------+--------+------------------------------------------------------------------+------+
+ | 2009-09-08 02:31:48,532 | root | FATAL | Hello World! | 21858 | /srv/home/james/workspace/log4php/src/examples/php/appender_pdo. | 24 |
+ +-------------------------+--------+-------+--------------+--------+------------------------------------------------------------------+------+
++--
+
+** {LoggerAppenderPhp}
+
+ The LoggerAppenderPhp appender logs events by creating a PHP user-level message using the php function {{{http://www.php.net/manual/en/function.trigger-error.php}trigger_error}}.
+
+ The message type depends on the event's severity level:
+
+ * <E_USER_NOTICE> is used when the event's level is equal to or less than INFO
+
+ * <E_USER_WARNING> is used when the event's level is equal to WARN
+
+ * <E_USER_ERROR> is used when the event's level is equal to or greater than ERROR
+
+ []
+
+ This appender has no configurable parameters.
+
+*** Example
+
+ Configuration via xml file:
+
++--
+<appender name="default" class="LoggerAppenderPhp">
+ <layout class="LoggerLayoutTTCC" />
+</appender>
++--
+
+ Configuration via ini file:
+
++--
+log4php.appender.default = LoggerAppenderPhp
+log4php.appender.default.layout = LoggerLayoutTTCC
++--
+
+
+** {LoggerAppenderSocket}
+
+ The LoggerAppenderSocket appender serializes log events and sends them to a network socket.
+
+*-------------------+--------------*--------------------+------------------------+
+|| Parameter || Required || Default value || Description
+*-------------------+--------------*--------------------+------------------------+
+| remoteHost | <<Yes>> | - | Target host. On how to define a remote hostname see {{{http://php.net/manual/en/function.fsockopen.php}fsockopen() documentation}}.
+*-------------------+--------------*--------------------+------------------------+
+| port | No | 4446 | Target port of the socket.
+*-------------------+--------------*--------------------+------------------------+
+| timeout | No | 30 | Timeout in ms
+*-------------------+--------------*--------------------+------------------------+
+| useXml | No | false | If set to "true" the appender will sent the event formatted in XML, if set to "false" the appender will send the event as a serialized PHP object.
+*-------------------+--------------*--------------------+------------------------+
+| locationInfo | No | false | Whether location info is included for the XML event format. Ignored if XML format is not used.
+*-------------------+--------------*--------------------+------------------------+
+| log4jNamespace | No | false | In XML format, <log4php> namespace is used by default. If this parameter is set to true, <log4j> namespace will be used instead.
+*-------------------+--------------*--------------------+------------------------+
+
+*** Example 1
+
+ In this example, log events are sent to localhost:4242, using serialized
+ objects format. The host will recieve a serialized LoggerLoggingEvent
+ object.
+
+ Configuration via xml file:
+
++--
+<appender name="default" class="LoggerAppenderSocket">
+ <layout class="LoggerLayoutSimple" />
+ <param name="remoteHost" value="localhost" />
+ <param name="port" value="4242" />
+ <param name="useXml" value="false" />
+</appender>
++--
+
+ Configuration via ini file:
+
++--
+log4php.appender.default = LoggerAppenderSocket
+log4php.appender.default.layout = LoggerLayoutSimple
+log4php.appender.default.remoteHost = localhost
+log4php.appender.default.port = 4242
+log4php.appender.default.useXml = false
++--
+
+*** Example 2
+
+ In this example, log events are sent to localhost:4242 in the XML format.
+
+ Configuration via xml file:
+
++--
+<appender name="default" class="LoggerAppenderSocket">
+ <layout class="LoggerLayoutSimple" />
+ <param name="remoteHost" value="localhost" />
+ <param name="port" value="4242" />
+ <param name="useXml" value="true" />
+ <param name="locationInfo" value="false" />
+</appender>
++--
+
+ Configuration via ini file:
+
++--
+log4php.appender.default = LoggerAppenderSocket
+log4php.appender.default.layout = LoggerLayoutSimple
+log4php.appender.default.remoteHost = localhost
+log4php.appender.default.port = 4242
+log4php.appender.default.useXml = true
+log4php.appender.default.locationInfo = true
++--
+
+ Sample data sent to the remote host:
+
++--
+<log4php:event logger="root" level="INFO" thread="5512" timestamp="1273066263159">
+ <log4php:message><![CDATA[Hello World!]]></log4php:message>
+ <log4php:locationInfo class="main" file="D:\Projects\php-devel\org.apache.log4php\src\examples\php\appender_socket.php" line="23" method="main" />
+</log4php:event>
++--
+
+ If <locationInfo> was set to false, the <log4php:locationInfo> would not be present.
+
+ If <log4jNamespace> was set to true, all elements would be prefixed by <log4j:> instead <log4php:>.
+
+
+** {LoggerAppenderSyslog}
+
+ The LoggerAppenderSyslog logs events to the syslog.
+
+*-------------------+--------------*----------------------+------------------------+
+|| Parameter || Required || Default value || Description
+*-------------------+--------------*----------------------+------------------------+
+| ident | No | Log4PHP Syslog-Event | A string which will identify your appender.
+*-------------------+--------------*----------------------+------------------------+
+| overridePriority | No | false | If set to true, all messages will be sent to the syslog using the priority specified in the <priority> parameter. Otherwise, the pririty will depend on the level of the event being logged. See below.
+*-------------------+--------------*----------------------+------------------------+
+| priority | No/Yes | - | The syslog priority to use when overriding priority. This setting is required if <overridePriority> is set to true.
+*-------------------+--------------*----------------------+------------------------+
+| facility | No | USER | The syslog facility. Identifies the part of the system from which the event originated. See below.
+*-------------------+--------------*----------------------+------------------------+
+| option | No | PID \| CONS | Syslog options. See below.
+*-------------------+--------------*----------------------+------------------------+
+
+*** Priorities
+
+ The <priority> is the syslog equivalent of the log4php level. Here's a list of priorities available in syslog and the equivalent log4php levels.
+
+*-------------+-----------------------------------+--------------------------+
+|| Priority || Description || Equivalent level
+*-------------+-----------------------------------+--------------------------+
+| EMERG | System is unusable | -
+*-------------+-----------------------------------+--------------------------+
+| ALERT | Action must be taken immediately | FATAL
+*-------------+-----------------------------------+--------------------------+
+| CRIT | Critical conditions | -
+*-------------+-----------------------------------+--------------------------+
+| ERR | Error conditions | ERROR
+*-------------+-----------------------------------+--------------------------+
+| WARNING | Warning conditions | WARN
+*-------------+-----------------------------------+--------------------------+
+| NOTICE | Normal, but significant, condition| -
+*-------------+-----------------------------------+--------------------------+
+| INFO | Informational message | INFO
+*-------------+-----------------------------------+--------------------------+
+| DEBUG | Debug-level message | DEBUG, TRACE
+*-------------+-----------------------------------+--------------------------+
+
+ This means that messages with level FATAL will be logged using the syslog's
+ ALERT priority; ERROR message will use ERR priority, etc.
+
+ Note that there is no priority below DEBUG, therefore both TRACE and DEBUG
+ level mesages will be logged using the DEBUG syslog priority.
+
+
+*** Facilities
+
+ The <facility> parameter is used to specify what type of program is logging
+ the message. This allows you to specify (in your machine's syslog
+ configuration) how messages coming from different facilities will be handled.
+
+ The following facilities are available:
+
+*---------+--------------------------------------------+
+|| Name || Description
+*---------+--------------------------------------------+
+| KERN | Kernel messages
+*---------+--------------------------------------------+
+| USER | Generic user-level messages
+*---------+--------------------------------------------+
+| MAIL | Mail system
+*---------+--------------------------------------------+
+| DAEMON | System daemons
+*---------+--------------------------------------------+
+| AUTH | Security/authorization messages
+*---------+--------------------------------------------+
+| SYSLOG | Messages generated internally by syslogd
+*---------+--------------------------------------------+
+| LPR | Line printer subsystem
+*---------+--------------------------------------------+
+| NEWS | Network news subsystem
+*---------+--------------------------------------------+
+| UUCP | UUCP subsystem
+*---------+--------------------------------------------+
+| CRON | Clock daemon
+*---------+--------------------------------------------+
+| AUTHPRIV| Security/authorization messages (private)
+*---------+--------------------------------------------+
+| LOCAL0 | Reserved for local use
+*---------+--------------------------------------------+
+| LOCAL1 | Reserved for local use
+*---------+--------------------------------------------+
+| LOCAL2 | Reserved for local use
+*---------+--------------------------------------------+
+| LOCAL3 | Reserved for local use
+*---------+--------------------------------------------+
+| LOCAL4 | Reserved for local use
+*---------+--------------------------------------------+
+| LOCAL5 | Reserved for local use
+*---------+--------------------------------------------+
+| LOCAL6 | Reserved for local use
+*---------+--------------------------------------------+
+| LOCAL7 | Reserved for local use
+*---------+--------------------------------------------+
+
++--
+ Note: USER is the only available facility under Windows operating systems.
++--
+
+*** Options
+
+ The following additional options may be defined via the <option> parameter:
+
+*---------+--------------------------------------------+
+|| Name || Description
+*---------+--------------------------------------------+
+| CONS | If there is an error while sending data to the system logger, write directly to the system console
+*---------+--------------------------------------------+
+| NDELAY | Open the connection to the logger immediately.
+*---------+--------------------------------------------+
+| ODELAY | Delay opening the connection until the first message is logged (default).
+*---------+--------------------------------------------+
+| PERROR | Print log messages also to standard error.
+*---------+--------------------------------------------+
+| PID | Include the PID with each message.
+*---------+--------------------------------------------+
+
+ Multiple options may be set by separating them with a "|". For exampe "CONS|PID|NODELAY".
+
+*** Examples
+
+ Configuration via XML file:
+
++--
+<appender name="default" class="LoggerAppenderSyslog">
+ <layout class="LoggerLayoutSimple" />
+ <param name="ident" value="log4php-test" />
+ <param name="facility" value="LOCAL0" />
+ <param name="options" value="NDELAY|PID" />
+</appender>
++--
+
+ Configuration via ini file:
+
++--
+log4php.appender.default = LoggerAppenderSyslog
+log4php.appender.default.layout = LoggerLayoutSimple
+log4php.appender.default.ident = log4php-test
+log4php.appender.default.facility = LOCAL0
+log4php.appender.default.options = NDELAY|PID
++--
Added: logging/log4php/trunk/src/site/apt/docs/appender/filter.apt
URL: http://svn.apache.org/viewvc/logging/log4php/trunk/src/site/apt/docs/appender/filter.apt?rev=1056712&view=auto
==============================================================================
--- logging/log4php/trunk/src/site/apt/docs/appender/filter.apt (added)
+++ logging/log4php/trunk/src/site/apt/docs/appender/filter.apt Sat Jan 8 14:28:56 2011
@@ -0,0 +1,170 @@
+~~ Licensed to the Apache Software Foundation (ASF) under one or more
+~~ contributor license agreements. See the NOTICE file distributed with
+~~ this work for additional information regarding copyright ownership.
+~~ The ASF licenses this file to You under the Apache License, Version 2.0
+~~ (the "License"); you may not use this file except in compliance with
+~~ the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing, software
+~~ distributed under the License is distributed on an "AS IS" BASIS,
+~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+~~ See the License for the specific language governing permissions and
+~~ limitations under the License.
+ ------
+Appender Filters
+ ------
+ ------
+ ------
+
+Appender Filters
+
+ Filtering is a mechanism which allows the user to configure more precisely which logging events will be logged by an appender, and which will be ignored. Logging events can be filtered based on the level of the logging request, or the message itself.
+
+ Multiple filters can be defined on any appender; they will form a filter chain. When a logging event is passed onto an appender, the event will first pass through the filter chain. Each filter in the chain will examine the logging event and make a decision to:
+
+ [[a]] <<ACCEPT>> the logging event - The event will be logged without consulting the remaining filters in the chain.
+
+ [[b]] <<DENY>> the logging event - The event will be not logged without consulting the remaining filters in the chain.
+
+ [[c]] Remain <<NEUTRAL>> - No decision is made, therefore the next filter in the chain is consulted. If there are no remaining filters in the chain, the event is logged.
+
+ []
+
+* Configuring
+
+ Currently filters are only configurable in the XML configuration.
+
+ Like appenders and layouts, depending on the class used, filters may have configurable parameters which determine their behaviour.
+
+ Here is a configuration example:
+
++--
+<?xml version="1.0" encoding="UTF-8"?>
+<log4php:configuration xmlns:log4php="http://logging.apache.org/log4php/">
+
+ <appender name="defualt" class="LoggerAppenderEcho">
+ <layout class="LoggerLayoutSimple"/>
+
+ <filter class="LoggerFilterStringMatch">
+ <param name="stringToMatch" value="interesting" />
+ <param name="acceptOnMatch" value="true" />
+ </filter>
+ <filter class="LoggerFilterLevelRange">
+ <param name="levelMin" value="debug" />
+ <param name="levelMax" value="error" />
+ </filter>
+</appender>
+
+ <root>
+ <level value="TRACE" />
+ <appender_ref ref="defualt" />
+ </root>
+</log4php:configuration>
++--
+
+ In this example, there are two filters defined for the <default> appender.
+
+ The first filter (LoggerFilterStringMatch) searches for the string "interesting" in the logging event's message. If the string is found, the filter will ACCEPT the logging event, and the event will be logged. If the string is not found, the filter will remain NEUTRAL, and the event will be passed on to the next filter.
+
+ The second filter (LoggerFilterLevelRange) ACCEPTS all events which have a level between DEBUG and ERROR (in other words, levels DEBUG, INFO, WARN and ERROR). It DENIES all other events.
+
+ Therefore, this filter configuration will log events which which have a level between DEBUG and ERROR, except of theose which have the string "interesting" in the message. Those will be logged regardless of their level.
+
+
+* Filter reference
+
+ The following filters are available in log4php:
+
+*-----------------------------+---------------------------------------+
+|| Name || Description
+*-----------------------------+---------------------------------------+
+| {{LoggerFilterDenyAll}} | Denies all logging events.
+*-----------------------------+---------------------------------------+
+| {{LoggerFilterLevelMatch}} | Filters based on logging event level.
+*-----------------------------+---------------------------------------+
+| {{LoggerFilterLevelRange}} | Filters based on logging event level range.
+*-----------------------------+---------------------------------------+
+| {{LoggerFilterStringMatch}} | Filters by searching for a string in the logging event message.
+*-----------------------------+---------------------------------------+
+
+** {LoggerFilterDenyAll}
+
+ This filters simply denies all logging events. It has no configurable parameters.
+
+** {LoggerFilterLevelMatch}
+
+ This filter accepts the specified logger level or denys it.
+
+*** Configurable parameters
+
+*---------------------+--------------*----------------+------------------------+
+|| Parameter || Required || Default value || Description
+*---------------------+--------------*----------------+------------------------+
+| levelToMatch | <<Yes>> | - | The level to match
+*---------------------+--------------*----------------+------------------------+
+| acceptOnMatch | No | true | If true, the matching log level is accepted, denied otherwise
+*---------------------+--------------*----------------+------------------------+
+
+*** Example
+
++--
+<filter class="LoggerFilterLevelMatch">
+ <param name="levelToMatch" value="debug" />
+ <param name="acceptOnMatch" value="false" />
+</filter>
++--
+
+** {LoggerFilterLevelRange}
+
+ This filter accepts or denies logging events if their log level is within the specified range.
+
+*** Configurable parameters
+
+*---------------------+--------------*----------------+------------------------+
+|| Parameter || Required || Default value || Description
+*---------------------+--------------*----------------+------------------------+
+| levelMin | No | - | The minimum level to log. If set, levels lower than this will be denied.
+*---------------------+--------------*----------------+------------------------+
+| levelMax | No | - | The maximum level to log. If set, levels higher than this will be denied.
+*---------------------+--------------*----------------+------------------------+
+| acceptOnMatch | No | true | If true, the matching log level is accepted, denied otherwise.
+*---------------------+--------------*----------------+------------------------+
+
+*** Example
+
++--
+<filter class="LoggerFilterLevelRange">
+ <param name="levelMax" value="warn" />
+ <param name="acceptOnMatch" value="false" />
+</filter>
++--
+
+ This configuration denies levels greater than WARN.
+
+
+** {LoggerFilterStringMatch}
+
+ This filter allows or denies logging events if their message contains a given string.
+
+*** Configurable parameters
+
+*---------------------+--------------*----------------+------------------------+
+|| Parameter || Required || Default value || Description
+*---------------------+--------------*----------------+------------------------+
+| stringToMatch | <<Yes>> | - | The string to match.
+*---------------------+--------------*----------------+------------------------+
+| acceptOnMatch | No | true | If set to true, the matching events are accepted, denied otherwise.
+*---------------------+--------------*----------------+------------------------+
+
+*** Example
+
++--
+<filter class="LoggerFilterStringMatch">
+ <param name="StringToMatch" value="not-interesting" />
+ <param name="AcceptOnMatch" value="false" />
+</filter>
++--
+
+ This configuration will deny all events which contain the string "not-interesing" in their message.
Added: logging/log4php/trunk/src/site/apt/docs/appender/layout.apt
URL: http://svn.apache.org/viewvc/logging/log4php/trunk/src/site/apt/docs/appender/layout.apt?rev=1056712&view=auto
==============================================================================
--- logging/log4php/trunk/src/site/apt/docs/appender/layout.apt (added)
+++ logging/log4php/trunk/src/site/apt/docs/appender/layout.apt Sat Jan 8 14:28:56 2011
@@ -0,0 +1,307 @@
+~~ Licensed to the Apache Software Foundation (ASF) under one or more
+~~ contributor license agreements. See the NOTICE file distributed with
+~~ this work for additional information regarding copyright ownership.
+~~ The ASF licenses this file to You under the Apache License, Version 2.0
+~~ (the "License"); you may not use this file except in compliance with
+~~ the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing, software
+~~ distributed under the License is distributed on an "AS IS" BASIS,
+~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+~~ See the License for the specific language governing permissions and
+~~ limitations under the License.
+ ------
+Appender Layout
+ ------
+ ------
+ ------
+
+Appender Layout
+
+ More often than not, users wish to customize not only the output destination but also the output format. This is accomplished by associating a layout with an appender. All messages logged by that appender will use the given layout.
+
+ Layouts are a property of appenders just like filters and threshholds are. Like appenders, layouts themselves can have parameters which determine their behaviour. An example has been provided for each available layout.
+
+* {Available Layouts}
+
+ The following layouts are included with log4php:
+
+*------------------------------+--------------+
+|| Name || Description
+*------------------------------+--------------+
+| {{LoggerLayoutHTML}} | Outputs events in a HTML table.
+*------------------------------+--------------+
+| {{LoggerLayoutPattern}} | A flexible layout configurable via a pattern string.
+*------------------------------+--------------+
+| {{LoggerLayoutSimple}} | A simple, non configurable layout.
+*------------------------------+--------------+
+| {{LoggerLayoutTTCC}} | Consists of <<T>>ime, <<T>>hread, <<C>>ategory and nested diagnostic <<C>>ontext information
+*------------------------------+--------------+
+| {{LoggerLayoutXml}} | Formats the message as XML fragment.
+*------------------------------+--------------+
+
+
+** {LoggerLayoutHTML}
+
+ The LoggerLayoutHTML formats the message as HTML table.
+
+*** Configurable parameters
+
+*-------------------+--------------*----------------------+------------------------+
+|| Parameter || Required || Default value || Description
+*-------------------+--------------*----------------------+------------------------+
+| locationInfo | No | false | If set to true, adds the file name and line number of the statement at the origin of the log statement to the output.
+*-------------------+--------------*----------------------+------------------------+
+| title | No | Log4php Log Messages | Sets the \<title\> of the generated HTML document.
+*-------------------+--------------*----------------------+------------------------+
+
+*** Examples
+
+ Configuration via XML file:
+
++--
+<appender name="default" class="LoggerAppenderEcho">
+ <layout class="LoggerLayoutHtml">
+ <param name="locationInfo" value="true" />
+ </layout>
+</appender>
++--
+
+ Configuration via ini file:
+
++--
+log4php.appender.default = LoggerAppenderEcho
+log4php.appender.default.layout = LoggerLayoutHtml
+log4php.appender.default.layout.locationInfo = "true"
++--
+
+ This configuration will render an HTML document similar to:
+
++--
+Log session start time Wed Sep 9 00:11:30 2009
+
+Time Thread Level Category File:Line Message
+0 8318 INFO myLogger /home/ihabunek/log4php/example.php:8 My fitst message.
+1 8318 DEBUG myLogger /home/ihabunek/log4php/example.php:9 My second message.
+2 8318 WARN myLogger /home/ihabunek/log4php/example.php:10 My third message.
++--
+
+** {LoggerLayoutPattern}
+
+ LoggerLayoutPattern is a flexible layout configurable via a conversion pattern.
+
+*** Configurable parameters
+
+*-------------------+--------------*----------------------+------------------------+
+|| Parameter || Required || Default value || Description
+*-------------------+--------------*----------------------+------------------------+
+| conversionPattern | No | %m%n | This is the string which controls formatting and consists of a mix of literal content and conversion specifiers. See full specification below.
+*-------------------+--------------*----------------------+------------------------+
+
+*** Conversion pattern
+
+ The conversion pattern is closely related to the conversion pattern of the {{{http://www.cplusplus.com/reference/clibrary/cstdio/printf/}printf}} function in C. It is composed of literal text and format control expressions called conversion specifiers. You are free to insert any literal text within the conversion pattern.
+
+ Each conversion specifier starts with a percent sign (%) and is followed by optional format modifiers and a conversion character. The recognized conversion specifiers are:
+
+*------------+------------------------------------+
+|| Character || Converts to
+*------------+------------------------------------+
+| %c | The category of the logging event.
+*------------+------------------------------------+
+| %C | The fully qualified class name of the caller issuing the logging request.
+*------------+------------------------------------+
+| %d | The date of the logging event.
+| |
+| | The date conversion specifier may be followed by a date format specifier enclosed between braces. The format specifier follows the PHP {{{http://php.net/manual/en/function.date.php}date}} function. For example: %d\{Y-m-d H:i:s\}
+*------------+------------------------------------+
+| %F | The file name where the logging request was issued.
+*------------+------------------------------------+
+| %l | Location information of the caller which generated the logging event.
+*------------+------------------------------------+
+| %L | The line number from where the logging request was issued.
+*------------+------------------------------------+
+| %m | The message associated with the logging event.
+*------------+------------------------------------+
+| %n | A line break. Note that
+*------------+------------------------------------+
+| %M | The method or function name where the logging request was issued.
+*------------+------------------------------------+
+| %p | The priority of the logging event.
+*------------+------------------------------------+
+| %r | The number of milliseconds elapsed since the start of the application until the creation of the logging event.
+*------------+------------------------------------+
+| %t | The name of the thread that generated the logging event.
+*------------+------------------------------------+
+| %x | The NDC (Nested Diagnostic Context) associated with the thread that generated the logging event.
+*------------+------------------------------------+
+| %X | The MDC (Mapped Diagnostic Context) associated with the thread that generated the logging event.
+*------------+------------------------------------+
+| %% | A single percent sign.
+*------------+------------------------------------+
+
+*** Examples
+
+ Configuration via XML file:
+
++--
+<appender name="default" class="LoggerAppenderEcho">
+ <layout class="LoggerLayoutPattern">
+ <param name="conversionPattern" value="%d{Y-m-d H:i:s.u} %c %-5p %m%n" />
+ </layout>
+</appender>
++--
+
+ Configuration via ini file:
+
++--
+log4php.appender.default = LoggerAppenderEcho
+log4php.appender.default.layout = LoggerLayoutPattern
+log4php.appender.default.layout.conversionPattern = "%d{Y-m-d H:i:s.u} %c %-5p %m%n"
++--
+
+ Example output:
+
++--
+2011-01-06 16:00:03.582 myLogger INFO My first message.
+2011-01-06 16:00:03.583 myLogger DEBUG My second message.
+2011-01-06 16:00:03.583 myLogger WARN My third message.
++--
+
+
+
+** {LoggerLayoutSimple}
+
+ LoggerLayoutSimple is a basic layout which outputs only the level followed by the message.
+
+ It is interesting to note that the output of LoggerLayoutSimple is identical to LoggerLayoutPattern with the conversionPattern set to "%p - %m%n".
+
+ This layout does not have any configurable parameters.
+
+*** Examples
+
+ Configuration via XML file:
+
++--
+<appender name="default" class="LoggerAppenderEcho">
+ <layout class="LoggerLayoutSimple" />
+</appender>
++--
+
+ Configuration via ini file:
+
++--
+log4php.appender.default = LoggerAppenderEcho
+log4php.appender.default.layout = LoggerLayoutSimple
++--
+
+ Sample output:
+
++--
+INFO - My first message.
+DEBUG - My second message.
+WARN - My third message.
++--
+
+** {LoggerLayoutTTCC}
+
+ The TTCC layout format consists of time, thread, category and nested diagnostic context information, hence the name.
+
+*** Configurable parameters
+
+*---------------------+--------------*-------------------+------------------------+
+|| Parameter || Required || Default value || Description
+*---------------------+--------------*-------------------+------------------------+
+| threadPrinting | No | true | If set to true, the thread ID will be included in output.
+*---------------------+--------------*-------------------+------------------------+
+| categoryPrefixing | No | true | If set to true, the category will be included in output.
+*---------------------+--------------*-------------------+------------------------+
+| contextPrinting | No | true | If set to true, the nested diagnostic will be included in output.
+*---------------------+--------------*-------------------+------------------------+
+| microSecondsPrinting| No | true | If set to true, the microseconds will be included in output.
+*---------------------+--------------*-------------------+------------------------+
+| dateFromat | No | %c | Overrides the date format, using the format used in PHP {{{http://php.net/manual/en/function.strftime.php}strftime}} function.
+*---------------------+--------------*-------------------+------------------------+
+
+*** Examples
+
+ Configuration via XML file:
+
++--
+<appender name="default" class="LoggerAppenderEcho">
+ <layout class="LoggerLayoutTTCC" />
+</appender>
++--
+
+ Configuration via ini file:
+
++--
+log4php.appender.default = LoggerAppenderEcho
+log4php.appender.default.layout = LoggerLayoutTTCC
++--
+
+ Sample output:
+
++--
+01/06/11 16:45:33,512 [4596] INFO myLogger - My first message.
+01/06/11 16:45:33,513 [4596] DEBUG myLogger - My second message.
+01/06/11 16:45:33,513 [4596] WARN myLogger - My third message.
++--
+
+
+** {LoggerLayoutXml}
+
+ The LoggerLayoutXml formats the message as a XML fragment.
+
+
+*** Configurable parameters
+
+*---------------------+--------------*-------------------+------------------------+
+|| Parameter || Required || Default value || Description
+*---------------------+--------------*-------------------+------------------------+
+| locationInfo | No | true | If set to true then the file name and line number of the origin of the log statement will be included in output.
+*---------------------+--------------*-------------------+------------------------+
+
+*** Examples
+
+ Configuration via XML file:
+
++--
+<appender name="default" class="LoggerAppenderEcho">
+ <layout class="LoggerLayoutXml" />
+</appender>
++--
+
+ Configuration via ini file:
+
++--
+log4php.appender.default = LoggerAppenderEcho
+log4php.appender.default.layout = LoggerLayoutXml
++--
+
+ Sample output:
+
++--
+<log4php:eventSet xmlns:log4php="http://logging.apache.org/log4php/" version="0.3" includesLocationInfo="true">
+ <log4php:event logger="myLogger" level="INFO" thread="5032" timestamp="1294329322043">
+ <log4php:message><![CDATA[My first message.]]></log4php:message>
+ <log4php:NDC><![CDATA[foo]]></log4php:NDC>
+ <log4php:locationInfo class="main" file="/home/ihabunek/log4php/example.php" line="12" method="main" />
+ </log4php:event>
+
+ <log4php:event logger="myLogger" level="DEBUG" thread="5032" timestamp="1294329322044">
+ <log4php:message><![CDATA[My second message.]]></log4php:message>
+ <log4php:NDC><![CDATA[foo bar]]></log4php:NDC>
+ <log4php:locationInfo class="main" file="/home/ihabunek/log4php/example.php" line="14" method="main" />
+ </log4php:event>
+
+ <log4php:event logger="myLogger" level="WARN" thread="5032" timestamp="1294329322044">
+ <log4php:message><![CDATA[My third message.]]></log4php:message>
+ <log4php:NDC><![CDATA[foo bar baz]]></log4php:NDC>
+ <log4php:locationInfo class="main" file="/home/ihabunek/log4php/example.php" line="16" method="main" />
+ </log4php:event>
+
+</log4php:eventSet>
++--
Added: logging/log4php/trunk/src/site/apt/docs/appender/threshold.apt
URL: http://svn.apache.org/viewvc/logging/log4php/trunk/src/site/apt/docs/appender/threshold.apt?rev=1056712&view=auto
==============================================================================
--- logging/log4php/trunk/src/site/apt/docs/appender/threshold.apt (added)
+++ logging/log4php/trunk/src/site/apt/docs/appender/threshold.apt Sat Jan 8 14:28:56 2011
@@ -0,0 +1,71 @@
+~~ Licensed to the Apache Software Foundation (ASF) under one or more
+~~ contributor license agreements. See the NOTICE file distributed with
+~~ this work for additional information regarding copyright ownership.
+~~ The ASF licenses this file to You under the Apache License, Version 2.0
+~~ (the "License"); you may not use this file except in compliance with
+~~ the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing, software
+~~ distributed under the License is distributed on an "AS IS" BASIS,
+~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+~~ See the License for the specific language governing permissions and
+~~ limitations under the License.
+ ------
+Appender Threshold
+ ------
+ ------
+ ------
+
+Appender Threshold
+
+ A threshold is lets you filter out log events of a specified LoggerLevel on an
+ Appender-Level and on Configuration-Level. This is sometimes an easier option
+ than changing the LoggerLevel of the several components.
+
+ If you set a threshold, then every LoggerLevel which is greater or equal than
+ the threshold will be logged. For example, if you set WARN as threshold, then INFO
+ and DEBUG will not be logged, but ERROR and FATAL will.
+
+* Adding a threshold to Appenders
+
+ A threshold can be added to an appender in the property file like this:
+
++--
+log4php.appender.default = LoggerAppenderEcho
+log4php.appender.default.layout = LoggerLayoutSimple
+log4php.appender.default.threshold = WARN
++--
+
+ In a XML file it looks like this:
+
++--
+<appender threshold="INFO" name="blub" class="LoggerAppenderEcho">
+ <layout class="LoggerLayoutSimple"/>
+</appender>
++--
+
+* Adding a threshold on Configuration basis
+
+ If you specify a threshold on configuration basis, it will work for all appenders.
+ A threshold can be added to an appender in the property file like this:
+
++--
+log4php.threshold = WARN
+log4php.rootLogger = WARN, default, blub
++--
+
+ In a XML file it looks like this:
+
++--
+<log4php:configuration xmlns:log4php="http://logging.apache.org/log4php/" threshold="WARN">
+ <appender threshold="WARN" name="default" class="LoggerAppenderEcho">
+ <layout class="LoggerLayoutSimple"/>
+ </appender>
+ <root>
+ <level value="WARN" />
+ <appender_ref ref="default" />
+ </root>
+</log4php:configuration>
++--
\ No newline at end of file
Modified: logging/log4php/trunk/src/site/apt/docs/configuration.apt
URL: http://svn.apache.org/viewvc/logging/log4php/trunk/src/site/apt/docs/configuration.apt?rev=1056712&r1=1056711&r2=1056712&view=diff
==============================================================================
--- logging/log4php/trunk/src/site/apt/docs/configuration.apt (original)
+++ logging/log4php/trunk/src/site/apt/docs/configuration.apt Sat Jan 8 14:28:56 2011
@@ -13,12 +13,12 @@
~~ See the License for the specific language governing permissions and
~~ limitations under the License.
------
- Apache log4php Configuration
+Configuration
------
------
------
-Apache log4php Configuration
+Configuration
This text is based upon the Log4J manual written by Ceki Gülcü in March 2002.
You can find the original here: http://logging.apache.org/log4j/1.2/manual.html
Modified: logging/log4php/trunk/src/site/apt/docs/introduction.apt
URL: http://svn.apache.org/viewvc/logging/log4php/trunk/src/site/apt/docs/introduction.apt?rev=1056712&r1=1056711&r2=1056712&view=diff
==============================================================================
--- logging/log4php/trunk/src/site/apt/docs/introduction.apt (original)
+++ logging/log4php/trunk/src/site/apt/docs/introduction.apt Sat Jan 8 14:28:56 2011
@@ -13,256 +13,48 @@
~~ See the License for the specific language governing permissions and
~~ limitations under the License.
------
- Apache log4php Introduction
+Introduction
------
------
------
-Apache log4php Introduction
+Introduction
- This text is based upon the Log4J manual written by Ceki Gülcü in March 2002.
- You can find the original here: http://logging.apache.org/log4j/1.2/manual.html
-
-* Loggers, Appenders and Layouts
+* {Basic concepts}
- log4php has three main components: loggers, appenders and layouts.
- These three types of components work together to enable developers to log
- messages according to message type and level, and to control at runtime
- how these messages are formatted and where they are reported.
+ There are three main concepts in log4php: loggers, appenders and layouts. These three types of components work together to enable developers to log messages according to message type and level, and to control at runtime how these messages are formatted and where they are reported.
+** {Loggers, appenders and layouts}
+
+*** {Loggers}
-* Logger hierarchy
+ A logger is a component which will take your logging request and log it. Each class in a project can have an individual logger, or they can all use a common logger. Loggers are named entities; it is common to name them after the class which will use it for logging.
- The first and foremost advantage of any logging API over plain
- echo resides in its ability to disable certain log statements while allowing
- others to print unhindered. This capability assumes that the logging space,
- that is, the space of all possible logging statements, is categorized according
- to some developer-chosen criteria.
-
- Loggers are named entities. Logger names are case-sensitive and they
- follow the hierarchical naming rule:
+*** {Appenders}
-+--
-Named Hierarchy
+ Logging requests can be sent to multiple destinations. Such destinations are called appenders. Appenders exist for console, files, syslog, database, sockets and other output destinations. One or more appenders can be attached to a logger. Each enabled logging request for a given logger will be forwarded to all the appenders in that logger.
-A logger is said to be an ancestor of another logger if its name followed by a dot
-is a prefix of the descendant logger name. A logger is said to be a parent of a
-child logger if there are no ancestors between itself and the descendant logger.
-+--
+*** {Layouts}
- For example, the logger named "com.foo" is a parent of the logger named "com.foo.Bar".
- Similarly, "php" is a parent of "php.util" and an ancestor of "php.util.Blub".
-
- The root logger resides at the top of the logger hierarchy. It is exceptional in two ways:
+ More often than not, users wish to customize not only the output destination but also the output format. This is accomplished by associating a layout with an appender. All messages logged by that appender will use the given layout. Some appenders, such as the database appender (LoggerAppenderPDO) do not require a layout, since their output is not in form of a string.
- 1. it always exists,
- 2. it cannot be retrieved by name.
+** {Levels}
- Invoking the class static Logger.getRootLogger method retrieves it. All other loggers
- are instantiated and retrieved with the class static Logger.getLogger method.
- This method takes the name of the desired logger as a parameter. Some of the
- basic methods in the Logger class are listed below.
-
-+--
-class Logger {
-
- // Creation & retrieval methods (returning a Logger object)
- public function static getRootLogger();
- public function static getLogger($name);
-
- // printing methods:
- public function debug($message);
- public function info($message);
- public function warn($message);
- public function error($message);
- public function fatal($message);
-}
-+--
-
- Loggers may be assigned levels. The set of possible levels, that is:
-
- * DEBUG,
- * INFO,
- * WARN,
- * ERROR and
- * FATAL
-
- are defined in the LoggerLevel class. Although we do not encourage you to do so,
- you may define your own levels by sub-classing the Level class.
- A perhaps better approach will be explained later on.
-
- If a given logger is not assigned a level, then it inherits one from its closest
- ancestor with an assigned level. More formally:
-
-+--
- Level Inheritance
-
- The inherited level for a given logger C, is equal to the first non-null level
- in the logger hierarchy, starting at C and proceeding upwards in the hierarchy
- towards the root logger.
-+--
-
- To ensure that all loggers can eventually inherit a level, the root logger
- always has an assigned level.
-
- Below are four tables with various assigned level values and the resulting
- inherited levels according to the above rule.
-
-
-*-------------------*-------------------*-------------------*
- Logger name | Assigned level | Inherited level
-*-------------------*-------------------*-------------------*
- root | Proot | Proot
-*-------------------*-------------------*-------------------*
- X | none | Proot
-*-------------------*-------------------*-------------------*
- X.Y | none | Proot
-*-------------------*-------------------*-------------------*
- X.Y.Z | none | Proot
-*-------------------*-------------------*-------------------*
-Example 1
-
- In example 1 above, only the root logger is assigned a level.
- This level value, Proot, is inherited by the other loggers
- X, X.Y and X.Y.Z.
-
-*-------------------*-------------------*-------------------*
- Logger name | Assigned level | Inherited level
-*-------------------*-------------------*-------------------*
- root | Proot | Proot
-*-------------------*-------------------*-------------------*
- X | Px | Px
-*-------------------*-------------------*-------------------*
- X.Y | Pxy | Pxy
-*-------------------*-------------------*-------------------*
- X.Y.Z | Pxyz | Pxyz
-*-------------------*-------------------*-------------------*
-Example 2
-
- In example 2, all loggers have an assigned level value. There is
- no need for level inheritence.
-
-*-------------------*-------------------*-------------------*
- Logger name | Assigned level | Inherited level
-*-------------------*-------------------*-------------------*
- root | Proot | Proot
-*-------------------*-------------------*-------------------*
- X | Px | Px
-*-------------------*-------------------*-------------------*
- X.Y | none | Px
-*-------------------*-------------------*-------------------*
- X.Y.Z | Pxyz | Pxyz
-*-------------------*-------------------*-------------------*
-Example 3
-
- In example 3, the loggers root, X and X.Y.Z are assigned the levels Proot,
- Px and Pxyz respectively. The logger X.Y inherits its level value from
- its parent X.
-
-*-------------------*-------------------*-------------------*
- Logger name | Assigned level | Inherited level
-*-------------------*-------------------*-------------------*
- root | Proot | Proot
-*-------------------*-------------------*-------------------*
- X | Px | Px
-*-------------------*-------------------*-------------------*
- X.Y | none | Px
-*-------------------*-------------------*-------------------*
- X.Y.Z | none | Px
-*-------------------*-------------------*-------------------*
-Example 4
-
- In example 4, the loggers root and X and are assigned the levels Proot
- and Px respectively. The loggers X.Y and X.Y.Z inherits their level value
- from their nearest parent X having an assigned level..
-
- Logging requests are made by invoking one of the printing methods of a logger instance.
- These printing methods are debug, info, warn, error, fatal and log.
-
- By definition, the printing method determines the level of a logging request.
- For example, if c is a logger instance, then the statement c.info("..")
- is a logging request of level INFO.
-
- A logging request is said to be enabled if its level is higher than or equal to
- the level of its logger. Otherwise, the request is said to be disabled. A logger
- without an assigned level will inherit one from the hierarchy.
- This rule is summarized below.
-
-+--
-Basic Selection Rule
-
-A log request of level p in a logger with (either assigned or inherited,
-whichever is appropriate) level q, is enabled if p >= q.
-+--
+ A level describes the severity of a logging message. Log4PHP provides six levels, show here in descending order of severity.
+
+*----------*---------------*-------------------+
+|| Level || Severity || Description
+*----------*---------------*-------------------+
+| FATAL | Highest | Very severe error events that will presumably lead the application to abort.
+*----------*---------------*-------------------+
+| ERROR | ... | Error events that might still allow the application to continue running.
+*----------*---------------*-------------------+
+| WARN | ... | Potentially harmful situations which still allow the application to continue running.
+*----------*---------------*-------------------+
+| INFO | ... | Informational messages that highlight the progress of the application at coarse-grained level.
+*----------*---------------*-------------------+
+| DEBUG | ... | Fine-grained informational events that are most useful to debug an application.
+*----------*---------------*-------------------+
+| TRACE | Lowest | Finest-grained informational events.
+*----------*---------------*-------------------+
- This rule is at the heart of log4pho. It assumes that levels are ordered.
- For the standard levels, we have:
-
-+--
- DEBUG < INFO < WARN < ERROR < FATAL.
-+--
- Here is an example of this rule.
-
-+--
- // get a logger instance named "com.foo"
- $logger = Logger::getLogger("com.foo");
-
- // Now set its level. Normally you do not need to set the
- // level of a logger programmatically. This is usually done
- // in configuration files.
- $logger->setLevel(LoggerLevel::INFO);
-
- $barlogger = Logger::getLogger("com.foo.Bar");
-
- // This request is enabled, because WARN >= INFO.
- $logger->warn("Low fuel level.");
-
- // This request is disabled, because DEBUG < INFO.
- $logger->debug("Starting search for nearest gas station.");
-
- // The logger instance barlogger, named "com.foo.Bar",
- // will inherit its level from the logger named
- // "com.foo" Thus, the following request is enabled
- // because INFO >= INFO.
- $barlogger->info("Located nearest gas station.");
-
- // This request is disabled, because DEBUG < INFO.
- $barlogger->debug("Exiting gas station search");
-+--
-
- Calling the getLogger method with the same name will always return a
- reference to the exact same logger object.
-
- For example, in
-
-+--
- $x = Logger::getLogger("wombat");
- $y = Logger::getLogger("wombat");
-+--
-
- x and y refer to exactly the same logger object.
-
- Thus, it is possible to configure a logger and then to retrieve the same
- instance somewhere else in the code without passing around references.
- In fundamental contradiction to biological parenthood, where parents
- always preceed their children, log4php loggers can be created and
- configured in any order. In particular, a "parent" logger will find and
- link to its descendants even if it is instantiated after them.
-
- Configuration of the log4php environment is typically done at application
- initialization. The preferred way is by reading a configuration file.
- This approach will be discussed shortly.
-
- Apache log4php makes it easy to name loggers by software component. This can be
- accomplished by statically instantiating a logger in each class, with the
- logger name equal to the fully qualified name of the class (class namespace with dots).
- This is a useful and straightforward method of defining loggers. As the
- log output bears the name of the generating logger, this naming strategy makes
- it easy to identify the origin of a log message. However, this is only one possible,
- albeit common, strategy for naming loggers.
- log4php does not restrict the possible set of loggers. The developer is free
- to name the loggers as desired.
-
- Nevertheless, naming loggers after the class where they are located seems
- to be the best strategy known so far.
-
Added: logging/log4php/trunk/src/site/apt/docs/loggers.apt
URL: http://svn.apache.org/viewvc/logging/log4php/trunk/src/site/apt/docs/loggers.apt?rev=1056712&view=auto
==============================================================================
--- logging/log4php/trunk/src/site/apt/docs/loggers.apt (added)
+++ logging/log4php/trunk/src/site/apt/docs/loggers.apt Sat Jan 8 14:28:56 2011
@@ -0,0 +1,219 @@
+~~ Licensed to the Apache Software Foundation (ASF) under one or more
+~~ contributor license agreements. See the NOTICE file distributed with
+~~ this work for additional information regarding copyright ownership.
+~~ The ASF licenses this file to You under the Apache License, Version 2.0
+~~ (the "License"); you may not use this file except in compliance with
+~~ the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing, software
+~~ distributed under the License is distributed on an "AS IS" BASIS,
+~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+~~ See the License for the specific language governing permissions and
+~~ limitations under the License.
+ ------
+Loggers
+ ------
+ ------
+ ------
+
+Loggers
+
+ A logger is a component which will take your logging request and log it. Each class in a project can have an individual logger, or they can all use a common logger. Loggers are named entities; it is common to name them after the class which will use it for logging.
+
+ Creating a logger is done by calling the static getLogger() method on the Logger object and providing the name of the logger. For example, to create a logger named <foo>:
+
++--
+$logger = Logger::getLogger('foo');
++--
+
+ Logging requests are made by invoking one of the printing methods of a logger instance. These logging methods are: trace, debug, info, warn, error and fatal. The printing method determines the level of a logging request. For example, calling the method info() creates a logging request of level INFO. For example:
+
++--
+$logger->info("This is the message to be logged.");
++--
+
+ Loggers by themselves do not define where these messages will be logged. For that you need to assign one or more {{{appender/appender.html}appenders}} to the logger.
+
+* {Logger threshold}
+
+ A logger can be assigned a threshold level. All logging requests with level lower than this threshold will be ignored.
+
+ For example, setting logger threshold to INFO means that logging requests with levels TRACE and DEBUG will not be logged by this logger.
+
+ By default loggers do not have a threshold set, which means they will log all events, regardless of the level.
+
+
+* Configuring loggers
+
+ Loggers can be individually configured in the configuration file.
+
+ The simplest example is to configure the root logger, since all other loggers will inherit its settings, as explained in the {{{loggers.html#Logger_hierarchy}next section}}.
+
++--
+<log4php:configuration xmlns:log4php="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderConsole" />
+ <root>
+ <level value="debug" />
+ <appender_ref ref="default" />
+ </root>
+</log4php:configuration>
++--
+
+ This configuration adds the <default> appender to the root logger, and sets it's {{{loggers.html#Logger_threshold}threshold level}} to DEBUG.
+
+ It is also possible to configure individual named loggers. For example, let's configure the <foo> logger, used in the example above, and set it's threshold to WARN:
+
++--
+<log4php:configuration xmlns:log4php="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderConsole" />
+ <logger name="foo">
+ <level value="warn" />
+ <appender_ref ref="default" />
+ </logger>
+</log4php:configuration>
++--
+
+* {Logger hierarchy}
+
+ Loggers follow a parent-child relationship pattern which is implemented by using a naming pattern. A logger is said to be an <ancestor> of another logger if its name followed by a dot is a prefix of the <descendant> logger name. A logger is said to be a <parent> of a <child> logger if there are no ancestors between itself and the descendant logger.
+
+ For example, the logger named "foo" is a parent of the logger named "foo.bar". Similarly, "org" is a parent of "org.apache" and an ancestor of "org.apache.logging". This naming scheme should be familiar to most developers.
+
+ The root logger resides at the top of the logger hierarchy. It is exceptional in two ways:
+
+ [[1]] it always exists,
+
+ [[2]] it cannot be retrieved by name.
+
+ []
+
+ Invoking the class static Logger::getRootLogger() method retrieves the root logger. All other loggers are instantiated and retrieved with the Logger::getLogger($name) method. This method takes the name of the desired logger as a parameter.
+
+* {Logger inheritance}
+
+ The threshold level and appenders are inherited from the parent to the child loggers.
+
+ For example examine the following configuration:
+
++--
+<log4php:configuration xmlns:log4php="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderConsole" />
+ <root>
+ <level value="debug" />
+ <appender_ref ref="default" />
+ </root>
+</log4php:configuration>
++--
+
+ The threshold level of the root logger is set to debug. Also, the root logger is linked to a console appender. Any named logger that is created will inherit these root settings.
+
++--
+$main = Logger::getLogger('main');
+$main->trace('This will not be logged.');
+$main->info('This will be logged.');
++--
+
+ A logger named <main> is created. Since there is no logger-specific configuration, it will inherit all of it's settings from the root logger: a console appender, and threshold set to DEBUG. Therefore, this code will produce the following output:
+
++--
+INFO - This will be logged.
++--
+
+** Appender additivity
+
+ Appender additivity is a property of loggers to inherit their parent's appenders. By default all loggers have appender additivity enabled.
+
+ Let's take the following example:
+
++--
+<log4php:configuration xmlns:log4php="http://logging.apache.org/log4php/">
+ <appender name="A1" class="LoggerAppenderConsole" />
+ <appender name="A2" class="LoggerAppenderConsole" />
+ <root>
+ <appender_ref ref="A1" />
+ </root>
+ <logger name="foo">
+ <appender_ref ref="A2" />
+ </logger>
+</log4php:configuration>
++--
+
+ Since additivity is enabled by default, the logger <foo> will have two linked appenders: A1 which it will inherit from the root logger, and A2 which is defined for it specifically.
+
+ Therefore, by executing the following code:
+
++--
+$main = Logger::getLogger('foo');
+$main->info('This will be logged twice.');
++--
+
+ The message will be logged twice - once by A1 and once by A2, producing:
+
++--
+INFO - This will be logged twice.
+INFO - This will be logged twice.
++--
+
+*** Disabling appender additivity
+
+ Logger's appender additivity can also be disabled if needed.
+
+ If we had configured the <foo> logger like this:
+
++--
+<logger name="foo" additivity="false">
+ <appender_ref ref="A2" />
+</logger>
++--
+
+ Then the logger would not have inherited the A1 appender from the root logger, and the message would have been logged only once.
+
+
+** {A more complex example}
+
+ In this example we will look at multiple loggers making a hierarchy.
+
+ Not to make the example too complex, all appenders will log to the console. Of course, this doesn't always have to be the case.
+
+ Let's take the following configuration file:
+
++--
+<?xml version="1.0" encoding="UTF-8"?>
+<log4php:configuration xmlns:log4php="http://logging.apache.org/log4php/">
+ <appender name="A1" class="LoggerAppenderConsole" />
+ <appender name="A2" class="LoggerAppenderConsole" />
+ <appender name="A3" class="LoggerAppenderConsole" />
+ <appender name="A4" class="LoggerAppenderConsole" />
+
+ <root>
+ <appender_ref ref="A1" />
+ </root>
+ <logger name="foo">
+ <appender_ref ref="A2" />
+ <appender_ref ref="A3" />
+ </logger>
+ <logger name="foo.bar" />
+ <logger name="foo.bar.baz" additivity="false">
+ <appender_ref ref="A4" />
+ </logger>
+</log4php:configuration>
++--
+
+ The table below shows how the configuration is interpreted, and which appenders are inherited:
+
+*----------------+------------+--------------*-----------------+------------+
+|| Logger Name || Added || Additivity || Output || Comment |
+|| || Appenders || Flag || Targets || |
+*----------------+------------+--------------*-----------------+------------+
+| root | A1 | N/A | A1 | One appender, named A1, is added to root logger. Any logging requests to root logger will be forwarded only to that one appender.
+*----------------+------------+--------------*-----------------+------------+
+| foo | A2, A3 | true | A1, A2, A3 | A logger named <foo> is created and two appenders, named A2 and A3, are added to it. Additionally, because of logger additivity, <foo> inherits the appender A1 from the root logger which is it's parent in the logger hierarchy. Therefore logging requests to this logger will be forwarded to appenders A1, A2 and A3.
+*----------------+------------+--------------*-----------------+------------+
+| foo.bar | none | true | A1, A2, A3 | A logger named <foo.bar> is created. Because it's name starts with <foo.>, it will be created as a child of the <foo> logger. No appenders are added to <foo.bar> but it will inherit it's ancestor's appenders: appenders A2 and A3 from <foo> and A1 from <root>. Logging requests to this logger will be forwarded to appenders A1, A2 and A3.
+*----------------+------------+--------------*-----------------+------------+
+| foo.bar.baz | A4 | false | A4 | Finally, logger <foo.bar.baz> is created, and because of it's name it is created as child to <foo.bar>. One appender, A4 is added to it. However, since it's additivity flag is set to false, it will not inherit any appenders from it's ancestors. Logging requests to this logger will be forwarded only to appender A4.
+*----------------+------------+--------------*-----------------+------------+
+
+
Modified: logging/log4php/trunk/src/site/apt/docs/performance.apt
URL: http://svn.apache.org/viewvc/logging/log4php/trunk/src/site/apt/docs/performance.apt?rev=1056712&r1=1056711&r2=1056712&view=diff
==============================================================================
--- logging/log4php/trunk/src/site/apt/docs/performance.apt (original)
+++ logging/log4php/trunk/src/site/apt/docs/performance.apt Sat Jan 8 14:28:56 2011
@@ -13,12 +13,12 @@
~~ See the License for the specific language governing permissions and
~~ limitations under the License.
------
- Apache log4php Performance
+Performance
------
------
------
-Apache log4php Performance
+Performance
This text is based upon the Log4J manual written by Ceki Gülcü in March 2002.
You can find the original here: http://logging.apache.org/log4j/1.2/manual.html