Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## oracle.ifs.common
Class TraceLogger

    java.lang.Object

      |

      +--oracle.ifs.common.TraceLogger

public abstract class TraceLogger
extends java.lang.Object

TraceLogger is the abstract tracing superclass.

Tracing writes time-stamped status information, called traces, to disk files. These trace logs are useful in tracking down unusual application behavior.

The tracing function is carried out by TraceLogger and its subclasses. Each LibrarySession, S_LibrarySession, and S_LibraryService object instantiates a TraceLogger. Obtain a reference to this TraceLogger by invoking the `getTraceLogger` method of these classes.

The TraceLogger controls where the trace logs are created, the type of information they contain, and the detail of this information.

Use `setTraceType` to control where the trace logs are created. A TraceLogger can create local trace logs, remote trace logs, both, or neither.

Local trace logs are created on the file system of the computer on which the TraceLogger is running. For a LibrarySession's trace logger, this is the client-tier computer on which LibrarySession runs. For a S_LibrarySession or S_LibraryService trace logger, this is the middle-tier application server hosting the session and service. Use `setLocalStream` to set the stream to which the local trace log is written.

Remote trace logs allow aggregation of trace information from multiple sessions. For a LibrarySession's trace logger, remote tracing sends the traces to the trace logger of the corresponding S_LibrarySession. For a S_LibrarySession's trace logger, remote tracing sends the traces to the trace logger of the corresponding S_LibraryService. For a S_LibraryService's trace logger, remote tracing sends the traces to a single, realm-wide, trace logger which aggregates the traces from all services into a single trace log.

To issue a trace request, invoke `trace` on a LibraryObject, LibrarySession, S_LibraryObject, S_LibrarySession, or S_LibraryService. This method takes a channel number, trace level, and payload message as arguments. The channel describes the type of operation that led to the trace, such as event processing or transaction management. The level specifies how detailed is the information contained in the trace. Level 10 is very detailed information; level 1 is high-level information.

TraceLogger provides methods to allow the desired trace level to be specified on a channel-by-channel basis. Increasing channels' trace levels increases the amount of information written to the trace log. A TraceLogger writes a trace request to the trace log only if the request's trace level is less than or equal to the trace level of the channel. Setting a channel's trace level to `DISABLED` (level 0) disables all tracing for that channel.

iFS reserves channels numbered 0 to `LAST_RESERVED_CHANNEL` for internal use. An application may create and use additional channels.

The trace log contains one trace per line. Each trace consists of the following tab-delimited fields:

- DT: the date and time
- CH: the channel number
- LV: the trace level
- SV: the service id of the traced object
- SS: the session id of the traced object
- ID: the id of the traced object
- CN: the classname of the traced object
- MS: the payload message

Sometimes it may be computationally expensive for your application to prepare the string containing the payload message. To minimize performance degradation, use the TraceLogger `isTraced` method (or the LibraryObject, LibrarySession, S_LibraryObject, S_LibrarySession, or S_LibraryService convenience method of the same name) as follows:

     // Only invoke myExpensiveMethod() if necessary.
     if (session.isTraced(TraceLogger.CHANNEL_GENERAL, 2))
     {
         String payloadMessage = myExpensiveMethod();
         session.trace(TraceLogger.CHANNEL_GENERAL, 2, payloadMessage);
     }

Other tips to maximize trace performance are:

- only trace the channels of interest
- don't set channels' trace levels unnecessarily high
- use local trace logs rather than remote trace logs where possible
- if you turn on tracing to troubleshoot a problem, turn it off when you're finished

At the start of a session, the trace level for each channel of both the LibrarySession trace logger and S_LibrarySession trace logger is set to the trace level of the corresponding channel of the S_LibraryService trace logger. Use the `getLevels`, `setLevels`, `LibrarySession.getSessionTraceLoggerLevels` and `LibrarySession.setSessionTraceLoggerLevels` methods to subsequently synchronize the trace levels of the LibrarySession and S_LibrarySession trace loggers. The `LibrarySession.getServiceTraceLoggerLevels` and `LibrarySession.setServiceServiceTraceLoggerLevels` can be similarly used to synchronize the S_LibraryService trace logger.

Field Summary
`static int` | `CHANNEL_AUDIT` The Audit channel.
`static int` | `CHANNEL_CACHING` The Caching channel.
`static int` | `CHANNEL_CONNECTION_POOL` The Connection Pool channel.
`static int` | `CHANNEL_DIRECTORY_SERVICES` The Directory Services channel.
`static int` | `CHANNEL_EVENT` The Event channel.
`static int` | `CHANNEL_EXCEPTION` The Exception Management channel.
`static int` | `CHANNEL_GENERAL` The general-purpose trace channel.
`static int` | `CHANNEL_MAIL_SERVER` Mail server channel.
`static int` | `CHANNEL_METHOD_INVOCATION` The Method Invocation channel.
`static int` | `CHANNEL_OAS` The CORBA channel.
`static int` | `HIGHEST_VALID_LEVEL` The highest valid level.
`static int` | `LAST_RESERVED_CHANNEL` The last channel reserved for internal iFS use.
`static int` | `LEVEL_DISABLED` The value of level which represents disabling tracing.
`static int` | `TRACETYPE_BOTH` Trace logs are sent to both a local stream and a remote TraceLogger.
`static int` | `TRACETYPE_LOCAL` Trace logs are sent to a local stream.
`static int` | `TRACETYPE_NONE` Tracing is disabled.
`static int` | `TRACETYPE_REMOTE` Trace logs are sent to to a remote TraceLogger.

Method Summary
`void` | `flush()` Flushes the stream to which the local trace log is written.
`int` | `getChannelCount()` Gets the number of channels.
`int` | `getLevel(int channel)` Gets the level of the specified channel.
`int[]` | `getLevels()` Gets the levels of all channels.
`Localizer` | `getLocalizer()` Gets the Localizer of this TraceLogger.
`int` | `getTraceType()` Gets the trace type.
`boolean` | `isAutoFlushed()` Gets whether the stream to which the local trace log is written is automatically flushed each time a trace is written to it.
`boolean` | `isTraced(int channel, int level)` Gets whether tracing is enabled for the specified channel and level.
`void` | `setAutoFlushed(boolean autoFlushed)` Sets whether the stream to which the local trace log is written is automatically flushed each time a trace is written to it.
`void` | `setLevel(int channel, int level)` Sets the level of the specified channel.
`void` | `setLevels(int level)` Sets the level of each channel.
`void` | `setLevels(int[] levels)` Sets the levels of all channels.
`void` | `setLocalStream(java.io.File file)` Sets the stream to which the local trace log is written.
`void` | `setLocalStream(java.io.PrintWriter writer)` Sets the stream to which the local trace log is written.
`void` | `setTraceType(int traceType)` Sets the trace type.

Field Detail

### TRACETYPE_NONE

    public static final int TRACETYPE_NONE

  Tracing is disabled.

### TRACETYPE_LOCAL

    public static final int TRACETYPE_LOCAL

  Trace logs are sent to a local stream.

### TRACETYPE_REMOTE

    public static final int TRACETYPE_REMOTE

  Trace logs are sent to to a remote TraceLogger.

### TRACETYPE_BOTH

    public static final int TRACETYPE_BOTH

  Trace logs are sent to both a local stream and a remote TraceLogger.

### CHANNEL_GENERAL

    public static final int CHANNEL_GENERAL

  The general-purpose trace channel.

### CHANNEL_METHOD_INVOCATION

    public static final int CHANNEL_METHOD_INVOCATION

  The Method Invocation channel.

### CHANNEL_OAS

    public static final int CHANNEL_OAS

  The CORBA channel.

  This channel is used for tracing the CORBA infrastructure.

### CHANNEL_DIRECTORY_SERVICES

    public static final int CHANNEL_DIRECTORY_SERVICES

  The Directory Services channel.

  This channel is used for tracing the Directory Services infrastructure.

### CHANNEL_CONNECTION_POOL

    public static final int CHANNEL_CONNECTION_POOL

  The Connection Pool channel.

  This channel is used for tracing the connection pool, cursor pool, and transaction management infrastructure.

### CHANNEL_EXCEPTION

    public static final int CHANNEL_EXCEPTION

  The Exception Management channel.

### CHANNEL_EVENT

    public static final int CHANNEL_EVENT

  The Event channel.

### CHANNEL_AUDIT

    public static final int CHANNEL_AUDIT

  The Audit channel.

### CHANNEL_CACHING

    public static final int CHANNEL_CACHING

  The Caching channel.

### CHANNEL_MAIL_SERVER

    public static final int CHANNEL_MAIL_SERVER

  Mail server channel.

### LAST_RESERVED_CHANNEL

    public static final int LAST_RESERVED_CHANNEL

  The last channel reserved for internal iFS use.

### LEVEL_DISABLED

    public static final int LEVEL_DISABLED

  The value of level which represents disabling tracing.

### HIGHEST_VALID_LEVEL

    public static final int HIGHEST_VALID_LEVEL

  The highest valid level.

Method Detail

### getLocalizer

    public final Localizer getLocalizer()
                                 throws IfsException

  Gets the Localizer of this TraceLogger.
  Returns:
    the Localizer
  Throws:
    `IfsException` - if the operation fails

### getChannelCount

    public final int getChannelCount()
                              throws IfsException

  Gets the number of channels.
  Returns:
    the number of channels. Since channels are numbered starting at 0, the channel number of the highest channel is one less than this value.
  Throws:
    `IfsException` - if the operation fails

### setLevel

    public final void setLevel(int channel,
                               int level)
                        throws IfsException

  Sets the level of the specified channel.
  Parameters:
    `channel` - the channel number
    `level` - the level
  Throws:
    `IfsException` - (IFS-11201) if the channel is invalid
    `IfsException` - (IFS-11200) if the level is invalid

### setLevels

    public final void setLevels(int level)
                         throws IfsException

  Sets the level of each channel.
  Parameters:
    `level` - the level
  Throws:
    `IfsException` - (IFS-11200) if the level is invalid

### setLevels

    public final void setLevels(int[] levels)
                         throws IfsException

  Sets the levels of all channels.
  Parameters:
    `levels` - an array of levels. The array index corresponds to the channel number.
  Throws:
    `IfsException` - (IFS-11204) if the size of the array does not equal the number of channels
    `IfsException` - (IFS-11200) if a level is invalid

### getLevel

    public final int getLevel(int channel)
                       throws IfsException

  Gets the level of the specified channel.
  Parameters:
    `channel` - the channel number
  Returns:
    the level
  Throws:
    `IfsException` - (IFS-11201) if the channel is invalid

### getLevels

    public final int[] getLevels()
                          throws IfsException

  Gets the levels of all channels.
  Returns:
    an array of levels. The array index corresponds to the channel number.
  Throws:
    `IfsException` - if the operation fails

### setTraceType

    public final void setTraceType(int traceType)
                            throws IfsException

  Sets the trace type.
  Parameters:
    `traceType` - the desired trace type. Must be `TRACETYPE_NONE`, `TRACETYPE_LOCAL`, `TRACETYPE_REMOTE`, `TRACETYPE_BOTH`.
  Throws:
    `IfsException` - (IFS-11202) if the trace type is invalid

### getTraceType

    public final int getTraceType()
                           throws IfsException

  Gets the trace type.
  Returns:
    the trace type value
  Throws:
    `IfsException` - if the operation fails

### setLocalStream

    public final void setLocalStream(java.io.PrintWriter writer)
                              throws IfsException

  Sets the stream to which the local trace log is written.
  Parameters:
    `writer` - the PrintWriter to which the local trace log is written. If null, the local trace log is written to the standard error stream.
  Throws:
    `IfsException` - if the operation fails

### setLocalStream

    public final void setLocalStream(java.io.File file)
                              throws IfsException

  Sets the stream to which the local trace log is written.

  If the file does not exist, it will be created when the first trace is written to the local stream. If this file already exists, its existing contents will be overwritten.

  Parameters:
    `file` - the file to which the local trace log is written. If null, the local trace log is written to the standard error stream.
  Throws:
    `IfsException` - if the operation fails

### setAutoFlushed

    public final void setAutoFlushed(boolean autoFlushed)
                              throws IfsException

  Sets whether the stream to which the local trace log is written is automatically flushed each time a trace is written to it.

  If false, `flush` should be invoked before examining the local trace log to ensure its completeness.

  Parameters:
    `autoFlushed` - whether the stream is automatically flushed
  Throws:
    `IfsException` - if the operation fails

### isAutoFlushed

    public final boolean isAutoFlushed()
                                throws IfsException

  Gets whether the stream to which the local trace log is written is automatically flushed each time a trace is written to it.
  Returns:
    whether the stream is automatically flushed
  Throws:
    `IfsException` - if the operation fails

### flush

    public final void flush()
                     throws IfsException

  Flushes the stream to which the local trace log is written.
  Throws:
    `IfsException` - (IFS-11206) if the operation fails

### isTraced

    public final boolean isTraced(int channel,
                                  int level)
                           throws IfsException

  Gets whether tracing is enabled for the specified channel and level.
  Parameters:
    `channel` - the channel number
    `level` - the level
  Returns:
    whether tracing is enabled
  Throws:
    `IfsException` - (IFS-11201) if the channel is invalid

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD