<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd">
%CustomDTD;
]>
<chapter id="logging">
	<title>Logging</title>
	<section id="custom_logging">
		<title>Customized Logging</title>
		<para>
		The Teiid system provides a wealth of information using logging. To control logging level, 
        contexts, and log locations, you should be familiar with container's 
        <filename>standalone.xml</filename> or <filename>domain.xml</filename> configuration fileand check out
        "logging" subsystem. Refer to the Administrator Guide for more details about 
        different Teiid contexts available.  Refer to <ulink url="http://logging.apache.org/log4j/"/> 
        for more information about log4j.
		</para>
		
		<para>If you want a custom appender, follow the Log4J directions to write a custom appender. Refer to 
		the instructions at <ulink url="http://logging.apache.org/log4net/release/faq.html"/>. If you develop a custom 
            logging solution, the implementation jar should be placed as a jar in "org.jboss.teiid" module and 
            define its name in the module.xml file as part of the module.
    	</para>
        
        <section>
            <title>Command Logging API</title>
            <para>
                If you want to build a custom appender for command logging that will have access to 
                log4j "LoggingEvents" to the "COMMAND_LOG" context, the appender will receive a message that is an instance of
                <code>org.teiid.logging.CommandLogMessage</code>.  The relevant Teiid classes are defined in the <code>teiid-api-&versionNumber;.jar</code>. 
                The CommmdLogMessage includes information about vdb, session, command sql, etc.  CommandLogMessages are logged at the DEBUG level.  If the COMMAND_LOG is at the TRACE level,
                then CommandLogMessages will also contain the query plan for user queries after the NEW event.  A typical event sequence is user query NEW, optional user query PLAN, some number of source query NEW/END, then the user query END.
                CANCEL and ERROR events are also captured.
            </para>
            <example>
				<title>Sample CommandLogMessage Usage</title>
				<programlisting language="Java" role="JAVA"><![CDATA[package org.something;
import org.apache.log4j.AppenderSkeleton;
import org.apache.log4j.spi.LoggingEvent;
import org.teiid.logging.*;

public class CustomAppender extends AppenderSkeleton 
{
  
  protected void append(LoggingEvent event) {
    if (event.getMessage() instanceof CommandLogMessage) {
      CommandLogMessage clMessage = (CommandLogMessage)event.getMessage();
      String sql = clMessage.getSql();
      ...
      //log to a database, trigger an email, etc.
    }
    ...
  }
  
  ...
  
}]]></programlisting>
			</example>
        </section>
        
        <section id="audit_logging">
            <title>Audit Logging API</title>
            <para>If you want to build a custom appender for command logging that will have access to 
                log4j "LoggingEvents" to the "org.teiid.AUDIT_LOG" context, the appender will receive a message that is an instance of
                <code>org.teiid.logging.AuditMessage</code>.  The relevant Teiid classes are defined in the <code>teiid-api-&versionNumber;.jar</code>. The <code>AuditMessage</code> includes information about user, the action, and the
                target(s) of the action.  AuditMessages are logged at the DEBUG level.
            </para>                            
            <example>
				<title>Sample AuditMessage Usage</title>
				<programlisting language="Java" role="JAVA"><![CDATA[package org.something;
import org.apache.log4j.AppenderSkeleton;
import org.apache.log4j.spi.LoggingEvent;
import org.teiid.logging.*;

public class CustomAppender extends AppenderSkeleton 
{
  
  protected void append(LoggingEvent event) {
    if (event.getMessage() instanceof AuditMessage) {
      AuditMessage auditMessage = (AuditMessage)event.getMessage();
      String activity = auditMessage.getActivity();
      ...
      //log to a database, trigger an email, etc.
    }
    ...
  }
  
  ...
  
}]]></programlisting>
			</example>
        </section>
	</section>
</chapter>