[logback-dev] svn commit: r883 - in logback/trunk: logback-core/src/main/java/ch/qos/logback/core/db logback-examples/src/main/java/chapter4/db logback-site/src/site logback-site/src/site/resources/manual/images/chapter4 logback-site/src/site/xdocTemplates/manual
noreply.seb at qos.ch
noreply.seb at qos.ch
Wed Nov 8 10:06:08 CET 2006
Author: seb
Date: Wed Nov 8 10:06:07 2006
New Revision: 883
Added:
logback/trunk/logback-site/src/site/resources/manual/images/chapter4/
logback/trunk/logback-site/src/site/resources/manual/images/chapter4/dbAppenderLE.gif (contents, props changed)
logback/trunk/logback-site/src/site/resources/manual/images/chapter4/dbAppenderLEException.gif (contents, props changed)
logback/trunk/logback-site/src/site/resources/manual/images/chapter4/dbAppenderLEProperty.gif (contents, props changed)
Modified:
logback/trunk/logback-core/src/main/java/ch/qos/logback/core/db/DataSourceConnectionSource.java
logback/trunk/logback-examples/src/main/java/chapter4/db/append-toMySQL-with-driverManager.xml
logback/trunk/logback-examples/src/main/java/chapter4/db/append-with-datasource.xml
logback/trunk/logback-examples/src/main/java/chapter4/db/append-with-drivermanager.xml
logback/trunk/logback-examples/src/main/java/chapter4/db/append-with-jndi.xml
logback/trunk/logback-examples/src/main/java/chapter4/db/append-with-pooled-datasource.xml
logback/trunk/logback-site/src/site/ (props changed)
logback/trunk/logback-site/src/site/site.xml
logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml
Log:
On Work in progress on chapter 4
- DBAppender documentation
- configuration examples
- minor tweaks to site aesthetics
- added illustrations for dbAppender
- modified .svnignore on src/site
Modified: logback/trunk/logback-core/src/main/java/ch/qos/logback/core/db/DataSourceConnectionSource.java
==============================================================================
--- logback/trunk/logback-core/src/main/java/ch/qos/logback/core/db/DataSourceConnectionSource.java (original)
+++ logback/trunk/logback-core/src/main/java/ch/qos/logback/core/db/DataSourceConnectionSource.java Wed Nov 8 10:06:07 2006
@@ -10,21 +10,19 @@
package ch.qos.logback.core.db;
-
import java.sql.Connection;
import java.sql.SQLException;
import javax.sql.DataSource;
-
/**
- * The DataSourceConnectionSource is an implementation of {@link ConnectionSource}
- * that obtains the Connection in the recommended JDBC manner based on
- * a {@link javax.sql.DataSource DataSource}.
- * <p>
- *
- * @author Ray DeCampo
- * @author Ceki Gülcü
+ * The DataSourceConnectionSource is an implementation of
+ * {@link ConnectionSource} that obtains the Connection in the recommended JDBC
+ * manner based on a {@link javax.sql.DataSource DataSource}.
+ * <p>
+ *
+ * @author Ray DeCampo
+ * @author Ceki Gülcü
*/
public class DataSourceConnectionSource extends ConnectionSourceBase {
@@ -32,20 +30,21 @@
@Override
public void start() {
- //LogLog.debug("**********DataSourceConnectionSource.activateOptions called");
if (dataSource == null) {
addWarn("WARNING: No data source specified");
} else {
Connection connection = null;
try {
connection = getConnection();
- } catch(SQLException se) {
- addWarn("Could not get a connection to discover the dialect to use.", se);
+ } catch (SQLException se) {
+ addWarn("Could not get a connection to discover the dialect to use.",
+ se);
}
- if(connection != null) {
+ if (connection != null) {
discoverConnnectionProperties();
- }
- if(!supportsGetGeneratedKeys() && getSQLDialectCode() == ConnectionSource.UNKNOWN_DIALECT) {
+ }
+ if (!supportsGetGeneratedKeys()
+ && getSQLDialectCode() == ConnectionSource.UNKNOWN_DIALECT) {
addWarn("Connection does not support GetGeneratedKey method and could not discover the dialect.");
}
}
Modified: logback/trunk/logback-examples/src/main/java/chapter4/db/append-toMySQL-with-driverManager.xml
==============================================================================
--- logback/trunk/logback-examples/src/main/java/chapter4/db/append-toMySQL-with-driverManager.xml (original)
+++ logback/trunk/logback-examples/src/main/java/chapter4/db/append-toMySQL-with-driverManager.xml Wed Nov 8 10:06:07 2006
@@ -1,23 +1,22 @@
-<configuration>
-
- <appender name="DB" class="ch.qos.logback.classic.db.DBAppender">
- <connectionSource class="ch.qos.logback.classic.db.DriverManagerConnectionSource">
- <driverClass>"com.mysql.jdbc.Driver</driverClass>
- <url>jdbc:mysql://host_name:3306/datebase_name</url>
- <user>logback</user>
- <password>logback</password>
- </connectionSource>
- </appender>
+<?xml version="1.0" encoding="UTF-8" ?>
+<configuration>
- <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
- <layout class="ch.qos.logback.classic.PatternLayout">
- <pattern>%level %thread %logger - %msg%n</pattern>
- </layout>
- </appender>
- <root>
- <level value="debug"/>
- <appender-ref ref="STDOUT"/>
- <appender-ref ref="DB"/>
- </root>
+ <appender name="DB" class="ch.qos.logback.classic.db.DBAppender">
+ <connectionSource class="ch.qos.logback.core.db.DriverManagerConnectionSource">
+ <driverClass>com.mysql.jdbc.Driver</driverClass>
+ <url>jdbc:mysql://host_name:3306/datebase_name</url>
+ <user>username</user>
+ <password>password</password>
+ </connectionSource>
+ </appender>
+
+ <!-- Prevent internal logback DEBUG messages from polluting the output. -->
+ <logger name="ch.qos.logback.core.joran"><level value="INFO" /></logger>
+ <logger name="ch.qos.logback.classic.joran"><level value="INFO" /></logger>
+
+ <root>
+ <level value="debug" />
+ <appender-ref ref="DB" />
+ </root>
</configuration>
Modified: logback/trunk/logback-examples/src/main/java/chapter4/db/append-with-datasource.xml
==============================================================================
--- logback/trunk/logback-examples/src/main/java/chapter4/db/append-with-datasource.xml (original)
+++ logback/trunk/logback-examples/src/main/java/chapter4/db/append-with-datasource.xml Wed Nov 8 10:06:07 2006
@@ -6,6 +6,10 @@
<connectionSource class="ch.qos.logback.core.db.DataSourceConnectionSource">
<dataSource class="${dataSourceClass}">
+ <!-- Joran cannot substitute variables
+ that are not attribute values. Therefore, we cannot
+ declare the next parameter like the others.
+ -->
<param name="${url-key:-url}" value="${url}"/>
<serverName>${serverName}</serverName>
<databaseName>${databaseName}</databaseName>
Modified: logback/trunk/logback-examples/src/main/java/chapter4/db/append-with-drivermanager.xml
==============================================================================
--- logback/trunk/logback-examples/src/main/java/chapter4/db/append-with-drivermanager.xml (original)
+++ logback/trunk/logback-examples/src/main/java/chapter4/db/append-with-drivermanager.xml Wed Nov 8 10:06:07 2006
@@ -3,7 +3,8 @@
<configuration>
<appender name="DB" class="ch.qos.logback.classic.db.DBAppender">
- <connectionSource class="ch.qos.logback.core.db.DriverManagerConnectionSource">
+ <connectionSource
+ class="ch.qos.logback.core.db.DriverManagerConnectionSource">
<driverClass>${driverClass}</driverClass>
<url>${url}</url>
<user>${user}</user>
Modified: logback/trunk/logback-examples/src/main/java/chapter4/db/append-with-jndi.xml
==============================================================================
--- logback/trunk/logback-examples/src/main/java/chapter4/db/append-with-jndi.xml (original)
+++ logback/trunk/logback-examples/src/main/java/chapter4/db/append-with-jndi.xml Wed Nov 8 10:06:07 2006
@@ -4,7 +4,7 @@
<!-- We create a joran rule that will instance and bind the appropriate
data source instance to JNDI. -->
<newRule pattern="configuration/bindDataSourceToJNDI"
- actionClass="org.apache.log4j.db.BindDataSourceToJNDIAction"/>
+ actionClass="ch.qos.logback.core.db.BindDataSourceToJNDIAction"/>
<bindDataSourceToJNDI />
@@ -12,6 +12,10 @@
<connectionSource class="ch.qos.logback.core.db.DataSourceConnectionSource">
<dataSource class="${dataSourceClass}">
+ <!-- Joran cannot substitute variables
+ that are not attribute values. Therefore, we cannot
+ declare the next parameter like the others.
+ -->
<param name="${url-key:-url}" value="${url}"/>
<serverName>${serverName}</serverName>
<databaseName>${databaseName}</databaseName>
Modified: logback/trunk/logback-examples/src/main/java/chapter4/db/append-with-pooled-datasource.xml
==============================================================================
--- logback/trunk/logback-examples/src/main/java/chapter4/db/append-with-pooled-datasource.xml (original)
+++ logback/trunk/logback-examples/src/main/java/chapter4/db/append-with-pooled-datasource.xml Wed Nov 8 10:06:07 2006
@@ -6,6 +6,10 @@
<connectionSource class="ch.qos.logback.core.db.DataSourceConnectionSource">
<dataSource class="${pooledDataSourceClass}">
+ <!-- Joran cannot substitute variables
+ that are not attribute values. Therefore, we cannot
+ declare the next parameter like the others.
+ -->
<param name="${url-key:-url}" value="${url}"/>
<serverName>${serverName}</serverName>
<databaseName>${databaseName}</databaseName>
Added: logback/trunk/logback-site/src/site/resources/manual/images/chapter4/dbAppenderLE.gif
==============================================================================
Binary file. No diff available.
Added: logback/trunk/logback-site/src/site/resources/manual/images/chapter4/dbAppenderLEException.gif
==============================================================================
Binary file. No diff available.
Added: logback/trunk/logback-site/src/site/resources/manual/images/chapter4/dbAppenderLEProperty.gif
==============================================================================
Binary file. No diff available.
Modified: logback/trunk/logback-site/src/site/site.xml
==============================================================================
--- logback/trunk/logback-site/src/site/site.xml (original)
+++ logback/trunk/logback-site/src/site/site.xml Wed Nov 8 10:06:07 2006
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="ISO-8859-1"?>
-<project name="Logback Main Site">
+<project name="Logback Project">
<skin>
<groupId>ch.qos.logback</groupId>
@@ -10,7 +10,7 @@
<publishDate position="navigation-bottom" format="dd-MM-yyyy"/>
<bannerLeft>
- <name>${project.name}</name>
+ <name>Logback Project</name>
<src>/images/logos/lblogo.jpg</src>
<href>http://logback.qos.ch</href>
</bannerLeft>
@@ -24,7 +24,7 @@
</links>
-->
- <menu name="${project.name}">
+ <menu name="Logback Project">
<item name="Introduction" href="index.html"/>
<item name="News" href="news.html" />
<item name="Download" href="download.html" />
Modified: logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml
==============================================================================
--- logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml (original)
+++ logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml Wed Nov 8 10:06:07 2006
@@ -1380,9 +1380,10 @@
<h3>SMTPAppender</h3>
<p>
- The <code>SMTPAppender</code> accumulates logging events in a fixed-size
- buffer and sends them in an email when a user specified triggering event occurs.
- By default, the triggering event is taken as the reception of an event
+ The <a href="../xref/ch/qos/logback/classic/net/SMTPAppender.html"><code>SMTPAppender</code></a>
+ accumulates logging events in a fixed-size buffer and sends them in an email when a
+ user specified triggering event occurs.
+ By default, the triggering event is taken as the reception of an event
of level <em>ERROR</em> or higher.
</p>
@@ -1643,17 +1644,331 @@
</configuration></pre></div>
<h3>DBAppender</h3>
+
+ <p>
+ The <a href="../xref/ch/qos/logback/classic/db/DBAppender.html"><code>DBAppender</code></a>
+ inserts loggin events into three database tables in a format
+ independent of the Java programming language.
+ </p>
+ <p>
+ These three tables are <em>logging_event</em>, <em>logging_event_property</em> and
+ <em>logging_event_exception</em>. They all must exist before <code>DBAppender</code>
+ can be used. Logback ships with SQL scripts that will create the tables.
+ They can be found in the found in the
+ <em>logback-classic/src/main/java/ch/qos/logback/classic/db/dialect</em> directory. There
+ is a specific script for each of the most popular database systems.
+ If the script for your particular type of database system is missing, it should be
+ quite easy to write one, taking example on the already existing scripts. If
+ you send them to us, we will gladly include missing scripts in future
+ </p>
+ <p>
+ If the JDBC driver you are using supports the
+ <code>getGeneratedKeys</code> method introduced in
+ JDBC 3.0 specification, then no more steps are required, excluding usual
+ configuration.
+ </p>
+ <p>
+ Otherwise, there must be an <code>SQLDialect</code> appropriate for your
+ database system. Currently, we have dialects for PostgreSQL,
+ MySQL, Oracle and MsSQL. As mentioned previously, an
+ <code>SQLDialect</code> is required only if the JDBC driver for your
+ database system does not support the <code>getGeneratedKeys</code>
+ method.
+ </p>
+ <p>
+ The table below summarizes the database tapes and their support of the
+ <code>getGeneratedKeys()</code> method.
+ </p>
+ <table border="1" cellpadding="4">
+ <tr>
+ <th>RDBMS</th>
+ <th>
+ supports
+ <br />
+ <code>getGeneratedKeys()</code>
+ method
+ </th>
+ <th>
+ specific
+ <br />
+ SQLDialect support
+ </th>
+ </tr>
+ <tr>
+ <td>PostgreSQL</td>
+ <td>NO</td>
+ <td>present and used</td>
+ </tr>
+ <tr>
+ <td>MySQL</td>
+ <td>YES</td>
+ <td>present, but not actually needed or used</td>
+ </tr>
+ <tr>
+ <td>Oracle</td>
+ <td>YES</td>
+ <td>present, but not actually needed or used</td>
+ </tr>
+ <tr>
+ <td>DB2</td>
+ <td>YES</td>
+ <td>not present, and not needed or used</td>
+ </tr>
+ <tr>
+ <td>MsSQL</td>
+ <td>YES</td>
+ <td>not present, and not needed or used</td>
+ </tr>
+ <tr>
+ <td>HSQL</td>
+ <td>NO</td>
+ <td>present and used</td>
+ </tr>
+ </table>
+
+ <p>
+ Experiments show that writing a single event
+ into the database takes approximately 50 milliseconds, on a
+ "standard" PC. If pooled connections are used, this figure
+ drops to under 10 milliseconds. Note that most JDBC drivers
+ already ship with connection pooling support.
+ </p>
+
+ <p>
+ Configuring logback to use <code>DBAppender</code> can be done
+ in several different ways, depending on the tools one has to
+ connect to the database, and the database itself.
+ </p>
+
+ <p>
+ The first example that we will review is a configuration using
+ <code>DriverManagerConnectionSource</code> and a MySQL database.
+ The following configuration file is what one would need.
+ </p>
+
+<em>Example 4.6: <code>DBAppender</code> configuration (logback-examples/src/main/java/chapter4/db/append-toMySQL-with-driverManager.xml)</em>
+<div class="source"><pre><configuration>
+ <b><appender name="DB" class="ch.qos.logback.classic.db.DBAppender">
+ <connectionSource class="ch.qos.logback.core.db.DriverManagerConnectionSource">
+ <driverClass>com.mysql.jdbc.Driver</driverClass>
+ <url>jdbc:mysql://host_name:3306/datebase_name</url>
+ <user>username</user>
+ <password>password</password>
+ </connectionSource>
+ </appender></b>
+
+ <!-- Prevent internal logback DEBUG messages from polluting the output. -->
+ <logger name="ch.qos.logback.core.joran"><level value="INFO" /></logger>
+ <logger name="ch.qos.logback.classic.joran"><level value="INFO" /></logger>
+
+ <root>
+ <level value="debug" />
+ <appender-ref ref="DB" />
+ </root>
+</configuration></pre></div>
+ <p>
+ The correct driver must be declared. Here, the <code>com.mysql.jdbc.Driver</code>
+ class is used. The <span class="option">url</span> must begin with <em>jdbc:myslq://</em>.
+ </p>
+
+ <p>Connecting to a database using a <code>DataSource</code> is rather similar:</p>
+
+<em>Example 4.7: <code>DBAppender</code> configuration (logback-examples/src/main/java/chapter4/db/append-with-datasource.xml)</em>
+<div class="source"><pre><configuration>
+ <appender name="DB" class="ch.qos.logback.classic.db.DBAppender">
+ <b><connectionSource class="ch.qos.logback.core.db.DataSourceConnectionSource">
+
+ <dataSource class="${dataSourceClass}">
+ </b><!-- Joran cannot substitute variables
+ that are not attribute values. Therefore, we cannot
+ declare the next parameter like the others.
+ -->
+ <b><param name="${url-key:-url}" value="${url_value}"/>
+ <serverName>${serverName}</serverName>
+ <databaseName>${databaseName}</databaseName>
+ </dataSource></b>
+
+ <user>${user}</user>
+ <password>${password}</password>
+ </connectionSource>
+ </appender>
+
+ <!-- Prevent internal logback DEBUG messages from polluting the output. -->
+ <logger name="ch.qos.logback.core.joran"><level value="INFO" /></logger>
+ <logger name="ch.qos.logback.classic.joran"><level value="INFO" /></logger>
+
+ <root>
+ <level value ="debug"/>
+ <appender-ref ref="DB" />
+ </root>
+</configuration></pre></div>
+ <p>
+ Not that in this configuration sample, we make heavy use of substitution variables.
+ They are sometimes handy when connection details have to be centralised in a
+ single configuration file and shared by logback and other frameworks.
+ </p>
+
+ <p>
+ Once logback is configured properly, the logging events are sent to
+ the specified database. As stated previously, there are three tables
+ used by logback to store logging event data.
+ </p>
+
+ <p>
+ The <em>logging_event</em> table contains the following fields:
+ </p>
+ <table>
+ <tr>
+ <th>Field</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><b>timestmp</b></td>
+ <td><code>big int</code></td>
+ <td>The timestamp that was valid at the logging event's creation.</td>
+ </tr>
+ <tr>
+ <td><b>formatted_message</b></td>
+ <td><code>text</code></td>
+ <td>The message that has been added to the logging event, after formatting with
+ <code>org.slf4j.impl.MessageFormatter</code>, in case object were passed
+ along with the message.</td>
+ </tr>
+ <tr>
+ <td><b>logger_name</b></td>
+ <td><code>varchar</code></td>
+ <td>The name of the logger used to issue the logging request.</td>
+ </tr>
+ <tr>
+ <td><b>level_string</b></td>
+ <td><code>varchar</code></td>
+ <td>The level of the logging event.</td>
+ </tr>
+ <tr>
+ <td><b>reference_flag</b></td>
+ <td><code>smallint</code></td>
+ <td>
+ <p>
+ This field is used by logback to identify logging events that
+ have an exception or <code>MDC</code>property values associated.
+ </p>
+ <p>
+ It's value is computed by
+ <code>ch.qos.logback.classic.db.DBHelper</code>. A logging event that
+ contains <code>MDC</code> or <code>Context</code>
+ properties has a flag number of <em>1</em>. One
+ that contains an exception has a flag number of <em>2</em>. A logging
+ event that contains both elements has a flag number of <em>3</em>.
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td><b>caller_filename</b></td>
+ <td><code>varchar</code></td>
+ <td>The name of the file where the logging request was issued.</td>
+ </tr>
+ <tr>
+ <td><b>caller_class</b></td>
+ <td><code>varchar</code></td>
+ <td>The class where the logging request was issued.</td>
+ </tr>
+ <tr>
+ <td><b>caller_method</b></td>
+ <td><code>varchar</code></td>
+ <td>The name of the method where the logging request was issued.</td>
+ </tr>
+ <tr>
+ <td><b>caller_line</b></td>
+ <td><code>char</code></td>
+ <td>The line number where the logging request was issued.</td>
+ </tr>
+ <tr>
+ <td><b>event_id</b></td>
+ <td><code>int</code></td>
+ <td>The database id of the logging event.</td>
+ </tr>
+ </table>
+
+ <p>
+ The <em>logging_event_property</em> is used to store the keys and values
+ contained in the <code>MDC</code> or the <code>Context</code>.
+ It contains these fields:
+ </p>
+ <table>
+ <tr>
+ <th>Field</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><b>event_id</b></td>
+ <td><code>int</code></td>
+ <td>The database id of the logging event.</td>
+ </tr>
+ <tr>
+ <td><b>mapped_key</b></td>
+ <td><code>varchar</code></td>
+ <td>The key of the <code>MDC</code> property</td>
+ </tr>
+ <tr>
+ <td><b>mapped_value</b></td>
+ <td><code>text</code></td>
+ <td>The value of the <code>MDC</code> property</td>
+ </tr>
+ </table>
+
+ <p>
+ The <em>logging_event_exception</em> table contains the following fields:
+ </p>
+
+ <table>
+ <tr>
+ <th>Field</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><b>event_id</b></td>
+ <td><code>int</code></td>
+ <td>The database id of the logging event.</td>
+ </tr>
+ <tr>
+ <td><b>i</b></td>
+ <td><code>smallint</code></td>
+ <td>The index of the line in the full stack trace.</td>
+ </tr>
+ <tr>
+ <td><b>trace_line</b></td>
+ <td><code>varchar</code></td>
+ <td>The corresponding line</td>
+ </tr>
+ </table>
+
+ <p>
+ To give a more visual example of the work done by <code>DBAppender</code>, here
+ is a screenshot of a MySQL database with content provided by <code>DBAppender</code>.
+ </p>
+
+ <p>The <em>logging_event</em> table:</p>
+ <img src="images/chapter4/dbAppenderLE.gif" alt="Logging Event table" />
+ <p>The <em>logging_event_exception</em> table:</p>
+
+ <img src="images/chapter4/dbAppenderLEException.gif" alt="Logging Event Exception table" />
+ <p>The <em>logging_event_property</em> table:</p>
+
+ <img src="images/chapter4/dbAppenderLEProperty.gif" alt="Logging Event Property table" />
<h3>SyslogAppender</h3>
More information about the logback-dev
mailing list