5 Managing Log Files

5.1.1 Viewing Log Files

You can view the log files for a specific component with Application Server Control Console:

1. Select a system component link on the Application Server Control Console Home page, then select the Logs link. The Log Files page is displayed.

2. You can choose to view application logs, diagnostic logs, management system logs, or Web services log, or all types of logs by selecting a option from the View menu.

3. In the table, expand items until you see a list of log files for the component. For example, expand Components, expand Enterprise Manager, and Application Server Control. The log files are listed in the table, as shown in Figure 5-1.

   Figure 5-1 Enterprise Manager Log Files Page

   
   Description of "Figure 5-1 Enterprise Manager Log Files Page"
   
   

4. For any particular log file, click View. The log file text is displayed.

5.1.2 Listing Log Files for Components

You can list the log files for individual components, some components, or all components by using the Application Server Control Console. To list the log files, perform the following steps:

1. Select a system component link on the Application Server Control Console Home page, then select the Logs link. The Log Files page is displayed.

2. You can choose to view application logs, diagnostic logs, management system logs, or Web services log, or all types of logs by selecting them from the View menu.

3. To view all components, select Components in the table. To view some components, expand the Components item, then expand items under Components until you reach the level you want. Then, select those components.

4. Click Search to list the log files for the selected components.

5. On the Search Logs page, which is displayed when the search returns, click Show Selected Log Files. The Search Logs page shows the names of the log files.

5.1.3 Searching Log Files and Viewing Messages

You can filter the search for log files by certain log file attributes by using the Search Logs page of the Application Server Control Console.

Take the following steps:

1. Select a system component link on the Application Server Control Console Home page, then select the Logs link. The Log Files page is displayed.

2. Select the type of log files by selecting it in the View menu.

3. To view the log files of specific components, select them in the table.

4. Click Search. The Search Logs page is displayed.

5. Specify the Search criteria, such as Date Range or Message Type.

6. Click Advanced Search Options to display the Filter by Log Message Fields table.

7. Select a field from the Log Message Field list.

8. Click Add Row to add a row for the selected log message field.

9. Enter the desired search value in the Value field.

10. To indicate this is a regular expression, click Regular Expression. (See Section 5.1.4 for information about regular expressions.)

11. If you want to select additional fields with values, click Add Another Row and enter additional values.

12. Click Search to perform the search. When the search returns, the Results section shows log files with matching fields, as shown in Figure 5-2.

    Figure 5-2 Log Search Results Section

    
    Description of "Figure 5-2 Log Search Results Section"
    
    

13. To view a log entry, click Show in the Details column of the Results area on the Search Logs page.

    The details of the error message are displayed. This information includes the Component Name and ID, Message Level, Module ID, Message Type, Message Text, and optionally the Execution Context ID (ECID).

5.1.4 Using Regular Expressions with Search

Regular expression matching is applied when you select the check box in the Regular Expression field on the Search Logs page. You can specify a regular expression for the Message Text field and for the Filter by Log Message Fields table. Using a regular expression in a search enables you to enter a pattern description to match strings for a search.

The search uses the Apache Jakarta regular expression engine, which uses "*" for a string of characters, "?" for a single character, and supports boundary matches, including "^" for a match only at the beginning of an entry, and "$" for a match only at the end of an entry, and special characters, including "\t" for Tab, "\n" for newline, "\r" for return, and "\f" for form feed.

5.2.1 Understanding Log File Formats and Naming

Log files of Oracle Application Server components use either text-base formatting or Oracle Diagnostic Logging (ODL).

Using ODL, log file naming and the format of the contents of log files conforms to an Oracle standard and the diagnostic messages are written in XML. Some Oracle Application Server components do not use ODL, and write their diagnostic messages using a component-specific text format. Other components support ODL, but do not enable ODL by default.

Regardless of the format, ODL or text based, of the messages that are stored in log files, you can view log files using the Application Server Control Console, or you can download log files to your local client and view them using another tool (for example a text editor, or another file viewing utility).

This section covers the following topics:

• ODL Message Formatting and ODL Log File Naming

• Log File Message Formats by Component

  
  

  Note: Some Oracle Application Server components do not support ODL. Other components support ODL, but do not enable ODL by default.

  
  

5.2.2 Configuring Component Logging Options

Administrators can configure logging options to manage and limit the logging information that Oracle Application Server components generate and save.

For example, to configure logging options for OC4J components using Java logging, you modify the j2ee-logging.xml file, which is installed in the ORACLE_HOME/j2ee/home/config directory. See the chapter, "Logging in OC4J" in the Oracle Containers for J2EE Configuration and Administration Guide for more information.

The logging configuration options for components include:

• Specifying log file names and pathnames: Most Oracle Application Server components let you specify the directory for storing diagnostic log files. Specifying the diagnostic logging directory allows administrators to manage system and network resources.

• Limiting log file size: As Oracle Application Server components run and generate diagnostic messages, the size of the log files increases. Oracle Application Server components use one of several strategies to deal with log file size. Some components allow log files to keep increasing in size; in this case, it is the administrator's responsibility to monitor and clean up the log files. Other components, including OC4J, let you specify configuration options that limit how much log file data is collected and saved.

• Using log file archiving: Certain Oracle Application Server components let you specify configuration options to control the size of diagnostic logging directories. This lets you determine a maximum size for the directories containing a component's log files. When the maximum size is reached, older logging information is deleted before newer logging information is saved.

• Setting component logging levels: Certain Oracle Application Server components, including Oracle HTTP Server, allow administrators to configure logging levels. By configuring logging levels, the number of messages saved to diagnostic log files can be reduced. For example, you can set the logging level so that the system only reports and saves critical messages.

5.3.1 Correlating Messages Across Log Files and Components

Certain Oracle Application Server components provide message correlation information for diagnostic messages. Message correlation information helps those viewing diagnostic messages determine relationships between messages across components. The Execution Context ID (ECID) is a globally unique identifier associated with a thread of execution. The ECID helps you to use log file entries to correlate messages from one application or across application server components. By searching related messages using the message correlation information, multiple messages can be examined and the component that first generates a problem can be identified (this technique is called first-fault component isolation). Message correlation data can help establish a clear path for a diagnostic message across components, within which errors and related behavior can be understood.

When you view an entry on the Log Message Details page in the Application Server Control Console, if the ECID field is available, it displays the Execution Context ID as a link. Selecting the Execution Context ID link shows you all the diagnostic messages in the Log Repository with the same ECID.

You can use the ECID to track requests as they move through Oracle Application Server.

The ECID takes the following format:

request_id, sequence_number

• The request_id is a unique string that is associated with each request.

• The sequence_number represents the hop number of the request, as it passes through Oracle Application Server (or through the component).

  For example, Oracle HTTP Server assigns an initial sequence number of 0 to a request. After that, the sequence number is incremented as the request moves through Oracle Application Server components.

Table 5-2 lists the Oracle Application Server components that provide message correlation information (using an ECID), and specifies if a component supports message correlation, but it is not enabled by default.

5.3.2 Diagnosing Component Problems

When an Oracle Application Server component has a problem, you can isolate and determine the cause of the problem by viewing the diagnostic messages. The following general techniques can assist you in accomplishing this task:

• Search for errors or warnings related to the problem

• Correlate the errors across components

• Correlate the errors across a time interval

• Perform component-based analysis

5.4.1 Understanding ODL Messages and ODL Log Files

This section covers the following topics:

• ODL Message Contents

• ODL Log File Rotation and Naming

<MESSAGE>
  <HEADER>
    <TSTZ_ORIGINATING>2006-05-05T08:13:33.138-07:00</TSTZ_ORIGINATING>
    <COMPONENT_ID>tip</COMPONENT_ID>
    <MSG_TYPE TYPE="ERROR"></MSG_TYPE>
    <MSG_LEVEL>1</MSG_LEVEL>
    <HOST_ID>sta.oracle.com</HOST_ID>
    <HOST_NWADDR>140.87.7.135</HOST_NWADDR>
    <MODULE_ID>esb.server.dispatch.agent</MODULE_ID>
    <THREAD_ID>64</THREAD_ID>
    <USER_ID>oracle1</USER_ID>
  </HEADER>
  <CORRELATION_DATA>
    <EXEC_CONTEXT_ID><UNIQUE_ID>140.87.7.135:59844:1146765043873:54</UNIQUE_ID><SEQ>0</SEQ></EXEC_CONTEXT_ID>
  </CORRELATION_DATA>
  <PAYLOAD>
    <MSG_TEXT></MSG_TEXT>
  </PAYLOAD>
</MESSAGE>

File                        Size

log.xml                     10002
log9872.xml                 15000
log9873.xml                 15000
log9874.xml                 15000
log9875.xml                 15000
log9876.xml                 15000

<log>
<odl path="../log/petstore/" max-file-size="1000" max-directory-size="10000" />
</log>

ORACLE_HOME/j2ee/instance_name/config/j2ee-logging.xml

<log_handler name="h1" class="oracle.core.ojdl.logging.ODLHandlerFactory">
     <property name="path" value="log"/>
     <property name="baseRotationTime" value="04:00"/>
     <property name="rotationFrequency" value="daily"/>
     <property name="maxFileSize" value=" 2000000"/> 
</log_handler>

5.4.2 Component Diagnostic Log File Registration

The Application Server Control Console reads Oracle Application Server component diagnostic registration files to determine names, locations, and additional configuration information about diagnostic log files. The following directory contains the diagnostic log file registration files:

ORACLE_HOME/j2ee/instance/applications/ascontrol/ascontrol/WEB-INF/config/registration

Oracle Application Server components may have multiple registration files in the configuration registration directory.

The format for the registration files includes an Oracle Application Server component ID, and the extension .xml. Table 5-4 lists the Oracle Application Server components and their associated IDs.

5.4.3 Configuring Components to Produce ODL Messages

This section covers the following topics:

• Configuring Oracle HTTP Server to Produce ODL Messages

• Configuring OC4J to Produce ODL Messages

Table 5-5 lists the Oracle Application Server components that support ODL messages but that generate text messages by default. By making configuration changes, you can configure these components to produce ODL messages. (Table 5-1 lists the Oracle Application Server components that produce ODL messages.)

ORACLE_HOME/Apache/Apache/logs

ORACLE_HOME/j2ee/application-deployments/application_name/application.log

ORACLE_HOME/j2ee/instance_name/log/instance_group_process/oc4j/log.xml

ORACLE_HOME/j2ee/instance_name/log/oc4j/log.xml

^Footnote 1 Locations are shown in UNIX format. Invert the slashes for Windows format.

<log>
<odl path="../log/petstore/" max-file-size="1000" max-directory-size="10000" />
</log>

5.4.4 Managing OC4J Redirected stderr and stdout Files

You can set runtime options for OC4J log files that specify that redirected stderr and stdout log files be rotated when the files reach a specific size or at the particular time of day. You can also specify the maximum number of log files to keep as archives. The following example specifies that the stdout log file will be rotated at 1:30 AM each day and that the maximum number of log files is 10:

java -Dstdstream.rotatetime=1:30 -Dstdstream.filenumber=10 -jar oc4j.jar -out d:\logs\oc4j.out

5.4.5 Configuration Issue for Log Files

The Logs link in the Application Server Control Console gives you an integrated view of many Oracle Application Server component log files. However, certain log files are only available at the component level. Oracle Application Server components use the following directory to make their log files visible to the Application Server Control Console:

ORACLE_HOME/j2ee/home/applications/ascontrol/ascontrol/WEB-INF/config/registration

Some Oracle Application Server component log files are not exposed through Application Server Control Console pages.