logging-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ihabu...@apache.org
Subject svn commit: r1374599 - /logging/log4php/trunk/src/site/xdoc/docs/appenders/pdo.xml
Date Sat, 18 Aug 2012 15:40:37 GMT
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>



Mime
View raw message