Skip Headers

Oracle® HTTP Server Administrator's Guide 10g Release 3 (10.1.3) B25211-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 6 Configuring and Using Server Logs

This chapter discusses Oracle Diagnostic Logging, log formats, and describes various log files and their locations.

Topics discussed are:

- Using Oracle Diagnostic Logging

- Specifying Log Level

- Specifying Log Files

Documentation from the Apache Software Foundation is referenced when applicable.

Note: Readers using this guide in PDF or hard copy formats will be unable to access third-party documentation, which Oracle provides in HTML format only. To access the third-party documentation referenced in this guide, use the HTML version of this guide and click the hyperlinks.

## 6.1 Using Oracle Diagnostic Logging

Oracle offers a new method for reporting diagnostic messages. This new method, Oracle Diagnostic Logging (ODL), presents a common format for diagnostic messages and log files, and a mechanism for correlating all diagnostic messages from various components across Oracle Application Server. Using ODL, each component logs messages to its own private local repository. A tool called `LogLoader` collects messages from each repository and loads them into a common repository where messages can be viewed as a single log stream, or analyzed in different ways.

You can view Oracle Application Server diagnostic log files using either Application Server Control Console, or a text editor.

See Also: Oracle Application Server Administrator's Guide

ODL is further discussed in the following sections:

- Overview

- Configuring Oracle HTTP Server

### 6.1.1 Overview

Oracle HTTP Server enables you to choose the format in which you want to generate log messages. You can either continue to generate log messages in the legacy Apache message format, or generate log messages using ODL, which complies with the new Oracle-wide standards for generating log messages.

### 6.1.2 Configuring Oracle HTTP Server

To enable Oracle HTTP Server to use ODL, enter the following directives in the `httpd.conf` file:

- OraLogMode oracle | odl | apache

- OraLogSeverity module_name <msg_type>{:msg_level]

- OraLogDir <bus stop dir>

Oracle recommends that you enter the directives before any modules are loaded (`LoadModule` directive) in the `httpd.conf` file so that module-specific logging severities are in effect before modules have the opportunity to perform any logging.

#### 6.1.2.1 OraLogMode oracle | odl | apache

Enables you to switch between the Oracle logging format, the legacy Apache logging format, and the ODL logging format. Logging formats are defined as follows:

- oracle: Fully conformant, multi-line log records in XML format. Provides the most information.

- odl: Standard Apache log format and ECID information for log records specifically associated with a request. This is the default setting.

- apache: Standard Apache log format. Provides the least information.

#### 6.1.2.2 OraLogSeverity module_name <msg_type>{:msg_level]

Enables you to set message severity. The message severity specified with this directives is interpreted as the lowest message severity that is desired, and all messages of that severity level and higher will be logged.

`OraLogSeverity` may be specified multiple times. It can be specified globally (no module_name) and once for each module for which a module-specific logging severity is desired.

This directive is only used when `OraLogMode` is set to "oracle". This directive can be used in place of the `LogLevel` directive, but is not required. If `OraLogSeverity` is present and `OraLogMode` is set to "oracle", then `LogLevel` will be ignored.

##### 6.1.2.2.1 module_name

This argument is the internal name of a module, as it appears in the module structure. The <`IfModule`> directive also makes use of this internal name. The module structure derives the module name from the value of the `_FILE_` macro, without path prefix, of the file which defines the module structure. If a module name is not supplied, the `OraLogSeverity` directive is applied globally.

If the module name is specified, then the directive overrides the global directive value of all the messages originating from the specified module. Specifying a module name for a module that does not get loaded generates an error.

##### 6.1.2.2.2 msg_type

Message types may be specified in upper or lower case, but will appear in the message output in upper case. This parameter must be of one of the following values:

- `INTERNAL_ERROR`

- `ERROR`

- `WARNING`

- `NOTIFICATION`

- `TRACE`

##### 6.1.2.2.3 msg_level

This parameter must be an integer in the range of 1-32. 1 is most severe, 32 is least severe. Using level 1 will result in fewer messages than using level 32.

Table 6-1 lists some examples of `OraLogSeverity`.

Table 6-1 Examples of OraLogSeverity

OraLogSeverity Example | Action Taken
--- | ---
`OraLogSeverity INTERNAL_ERROR:10` | Logs all messages of type "internal error" of levels 1-10
`OraLogSeverity WARNING:7` | Logs all messages of type "internal error" of all levels Logs all messages of type "error" of all levels Logs all messages of type "warning" of levels 1-7
`OraLogSeverity WARNING` `OraLogSeverity mod_oc4j.c NOTIFICATION:4` | If message source is `mod_oc4j`, then Logs all messages of type "internal error" of all levels Logs all messages of type "error" of all levels Logs all messages of type "warning" of all levels Logs all messages of type "notification" of levels 1-4 For messages from all other sources: Logs all messages of type "internal error" of all levels Logs all messages of type "error" of all levels Logs all messages of type "warning" of all levels

##### 6.1.2.2.4 Default

If a message level is not specified, then the level defaults to the lowest severity. If the entire directive is omitted, then the value of the global Apache `LogLevel` directive is used and translated to the corresponding Oracle message type and the lowest level within the corresponding range, as listed in Table 6-2:

Table 6-2 Apache Log Level and Corresponding Oracle Message Type

Apache Log Level | Oracle Message Type
--- | ---
`emerg` | `INTERNAL_ERROR:16`
`alert` | `INTERNAL_ERROR:32`
`crit` | `ERROR:16`
`error` | `ERROR:32`
`warn` | `WARNING:32`
`notice` | `NOTIFICATION:16`
`info` | `NOTIFICATION:32`
`debug` | `TRACE:32`

See Also: "Specifying Log Level"

#### 6.1.2.3 OraLogDir <bus stop dir>

Specifies the path to the directory which contains all log files. This directory must exist.

Default:

- UNIX: `ORACLE_HOME``/Apache/Apache/logs/oracle`

- Windows: `ORACLE_HOME``\Apache\Apache\logs\oracle`

## 6.2 Specifying Log Level

Table 6-3 lists all the different logging levels, their descriptions, and, example messages for `LogLevel` directive:

Table 6-3 Logging Level

Logging Level | Description | Example Message
--- | --- | ---
`emerg` | Emergencies- system is unusable. | "Child cannot open lock file. Exiting."
`alert` | Action must be taken immediately. | "getpwuid: couldn't determine user name from uid"
`crit` | Critical conditions. | "socket: Failed to get a socket, exiting child"
`error` | Error conditions. | "Premature end of script headers"
`warn` | Warning conditions. | "child process 1234 did not exit, sending another `SIGHUP`"
`notice` | Normal but significant condition. | "httpd: caught `SIGBUS`, attempting to dump core in..."
`info` | Informational. | "Server seems busy, (you may need to increase `StartServers`, or `Min`/`MaxSpareServers`)..."
`debug` | Debug-level messages. | "Opening config file..."

Note: `LogLevel` directive may be omitted when `OraLogMode` is "oracle' and `OraLogSeverity` is set.

## 6.3 Specifying Log Files

The following log files are described in subsequent sections:

- Access Log

- CustomLog

- Error Log

- PID File

- Piped Log

- Rewrite Log

- Script Log

- SSL Log

- Transfer Log

It is important to periodically rotate the log files by moving or deleting existing logs on a moderately busy server. For this, the server must be restarted after the log files are moved or deleted so that new log files are opened.

See Also: "Log Rotation" in the Apache Server documentation.

### 6.3.1 Access Log

Records all requests processed by the server. The location and content of the access log is controlled by the CustomLog directive. The `LogFormat` directive can be used to simplify the selection of the contents of the logs.

#### 6.3.1.1 Specifying LogFormat

`LogFormat` specifies the information included in the log file, and the manner in which it is written. The default format is the Common Log Format (CLF). The CLF format is: `host ident authuser date request status bytes`

- `host`: This is the client domain name or its IP number.

- `ident`: If `IdentityCheck` is enabled and the client machine runs `identd`, then this is the client identity information.

- `authuser`: This is the user ID for authorized user.

- `date`: This is the date and time of the request in the `<day/month/year:hour:minute:second>` format.

- `request`: This is the request line, in double quotes, from the client.

- `status`: This is the three-digit status code returned to the client.

- `bytes`: This is the number of bytes, excluding headers, returned to the client.

See Also: "Access Log" in the Apache Server documentation.

### 6.3.2 CustomLog

Log requests to the server. A log format is specified, and the logging can optionally be made conditional on request characteristics using environment variables.

See Also: "`CustomLog` directive" in the Apache Server documentation.

### 6.3.3 Error Log

The server sends diagnostic information and records error messages to a log file located, by default, in:

- UNIX: `ORACLE_HOME``/Apache/Apache/logs/error_log`

- Windows: `ORACLE_HOME``\Apache\Apache\logs\error_log`

The file name can be set using the ErrorLog directive.

See Also: "ErrorLog directive" in the Apache Server documentation.

### 6.3.4 PID File

When the server is started, it notes the process ID of the parent httpd process to the PID file located, by default, in

- UNIX: `ORACLE_HOME``/Apache/Apache/logs/httpd.pid`

- Windows: `ORACLE_HOME``\Apache\Apache\logs\httpd.pid`

This filename can be changed with the PidFile directive. The process ID is for use by the administrator for restarting and terminating the daemon. If the process dies (or is killed) abnormally, then it is necessary to kill the children httpd processes.

See Also: "Pid File" in the Apache Server documentation.

### 6.3.5 Piped Log

Oracle HTTP Server is capable of writing error and access log files through a pipe to another process, rather than directly to file. This increases the flexibility of logging, without adding code to the main server. In order to write logs to a pipe, replace the file name with the pipe character "|", followed by the name of the executable which should accept log entries on its standard input. Oracle HTTP Server starts the piped-log process when the server starts, and restarts it if it crashes while the server is running.

Piped log processes are spawned by the parent Oracle HTTP Server httpd process, and inherit the user ID of that process. This means that piped log programs usually run as `root` so it is important to keep the programs simple and secure.

See Also: "Piped Log" in the Apache Server documentation.

### 6.3.6 Rewrite Log

Necessary for debugging when mod_rewrite is used. This log file produces a detailed analysis of how the rewriting engine transforms requests. The level of detail is controlled by the `RewriteLogLevel` directive.

See Also: "Rewrite Log" in the Apache Server documentation.

### 6.3.7 Script Log

Enables you to record the input to and output from the CGI scripts. This should only be used in testing, and not for live servers.

See Also: "Script Log" in the Apache Server documentation.

### 6.3.8 SSL Log

When Oracle HTTP Server starts in SSL mode, it creates `ssl_engine_log` and `ssl_request_log` in

- UNIX: `ORACLE_HOME``/Apache/Apache/logs`

- Windows: `ORACLE_HOME``\Apache\Apache\logs`

`ssl_engine_log` tracks SSL and protocol issues, where as `ssl_request_log` records user activity. Use the `SSLLogFile` directive to control output.

See Also: Chapter 10, "Enabling SSL for Oracle HTTP Server"

### 6.3.9 Transfer Log

Specifies the file in which to store the log of accesses to the site. If it is not explicitly included in the `conf` file, then no log is generated. The server typically logs each request to a transfer file located, by default, in

- UNIX:`ORACLE_HOME``/Apache/Apache/logs/access_log`

- Windows: `ORACLE_HOME``\Apache\Apache\logs\access_log`

The filename can be set using a `CustomLog` directive.