4 Managing Log Files

4.1.1 Understanding Log File Data and Naming

Several Oracle Application Server components use 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. Regardless of the format of the messages that are stored in log files, ODL or text based, 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 Messages by Component

  
  

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

  
  

4.1.2 Using A Log Repository

The Application Server Control Console supports viewing diagnostic messages from a Log Repository (a Log Repository stores error logs, but does not store access logs). A Log Repository contains diagnostic messages collected from multiple log files across components. The Oracle Application Server Log Loader component initializes and updates the data in a Log Repository. After the Log Loader starts, at regular intervals it stores information from diagnostic log files to the Log Repository.

Using a Log Repository consolidates Oracle Application Server log file data; this allows you to use the Application Server Control Console to easily search and view log file data generated by multiple components. Using a Log Repository can speed up the diagnostic process and reduce the resources required to support Oracle Application Server.

4.1.3 Configuring Component Logging Options

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

The logging configuration options 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 cleanup 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 the 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.

  
  

  See Also: Oracle Application Server component documentation for information on setting logging configuration options.

  
  

4.2.1 Listing Log Files for All Components

Selecting the Logs link on the Application Server Control Console shows the View Logs page. To list the log files, starting on the View Logs page perform the following steps:

1. Select the Move All button to move all available components to the Selected Components box.

2. Select the Search button to list the log files for the selected components.

3. After the search returns, the Results section shows log file information such as the name of the component associated with a log file and a link to the log file.

Figure 4-1 shows the Application Server Control Console View Logs page after a search.

Figure 4-1 Enterprise Manager View Logs Search Results

Description of the illustration logview2.gif

4.2.2 Listing Log Files for Selected Components

Using the Application Server Control Console, selecting the Logs link shows the View Logs page. To list selected components log files, starting on the View Logs page perform the following steps:

1. Select the components whose log files you want to view from the Available Components box and use the Move button to move the selected component to the Selected Components box (some browsers support double clicking to move components between the boxes).

2. Select the Search button to list the log files for the selected components.

3. After a search returns, the Results section shows log file information such as the name of the component associated with a log file and a link to the file.

Figure 4-1 shows the View Logs page Results after a search.

4.2.3 Listing Log Files from Oracle Application Server Components Pages

After you select a system component link on the Application Server Control Console main page, you can view the component log files by selecting the Logs link. When you select this link, the Application Server Control Console shows the View Logs page and runs a search for the component's log files. Thus, clicking on the Logs link for pages associated with a component runs a log file search for that component. You can then view the log files by selecting the Log File links shown in the Results section.

When you select the Logs link from a component page, the log file pages include a Return to link at the bottom of each page. The Return to link returns you to the component page from which you selected the Logs link.

4.2.4 Using Log Files Advanced Search

After selecting the Logs link on an Application Server Control Console page, the View Logs page is shown. Starting on the View Logs page, selecting the Advanced Search button shows the View Logs Advanced Search page. The Advanced Search page lets you list log files for Oracle Application Server components and allows you to filter the search for log files by certain log file attributes.

Starting on the View Logs Advanced Search page you can list log files using a search filter by performing the following steps:

1. Select the desired components from the Available Components box by using the Move or Move All buttons to move components to the Selected Components box (some browsers support double clicking to move components between the boxes).

2. Select a field from the Log File Attribute list.

3. Select the Add Row button to add a row for the selected log file attribute.

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

5. If you want to select additional fields with values, select the Add Another Row button and enter additional values.

6. Select the Search button to perform the search. When the search returns, the Results section shows log files with matching fields.

To obtain more information on filtering using log file attributes, click the information icon next to the Log File Attribute list.

Figure 4-2 shows the Advanced Search Filter By Log File Attributes selection box, with the Log File Attribute list and the Add Row button.

Figure 4-2 Log Files Advanced Search Filter By Log File Attributes

Description of the illustration filter.gif

4.2.5 Viewing Log File Details and Log File Contents

After selecting the Search button from either the View Logs Simple Search or Advanced Search page, the View Logs page shows the search output at the bottom of the page in the Results section. You can sort the output by selecting column headings. For example, to sort results by size, select the Size (bytes) column heading (multiple selections on a column heading toggle ascending and descending sort).

To view log file contents, select the link shown in the Log File column.

After selecting a log file link, the Log File page shows the contents of the selected log file, and supports the following:

• The Refresh list determines whether the file view is updated manually or automatically. Select Automatically when you want to refresh the page at regular intervals. The Log File page scrolls to the bottom when a page refreshes.

• Selecting the refresh icon next to the Page Refreshed date, on either the top or the bottom of the page, initiates manual refresh. Each refresh displays the log entries added since the last refresh.

• Selecting the Log File link lets you use browser features to display, print, or download the log file.

4.3.1 Getting Started With Log Repository

To use a Log Repository for searching and viewing diagnostic messages, select the Logs link on an Application Server Control Console page and then select the Search Log Repository link. The Search Log Repository Simple Search and Advanced Search pages allow you to search the diagnostic messages stored in the Log Repository.

Figure 4-3 shows the Application Server Control Console Search Log Repository page.

The Log Repository needs to contain diagnostic messages before you can search the Log Repository. The Log Loader component initializes and updates the diagnostic messages in the Log Repository.

4.3.2 Searching Log Repository With Simple Search

To search the Log Repository for diagnostic messages, go to the View Logs > Search Log Repository page, and use the Available Components and Selected Components boxes to select components. The online help describes the available search and display options for the View Logs > Search Log Repository page.

To search for diagnostic log entries in the Log Repository, do the following:

1. Select components from the Available Components box (optional). Select components and then use the Move or Move All button to move the selected components to the Selected Components box (some browsers support double clicking to move components between the boxes). This step is optional.

2. Use the default selections, or select the available search and result display options. The online help describes the available search and display options for the View Logs > Search Log Repository page.

3. Select the Search button to search for messages in the Log Repository that match the constraints you specify. When the search returns, the Results section shows the matching diagnostic log messages from the Log Repository.

   
   

   Note: The Message Type selection box includes the Unknown option. Some components do not include a message type when the component writes log file entries. These messages are loaded into the Log Repository with Unknown specified as the message type.

   
   
   
   

   See Also: Section 4.3.4, "Viewing Repository Log Entry Details"

   
   

Figure 4-3 Search Log Repository Page

Description of the illustration repos1.gif

4.3.3 Searching Log Repository With Advanced Search

To search the Log Repository for diagnostic messages using advanced search, go to the View Logs > Search Log Repository page, and select the Advanced Search button. On the View Logs > Search Log Repository Advanced Search page, use the Filter By Log Entry Fields box to select log fields and values to search. The View Logs pages shows the diagnostic log entries with matching field values when you enter after you select the Search button.

Figure 4-4 shows the Advanced Search Log Repository Filter By Log Entry Fields box.

To display Log Repository entries matching the Advanced Search filter, perform the following steps:

1. Use the default selections, or specify search and result date range and message type options by making selections and entering constraints on the View Logs > Search Log Repository Advanced Search page.

2. Select log entries with specified field values using the Filter by Log Entry Fields box. Select multiple fields using the Add Another Row button. When you specify values for multiple fields, the search only returns results that match all of the specified constraints. The online help describes the available search and display options for the View Logs > Search Log Repository page.

3. Select the Search button to search for messages in the Log Repository that match the selection constraints. When the search returns, the Results section shows the matching log entries.

Figure 4-4 Search Log Repository Advanced Search Filter By Log Entry Fields

Description of the illustration repos2.gif

4.3.4 Viewing Repository Log Entry Details

Using either the link shown in the Time field of the Results area on the View Logs page, or by selecting entries in the Select field and then selecting the View Details button, you can view a log entry and its associated information, including the Message Type, Component, the Message Text, and optionally the Execution Context ID (ECID).

Figure 4-5 shows a log entry details page.

Figure 4-5 Log Repository Log Entry Details Page

Description of the illustration logentry1.gif

4.3.5 Using Regular Expressions With Log Repository Search

Regular expression matching is applied when the checkbox in the Regular Expression field is selected on the Log Repository Simple Search or Advanced Search page. On the Simple Search page, the Regular Expression checkbox is under the Message Text field. On the Advanced Search page, the Regular Expression checkbox is in the Filter by Log Entry Fields box. Using a regular expression in a search allows you to enter a pattern description that enables you to match strings for a Log Repository search.

The Log Repository 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.

4.4.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 Entry Details page in the Application Server Control Console, if the Execution Context ID field is available, it displays the Execution Context ID as a link. Selecting the Execution Context ID link shows you all the messages with the same execution context ID.

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 integer 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, OracleAS Web Cache assigns an initial sequence number of 0 to a request (when OracleAS Web Cache handles the request). After that, the sequence number is incremented as the request moves through Oracle Application Server components.

Table 4-2 lists the Oracle Application Server components that provide message correlation information (using an ECID).

4.4.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. There are general techniques that can assist you in accomplishing this task. In general, the techniques include the following:

• 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

Using a Log Repository can make searching for the root cause of a problem much easier. A Log Repository consolidates log file data and allows you use to easily search, correlate, and view log file data that is generated by multiple Oracle Application Server components. A Log Repository correlates cross component information by time, and correlates events that occur in a cascading fashion. Once a problem is isolated to a particular component in the repository, then, if needed, the problem can be further analyzed by examining the component-specific diagnostic files.

4.5.1 Starting and Stopping Log Loader

You can use the controls on the Application Server Control Console Log Loader page to start and stop the Log Loader. Starting the Log Loader starts the Oracle Application Server component that periodically updates the Log Repository. Stopping the Log Loader stops the Oracle Application Server component that periodically updates the Log Repository.

To start the log loader, perform the following steps:

1. Select the Logs link on any Application Server Control Console page.

2. From the View Logs page select the Search Log Repository link.

3. Select the Log Loader button on the view logs page.

4. On the Log Loader page, select the Start button.

5. After selecting the Start button, on the confirmation page select either, Cancel, Start, or Start and Load Existing Logs. Use the Cancel button on this page to cancel, use the Start button to start the Log Loader, and use the Start and Load Existing Logs button to start and initialize the log repository with the existing log messages (using Start and Load Existing Logs is usually recommended, since this operation may be faster than simply starting the Log Loader).

   
   

   See Also: Section 4.3, "Searching Diagnostic Messages In A Log Repository"

   
   

4.5.2 Enabling and Disabling Log Loader

On the Log Loader page, the Enable button enables the Log Loader. By default, when you first install Oracle Application Server, the Log Loader is enabled. Disabling the Log Loader specifies that the Log Loader's own log files are not shown in the component lists on the View logs page.

4.5.3 Updating the Log Configuration

When the Log Loader starts, it loads configuration information about the component log files to use as source for the diagnostic messages that are stored in the Log Repository (this includes information on the location and format of the log files). If the instance is reconfigured after the Log Loader is started, for example when a new component is added, use the Update Log Configuration button to update the Log Loader configuration. Updating the log configuration lets the Log Loader reread configuration files to locate and load all the component log files into the Log Repository.

4.5.4 Setting Log Loader Properties

You can set Log Loader properties from the Log Loader page. To navigate to the Log Loader page:

1. Select the Logs link on any Application Server Control Console page.

2. From the View Logs page select the Search Log Repository link.

3. Select the Log Loader button on the view logs page.

4. Select the Log Loader Properties link in the Administration section.The Log Loader Properties page includes fields showing the current values for the Log Loader properties.

To change the Log Loader properties, perform the following steps:

1. Enter updated values in the appropriate fields on the Log Loader Properties page.

2. Select the Apply button to apply the new values.

Figure 4-6 shows the Application Server Control Console Log Loader Properties page.

The Application Server Control Console online help includes detailed information on the Log Loader Properties fields.

Figure 4-6 Log Loader Properties Page

Description of the illustration loaderprop.gif

4.5.5 Understanding Log Loader Diagnostic Messages

The Log Loader logs its diagnostic messages, including errors to its log file. Diagnostic messages might include errors encountered due to an incorrect configuration, or errors that occur while the Log Loader is reading data from a log file or is writing data to the log repository.

The common Log Loader problems include:

1. Errors in the Log Loader configuration file ($ORACLE_HOME/diagnostics/config/logloader.xml). Errors in the configuration file usually prevent the Log Loader from running. Such errors need to be corrected before the Log Loader can work properly.

2. Configuration errors that occur when a component's registration file contains errors ($ORACLE_HOME/diagnostics/config/registration/*.xml). Errors in the registration files do not prevent the Log Loader from running but may prevent the contents of certain log files from being loaded in the repository. Typically, there are two common types of registration file errors:

   1. XML syntax errors that prevent the file from being parsed. If such errors are encountered, the Log Loader completely ignores the contents of the file.

   2. A wrong path specified for a configuration file. If the Log Loader cannot find a log file at the specified path, it issues a Warning level diagnostic message. This does not always indicate an error, for example, it is possible that the component that generates that log was not active when the Log Loader started and the log file had not been created yet. The Log Loader continues to look for the log file and starts reading messages when the log file is created.

3. Errors may occur while the Log Loader is reading messages from a log file. If the log file includes contents that cannot be read or parsed, then the Log Loader issues a log message indicating that it cannot read part of the contents of the file. In this case, the Log Loader attempts to recover from the error and continue to read the Log File.

4. Errors may occur when writing messages to the repository (for example, a disk error). This type of error may indicate a problem that may require attention from the system administrator to correct the problem.

5. The Log Loader produces an error message when it skips reading log files because a log file exceeds the currently specified maximum load size. The maximum load size can be specified on the Log Loader properties page.

   In this case the Log Loader logs an error message in the following format:

   Size of data to be read from log /logfile exceeds threshold of x bytes. Skipping y_skipped bytes and moving to end of log.
   
   

   This message indicates the size of data to be read exceeds the specified maximum load size x, and that the Log Loader is skipping to the end of the log file. The error message provides information on the name of the log file /logfile, and the number of bytes skipped y_skipped.

4.6.1 Using the printlogs Tool to View Log Messages

The printlogs tool is a command-line alternative to the Application Server Control Console for viewing log messages. printlogs supports a variety of options for gathering and filtering log messages, and prints the results to standard output in a single format. For example, you can use printlogs to:

• Read log messages from the Log Repository or individual log files

• Filter log messages according to timestamp or log field value

• Print log messages in ODL or text format

• Sort log messages by field

• Report the number of log messages of a specified type

• Run in a continuous loop, printing log reports and sleeping for a specified amount of time

  
  

  See Also: Appendix E, "printlogs Tool Syntax and Usage" for more information

  
  

4.6.2 Understanding ODL Messages and ODL Log Files

This section covers the following topics:

• ODL Message Contents

• ODL Log File Naming

MESSAGE>
  <HEADER>
    <TSTZ_ORIGINATING>2002-04-01T18:38:48.058-08:00</TSTZ_ORIGINATING>
    <ORG_ID>oracle.com</ORG_ID>
    <COMPONENT_ID>OHS</COMPONENT_ID>
    <HOSTING_CLIENT_ID>0.0.255.255</HOSTING_CLIENT_ID>
    <MSG_TYPE TYPE="ERROR"></MSG_TYPE>
    <MSG_LEVEL>17</MSG_LEVEL>
    <HOST_ID>test-perf9</HOST_ID>
    <HOST_NWADDR>0.0.255.255</HOST_NWADDR>
    <MODULE_ID>apache_core</MODULE_ID>
    <PROCESS_ID>5713</PROCESS_ID>
  </HEADER>
  <CORRELATION_DATA>    <EXEC_CONTEXT_ID>
      <UNIQUE_ID>1017715128:255..255.255.88:5713:0:1</UNIQUE_ID>
      <SEQ>1</SEQ>
    </EXEC_CONTEXT_ID>
  </CORRELATION_DATA>
  <PAYLOAD>
    <MSG_TEXT>File does not exist: /files/Apache/docs/images/java-apache-project.gif
    </MSG_TEXT>
  </PAYLOAD>
</MESSAGE>

File                        Size

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

4.6.3 Understanding Log Loader Log File Format Conversion

The Log Loader reads logs in several different formats and it converts the contents of non-ODL logs to ODL format. In most cases, the resulting ODL log record will contain only a timestamp and the message text from the original log entry. Values for other ODL message fields, such as COMPONENT_ID and MODULE_ID can be provided in the log registration file for each log, so that these values are set to all log records parsed from the log. The Log Loader attempts to determine the severity or level of each non-ODL log and generate an appropriate ODL message type. However, in many cases, if the severity or level cannot be determined, the resulting ODL log record will have the message type set to UNKNOWN.

The Log Loader can even read "unformatted" logs, that may not even contain timestamp values. This is the case for several logs in the $ORACLE_HOME/opmn/logs directory which contain redirected output from Oracle Application Server processes managed by Oracle Process Manager and Notification Server. When log entries do not contain a timestamp, the Log Loader will set the timestamp to the value of the "last known timestamp" for that log. The value of the last known timestamp is determined according to the following rules:

1. The initial value of the last known timestamp is zero. Note that whenever adding a log record to the repository, a zero value timestamp will be converted to the current time.

2. If the Log Loader finds an Oracle Process Manager and Notification Server generated timestamp it will set the last known timestamp with its value.

3. When the Log Loader reaches the end of the log, it sets the last known timestamp with the current time. If the Log Loader is running regularly, such as once every five minutes, this will result in timestamps that are approximate to the actual time the message was written within a five minute range. If the Log Loader is not run frequently, the value of these timestamps could be inaccurate.

   
   

   Note: The OC4J redirected logs found in the $ORACLE_HOME/opmn/logs directory are not treated as "unformatted" logs, since each line in the OC4J logs contains a timestamp. Most other logs in this directory are treated as unformatted logs, and will have timestamps assigned according to the preceding rules.

   
   

4.6.4 Component Diagnostic Log File Registration

The Application Server Control Console and the Log Loader read Oracle Application Server component diagnostic registration files to determine names, locations, and additional configuration information about diagnostic log files. The directory $ORACLE_HOME/diagnostics/config/registration contains the diagnostic log file registration files.

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

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

4.6.5 Configuring Components to Produce ODL Messages and ECIDs

Table 4-5 lists the Oracle Application Server components that support ODL messages but that generate text messages by default. By making configuration changes, these components can be configured to produce ODL messages and for OC4J, an ECID.

This section covers the following topics:

• Configuring Oracle HTTP Server to Produce ODL Messages

• Configuring OC4J to Produce ODL Messages

• Configuring OC4J to Produce ECIDs

See Table 4-1 for the complete list of Oracle Application Server components that produce ODL messages.

4.6.6 Limitations and Configuration

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 directory $ORACLE_HOME/diagnostics/config/registration to make their log files visible to the Application Server Control Console. Some Oracle Application Server component log files are not exposed through Application Server Control Console pages.