http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/layouts/html.rst ---------------------------------------------------------------------- diff --git a/docs/layouts/html.rst b/docs/layouts/html.rst new file mode 100644 index 0000000..7ef4e98 --- /dev/null +++ b/docs/layouts/html.rst @@ -0,0 +1,123 @@ +================ +LoggerLayoutHTML +================ + +LoggerLayoutHTML formats the log as an HTML document. + +Parameters +---------- + ++----------------+---------+----------+----------+-------------------------------------------------+ +| Parameter | Type | Required | Default | Description | ++================+=========+==========+==========+=================================================+ +| locationInfo | boolean | No | true | If set to true, adds the file name and line | +| | | | | number at which the log statement originated. | ++----------------+---------+----------+----------+-------------------------------------------------+ +| title | string | No | Log3php | Sets the title of the generated HTML document. | +| | | | Log | | +| | | | Messages | | ++----------------+---------+----------+----------+-------------------------------------------------+ + +Examples +-------- + +.. container:: tabs + + .. rubric:: XML format + .. code-block:: xml + + + + + + + + + + + + + .. rubric:: PHP format + .. code-block:: php + + array( + 'appenders' => array( + 'default' => array( + 'class' => 'LoggerAppenderEcho', + 'layout' => array( + 'class' => 'LoggerLayoutHtml', + ) + ) + ), + 'rootLogger' => array( + 'appenders' => array('default') + ), + ) + +Running the following code: + +.. code-block:: php + + Logger::configure("layout_xml.xml"); + $log = Logger::getRootLogger(); + $log->debug("Hello World!"); + $log->info("Hello World!"); + +Produces the output as a HTML table: + ++------+--------+-------+----------+--------------------------------+--------------+ +| Time | Thread | Level | Category | File\:Line | Message | ++======+========+=======+==========+================================+==============+ +| 0 | 5868 | DEBUG | root | /tmp/log4php/layout_html.php:3 | Hello world! | ++------+--------+-------+----------+--------------------------------+--------------+ +| 2 | 5868 | INFO | root | /tmp/log4php/layout_html.php:4 | Hello world! | ++------+--------+-------+----------+--------------------------------+--------------+ + +Source of the output: + +.. code-block:: html + + + + + Log4php Log Messages + + + +
+ Log session start time 09/22/11 13:19:23
+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
TimeThreadLevelCategoryFile:LineMessage
05868DEBUGrootD:\Projects\apache\log4php-config-adapters\src\examples\php\layout_html.php:23Hello World!
25868INFOrootD:\Projects\apache\log4php-config-adapters\src\examples\php\layout_html.php:24Hello World!
+
+ + http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/layouts/index.rst ---------------------------------------------------------------------- diff --git a/docs/layouts/index.rst b/docs/layouts/index.rst new file mode 100644 index 0000000..deaa978 --- /dev/null +++ b/docs/layouts/index.rst @@ -0,0 +1,24 @@ +======= +Layouts +======= + +Layouts are components responsible for transforming a logging event into a +string. + +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. + + +Layout reference +================ + +.. toctree:: + :maxdepth: 1 + + html + pattern + serialized + simple + ttcc + xml http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/layouts/pattern.rst ---------------------------------------------------------------------- diff --git a/docs/layouts/pattern.rst b/docs/layouts/pattern.rst new file mode 100644 index 0000000..3c10c9b --- /dev/null +++ b/docs/layouts/pattern.rst @@ -0,0 +1,498 @@ +=================== +LoggerLayoutPattern +=================== + +LoggerLayoutPattern is a flexible layout configurable via a conversion pattern. + +Parameters +========== + +The following parameters are available: + ++-------------------+---------+----------+------------------+------------------------------------+ +| Parameter | Type | Required | Default | Description | ++===================+=========+==========+==================+====================================+ +| conversionPattern | boolean | No | %message%newline | String which controls the output. | +| | | | | See full specification below. | ++-------------------+---------+----------+------------------+------------------------------------+ + +.. list-table:: + :widths: 20 10 10 20 40 + :header-rows: 1 + + * - Parameter + - Type + - Required + - Default + - Description + * - conversionPattern + - boolean + - No + - %message%newline + - String which controls the output. See full specification below. + +Conversion patterns +=================== + +**Conversion pattern** is a string which controls the formatting of logging +events. It controls how logging events will be transformed into strings by the +layout. + +The conversion pattern is closely related to the conversion pattern of the PHP +`sprintf `_ function. It is +composed of literal text and format control expressions called *conversion +specifiers*. + +A conversion specifier begins with a percent sign (%) and is followed by a +*conversion word*. Some conversion words require one or more *options* to be +given. These are specified in braces after the conversion word. An example of a +conversion specifier is ``%message`` which will be converted into the message +from the logging event which is being logged. + + + +Conversion specifiers +--------------------- + +.. function:: %c{length} +.. function:: %lo{length} +.. function:: %logger{length} + + Name of the Logger which generated the logging request. + + Optionally, a desired output length can be specified. If given, the + converter will attempt to abbreviate the logger name without losing too much + information in the process. If zero length is specified, only the rightmost + name fragment will be output. + + Specifying the desired length 0 means that only the class name will be + returned without the corresponding namespace. + + Several examples of the shortening algorithm in action: + + .. list-table:: + :header-rows: 1 + + * - Conversion specifier + - Logger name + - Result + * - ``%logger`` + - org\\apache\\logging\\log4php\\Foo + - org\\apache\\logging\\log4php\\Foo + * - ``%logger{0}`` + - org\\apache\\logging\\log4php\\Foo + - Foo + * - ``%logger{10}`` + - org\\apache\\logging\\log4php\\Foo + - o\\a\\l\\l\\Foo + * - ``%logger{20}`` + - org\\apache\\logging\\log4php\\Foo + - o\\a\\l\\log4php\\Foo + * - ``%logger{25}`` + - org\\apache\\logging\\log4php\\Foo + - o\\a\\logging\\log4php\\Foo + * - ``%logger{30}`` + - org\\apache\\logging\\log4php\\Foo + - org\\apache\\logging\\log4php\\Foo + + Note that rightmost segment will never be shortened. It is possible that the + resulting string will be longer than the specified desired length. + For backward compatibility, a dot can be used as a namespace separator, as + well as the backslash. + +.. function:: %C{length} +.. function:: %class{length} + + The fully qualified class name of the caller issuing the logging request. + Just like **%logger**, a desired length can be defined as an option. + +.. function:: %cookie{key} + + A value from the $_COOKIE superglobal array corresponding to the given key. + If no key is given, will return all values in key=value format. + +.. function:: %d{pattern} +.. function:: %date{pattern} + + The date/time of the logging event. Accepts a pattern string as an option. + The pattern syntax is the same as used by the + `PHP date `_ function. + + If no pattern is given, the date format will default to the ISO8601 datetime + format, which is the same as giving the pattern: ``c``. + + +-------------------------------+-------------------------------------------+ + | Conversion specifier | Result | + +===============================+===========================================+ + | %d | 2011-12-27T12:01:32+01:00 | + +-------------------------------+-------------------------------------------+ + | %date | 2011-12-27T12:01:32+01:00 | + +-------------------------------+-------------------------------------------+ + | %date{ISO8601} | 2011-12-27T12:01:32+01:00 | + +-------------------------------+-------------------------------------------+ + | %date{Y-m-d H:i:s,u} | 2011-12-27 12:01:32,610 | + +-------------------------------+-------------------------------------------+ + | %date{l jS \of F Y h:i:s A} | Tuesday 27th of December 2011 12:01:32 PM | + +-------------------------------+-------------------------------------------+ + +.. function:: %e{key} +.. function:: %env{key} + + A value from the $_ENV superglobal array corresponding to the given key. + + If no key is given, will return all values in key=value format. + +.. function:: %ex +.. function:: %exception +.. function:: %throwable + + The exception associated with the logging event, along with it's stack + trace. If there is no exception, evalutates to an empty string. + +.. function:: %F +.. function:: %file + + Name of the file from which the logging request was issued. + +.. function:: %l +.. function:: %location + + Location information of the caller which generated the logging event. + + Identical to ``%C.%M(%F:%L)`` + +.. function:: %L +.. function:: %line + + The line number at which the logging request was issued. + +.. function:: %m +.. function:: %msg +.. function:: %message + + The message associated with the logging event. + +.. function:: %M +.. function:: %method + + The method or function name from which the logging request was issued. + +.. function:: %n +.. function:: %newline + + A platform dependent line-break character(s). + + Note that a line break will not be printed unless explicitely specified. + +.. function:: %p +.. function:: %le +.. function:: %level + + The level of the logging event. + +.. function:: %r +.. function:: %relative + + The number of milliseconds elapsed since the start of the application until + the creation of the logging event. + +.. function:: %req{key} +.. function:: %request{key} + + A value from the $_REQUEST superglobal array corresponding to the given key. + + If no key is given, will return all values in key=value format. + +.. function:: %s{key} +.. function:: %server{key} + + A value from the $_SERVER superglobal array corresponding to the given key. + + If no key is given, will return all values in key=value format. + +.. function:: %ses{key} +.. function:: %session{key} + + A value from the $_SESSION superglobal array corresponding to the given key. + + If no key is given, will return all values in key=value format. + +.. function:: %sid +.. function:: %sessionid + + The active session ID, or an empty string if not in session. + + Equivalent to calling ``session_id()``. + +.. function:: %t +.. function:: %pid +.. function:: %process + + The ID of the process that generated the logging event. + +.. function:: %x +.. function:: %ndc + + The NDC (Nested Diagnostic Context) associated with the thread that + generated the logging event. + +.. function:: %X{key} +.. function:: %mdc{key} + + A value from the Mapped Diagnostic Context (MDC) corresponding to the given + key. + +Format modifiers +---------------- + +By default the relevant information is output as-is. However, with the aid of +format modifiers it is possible to change the minimum and maximum width and the +justifications of each data field. + +Both format modifiers are optional, and are placed between the percent sign (%) +and the conversion word. These are, in order: + +#. A **minimum width specifier**, a number which determines the minimum width of + the resulting string. If the resulting string is shorter that the given + number, it will be padded with spaces to the desired length. By default, the + string is right-justified (padded from left), but adding a "-" sign before + the specifier will make it left-justified. + +#. A **maximum widht specifier**, a dot (".") followed by a number which + determines the maximum allowed width of the resulting string. If the + resulting string is shorter than the given number, it will be truncated to + the maximum width. By default the string is truncated from the right, but + adding a "-" sign before the specifier will cause it to truncate from the + left. + +The following table demonstrates various uses of format modifiers: + +.. list-table:: + :header-rows: 1 + :widths: 10 10 10 10 10 50 + + * - Format modifier + - Padding + - Trimming + - Min. width + - Max. width + - Comment + * - ``%logger`` + - none + - none + - none + - none + - Output the logger name as-is. + * - ``%20logger`` + - right + - none + - 20 + - none + - Left pad with spaces if the logger name is less than 20 characters long. + * - ``%-20logger`` + - left + - none + - 20 + - none + - Right pad with spaces if the logger name is less than 20 characters + long. + * - ``%.30logger`` + - none + - right + - none + - 30 + - Trim from the end if the logger name is longer than 30 characters. + * - ``%.-30logger`` + - none + - left + - none + - 30 + - Trim from the beginning if the logger name is longer than 30 characters. + * - ``%20.30logger`` + - right + - right + - 20 + - 30 + - Left pad with spaces if the logger name is shorter than 20 characters. + However, if the logger name is longer than 30 characters, then trim from + the end. + * - ``%-20.30logger`` + - left + - right + - 20 + - 30 + - Right pad with spaces if the logger name is shorter than 20 characters. + However, if the logger name is longer than 30 characters, then trim from + the end. + +The following table lists a couple of examples for using format modifiers. + +Note that the square brackets are only added to the conversion pattern to +visually delimit the output. + ++--------------------+------------------------+------------------+-------------------------------+ +| Conversion pattern | Logger name | Result | Note | ++====================+========================+==================+===============================+ +| [%10logger] | Foo | ``[ Foo]`` | Added padding, right aligned. | ++--------------------+------------------------+------------------+-------------------------------+ +| [%-10logger] | Foo | ``[Foo ]`` | Added padding, left aligned. | ++--------------------+------------------------+------------------+-------------------------------+ +| [%.10logger] | org.apache.log4php.Foo | ``[org.apache]`` | Trimmed from right. | ++--------------------+------------------------+------------------+-------------------------------+ +| [%.-10logger] | org.apache.log4php.Foo | ``[og4php.Foo]`` | Trimmed from left. | ++--------------------+------------------------+------------------+-------------------------------+ + +Examples +-------- + +The following configuration configures a ``LoggerAppenderEcho`` which uses the +pattern layout. All examples will use the same code and configuration, only the +conversion pattern will change from example to example. + +.. container:: tabs + + .. rubric:: XML format + .. code-block:: xml + + + + + + + + + + + + + .. rubric:: PHP format + .. code-block:: php + + array( + 'appenders' => array( + 'default' => array( + 'class' => 'LoggerAppenderEcho', + 'layout' => array( + 'class' => 'LoggerLayoutPattern', + 'params' => array( + 'conversionPattern' => '%date %logger %-5level %msg%n' + ) + ) + ) + ), + 'rootLogger' => array( + 'appenders' => array('default') + ), + ) + +Example code: + +.. code-block:: php + + Logger::configure("config.xml"); + $logger = Logger::getLogger('myLogger'); + $logger->info("Lorem ipsum dolor sit amet, consectetur adipiscing elit."); + $logger->debug("Donec a diam lectus."); + $logger->warn("Sed sit amet ipsum mauris."); + +A simple example +~~~~~~~~~~~~~~~~ + +Conversion pattern: ``%date %logger %-5level %msg%n`` + +Running the example code produces the following output: + +.. code-block:: bash + + 2012-02-27T19:42:17+01:00 myLogger INFO Lorem ipsum dolor sit amet, consectetur adipiscing elit. + 2012-02-27T19:42:17+01:00 myLogger DEBUG Donec a diam lectus. + 2012-02-27T19:42:17+01:00 myLogger WARN Sed sit amet ipsum mauris. + +In this example, ``%date`` is converted to the event datetime in default format +(corresponding to the ISO-8601 specification), and ``%-5level`` produces the +event level right padded to 5 characters. Since longest level name is 5 +characters long, this ensures that the message always starts at the same +character position which improves log readability. + +Notice that the newline between logging events (%n) has to be explicitely +defined. Otherwise all logging events will be logged in the same line. + +Formatting the date +~~~~~~~~~~~~~~~~~~~ + +The ``%date`` conversion word can take the desired date format as an option. For +example, if you're European, the d.m.Y date format might be more familiar. Also, +adding milliseconds. + +Conversion pattern: ``%date{d.m.Y H:i:s,u} %logger %-5level %msg%n`` + +Running the example code produces the following output: + +.. code-block:: bash + + 27.02.2012 20:14:41,624 myLogger INFO Lorem ipsum dolor sit amet, consectetur adipiscing elit. + 27.02.2012 20:14:41,625 myLogger DEBUG Donec a diam lectus. + 27.02.2012 20:14:41,626 myLogger WARN Sed sit amet ipsum mauris. + +Logging HTTP requests +~~~~~~~~~~~~~~~~~~~~~ + +If log4php is used to log HTTP requests, a pattern like this might be useful: + +``%date [%pid] From:%server{REMOTE_ADDR}:%server{REMOTE_PORT} Request:[%request] Message: %msg%n`` + +Request ``/test.php?foo=bar`` it will produce the output similar to: + +.. code-block:: bash + + 2012-01-02T14:19:33+01:00 [22924] From:194.152.205.71:11257 Request:[foo=bar] Message: Lorem ipsum dolor sit amet, consectetur adipiscing elit. + 2012-01-02T14:19:33+01:00 [22924] From:194.152.205.71:11257 Request:[foo=bar] Message: Donec a diam lectus. + 2012-01-02T14:19:33+01:00 [22924] From:194.152.205.71:11257 Request:[foo=bar] Message: Sed sit amet ipsum mauris. + +``%server{REMOTE_ADDR}`` is equivalent to PHP code ``$_SERVER['REMOTE_ADDR']``. + +Logging exceptions +~~~~~~~~~~~~~~~~~~ + +If you wish to log any exception passed to the logging methods, you should add +the ``%ex`` specifier to the end of your conversion pattern, after ``%newline``. +This way, if an exception is loggerd it will be addded to your log below your +message. + +For example: ``%date %logger %message%newline%ex`` + +In the following code, suppose that the work() method can throw an exception. +This wolud be a good way to deal with it: + +.. code-block:: php + + $log = Logger::getLogger('foo'); + $log->info("Let's try this"); + + try + { + $foo = new Foo(); + $foo->work(123); + } + catch(Exception $ex) + { + // Exception is passed as the second parameter + $log->error("That didn't work", $ex); + } + $log->info("Done."); + +If work() throws an exception, your log might look something like this: + +.. code-block:: bash + + 2012-10-08T10:11:18+02:00 foo Let's try this + 2012-10-08T10:11:18+02:00 foo That didn't work + exception 'Exception' with message 'Doesn't work' in D:\work\exceptions.php:38 + Stack trace: + #0 D:\work\exceptions.php(29): Bar->work(123) + #1 D:\work\exceptions.php(48): Foo->work(123) + #2 {main} + 2012-10-08T10:11:18+02:00 foo Done. + +The exception, along with the full stack trace ends up in your log. This also +works with nested exceptions, the full stack trace is added. http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/layouts/serialized.rst ---------------------------------------------------------------------- diff --git a/docs/layouts/serialized.rst b/docs/layouts/serialized.rst new file mode 100644 index 0000000..88b15e7 --- /dev/null +++ b/docs/layouts/serialized.rst @@ -0,0 +1,72 @@ +====================== +LoggerLayoutSerialized +====================== + +``LoggerLayoutSerialized`` formats the logging event using the PHP's +`serialize() `_ function. + +Parameters +---------- + +The following parameters are available: + ++--------------+---------+----------+---------+-------------------------------------------------+ +| Parameter | Type | Required | Default | Description | ++==============+=========+==========+=========+=================================================+ +| locationInfo | boolean | No | true | If set to true, event's location information | +| | | | | will be initialized before serialization. | +| | | | | Enabling this parameter makes logging slower | +| | | | | and should be used only if required. | ++--------------+---------+----------+---------+-------------------------------------------------+ + +Examples +-------- + +.. container:: tabs + + .. rubric:: XML format + .. code-block:: xml + + + + + + + + + + + .. rubric:: PHP format + .. code-block:: php + + array( + 'appenders' => array( + 'default' => array( + 'class' => 'LoggerAppenderEcho', + 'layout' => array( + 'class' => 'LoggerLayoutSerialized', + ) + ) + ), + 'rootLogger' => array( + 'appenders' => array('default') + ), + ) + +Running the following code: + +.. code-block:: php + + Logger::configure("config.xml"); + $logger = Logger::getLogger('myLogger'); + $logger->info("Lorem ipsum dolor sit amet, consectetur adipiscing elit."); + $logger->debug("Donec a diam lectus."); + $logger->warn("Sed sit amet ipsum mauris."); + +Produces the following output: + +.. code-block:: bash + + O:18:"LoggerLoggingEvent":10:{s:24:" LoggerLoggingEvent fqcn";s:6:"Logger";s:32:" LoggerLoggingEvent categoryName";s:8:"myLogger";s:8:" * level";O:11:"LoggerLevel":3:{s:18:" LoggerLevel level";i:20000;s:21:" LoggerLevel levelStr";s:4:"INFO";s:29:" LoggerLevel syslogEquivalent";i:6;}s:23:" LoggerLoggingEvent ndc";N;s:37:" LoggerLoggingEvent ndcLookupRequired";b:1;s:27:" LoggerLoggingEvent message";s:56:"Lorem ipsum dolor sit amet, consectetur adipiscing elit.";s:35:" LoggerLoggingEvent renderedMessage";N;s:30:" LoggerLoggingEvent threadName";N;s:9:"timeStamp";d:1319380554.782227;s:32:" LoggerLoggingEvent locationInfo";N;} + O:18:"LoggerLoggingEvent":10:{s:24:" LoggerLoggingEvent fqcn";s:6:"Logger";s:32:" LoggerLoggingEvent categoryName";s:8:"myLogger";s:8:" * level";O:11:"LoggerLevel":3:{s:18:" LoggerLevel level";i:10000;s:21:" LoggerLevel levelStr";s:5:"DEBUG";s:29:" LoggerLevel syslogEquivalent";i:7;}s:23:" LoggerLoggingEvent ndc";N;s:37:" LoggerLoggingEvent ndcLookupRequired";b:1;s:27:" LoggerLoggingEvent message";s:20:"Donec a diam lectus.";s:35:" LoggerLoggingEvent renderedMessage";N;s:30:" LoggerLoggingEvent threadName";N;s:9:"timeStamp";d:1319380554.78247;s:32:" LoggerLoggingEvent locationInfo";N;} + O:18:"LoggerLoggingEvent":10:{s:24:" LoggerLoggingEvent fqcn";s:6:"Logger";s:32:" LoggerLoggingEvent categoryName";s:8:"myLogger";s:8:" * level";O:11:"LoggerLevel":3:{s:18:" LoggerLevel level";i:30000;s:21:" LoggerLevel levelStr";s:4:"WARN";s:29:" LoggerLevel syslogEquivalent";i:4;}s:23:" LoggerLoggingEvent ndc";N;s:37:" LoggerLoggingEvent ndcLookupRequired";b:1;s:27:" LoggerLoggingEvent message";s:26:"Sed sit amet ipsum mauris.";s:35:" LoggerLoggingEvent renderedMessage";N;s:30:" LoggerLoggingEvent threadName";N;s:9:"timeStamp";d:1319380554.78268;s:32:" LoggerLoggingEvent locationInfo";N;} http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/layouts/simple.rst ---------------------------------------------------------------------- diff --git a/docs/layouts/simple.rst b/docs/layouts/simple.rst new file mode 100644 index 0000000..4b63bd5 --- /dev/null +++ b/docs/layouts/simple.rst @@ -0,0 +1,71 @@ +================== +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 that of `LoggerLayoutPattern `_ with the `conversion pattern` +set to ``%p - %m%n``. + +Parameters +---------- + +This layout does not have any configurable parameters. + +Examples +-------- + +Sample configuration: + +.. container:: tabs + + .. rubric:: XML format + .. code-block:: xml + + + + + + + + + + + .. rubric:: PHP format + .. code-block:: php + + array( + 'appenders' => array( + 'default' => array( + 'class' => 'LoggerAppenderEcho', + 'layout' => array( + 'class' => 'LoggerLayoutSimple', + ) + ) + ), + 'rootLogger' => array( + 'appenders' => array('default') + ), + ) + + + +Running the following code: + +.. code-block:: php + + Logger::configure("layout_xml.xml"); + $log = Logger::getRootLogger(); + $log->info("My first message."); + $log->debug("My second message."); + $log->warn("My third message."); + +Produces the following output: + +.. code-block:: bash + + INFO - My first message. + DEBUG - My second message. + WARN - My third message. http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/layouts/ttcc.rst ---------------------------------------------------------------------- diff --git a/docs/layouts/ttcc.rst b/docs/layouts/ttcc.rst new file mode 100644 index 0000000..0fc2a22 --- /dev/null +++ b/docs/layouts/ttcc.rst @@ -0,0 +1,115 @@ +================ +LoggerLayoutTTCC +================ + +.. warning:: + + LoggerLayoutTTCC is deprecated and will be removed in a future release. Please + use `LoggerLayoutPattern `_ instead. + +The TTCC layout format was taken from Apache log4j, and originally consisted of +Time, Thread, Category and nested diagnostic Context information, hence the +name. + +``LoggerLayoutTTCC`` contains equivalent information: + +* Time +* Process ID +* Logger name +* Nested diagnostic context + +Output of ``LoggerLayoutTTCC`` is identical to that of LoggerLayoutPattern_ +with the *conversion pattern* set to ``%d{m/d/y H:i:s,u} [%t] %p %c %x - %m%n``. + +Parameters +---------- + +The following parameters are available: + + +.. list-table:: + :widths: 20 10 10 10 50 + :header-rows: 1 + + * - Parameter + - Type + - Required + - Default + - Description + * - threadPrinting + - boolean + - No + - true + - If set to true, the process ID will be included in output. + * - categoryPrefixing + - boolean + - No + - true + - If set to true, the logger name will be included in output. + * - contextPrinting + - boolean + - No + - true + - If set to true, the nested diagnostic context will be included in output. + * - microSecondsPrinting + - boolean + - No + - true + - If set to true, the microseconds will be included in output. + +Examples +-------- + +Configuration: + +.. container:: tabs + + .. rubric:: XML format + .. code-block:: xml + + + + + + + + + + + .. rubric:: PHP format + .. code-block:: php + + array( + 'appenders' => array( + 'default' => array( + 'class' => 'LoggerAppenderEcho', + 'layout' => array( + 'class' => 'LoggerLayoutTTCC', + ) + ) + ), + 'rootLogger' => array( + 'appenders' => array('default') + ), + ) + +For this example, some Nested Diagnostic Context is added also. Running the +following code: + +.. code-block:: php + + Logger::configure("config.xml"); + LoggerNDC::push("Some Context"); + + $logger = Logger::getLogger('myLogger'); + $logger->info("Lorem ipsum dolor sit amet, consectetur adipiscing elit."); + $logger->debug("Donec a diam lectus."); + $logger->warn("Sed sit amet ipsum mauris."); + +Produces the following output: + +.. code-block:: bash + + 02/20/12 23:36:39,772 [9820] INFO myLogger Some Context - Lorem ipsum dolor sit amet, consectetur adipiscing elit. + 02/20/12 23:36:39,773 [9820] DEBUG myLogger Some Context - Donec a diam lectus. + 02/20/12 23:36:39,773 [9820] WARN myLogger Some Context - Sed sit amet ipsum mauris. http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/layouts/xml.rst ---------------------------------------------------------------------- diff --git a/docs/layouts/xml.rst b/docs/layouts/xml.rst new file mode 100644 index 0000000..d1385f2 --- /dev/null +++ b/docs/layouts/xml.rst @@ -0,0 +1,137 @@ +=============== +LoggerLayoutXml +=============== + +``LoggerLayoutXml`` formats the messages as an XML document. + +Parameters +========== + ++-----------------+---------+----------+---------+-------------------------------------------------+ +| Parameter | Type | Required | Default | Description | ++=================+=========+==========+=========+=================================================+ +| locationInfo | boolean | No | true | If set to true, adds the file name and line | +| | | | | number at which the log statement originated. | ++-----------------+---------+----------+---------+-------------------------------------------------+ +| log4jNamespace | boolean | No | false | If set to true then log4j XML namespace will be | +| | | | | used instead of the log4php namespace. This can | +| | | | | be useful when using log viewers which can only | +| | | | | parse the log4j namespace such as Apache | +| | | | | Chainsaw. | ++-----------------+---------+----------+---------+-------------------------------------------------+ + +Examples +======== + +Default configuration example +----------------------------- + +The default configuration of ``LoggerLayoutXml`` will use the log4php XML +namespace and include the location information. + +Configuration file: + +.. container:: tabs + + .. rubric:: XML format + .. code-block:: xml + + + + + + + + + + + .. rubric:: PHP format + .. code-block:: php + + array( + 'appenders' => array( + 'default' => array( + 'class' => 'LoggerAppenderEcho', + 'layout' => array( + 'class' => 'LoggerLayoutXml', + ) + ) + ), + 'rootLogger' => array( + 'appenders' => array('default') + ), + ) + +Running the following code: + +.. code-block:: php + + Logger::configure("config.xml"); + $logger = Logger::getLogger('myLogger'); + $logger->info("Lorem ipsum dolor sit amet, consectetur adipiscing elit."); + $logger->debug("Donec a diam lectus."); + $logger->warn("Sed sit amet ipsum mauris."); + +Produces the following output: + +.. code-block:: xml + + + + + ]]> + + + + + ]]> + + + + + ]]> + + + + + +Overriding default options +-------------------------- + +This example show how to configure ``LoggerLayoutXml`` to exclude the location +information and use the log4j XML namespace. + +Configuration file: + +.. code-block:: xml + + + + + + + + + + + + + +Using this configuration will produce the following output: + +.. code-block:: xml + + + + ]]> + + + + ]]> + + + + ]]> + + + http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/make.bat ---------------------------------------------------------------------- diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..78149c8 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,190 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=_build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +set I18NSPHINXOPTS=%SPHINXOPTS% . +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^` where ^ is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. singlehtml to make a single large HTML file + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. texinfo to make Texinfo files + echo. gettext to make PO message catalogs + echo. changes to make an overview over all changed/added/deprecated items + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Apachelog4php.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Apachelog4php.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +:end http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/quickstart.rst ---------------------------------------------------------------------- diff --git a/docs/quickstart.rst b/docs/quickstart.rst new file mode 100644 index 0000000..c864f5b --- /dev/null +++ b/docs/quickstart.rst @@ -0,0 +1,180 @@ +=========== +Quick start +=========== + +First, install Apache log4php. + +You may also like to read the `introduction `_ chapter to +familiarise yoursef with the basic concepts used throughout the documentation +and examples. + +A trivial example +----------------- + +Just want logging to stdout? + +.. code-block:: php + + include('Logger.php'); + $logger = Logger::getLogger("main"); + $logger->info("This is an informational message."); + $logger->warn("I'm not feeling so good..."); + +This produces the following output: + +.. code-block:: bash + + INFO - This is an informational message. + WARN - I'm not feeling so good... + +A simple example +----------------- + +This example shows how to configure log4php using an XML configuration file. The framework will be +configured to log messages to a file, but only those with level greater or equal to ``WARN``. + +First, create a configuration file named ``config.xml`` containing: + +.. code-block:: xml + :linenos: + + + + + + + + + + + +This configuration file does the following: + +- *line 2*: Creates an appender named ``myAppender`` using appender class ``LoggerAppenderFile`` + which is used for logging to a file. +- *line 3*: Sets the ``file`` parameter, which tells the appender to which file to write. +- *line 6*: Sets the root logger level to ``WARN``. This means that logging requests with the level + lower than ``WARN`` will not be logged by the root logger. +- *line 7*: Links ``myAppender`` to the root logger so that all events recieved by the root + logger will be forwarded to ``myAppender`` and written into the log file. + +To try it out, run the following code: + +.. code-block:: php + + // Insert the path where you unpacked log4php + include('log4php/Logger.php'); + + // Tell log4php to use our configuration file. + Logger::configure('config.xml'); + + // Fetch a logger, it will inherit settings from the root logger + $log = Logger::getLogger('myLogger'); + + // Start logging + $log->trace("My first message."); // Not logged because TRACE < WARN + $log->debug("My second message."); // Not logged because DEBUG < WARN + $log->info("My third message."); // Not logged because INFO < WARN + $log->warn("My fourth message."); // Logged because WARN >= WARN + $log->error("My fifth message."); // Logged because ERROR >= WARN + $log->fatal("My sixth message."); // Logged because FATAL >= WARN + +This will create a file named ``myLog.log`` containing the following output: + +.. code-block:: bash + + WARN - My fourth message. + ERROR - My fifth message. + FATAL - My sixth message. + +An advanced example +------------------- + +This example covers named loggers, layouts and best practices in object-oriented programming. + +Create a configuration file named ``config.xml`` with the following content: + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + +The configuration defines two appenders: one writes to the console, and the other to a file. + +The +console appender doesn't have a layout defined, so it will revert to default layout +(``LoggerLayoutSimple``). The file appender uses a different layout +(``LoggerLayoutPattern``) which will result in different formatting of the logging +events. + +The console appender is linked to the root logger. The file appender is linked to the logger named +``Foo``, however ``Foo`` also inherits appenders from the root logger (in this case the console +appender). This means that logging events sent to the ``Foo`` logger will be logged both to the +console and the file. + +Consider the following code snippet: + +.. code-block:: php + + // Include and configure log4php + include('log4php/Logger.php'); + Logger::configure('config.xml'); + + /** + * This is a classic usage pattern: one logger object per class. + */ + class Foo + { + /** Holds the Logger. */ + private $log; + + /** Logger is instantiated in the constructor. */ + public function __construct() + { + // The __CLASS__ constant holds the class name, in our case "Foo". + // Therefore this creates a logger named "Foo" (which we configured in the config file) + $this->log = Logger::getLogger(__CLASS__); + } + + /** Logger can be used from any member method. */ + public function go() + { + $this->log->info("We have liftoff."); + } + } + + $foo = new Foo(); + $foo->go(); + +This produces the following output in the console: + +.. code-block:: bash + + INFO - We have liftoff. + +And the following in the log file: + +.. code-block:: bash + + 01/06/11 18:43:39,545 [5428] INFO Foo - We have liftoff. + +Note the different layout, this is because ``LoggerLayoutTTCC`` was used as layout for the file +appender. http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/requirements.txt ---------------------------------------------------------------------- diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..3ef90b4 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +Sphinx==1.1.3