<?xml version="1.0" encoding="UTF-8"?>
<!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at
 
 http://www.apache.org/licenses/LICENSE-2.0
 
 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.   
-->
<chapter id="ref_guide_logging">
    <title>
        Logging and Auditing
    </title>
    <indexterm zone="ref_guide_logging">
        <primary>
            logging
        </primary>
    </indexterm>
    <indexterm zone="ref_guide_logging">
        <primary>
            Log
        </primary>
    </indexterm>
    <para>
Logging is an important means of gaining insight into your application's runtime
behavior. OpenJPA provides a flexible logging system that integrates with many
existing runtime systems, such as application servers and servlet runners.
    </para>
    <para>
There are five built-in logging plugins: a
<link linkend="ref_guide_logging_openjpa">default logging framework</link> that
covers most needs, a <link linkend="ref_guide_logging_log4j"> Log4J</link>
delegate, a <link linkend="ref_guide_logging_slf4j"> SLF4J</link>
delegate, an <link linkend="ref_guide_logging_commons"> Apache Commons Logging
</link> delegate, and a <link linkend="ref_guide_logging_noop">no-op</link>
implementation for disabling logging.
    </para>
    <warning>
        <para>
Logging can have a negative impact on performance. Disable verbose logging (such
as logging of SQL statements) before running any performance tests. It is
advisable to limit or disable logging for a production system. You can disable
logging altogether by setting the <literal>openjpa.Log</literal> property to
<literal>none</literal>.
        </para>
    </warning>
    <section id="ref_guide_logging_channels">
        <title>
            Logging Channels
        </title>
        <indexterm zone="ref_guide_logging_channels">
            <primary>
                logging
            </primary>
            <secondary>
                channels
            </secondary>
        </indexterm>
        <para>
Logging is done over a number of <emphasis>logging channels</emphasis>, each of
which has a <emphasis>logging level</emphasis> which controls the verbosity of
log messages recorded for the channel. OpenJPA uses the following logging
channels:
        </para>
        <itemizedlist>
            <listitem>
                <para>
<literal>openjpa.Tool</literal>: Messages issued by the OpenJPA command line
and Ant tools. Most messages are basic statements detailing which classes or
files the tools are running on. Detailed output is only available via the
logging category the tool belongs to, such as <literal>openjpa.Enhance</literal>
for the enhancer (see <xref linkend="ref_guide_pc_enhance"/>) or <literal>
openjpa.MetaData</literal> for the mapping tool (see
<xref linkend="ref_guide_mapping_mappingtool"/>). This logging category
is provided so that you can get a general idea of what a tool is doing without
having to manipulate logging settings that might also affect runtime behavior.
                </para>
            </listitem>
            <listitem>
                <para>
                <indexterm>
                    <primary>
                        enhancement
                    </primary>
                    <secondary>
                        log messages
                    </secondary>
                </indexterm>
<literal>openjpa.Enhance</literal>: Messages pertaining to enhancement and
runtime class generation.
                </para>
            </listitem>
            <listitem>
                <para>
                <indexterm>
                    <primary>
                        metadata
                    </primary>
                    <secondary>
                        log messages
                    </secondary>
                </indexterm>
<literal>openjpa.MetaData</literal>: Details about the generation of metadata
and object-relational mappings.
                </para>
            </listitem>
            <listitem>
                <para>
<literal>openjpa.Runtime</literal>: General OpenJPA runtime messages.
                </para>
            </listitem>
            <listitem>
                <para>
                <indexterm>
                    <primary>
                        Query
                    </primary>
                    <secondary>
                        log messages
                    </secondary>
                </indexterm>
<literal>openjpa.Query</literal>: Messages about queries. Query strings and any
parameter values, if applicable, will be logged to the <literal>TRACE</literal>
level at execution time. Information about possible performance concerns will be
logged to the <literal>INFO</literal> level.
                </para>
            </listitem>
            <listitem>
                <para>
                <indexterm>
                    <primary>
                        caching
                    </primary>
                    <secondary>
                        log messages
                    </secondary>
                </indexterm>
<literal>openjpa.DataCache</literal>: Messages from the L2 data cache plugins.
                </para>
            </listitem>
            <listitem>
                <para>
                <indexterm>
                    <primary>
                        JDBC
                    </primary>
                    <secondary>
                        log messages
                    </secondary>
                </indexterm>
<literal>openjpa.jdbc.JDBC</literal>: JDBC connection information. General JDBC
information will be logged to the <literal>TRACE</literal> level. Information
about possible performance concerns will be logged to the <literal>INFO
</literal> level.
                </para>
            </listitem>
            <listitem>
                <para>
                <indexterm>
                    <primary>
                        SQL
                    </primary>
                    <secondary>
                        log messages
                    </secondary>
                </indexterm>
<literal>openjpa.jdbc.SQL</literal>: This is the most common logging channel to
use. Detailed information about the execution of SQL statements will be sent to
the <literal>TRACE</literal> level. It is useful to enable this channel if you
are curious about the exact SQL that OpenJPA issues to the datastore.
<note>
The SQL issued to the database may contain sensitive information. By default the
parameter values used in the prepared statements generated by OpenJPA will not 
be printed in the SQL log - instead you will see a ? for each value. The actual 
values may be printed by adding <literal>PrintParameters=True</literal> to the
<link linkend="openjpa.ConnectionFactoryProperties">
<literal>openjpa.ConnectionFactoryProperties</literal></link> property. Also
see <link linkend="ref_guide_dbsetup_builtin"><literal>Using the OpenJPA
DataSource</literal></link>
</note>
                </para>
                <para>
When using the built-in OpenJPA logging facilities, you can enable SQL logging
by adding <literal>SQL=TRACE</literal> to your <literal>openjpa.Log</literal>
property.
                </para>
                <para>
OpenJPA can optionally reformat the logged SQL to make it easier to read. To
enable pretty-printing, add <literal>PrettyPrint=true</literal> to the
<link linkend="openjpa.ConnectionFactoryProperties"><literal>
openjpa.ConnectionFactoryProperties</literal></link> property. You can control
how many columns wide the pretty-printed SQL will be with the <literal>
PrettyPrintLineLength</literal> property. The default line length is 60 columns.
                </para>
                <para>
While pretty printing makes things easier to read, it can make output harder to
process with tools like grep.
                </para>
                <para>
Pretty-printing properties configuration might look like so:
                </para>
<programlisting>
&lt;property name="openjpa.Log" value="SQL=TRACE"/&gt;
&lt;property name="openjpa.ConnectionFactoryProperties" 
    value="PrettyPrint=true, PrettyPrintLineLength=72"/&gt;
</programlisting>
            </listitem>
            <listitem>
                <para>
                <indexterm>
                    <primary>
                        SQLDiag
                    </primary>
                    <secondary>
                        log messages
                    </secondary>
                </indexterm>
<literal>openjpa.jdbc.SQLDiag</literal>: This logging channel provides additional
information about entity actitvies such as create, find, update or delete, and eager 
loading of relation or field properties. If you enable this channel, it is recommended
that <literal>openjpa.jdbc.SQL</literal> channel is also enabled. 
The additional trace can help you relate the entity activities to the execution of 
SQL statements that OpenJPA issued to the datastore.
                </para>
                <para>
When using the built-in OpenJPA logging facilities, you can enable SQLDiag logging
by adding <literal>SQLDiag=TRACE</literal> to your <literal>openjpa.Log</literal>
property.
                </para>
            </listitem>
            <listitem>
                <para>
                <indexterm>
                    <primary>
                        schema
                    </primary>
                    <secondary>
                        log messages
                    </secondary>
                </indexterm>
<literal>openjpa.jdbc.Schema</literal>: Details about operations on the
database schema.
                </para>
            </listitem>
        </itemizedlist>
    </section>
    <section id="ref_guide_logging_openjpa">
        <title>
            OpenJPA Logging
        </title>
        <indexterm zone="ref_guide_logging_openjpa">
            <primary>
                logging
            </primary>
            <secondary>
                default
            </secondary>
        </indexterm>
        <para>
By default, OpenJPA uses a basic logging framework with the following output
format:
        </para>
        <para>
<literal>millis</literal>&nbsp;&nbsp;<literal>diagnostic context</literal>&nbsp;&nbsp;<literal>level</literal>&nbsp;&nbsp;[<literal>thread name</literal>]&nbsp;&nbsp;<literal>channel</literal> - <literal>message</literal>
        </para>
        <para>
For example, when loading an application that uses OpenJPA, a message like the
following will be sent to the <literal>openjpa.Runtime</literal> channel:
        </para>
<programlisting>
2107  INFO   [main] openjpa.Runtime - Starting OpenJPA 2.2.0
</programlisting>
        <para>
The default logging system accepts the following parameters:
        </para>
        <itemizedlist>
            <listitem>
                <para>
<literal>File</literal>: The name of the file to log to, or <literal>stdout
</literal> or <literal>stderr</literal> to send messages to standard out and
standard error, respectively. By default, OpenJPA sends log messages to standard
error.
                </para>
            </listitem>
            <listitem>
                <para>
<literal>DefaultLevel</literal>: The default logging level of unconfigured
channels. Recognized values are <literal>TRACE, INFO, WARN, ERROR </literal> 
and <literal>FATAL</literal>. Defaults to <literal>INFO</literal>.
                </para>
            </listitem>
            <listitem>
                <para>
<literal>DiagnosticContext</literal>: A string that will be prepended to all
log messages. If this is not supplied and an <literal>openjpa.Id</literal>
property value is available, that value will be used.
                </para>
            </listitem>
            <listitem>
                <para>
<literal>&lt;channel&gt;</literal>: Using the last token of the
<link linkend="ref_guide_logging_channels">logging channel</link> name, you can
configure the log level to use for that channel. See the examples below.
                </para>
            </listitem>
        </itemizedlist>
        <example id="ref_guide_logging_openjpa_std_ex">
            <title>
                Standard OpenJPA Log Configuration
            </title>
<programlisting>
&lt;property name="openjpa.Log" value="DefaultLevel=WARN, Runtime=INFO, Tool=INFO"/&gt;
</programlisting>
        </example>
        <example id="ref_guide_logging_openjpa_sql_ex">
            <title>
                Standard OpenJPA Log Configuration + All SQL Statements
            </title>
<programlisting>
&lt;property name="openjpa.Log" value="DefaultLevel=WARN, Runtime=INFO, Tool=INFO, SQL=TRACE"/&gt;
</programlisting>
        </example>
        <example id="ref_guide_logging_openjpa_file">
            <title>
                Logging to a File
            </title>
<programlisting>
&lt;property name="openjpa.Log" value="File=/tmp/org.apache.openjpa.log, DefaultLevel=WARN, Runtime=INFO, Tool=INFO"/&gt;
</programlisting>
        </example>
    </section>
    <section id="ref_guide_logging_noop">
        <title>
            Disabling Logging
        </title>
        <indexterm zone="ref_guide_logging_noop">
            <primary>
                logging
            </primary>
            <secondary>
                disabling
            </secondary>
        </indexterm>
        <para>
Disabling logging can be useful to analyze performance without any I/O overhead
or to reduce verbosity at the console. To do this, set the <literal>openjpa.Log
</literal> property to <literal>none</literal>.
        </para>
        <para>
Disabling logging permanently, however, will cause all warnings to be consumed.
We recommend using one of the more sophisticated mechanisms described in this
chapter.
        </para>
    </section>
    <section id="ref_guide_logging_log4j">
        <title>
            Log4J
        </title>
        <indexterm zone="ref_guide_logging_log4j">
            <primary>
                logging
            </primary>
            <secondary>
                Log4j
            </secondary>
        </indexterm>
        <para>
When <literal>openjpa.Log</literal> is set to <literal>log4j</literal>, OpenJPA
will delegate to Log4J for logging. In a standalone application, Log4J logging
levels are controlled by a resource named <filename>log4j.properties</filename>
, which should be available as a top-level resource (either at the top level of
a jar file, or in the root of one of the <literal>CLASSPATH</literal>
directories). When deploying to a web or EJB application server, Log4J
configuration is often performed in a <filename>log4j.xml</filename> file
instead of a properties file. For further details on configuring Log4J, please
see the <ulink url="http://logging.apache.org/log4j/1.2/manual.html">Log4J
Manual</ulink>. We present an example <filename>log4j.properties</filename> file
below.
        </para>
        <example id="ref_guide_logging_log4j_ex">
            <title>
                Standard Log4J Logging
            </title>
<programlisting>
log4j.rootCategory=WARN, console
log4j.category.openjpa.Tool=INFO
log4j.category.openjpa.Runtime=INFO
log4j.category.openjpa.Remote=WARN
log4j.category.openjpa.DataCache=WARN
log4j.category.openjpa.MetaData=WARN
log4j.category.openjpa.Enhance=WARN
log4j.category.openjpa.Query=WARN
log4j.category.openjpa.jdbc.SQL=WARN
log4j.category.openjpa.jdbc.SQLDiag=WARN
log4j.category.openjpa.jdbc.JDBC=WARN
log4j.category.openjpa.jdbc.Schema=WARN

log4j.appender.console=org.apache.log4j.ConsoleAppender
</programlisting>
        </example>
    </section>
    <section id="ref_guide_logging_commons">
        <title>
            Apache Commons Logging
        </title>
        <indexterm zone="ref_guide_logging_commons">
            <primary>
                logging
            </primary>
            <secondary>
                Apache Commons
            </secondary>
        </indexterm>
        <para>
Set the <literal>openjpa.Log</literal> property to <literal>commons</literal> to
use the <ulink url="http://commons.apache.org/logging/"> Apache
Commons Logging</ulink> thin library for issuing log messages. The
Commons Logging library act as a wrapper around a number of popular logging
APIs, including the
<ulink url="http://logging.apache.org/log4j/1.2/index.html"> Jakarta Log4J
</ulink> project, and the native
<ulink url="http://download.oracle.com/javase/6/docs/api/java/util/logging/package-summary.html">
java.util.logging</ulink> package in JDK.
        </para>
        <para>
When using the Commons Logging framework in conjunction with Log4J,
configuration will be the same as was discussed in the Log4J section above.
        </para>
        <section id="ref_guide_logging_jdk14">
            <title>
                JDK java.util.logging
            </title>
            <indexterm zone="ref_guide_logging_jdk14">
                <primary>
                    logging
                </primary>
                <secondary>
                    JDK
                </secondary>
            </indexterm>
            <para>
When using JDK logging in conjunction with OpenJPA's Commons Logging
support, logging will proceed through Java's built-in logging provided by the
<ulink url="http://download.oracle.com/javase/6/docs/api/java/util/logging/package-summary.html">
java.util.logging</ulink> package. For details on configuring the built-in
logging system, please see the
<ulink url="http://download.oracle.com/javase/6/docs/technotes/guides/logging/overview.html">
Java Logging Overview</ulink>.
            </para>
            <para>
By default, JDK's logging package looks in the <filename>
JAVA_HOME/lib/logging.properties</filename> file for logging configuration. This
can be overridden with the <literal>java.util.logging.config.file</literal>
system property. For example:
            </para>
<programlisting>
java -Djava.util.logging.config.file=mylogging.properties com.company.MyClass
</programlisting>
            <example id="ref_guide_logging_jdk14_propfile">
                <title>
                    JDK Log Properties
                </title>
<programlisting>
# specify the handlers to create in the root logger
# (all loggers are children of the root logger)
# the following creates two handlers
handlers=java.util.logging.ConsoleHandler, java.util.logging.FileHandler
    
# set the default logging level for the root logger
.level=ALL
    
# set the default logging level for new ConsoleHandler instances
java.util.logging.ConsoleHandler.level=INFO

# set the default logging level for new FileHandler instances
java.util.logging.FileHandler.level=ALL

# set the default formatter for new ConsoleHandler instances
java.util.logging.ConsoleHandler.formatter=java.util.logging.SimpleFormatter

# set the default logging level for all OpenJPA logs
openjpa.Tool.level=INFO
openjpa.Runtime.level=INFO
openjpa.Remote.level=INFO
openjpa.DataCache.level=INFO
openjpa.MetaData.level=INFO
openjpa.Enhance.level=INFO
openjpa.Query.level=INFO
openjpa.jdbc.SQL.level=INFO
openjpa.jdbc.SQLDiag.level=INFO
openjpa.jdbc.JDBC.level=INFO
openjpa.jdbc.Schema.level=INFO
</programlisting>
            </example>
        </section>
    </section>
    <section id="ref_guide_logging_slf4j">
        <title>
            SLF4J
        </title>
        <indexterm zone="ref_guide_logging_slf4j">
            <primary>
                logging
            </primary>
            <secondary>
                SLF4j
            </secondary>
        </indexterm>
        <para>
When <literal>openjpa.Log</literal> is set to <literal>slf4j</literal>, OpenJPA
will delegate to SLF4J API for logging, which provides several adapters or
a simple logging mechanism. For further details on logging adapters and
configuring SLF4J, please see the
<ulink url="http://www.slf4j.org/manual.html">SLF4J website</ulink>.
        </para>
        <para>
Note, as SLF4J does not provide a <literal>FATAL</literal> log level the
<literal>SLF4JLogFactory</literal> will map it to the <literal>ERROR</literal>
log level.
        </para>
    </section>
    <section id="ref_guide_logging_custom">
        <title>
            Custom Log
        </title>
        <indexterm zone="ref_guide_logging_custom">
            <primary>
                logging
            </primary>
            <secondary>
                custom
            </secondary>
        </indexterm>
        <para>
If none of available logging systems meet your needs, you can configure the
logging system with a custom logger. You might use custom logging to integrate
with a proprietary logging framework used by some applications servers, or for
logging to a graphical component for GUI applications.
        </para>
        <para>
A custom logging framework must include an implementation of the
<ulink url="../javadoc/org/apache/openjpa/lib/log/LogFactory.html"><classname>
org.apache.openjpa.lib.log.LogFactory</classname></ulink> interface. We present
a custom <classname>LogFactory</classname> below.
        </para>
        <example id="ref_guide_logging_custom_ex">
            <title>
                Custom Logging Class
            </title>
<programlisting>
package com.xyz;

import org.apache.openjpa.lib.log.*;

public class CustomLogFactory
    implements LogFactory {   

    private String _prefix = "CUSTOM LOG";

    public void setPrefix(String prefix) {
        _prefix = prefix;
    }
 
    public Log getLog(String channel) {
        // Return a simple extension of AbstractLog that will log
        // everything to the System.err stream. Note that this is 
        // roughly equivalent to OpenJPA's default logging behavior.
        return new AbstractLog() {

            protected boolean isEnabled(short logLevel) {
                // log all levels
                return true;
            }

            protected void log(short type, String message, Throwable t) {
                // just send everything to System.err
                System.err.println(_prefix + ": " + type + ": "
                    + message + ": " + t);
            }
        };
    }
}
</programlisting>
        </example>
        <para>
To make OpenJPA use your custom log factory, set the
<link linkend="openjpa.Log"><literal>openjpa.Log</literal></link> configuration
property to your factory's full class name. Because this property is a plugin
property (see <xref linkend="ref_guide_conf_plugins"/> ), you can also
pass parameters to your factory. For example, to use the example factory above
and set its prefix to "LOG MSG", you would set the <literal>openjpa.Log
</literal> property to the following string:
        </para>
<programlisting>
com.xyz.CustomLogFactory(Prefix="LOG MSG")
</programlisting>
    </section>
    
    
<section id="ref_guide_audit">
   <title>OpenJPA Audit</title>
    Transactional applications often require to audit changes in persistent objects.
    OpenJPA can enable audit facility for all persistent entities in few simple steps.
    <section>
    <title>Configuration</title>
    <para><emphasis>Annotate Persistent Entity</emphasis>
    Any persistence entity can be enabled for audit by annotating with 
    <literal>org.apache.openjpa.audit.Auditable</literal>.
    </para>
    <programlisting>
      @javax.persistence.Entity
      @org.apache.openjpa.audit.Auditable
      public class MyDomainObject { ...}
    </programlisting>
    <para>
    This <literal>Auditable</literal> annotation enables auditing of creation, update or delete of 
    <literal>MyDomainObject</literal> instances. The <literal>Auditable</literal> annotation accepts  
    list of enumerated values <literal>org.apache.openjpa.audit.AuditableOperation</literal> namely
    <literal>CREATE</literal>, <literal>UPDATE</literal> and <literal>DELETE</literal> to customize
    only appropriate operations be audited. By deafult, all of the above operations are audited.
    </para>
    <para><emphasis>Configure Persistence Configuration</emphasis>
    The audit facility is invoked at runtime via configuration of <literal>META-INF/persistence.xml</literal>.
    The following property configures auditing via a default auditor
    </para>
    <programlisting>&lt;property name="openjpa.Auditor" value="default"/&gt;</programlisting>
    <para>
    The default auditor does not do much. It simply prints each auditable instance with its latest and original
    states on a standard console (or to a designated file).
    </para>
    <para>The <emphasis>latest</emphasis> state of an instance designates the state which is commited to the
    database.
    The <emphasis>original</emphasis>state designates the state when the instance entered the managed persistent
    context. For example, when a new instance is persisted or a existing instance is loaded from the database.
    </para>
    </section>  
    <section>
    <title>Developing custom auditing</title>
          
    <para>
    For real use case, an application will prefer more than printing the changed instances. The application, in
    such case, needs to implement <literal>org.apache.openjpa.audit.Auditor</literal> interface.
    This simple interface has the following method:
    </para>
    <programlisting>
    /**
	 * OpenJPA runtime will invoke this method with the given parameters
	 * within a transaction.
	 * 
	 * @param broker the active persistence context.
	 * @param newObjects the set of auditable objects being created. Can be empty, but never null.
	 * @param updates the set of auditable objects being updated. Can be empty, but never null.
	 * @param deletes the set of auditable objects being deleted. Can be empty, but never null.
	 */
	public void audit(Broker broker, Collection&lt;Audited> newObjects, Collection&lt;Audited> updates,
			Collection&lt;Audited> deletes);
    </programlisting> 
    <para>
    OpenJPA runtime will invoke this method <emphasis>before</emphasis> database commit. Via this callback method,
    the application receives 
    the auditable instances in three separate collections of <literal>org.apache.openjpa.audit.Auditable</literal>.
    An <literal>Auditable</literal> instance provides the latest and original state of a persistent object. 
    The latest object is
    the same persistent instance to be committed. The original instance is a transient instance holding the 
    original state of the instance when it entered the managed context. The active persistence context
    is also supplied in this callback method, so that an application may decide to persist the audit log
    in the same database. 
    </para>
    <para>
    It is important to note that the original object can not be persisted in the same transaction, because
    it has the same persistent identity of the latest object.
    </para>
    <para>
    A single instance of implemented <literal>org.apache.openjpa.audit.Auditor</literal> interface
    is available for a persistence unit. However, an application's own implementation of this interface
    need not be thread-safe, because OpenJPA runtime guards against concurrent invocation of the
    callback method. 
    </para>
    <para>
    The <literal>org.apache.openjpa.audit.Auditor</literal> interface is configurable. Hence any bean style
    getter and setter method on its implementation will be populated as usual for any other OpenJPA plugin.
    In the following example,
    </para>
    <programlisting>
    &lt;property name="openjpa.Auditor" value="com.acme.Auditor(param2=10,param2='hello')"/&gt;
    </programlisting>
    <para>
    An instance of <literal>com.acme.Auditor</literal> will be instantiated and if it has been style getter and
    setter methods for <literal>param1</literal> and <literal>param2</literal>, then the respective setters 
    will be called with <literal>10</literal> and <literal>"hello"</literal> before the instance being used.
    </para>
    </section>
	
</section>    
</chapter>
