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 [EMAIL PROTECTED]
ConnectionSource}
- * that obtains the Connection in the recommended JDBC manner based on
- * a [EMAIL PROTECTED] javax.sql.DataSource DataSource}.
- * <p>
- *
- * @author Ray DeCampo
- * @author Ceki Gülcü
+ * The DataSourceConnectionSource is an implementation of
+ * [EMAIL PROTECTED] ConnectionSource} that obtains the Connection in the
recommended JDBC
+ * manner based on a [EMAIL PROTECTED] 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>
_______________________________________________
logback-dev mailing list
[email protected]
http://qos.ch/mailman/listinfo/logback-dev
