You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by ih...@apache.org on 2013/12/14 18:24:02 UTC
[2/2] git commit: Added docs for several appenders
Added docs for several appenders
Signed-off-by: Ivan Habunek <ih...@apache.org>
Project: http://git-wip-us.apache.org/repos/asf/logging-log4php/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4php/commit/57c1ce09
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4php/tree/57c1ce09
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4php/diff/57c1ce09
Branch: refs/heads/develop
Commit: 57c1ce09a70656829851f1f52634846e76304d12
Parents: 5be1052
Author: Ivan Habunek <ih...@apache.org>
Authored: Sat Dec 14 18:23:44 2013 +0100
Committer: Ivan Habunek <ih...@apache.org>
Committed: Sat Dec 14 18:23:44 2013 +0100
----------------------------------------------------------------------
docs/appenders/daily-file.rst | 2 +-
docs/appenders/index.rst | 3 +
docs/appenders/mongodb.rst | 3 +-
docs/appenders/null.rst | 60 ++++++
docs/appenders/pdo.rst | 370 +++++++++++++++++++++++++++++++++++++
docs/appenders/php.rst | 74 ++++++++
6 files changed, 510 insertions(+), 2 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/57c1ce09/docs/appenders/daily-file.rst
----------------------------------------------------------------------
diff --git a/docs/appenders/daily-file.rst b/docs/appenders/daily-file.rst
index 0e5ec57..54ad173 100644
--- a/docs/appenders/daily-file.rst
+++ b/docs/appenders/daily-file.rst
@@ -35,7 +35,7 @@ The following parameters are available:
+-------------+---------+----------+---------+-------------------------------------------------------+
| Parameter | Type | Required | Default | Description |
+=============+=========+==========+=========+=======================================================+
-| file | string | **Yes** | - | Path to the target file. Should contain a ``%s`` |
+| file | string | **Yes** | \- | Path to the target file. Should contain a ``%s`` |
| | | | | which gets substituted by the date. |
+-------------+---------+----------+---------+-------------------------------------------------------+
| append | boolean | No | true | If set to true, the appender will append to the file, |
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/57c1ce09/docs/appenders/index.rst
----------------------------------------------------------------------
diff --git a/docs/appenders/index.rst b/docs/appenders/index.rst
index dbb6d1e..66f74a2 100644
--- a/docs/appenders/index.rst
+++ b/docs/appenders/index.rst
@@ -23,6 +23,9 @@ The following appender classes are available:
mail
mail-event
mongodb
+ null
+ pdo
+ php
Configuring appenders
---------------------
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/57c1ce09/docs/appenders/mongodb.rst
----------------------------------------------------------------------
diff --git a/docs/appenders/mongodb.rst b/docs/appenders/mongodb.rst
index 941fe83..2ba91ab 100644
--- a/docs/appenders/mongodb.rst
+++ b/docs/appenders/mongodb.rst
@@ -30,7 +30,8 @@ Note: additional parameters supported by the driver can be supplied by **connect
+------------------------+---------+----------+---------------------+-----------------------------------------------+
| databaseName | string | No | log4php_mongodb | Name of the database to which to log. |
+------------------------+---------+----------+---------------------+-----------------------------------------------+
-| collectionName | string | No | logs | Name of the collection to which to log. |
+| collectionName | string | No | logs | Name of the target collection within the |
+| | | | | given database. |
+------------------------+---------+----------+---------------------+-----------------------------------------------+
| username | string | No | | Username used to connect to the database. |
+------------------------+---------+----------+---------------------+-----------------------------------------------+
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/57c1ce09/docs/appenders/null.rst
----------------------------------------------------------------------
diff --git a/docs/appenders/null.rst b/docs/appenders/null.rst
new file mode 100644
index 0000000..1d32f6e
--- /dev/null
+++ b/docs/appenders/null.rst
@@ -0,0 +1,60 @@
+==================
+LoggerAppenderNull
+==================
+
+``LoggerAppenderNull`` ignores all logging requests; it never outputs a message
+to any device.
+
+Layout
+------
+
+This appender does not require a layout.
+
+Parameters
+----------
+
+This appender does not have any configurable parameters.
+
+Examples
+--------
+
+.. container:: tabs
+
+ .. rubric:: XML format
+ .. code-block:: xml
+
+ <configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderNull" />
+ <root>
+ <appender_ref ref="default" />
+ </root>
+ </configuration>
+
+ .. rubric:: PHP format
+ .. code-block:: php
+
+ array(
+ 'appenders' => array(
+ 'default' => array(
+ 'class' => 'LoggerAppenderNull',
+ ),
+ ),
+ 'rootLogger' => array(
+ 'appenders' => array('default'),
+ ),
+ );
+
+.. 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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/57c1ce09/docs/appenders/pdo.rst
----------------------------------------------------------------------
diff --git a/docs/appenders/pdo.rst b/docs/appenders/pdo.rst
new file mode 100644
index 0000000..65f0a37
--- /dev/null
+++ b/docs/appenders/pdo.rst
@@ -0,0 +1,370 @@
+=====================
+LoggerAppenderPDO
+=====================
+
+``LoggerAppenderPDO`` appender logs to a database using the PHP's PDO_
+extension.
+
+.. _PDO: http://php.net/manual/en/book.pdo.php
+
+Layout
+------
+
+This appender does not require a layout.
+
+Parameters
+----------
+
+The following parameters are available:
+
++---------------+--------+----------+---------+-------------------------------------------------------------+
+| Parameter | Type | Required | Default | Description |
++===============+========+==========+=========+=============================================================+
+| dsn | string | **Yes** | \- | The Data Source Name (DSN) used to connect to the database. |
++---------------+--------+----------+---------+-------------------------------------------------------------+
+| user | string | No | stdout | The stream to write to; either "stdout" or "stderr". |
++---------------+--------+----------+---------+-------------------------------------------------------------+
+| password | string | No | stdout | The stream to write to; either "stdout" or "stderr". |
++---------------+--------+----------+---------+-------------------------------------------------------------+
+| table | string | No | stdout | The stream to write to; either "stdout" or "stderr". |
++---------------+--------+----------+---------+-------------------------------------------------------------+
+| insertSql | string | No | stdout | The stream to write to; either "stdout" or "stderr". |
++---------------+--------+----------+---------+-------------------------------------------------------------+
+| insertPattern | string | No | stdout | The stream to write to; either "stdout" or "stderr". |
++---------------+--------+----------+---------+-------------------------------------------------------------+
+
+Parameters ``dsn``, ``user`` and ``password`` are used by PDO to connect to the
+database which will be used for logging.
+
+Data Source Name
+----------------
+
+The Data Source Name or DSN is a database-specific string which contains the
+information required to connect to the database.
+
+Some common examples of DSNs:
+
++------------+---------------------------------------+---------------------+
+| MySQL | ``mysql:host=localhost;dbname=logdb`` | `full reference`__ |
++------------+---------------------------------------+---------------------+
+| SQLite | ``sqlite:/path/to/log.db`` | `full reference`__ |
++------------+---------------------------------------+---------------------+
+| PostgreSQL | ``pgsql:host=localhost;port=5432`` | `full reference`__ |
++------------+---------------------------------------+---------------------+
+
+__ http://php.net/manual/en/ref.pdo-mysql.connection.php
+__ http://php.net/manual/en/ref.pdo-sqlite.connection.php
+__ http://php.net/manual/en/ref.pdo-pgsql.connection.php
+
+For other available database drivers and corresponding DSN format, please see
+the `PDO driver documentation <http://www.php.net/manual/en/pdo.drivers.php>`_.
+
+Database table
+--------------
+
+.. versionadded:: 2.3.0
+
+ The appender will no longer create a database table by itself. You have to
+ create a database table yourself. The reason for this is that various
+ databases use various create statements and column types. Some common
+ databases are covered in this chapter.
+
+By default the table should contain the following columns:
+
+- timestamp DATETIME
+- logger VARCHAR
+- level VARCHAR
+- message VARCHAR
+- thread VARCHAR
+- file VARCHAR
+- line VARCHAR
+
+If you wish to use an alternative table structure, see the next chapter.
+
+Here are CREATE TABLE statements for some popular databases:
+
+MySQL
+~~~~~
+
+.. code-block:: sql
+
+ CREATE TABLE log4php_log (
+ timestamp DATETIME,
+ logger VARCHAR(256),
+ level VARCHAR(32),
+ message VARCHAR(4000),
+ thread INTEGER,
+ file VARCHAR(255),
+ line VARCHAR(10)
+ );
+
+SQLite
+~~~~~~
+
+SQLite does not have a datetime type, so varchar is used instead.
+
+.. code-block:: sql
+
+ CREATE TABLE log4php_log (
+ timestamp VARCHAR(50),
+ logger VARCHAR(256),
+ level VARCHAR(32),
+ message VARCHAR(4000),
+ thread INTEGER,
+ file VARCHAR(255),
+ line VARCHAR(10)
+ );
+
+PostgreSQL
+~~~~~~~~~~
+
+.. code-block:: sql
+
+ CREATE TABLE log4php_log (
+ timestamp TIMESTAMP,
+ logger VARCHAR(256),
+ level VARCHAR(32),
+ message VARCHAR(4000),
+ thread INTEGER,
+ file VARCHAR(255),
+ line VARCHAR(10)
+ );
+
+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 you know what you are doing.
+
+The default values of these parameters are:
+
++---------------+-----------------------------------------------------------------+
+| Parameter | Default value |
++===============+=================================================================+
+| insertSql | INSERT INTO __TABLE__ (timestamp, logger, level, message, |
+| | thread, file, line) VALUES (?, ?, ?, ?, ?, ?, ?) |
++---------------+-----------------------------------------------------------------+
+| insertPattern | ``%date{Y-m-d H:i:s},%logger,%level,%message,%pid,%file,%line`` |
++---------------+-----------------------------------------------------------------+
+
+The string ``__TABLE__`` in insertSql will be replaced with the table name
+defined in table. Question marks in insertSql will be replaced by evaluated
+``LoggerLayoutPattern`` format strings defined in insertPattern. See
+``LoggerLayoutPattern`` documentation for format string description.
+
+Examples
+--------
+
+Example 1
+~~~~~~~~~
+
+The simplest example is connecting to an SQLite database which does not require
+any authentication.
+
+SQLite databases are contained in simple files and don't reuquire a server to
+run. This example will log to the database contained in ``/var/log/log.sqlite``.
+
+First, create a database and a table for logging. In this example, let's create
+the database at ``/tmp/log.db``.
+
+.. code-block:: bash
+
+ $ sqlite3 /tmp/log.db
+ SQLite version 3.7.9 2011-11-01 00:52:41
+ Enter ".help" for instructions
+ Enter SQL statements terminated with a ";"
+ sqlite> CREATE TABLE log4php_log (
+ ...> timestamp VARCHAR(256),
+ ...> logger VARCHAR(256),
+ ...> level VARCHAR(32),
+ ...> message VARCHAR(4000),
+ ...> thread INTEGER,
+ ...> file VARCHAR(255),
+ ...> line VARCHAR(10)
+ ...> );
+
+When the database is set up, use the following configuration to set up log4php.
+
+.. container:: tabs
+
+ .. rubric:: XML format
+ .. code-block:: xml
+
+ <configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderPDO">
+ <param name="dsn" value="sqlite:/tmp/log.db" />
+ </appender>
+ <root>
+ <appender_ref ref="default" />
+ </root>
+ </configuration>
+
+ .. rubric:: PHP format
+ .. code-block:: php
+
+ array(
+ 'appenders' => array(
+ 'default' => array(
+ 'class' => 'LoggerAppenderPDO',
+ 'params' => array(
+ 'dsn' => 'sqlite:/tmp/log.db',
+ ),
+ ),
+ ),
+ 'rootLogger' => array(
+ 'appenders' => array('default'),
+ ),
+ );
+
+Now the database is ready to accept some logging data.
+
+.. code-block:: php
+
+ require 'log4php/Logger.php';
+ Logger::configure('config.xml');
+
+ $log = Logger::getLogger('foo');
+ $log->info("foo");
+ $log->info("bar");
+ $log->info("baz");
+
+Now you can check out the data in the sqlite database.
+
+.. code-block:: bash
+
+ $ sqlite3 /tmp/log.db
+ SQLite version 3.7.9 2011-11-01 00:52:41
+ Enter ".help" for instructions
+ Enter SQL statements terminated with a ";"
+ sqlite> select * from log4php_log;
+ 2012-08-18 17:14:11|foo|INFO|foo|23531|/home/ihabunek/apache/sqlite.php|5
+ 2012-08-18 17:14:11|foo|INFO|bar|23531|/home/ihabunek/apache/sqlite.php|6
+ 2012-08-18 17:14:11|foo|INFO|baz|23531|/home/ihabunek/apache/sqlite.php|7
+
+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.
+
+First, a log table has to be created. For this example a database named
+``logdb`` will be created, and within it a table named ``log``.
+
+
+.. code-block:: bash
+
+ $ mysql -u root -p
+ Enter password: *******
+ Welcome to the MySQL monitor. Commands end with ; or \g.
+ Your MySQL connection id is 47
+ Server version: 5.5.24-0ubuntu0.12.04.1 (Ubuntu)
+
+ mysql> CREATE DATABASE logdb;
+ Query OK, 1 row affected (0.00 sec)
+
+ mysql> USE logdb;
+ Database changed
+
+ mysql> CREATE TABLE log (
+ -> timestamp DATETIME,
+ -> logger VARCHAR(256),
+ -> level VARCHAR(32),
+ -> message VARCHAR(4000),
+ -> thread INTEGER,
+ -> file VARCHAR(255),
+ -> line VARCHAR(10)
+ -> );
+ Query OK, 0 rows affected (0.01 sec)
+
+The following configuration allows log4php to write to the newly created table.
+
+.. container:: tabs
+
+ .. rubric:: XML format
+ .. code-block:: xml
+
+ <configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderPDO">
+ <param name="dsn" value="mysql:host=localhost;dbname=logdb" />
+ <param name="user" value="root" />
+ <param name="password" value="secret" />
+ <param name="table" value="log" />
+ </appender>
+ <root>
+ <appender_ref ref="default" />
+ </root>
+ </configuration>
+
+ .. rubric:: PHP format
+ .. code-block:: php
+
+ array(
+ 'appenders' => array(
+ 'default' => array(
+ 'class' => 'LoggerAppenderPDO',
+ 'params' => array(
+ 'dsn' => 'mysql:host=localhost;dbname=logdb',
+ 'user' => 'root',
+ 'password' => 'secret',
+ 'table' => 'log',
+ ),
+ ),
+ ),
+ 'rootLogger' => array(
+ 'appenders' => array('default'),
+ ),
+ );
+
+Now the database is ready to accept some logging data.
+
+.. code-block:: php
+
+ require 'log4php/Logger.php';
+ Logger::configure('config.xml');
+
+ $log = Logger::getLogger('main');
+ $log->info("foo");
+ $log->info("bar");
+ $log->info("baz");
+
+Finally, to see the logged data.
+
+.. code-block:: bash
+
+ $ mysql -u root -p
+ Enter password: *******
+ Welcome to the MySQL monitor. Commands end with ; or \g.
+ Your MySQL connection id is 47
+ Server version: 5.5.24-0ubuntu0.12.04.1 (Ubuntu)
+
+ mysql> select * from log;
+ +---------------------+--------+-------+---------+--------+---------------------------------+------+
+ | timestamp | logger | level | message | thread | file | line |
+ +---------------------+--------+-------+---------+--------+---------------------------------+------+
+ | 2012-08-18 17:30:05 | main | INFO | foo | 23638 | /home/ihabunek/apache/mysql.php | 5 |
+ | 2012-08-18 17:30:05 | main | INFO | bar | 23638 | /home/ihabunek/apache/mysql.php | 6 |
+ | 2012-08-18 17:30:05 | main | INFO | baz | 23638 | /home/ihabunek/apache/mysql.php | 7 |
+ +---------------------+--------+-------+---------+--------+---------------------------------+------+
+ 3 rows in set (0.00 sec)
+
+
+.. 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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/57c1ce09/docs/appenders/php.rst
----------------------------------------------------------------------
diff --git a/docs/appenders/php.rst b/docs/appenders/php.rst
new file mode 100644
index 0000000..9a287d8
--- /dev/null
+++ b/docs/appenders/php.rst
@@ -0,0 +1,74 @@
+==================
+LoggerAppenderPhp
+==================
+
+``LoggerAppenderPhp`` logs events by creating a PHP user-level message using
+the PHP's `trigger_error()`_ function.
+
+.. _`trigger_error()`: http://www.php.net/manual/en/function.trigger-error.php
+
+The error type depends on the event's severity level:
+
+- ``E_USER_NOTICE`` when the event's level is equal to or less than INFO
+- ``E_USER_WARNING`` when the event's level is equal to WARN
+- ``E_USER_ERROR`` when the event's level is equal to or greater than ERROR
+
+Layout
+------
+
+This appender requires a layout. If no layout is specified in configuration,
+``LoggerLayoutSimple`` will be used by default.
+
+Parameters
+----------
+
+This appender has no configurable parameters.
+
+Examples
+--------
+
+.. container:: tabs
+
+ .. rubric:: XML format
+ .. code-block:: xml
+
+ <configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderPhp">
+ <layout class="LoggerLayoutSimple" />
+ </appender>
+ <root>
+ <appender_ref ref="default" />
+ </root>
+ </configuration>
+
+ .. rubric:: PHP format
+ .. code-block:: php
+
+ array(
+ 'appenders' => array(
+ 'default' => array(
+ 'class' => 'LoggerAppenderPhp',
+ 'layout' => array(
+ 'class' => 'LoggerLayoutSimple',
+ ),
+ ),
+ ),
+ 'rootLogger' => array(
+ 'appenders' => array('default'),
+ ),
+ );
+
+.. 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.