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 2012/08/18 17:40:37 UTC
svn commit: r1374599 -
/logging/log4php/trunk/src/site/xdoc/docs/appenders/pdo.xml
Author: ihabunek
Date: Sat Aug 18 15:40:37 2012
New Revision: 1374599
URL: http://svn.apache.org/viewvc?rev=1374599&view=rev
Log:
Improved docs for LoggerAppenderPDO to reflect new functionality (no automatic table creation).
Modified:
logging/log4php/trunk/src/site/xdoc/docs/appenders/pdo.xml
Modified: logging/log4php/trunk/src/site/xdoc/docs/appenders/pdo.xml
URL: http://svn.apache.org/viewvc/logging/log4php/trunk/src/site/xdoc/docs/appenders/pdo.xml?rev=1374599&r1=1374598&r2=1374599&view=diff
==============================================================================
--- logging/log4php/trunk/src/site/xdoc/docs/appenders/pdo.xml (original)
+++ logging/log4php/trunk/src/site/xdoc/docs/appenders/pdo.xml Sat Aug 18 15:40:37 2012
@@ -68,13 +68,6 @@
<td>Password used to connect to the database.</td>
</tr>
<tr>
- <td>createTable</td>
- <td>boolean</td>
- <td>No</td>
- <td>true</td>
- <td>If set to true, the table will be created if it doesn't exist.</td>
- </tr>
- <tr>
<td>table</td>
<td>string</td>
<td>No</td>
@@ -99,12 +92,108 @@
</table>
<p>Parameters <code>dsn</code>, <code>user</code> and <code>password</code> 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 <a href="http://www.php.net/manual/en/pdo.drivers.php" target="_blank"
- class="externalLink">PDO driver documentation</a>.</p>
+ the database which will be used for logging.</p>
+ </subsection>
+
+ <subsection name="Data Source Name">
+ <p>The Data Source Name or DSN is a database-specific string which contains the information required
+ to connect to the database.</p>
+
+ <p>Some common examples of DSNs:</p>
+
+ <table class="table table-compact table-bordered table-not-wide">
+ <tbody>
+ <tr>
+ <th>MySQL</th>
+ <td><code>mysql:host=localhost;dbname=logdb</code></td>
+ <td><a href="http://php.net/manual/en/ref.pdo-mysql.connection.php" class="externalLink">full reference</a> </td>
+ </tr>
+ <tr>
+ <th>SQLite</th>
+ <td><code>sqlite:/path/to/log.db</code></td>
+ <td><a href="http://php.net/manual/en/ref.pdo-sqlite.connection.php" class="externalLink">full reference</a> </td>
+ </tr>
+ <tr>
+ <th>PostgreSQL </th>
+ <td><code>pgsql:host=localhost;port=5432</code></td>
+ <td><a href="http://php.net/manual/en/ref.pdo-pgsql.connection.php" class="externalLink">full reference</a> </td>
+ </tr>
+ </tbody>
+ </table>
+
+ <p>For other available database drivers and corresponding DSN format, please see the
+ <a href="http://www.php.net/manual/en/pdo.drivers.php" target="_blank" class="externalLink">PDO
+ driver documentation</a>.</p>
</subsection>
+ <subsection name="Database table">
+
+ <p>Since version 2.3.0, the appender will <strong>not</strong> 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.</p>
+
+ <p>By default the table should contain the following columns: </p>
+
+ <ul>
+ <li>timestamp DATETIME</li>
+ <li>logger VARCHAR</li>
+ <li>level VARCHAR</li>
+ <li>message VARCHAR</li>
+ <li>thread VARCHAR</li>
+ <li>file VARCHAR</li>
+ <li>line VARCHAR</li>
+ </ul>
+
+ <p>If you wish to use an alternative table structure, see the next chapter.</p>
+
+ <p>The following examples show CREATE TABLE statements for some popular databases.</p>
+
+ <h4>MySQL</h4>
+
+<pre class="prettyprint">
+CREATE TABLE log4php_log (
+ timestamp DATETIME,
+ logger VARCHAR(256),
+ level VARCHAR(32),
+ message VARCHAR(4000),
+ thread INTEGER,
+ file VARCHAR(255),
+ line VARCHAR(10)
+);
+</pre>
+
+ <h4>SQLite</h4>
+
+ <p>SQLite does not have a datetime type, so varchar is used instead.</p>
+
+<pre class="prettyprint">
+CREATE TABLE log4php_log (
+ timestamp VARCHAR(50),
+ logger VARCHAR(256),
+ level VARCHAR(32),
+ message VARCHAR(4000),
+ thread INTEGER,
+ file VARCHAR(255),
+ line VARCHAR(10)
+);
+</pre>
+
+ <h4>PostgreSQL</h4>
+
+<pre class="prettyprint">
+CREATE TABLE log4php_log (
+ timestamp TIMESTAMP,
+ logger VARCHAR(256),
+ level VARCHAR(32),
+ message VARCHAR(4000),
+ thread INTEGER,
+ file VARCHAR(255),
+ line VARCHAR(10)
+);
+</pre>
+ </subsection>
+
<subsection name="Advanced configuration" id="Advanced_configuration">
<p>Parameters <code>insertSql</code> and <code>insertPattern</code> 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
@@ -129,7 +218,7 @@
</tr>
<tr>
<td>insertPattern</td>
- <td>%d,%c,%p,%m,%t,%F,%L</td>
+ <td>%date{Y-m-d H:i:s},%logger,%level,%message,%pid,%file,%line</td>
</tr>
</tbody>
</table>
@@ -151,8 +240,28 @@
authentication.</p>
<p>SQLite databases are contained in simple files and don't reuquire a server to run. This example will
- log to the database contained in <code>/var/log/log.sqlite</code>. The database will be created if it
- doesn't already exist.</p>
+ log to the database contained in <code>/var/log/log.sqlite</code>.</p>
+
+ <p>First, create a database and a table for logging. In this example, let's create the database at
+ <code>/tmp/log.db</code>.</p>
+
+<pre><![CDATA[
+$ 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)
+ ...> );
+]]></pre>
+
+ <p>When the database is set up, use the following configuration to set up log4php.</p>
<div class="auto-tabs">
<ul>
@@ -165,7 +274,7 @@
<pre class="prettyprint"><![CDATA[
<configuration xmlns="http://logging.apache.org/log4php/">
<appender name="default" class="LoggerAppenderPDO">
- <param name="dsn" value="sqlite:/var/log/log.sqlite" />
+ <param name="dsn" value="sqlite:/tmp/log.db" />
</appender>
<root>
<appender_ref ref="default" />
@@ -180,7 +289,7 @@ array(
'default' => array(
'class' => 'LoggerAppenderPDO',
'params' => array(
- 'dsn' => 'sqlite:/var/log/log.sqlite',
+ 'dsn' => 'sqlite:/tmp/log.db',
),
),
),
@@ -193,15 +302,66 @@ array(
</div>
</div>
+ <p>Now the database is ready to accept some logging data.</p>
+
+<pre class="prettyprint linenums"><![CDATA[
+require 'log4php/Logger.php';
+Logger::configure('config.xml');
+
+$log = Logger::getLogger('foo');
+$log->info("foo");
+$log->info("bar");
+$log->info("baz");
+]]></pre>
+
+ <p>And you can .</p>
+
+<pre><![CDATA[
+$ 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
+]]></pre>
+
<h4>Example 2</h4>
<p>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.</p>
- <p>For this example, MySQL server needs to be running on localhost, and needs to contain a database
- named <code>logdb</code>. The log will be written to a table named <code>log_table</code>. The table
- will be created if it doesn't already exist.</p>
+ <p>First, a log table has to be created. For this example a database named <code>logdb</code> will be
+ created, and within it a table named <code>log</code>.</p>
+
+<pre><![CDATA[
+$ 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)
+]]></pre>
+
+ <p>The following configuration allows log4php to write to the newly created table.</p>
+
<div class="auto-tabs">
<ul>
<li>XML</li>
@@ -216,7 +376,7 @@ array(
<param name="dsn" value="mysql:host=localhost;dbname=logdb" />
<param name="user" value="root" />
<param name="password" value="secret" />
- <param name="table" value="log_table" />
+ <param name="table" value="log" />
</appender>
<root>
<appender_ref ref="default" />
@@ -234,7 +394,7 @@ array(
'dsn' => 'mysql:host=localhost;dbname=logdb',
'user' => 'root',
'password' => 'secret',
- 'table' => 'log_table',
+ 'table' => 'log',
),
),
),
@@ -247,29 +407,37 @@ array(
</div>
</div>
- <p>This is an output sample retrieved from the MySQL database.</p>
+ <p>Now the database is ready to accept some logging data.</p>
-<pre>
- mysql> desc log_table;
-+-----------+---------------+------+-----+---------+-------+
-| Field | Type | Null | Key | Default | Extra |
-+-----------+---------------+------+-----+---------+-------+
-| timestamp | varchar(32) | YES | | NULL | |
-| logger | varchar(64) | YES | | NULL | |
-| level | varchar(32) | YES | | NULL | |
-| message | varchar(9999) | YES | | NULL | |
-| thread | varchar(32) | YES | | NULL | |
-| file | varchar(255) | YES | | NULL | |
-| line | varchar(6) | YES | | NULL | |
-+-----------+---------------+------+-----+---------+-------+
-
- mysql> SELECT * FROM log_table;
- +-------------------------+--------+-------+--------------+--------+--------------+------+
- | timestamp | logger | level | message | thread | file | line |
- +-------------------------+--------+-------+--------------+--------+--------------+------+
- | 2011-10-02 19:36:07,935 | main | INFO | Hello World! | 21858 | /tmp/log.php | 24 |
- +-------------------------+--------+-------+--------------+--------+--------------+------+
-</pre>
+<pre class="prettyprint linenums"><![CDATA[
+require 'log4php/Logger.php';
+Logger::configure('config.xml');
+
+$log = Logger::getLogger('main');
+$log->info("foo");
+$log->info("bar");
+$log->info("baz");
+]]></pre>
+
+ <p>Finally, to see the newly logged data.</p>
+
+<pre><![CDATA[
+$ 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)
+]]></pre>
</subsection>
</section>