Skip Headers

Oracle TopLink Developer's Guide 10g Release 3 (10.1.3) B13593-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 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").