Configuring Logging

Use the TopLink logging framework to record TopLink behavior to a log file or session console.

Table 77-6 summarizes which sessions support logging configuration.

Table 77-6 Session Support for Logging

Session	Using TopLink Workbench	Using Java
Server and Client Sessions
Unit of Work Sessions
Session Broker and Client Sessions
Database Sessions

Note: If the session belongs to a session broker, you must specify the logging information in the session broker–not in the session itself.

For a non-CMP application, you can configure logging using TopLink Workbench (see "Using TopLink Workbench"). For a CMP application, see "Configuring Logging in a CMP Application".

For more information, see "Logging".

Using TopLink Workbench

To specify the logging information for a session, use this procedure:

1. Select a database session in the Navigator. Its properties appear in the Editor.

2. Click the Logging tab. The Logging tab appears.

   Figure 77-3 Logging Tab

   
   

Use the following information to enter data in each field of the Logging tab to select the profiler option to use with this session:

Option	Description
No Logging	Select this option to specify that nothing is logged for this session.
Server	Select this option to use logging capabilities of the application server to which you are deploying this application.
Java	Select this option to use java.util.logging package.
Standard	Select this option to use the TopLink logging framework. When selected, you can optionally configure the following options.
Logging Level	Define the amount of logging information to record (in ascending order of information): Config–Log only login, JDBC connection, and database information. Info (default)–Log the login/logout per sever session, with user name. After acquiring the session, detailed information is logged. Warning–Log exceptions that do not force TopLink to stop, including all exceptions not logged with Severe level. This does not include a stack trace. Severe –Log exceptions indicating TopLink cannot continue, and any exceptions generated during login. This includes a stack trace. Fine–Log SQL (including thread information). Finer–Similar to warning. Includes stack trace. Finest–Includes additional low-level information. All–Log everything.
Console	Select this option to display logging information to the standard console output.
File	Select this option to record logging information in a file. Click Browse to specify the name and location of the log file.
Options	Select this option to override additional logging option defaults for Java and Standard logging only.
Log Exception Stack Trace	Select this option to include the stack trace with any exception written to the log. Default: For SEVERE messages, log stack trace. For WARNING messages, only log stack trace at log level FINER or lower.
Print Connection	Select this option to include the connection identifier in any connection related log messages. Default: Enabled for all message and log levels.
Print Date	Select this option to include the date and time at which the log message was generated. Default: Enabled for all message and log levels.
Print Session	Select this option to include the session name in any session related log messages. Default: Enabled for all message and log levels.
Print Thread	Select this option to include the thread name in any thread related log messages. Default: Log only at log level FINER or lower.

Using Java

This section describes the following:

• Using Session Logging API

• Configuring a Session to use java.util.logging Package

• Configuring Logging in a CMP Application

Using Session Logging API

If you use TopLink native logging (the default), then at run time, you can configure logging options using oracle.toplink.sessions.Session logging API.

The Session interface defines the following logging methods:

• setSessionLog–specify the type of logging to use (any implementor of oracle.toplink.logging.SessionLog)

• dontLogMessages–disable logging

• setLog–specify the java.io.Writer to which the session logs messages

• setLogLevel– specify the level at which the session logs using oracle.toplink.logging.SessionLog constants:

  • OFF

  • SEVERE

  • WARNING

  • INFO

  • CONFIG

  • FINE

  • FINER

  • FINEST

  • ALL

Example 77-1 illustrates how to configure a session to use java.util.logging package.

Example 77-1 Configuring a Session to Use java.util.logging

session.setSessionLog(new JavaLog());

Example 77-2 illustrates how to configure a session to use the server log that OC4J provides. For more information about server logging, see "Server Logging".

Example 77-2 Configuring a Session to Use Application Server Logging

session.setSessionLog(new OjdlLog());

Example 77-3 illustrates how to configure a session to log to a java.io.Writer:

Example 77-3 Configuring a Session to Log to a java.io.Writer

session.setLog(myWriter);

Configuring a Session to use java.util.logging Package

If you use java.util.logging package, then you configure logging options in the <JRE_HOME>/lib/logging.properties file. Messages are written to zero or multiple destinations based on this configuration file.

If you configure a session to use java.util.logging package, consider the following:

• logging.properties

• Formatters

• Namespace

logging.properties

Configure the logging.properties file as Example 77-4 illustrates:

Example 77-4 java.util.logging Configuration in logging.properties

handlers = java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.level = CONFIG
java.util.logging.ConsoleHandler.formatter = oracle.toplink.logging.TopLinkSimpleFormatter
oracle.toplink.LoggingSession.connection.level = CONFIG

For information about the types of formatters available, see "Formatters".

Formatters

TopLink provides two formatters: TopLinkSimpleFormatter and TopLinkXMLFormatter. They override the corresponding java.util.logging formatters and always log session and connection info when available. They also log thread and exception stack trace information at certain levels as specified by the logging level.

Namespace

Namespace is supported for java.util.logging. Table 77-7 lists the static constants defined in oracle.toplink.logging.SessionLog for TopLink components and the corresponding strings in logging.properties.

Table 77-7 Logging Property FIle Names

SessionLog	logging.properites
Not Applicable	oracle.toplink
Not Applicable	oracle.toplink.<sessionname>
SQL	oracle.toplink.<sessionname>.sql
TRANSACTION	oracle.toplink.<sessionname>.transaction
EVENT	oracle.toplink.<sessionname>.event
CONNECTION	oracle.toplink.<sessionname>.connection
QUERY	oracle.toplink.<sessionname>.query
CACHE	oracle.toplink.<sessionname>.cache
PROPAGATION	oracle.toplink.<sessionname>.propagation
SEQUENCING	oracle.toplink.<sessionname>.sequencing
EJB	oracle.toplink.<sessionname>.ejb

In the logging.properties names listed in Table 77-7, note that <sessionname> is the name of the session that the application is running in. For example, if the name of the session is MyApplication, then you would use oracle.toplink.MyApplication.sql for the SQL logging property.

An application can also define its own namespace and write to it through the logging API, as long as the logger for that namespace is defined in the logging configuration. Otherwise messages are written to the parent logger, oracle.toplink.<sessionname>.

Configuring Logging in a CMP Application

For a CMP project, you do not configure a session directly. In this case, you specify the type of logging by configuring system property toplink.log.destination with one of the following values:

• fully qualified file specification (for example, C:\logs\toplink.log)–use TopLink native logging to write log messages to the specified file.

• JAVA–use java.util.logging package to write log messages to any destination you configure in the <JRE_HOME>/lib/logging.properties file.

• SERVER–use server logging to write log messages to the application server's log file (there is no separate TopLink log file in this case).

• SYSOUT–write log messages to System.out.

To configure other logging options, use a customization-class (see "Configuring pm-properties").