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>