Oracle Web Cache Administration and Deployment Guide Release 1.0.2.3 Part Number A86722-03 |
Library | Service | Contents | Index

# 8
Administering Oracle Web Cache

This chapter explains how to perform administrative tasks to Oracle Web Cache. It contains these topics:

- Starting and Stopping Oracle Web Cache

- Invalidating Documents in the Cache

- Evaluating Event Logs

- Evaluating Access Logs

## Starting and Stopping Oracle Web Cache

Anytime Oracle Web Cache's configuration is modified, Oracle Web Cache must be stopped and restarted. To start and stop Oracle Web Cache, use either Oracle Web Cache Manager or the `webcachectl` utility.

When you start Oracle Web Cache from the `webcachectl` utility, the `admin` server process for the administrative interface and the `cache` server process for the actual cache are started. The Oracle Web Cache Manager starts only the `cache` server process. To initialize Oracle Web Cache for the first time, use the `webcachectl` utility to start both processes.

Use Oracle Web Cache Manager... | Use the webcachectl Utility...
--- | ---
1. To start the `cache` server process: Start Oracle Web Cache Manager. See Also: "Starting Oracle Web Cache Manager" In the navigator pane, select Administering Oracle Web Cache > Web Cache Operations. The Oracle Web Cache Operations page appears in the right pane. In the Oracle Web Cache Operations page, choose Start or Stop. | To start Oracle Web Cache: Determine the status of Oracle Web Cache. From the command line, enter:
       webcachectl status
   If the following message appears, Oracle Web Cache is not running. Continue to Step 2.
       Oracle Web Cache admin server is NOT running.
       Oracle Web Cache cache server is NOT running.
   If the following message appears, Oracle Web Cache is already running.
       Oracle Web Cache admin server is running
       (pid=pid).
       Oracle Web Cache cache server is running
       (pid=pid)
2. Start Oracle Web Cache. From the command line, enter:
       webcachectl start
   The following message appears:
       Oracle Web Cache started
To stop Oracle Web Cache, from the command line, enter:
    webcachectl stop
The following message appears:
    Oracle Web Cache admin server stopping.
    Oracle Web Cache cache server stopping.

On Windows NT, Oracle Web Cache can also be started through the Control Panel:

1. Double-click the Services icon in the Control Panel window.

2. Select the OracleHOME_NAMEWebCacheAdmin service to start the `admin` server.

3. Choose Start to start the service.

4. Select the OracleHOME_NAMEWebCache service to start the `cache` server.

5. In the Services window, choose Close.

## Invalidating Documents in the Cache

Invalidation messages are sent to Oracle Web Cache to an invalidation listening port through HTTP `POST` messages. The invalidation messages identify the documents to be invalidated.

This section contains the following invalidation-related topics:

- Setting the Invalidation Port Number

- Sending Invalidation Messages

- Invalidation Examples

### Setting the Invalidation Port Number

By default, Oracle Web Cache listens for invalidation requests at port 4001.

To change the default port number:

1. Start Oracle Web Cache Manager.

   See Also: "Starting Oracle Web Cache Manager"

2. Change the port numbers:

   1. In the navigator pane, select Administering Oracle Web Cache > Oracle Web Cache Invalidation/Statistics Port.

      The Oracle Web Cache Invalidation/Statistics Port page appears in the right pane.

   1. In the Oracle Web Cache Invalidation/Statistics Port page, choose Edit.

      The Change Invalidation/Statistics Port dialog box appears.

   2. In the New Invalidation Port field, enter the new port.

   3. Choose Submit.

3. Apply changes and restart Oracle Web Cache:

   1. In the Oracle Web Cache Manager main window, choose Apply Changes.

   1. In the navigator pane, select Administering Oracle Web Cache > Web Cache Operations.

      The Oracle Web Cache Operations page appears in the right pane.

   2. In the Oracle Web Cache Operations page, choose Stop and then Start to restart Oracle Web Cache.

### Sending Invalidation Messages

Invalidation messages are HTTP `POST` message written in Extensible Markup Language (XML) syntax. The contents of the XML message body tells the cache which URLs to mark as invalid. As shown in Figure 8-1, invalidation messages can be sent using one of the following methods:

- Manually, using either Oracle Web Cache Manager or `telnet`

- Automatically, using database triggers, scripts, or applications

#### Figure 8-1 Invalidation

Text description of the illustration admina.gif

This section describes how to send invalidation messages using one of the following methods:

- Manual Invalidation Using Telnet

- Manual Invalidation Using Oracle Web Cache Manager

- Automatic Invalidation Using Database Triggers

- Automatic Invalidation Using Scripts

- Automatic Invalidation Using Applications

#### Manual Invalidation Using Telnet

When you send an invalidation message with a HTTP `POST` message, you specify the host name of Oracle Web Cache, the invalidation listening port number, and the invalidation message.

For example, if you were using `telnet`, you would send an invalidation message using the following procedure:

1. Connect to Oracle Web Cache at the invalidation listening port:

       telnet webcache_host invalidation_port

2. Once you have telneted to the port, specify a `POST` message header and authenticate the user invalidator using Base64 encoding string with the following syntax.

       POST /x-oracle-cache-invalidate http/1.0|1
       Authorization: BASIC <base64 encryption of invalidator:invalidator_password>
       content-length:#bytes

   An example of `Authorization: BASIC <``base64 encryption of invalidator:invalidator_password``>` follows:

       Authorization: BASIC aW52YWxpZGF0b3I6YWRtaW4=

   In this example, `aW52YWxpZGF0b3I6YWRtaW4=` is "`invalidator:admin`" encoded.

   See Also: "Task 2: Modify Security Settings" for further information about changing the invalidation password

3. Enter one carriage return.

4. Send the invalidation message with the following XML syntax:

       <?xml version="1.0"?>

       <!DOCTYPE INVALIDATION SYSTEM "internal:///invalidation.dtd">
       <INVALIDATION>
           <URL EXP="URL" PREFIX="YES|NO">
               <VALIDITY LEVEL="validity" REFRESHTIME="seconds"/>
               <COOKIE NAME="cookie_name" VALUE="value" NONEXIST="YES|NO"/>
               <HEADER NAME="HTTP_request_header" VALUE="value"/>
           </URL>
       </INVALIDATION>

Table 8-1 Invalidation Message Syntax

#####

Invalidation Element/Attribute | Description
--- | ---
`URL` | Required element in the invalidation message. You can specify more than one URL element in the message.
`EXP` | Required attribute for the `URL` element. Specify the URL of the documents you want to invalidate.
`PREFIX` | Optional attribute for the `URL` element. Specify `YES` to invalidate documents that match a prefix-based regular expression

. `YES` limits the URL expression (`EXP`) to a limited form of regular expression, whereby the URL path (from first "/" to the last "/") matches the prefix of the URL. For example, if you have the URL expression set to `/cec/cstage\?ecaction=viewitem`, then `/cec/` is the common prefix of the URLs to invalidate. Therefore, URLs such as `/cec/cstage?ecaction=viewitem&zip=94405` and `/cec/cstage?ecaction=viewitem&zip=94305` match, but `/usa/cec/cstage?ecaction=viewitem&zip=94209` does not match. The path section cannot contain any reserved regular expression characters. Reserved regular expression characters include periods (`.`), question marks (`?`), asterisks (`*`), brackets (`[]`), curly braces (`{}`), carats (`^`), dollar signs (`$`), or backslashes (`\`). However, the part after the path, which is usually the file name, can include regular expression characters.

Specify `NO` to only invalidate documents contained within the URL. `NO` also means that the URL expression (`EXP`) is interpreted literally.

EXAMPLE 1

Invalidation Intent: Invalidate `sample.gif` contained within the `/cec/cstage/graphic*/sample.gif` directory.

URL Expression Entered: `/cec/cstage/graphic*/sample.gif`

Result:

If `PREFIX` is set to `NO`, then `/cec/cstage/graphic*/sample.gif` matches and Oracle Web Cache invalidates only `/cec/cstage/graphic*/sample.gif`. The "`*`" and "." characters are not interpreted as regular expression characters.

If `PREFIX` is set to `YES`, then `/cec/cstage/graphic*/sample.gif` is not invalidated. This is because the path includes "`*`", a reserved regular expression character that cannot be included in the path section, and the "." in the file name is interpreted as a regular expression character to match any character. If "`*`" is replaced with the exact directory name and the "." is escaped, as in `/cec/cstage/graphicsales/sample\.gif`, then `sample.gif` is invalidated.

EXAMPLE 2

Invalidation Intent: Invalidate documents contained in the `/cec/cstage?ecaction=ecsectview` directory.

URL Expression Entered: `/cec/cstage?ecaction=ecsectview`

Result:

If `PREFIX` is set to `NO`, then `/cec/cstage?ecaction=ecsectview` matches and Oracle Web Cache invalidates only `/cec/cstage?ecaction=ecsectview`. The "`?`" character is not interpreted as a regular expression character.

If `PREFIX` is set to `YES`, then `/cec/cstage?ecaction=ecsectview` is not invalidated. This is because the "`?`" in the file name is interpreted as a regular expression character to match zero or one occurrence of the character "`e`" it follows. If "`?`" is escaped, as in `/cec/cstage\?ecaction=ecsectview`, then all documents within the prefix `/cec/cstage?ecaction=ecsectview` are matched and invalidated.

`VALIDITY`

Required element in the invalidation message.

`LEVEL`

Optional attribute for the `VALIDITY` element.

Specify the validity level of the documents. The validity level ranges from 0 (for the least valid) to 9 (for the most valid).

The higher the validity level, the longer Oracle Web Cache serves documents stale from the cache before removing them. Oracle Web Cache serves documents with a low validity level for a short amount of time before removing them. After documents are removed, Oracle Web Cache retrieves new versions of the documents from the application Web servers.

A validity level of 0 means Oracle Web Cache will remove documents immediately. The default validity level is 0.

`REFRESHTIME`

Optional attribute for the `VALIDITY` element.

Specify the maximum time that documents can reside in the cache.

`COOKIE`

Optional element in the invalidation message.

`NAME`

Required attribute for the `COOKIE` element.

Specify the cookie name to invalidate documents based on the cookie. The name must match the cookie name of a multiple-version cacheability rule associated with this URL.

`VALUE`

Optional attribute for the `COOKIE` element.

Specify the value of the cookie.

`NONEXIST`

Optional attribute for the `COOKIE` element.

Specify `YES` to invalidate documents for requests without this cookie; specify `NO` to invalidate documents for requests with this cookie. `NO` is the default.

`HEADER`

Optional element in the invalidation message.

`NAME`

Required attribute for the `HEADER` element.

Specify the HTTP request header and its value to invalidate based on the request header. The name must match the header of a multiple-version cacheability rule associated with this URL.

`VALUE`

Optional attribute for the `HEADER` element.

Specify the value of the header.

See Also: "Invalidation Request DTD" for further information about invalidation request syntax

Invalidation responses are returned in the following format:

    <?xml version="1.0"?>
    <!DOCTYPE INVALIDATIONRESULT [
    <!ELEMENT INVALIDATIONRESULT (URL+)>
    <!ELEMENT URL   EMPTY>
    <!ATTLIST URL
              EXPR          CDATA   #REQUIRED
              ID            CDATA   #REQUIRED
              STATUS        CDATA   #REQUIRED
              NUMINV        CDATA   #REQUIRED
    >
    ]>
    <INVALIDATIONRESULT>
    <URL EXPR="URL" ID="ID" STATUS="status" NUMINV="number">
    </INVALIDATIONRESULT>

Table 8-2 Invalidation Response Syntax

#####

Invalidation Element/Attribute | Description
--- | ---
`URL` |
`EXP` | Specifies the URL of the document(s) that you requested to be invalidated
`ID` | Sequence number of all the URLs sent in the invalidation response. If there are multiple URLs specified in the invalidation message, then the sequence number starts at 1 for the first URL and sequentially numbers for each additional URL.
`STATUS` | Status of the invalidation. Status can be one of the following: `SUCCESS` for successful invalidations `URI NOT CACHEABLE` for documents not in the cache `URI NOT FOUND` for documents not found
`NUMINV` | Number of documents invalidated

See Also: "Invalidation Response DTD" for further information about invalidation response syntax

#### Manual Invalidation Using Oracle Web Cache Manager

Oracle Web Cache Manager provides an easy-to-use interface for invalidating cached objects. Under the covers, the message mechanics are much like the`telnet` example. The advantage of using Oracle Web Cache Manager is that the administrator is isolated from the intricacies of the HTTP and XML formats, and consequently, there is less chance for error. The administrator need only specify which objects to invalidate and how invalid those objects should be

To invalidate documents with Oracle Web Cache Manager:

1. Start Oracle Web Cache Manager.

   See Also: "Starting Oracle Web Cache Manager"

2. In the navigator pane, select Administering Oracle Web Cache > Cache Cleanup.

   The Cache Cleanup page appears in the right pane.

3. In the URL Scope section, specify which documents you want to invalidate:

   ALL | Select to remove all documents from the cache.
   URL or URL Prefix | Enter the URL of the document(s) contained within a specific URL or URL prefix pattern.
   apply to all documents matching prefix | Select to invalidate documents that match a prefix-based regular expression. This option limits the URL to a limited form of regular expression, whereby the URL path (from first "/" to the last "/") matches the prefix of the URL. For example, if you have the URL set to `/cec/cstage\?ecaction=viewitem`, then `/cec/` is the common prefix of the URLs to invalidate. Therefore, URLs such as `/cec/cstage?ecaction=viewitem&zip=94405` and `/cec/cstage?ecaction=viewitem&zip=94305` match, but `/usa/cec/cstage?ecaction=viewitem&zip=94209` does not match. The path section cannot contain any reserved regular expression characters. Reserved regular expression characters include periods (`.`), question marks (`?`), asterisks (`*`), brackets (`[]`), curly braces (`{}`), carats (`^`), dollar signs (`$`), or backslashes (`\`). However, the part after the path, which is usually the file name, can include regular expression characters. Deselect to only invalidate documents contained within the URL. This also means that the URL expression is interpreted literally.
   | EXAMPLE 1 Invalidation Intent: Invalidate `sample.gif` contained within the `/cec/cstage/graphic*/sample.gif` directory. URL Expression Entered: `/cec/cstage/graphic*/sample.gif` Result: If this option is not selected, then `/cec/cstage/graphic*/sample.gif` matches and Oracle Web Cache invalidates only `/cec/cstage/graphic*/sample.gif`. The "`*`" and "." characters are not interpreted as regular expression characters. If this option is selected, then `/cec/cstage/graphic*/sample.gif` is not invalidated. This is because the path includes "`*`", a reserved regular expression character that cannot be included in the path section, and the "." in the file name is interpreted as a regular expression character to match any character. If "`*`" is replaced with the exact directory name and the "." is escaped, as in `/cec/cstage/graphicsales/sample\.gif`, then `sample.gif` is invalidated.
   | EXAMPLE 2 Invalidation Intent: Invalidate documents contained in the `/cec/cstage?ecaction=ecsectview` directory. URL Expression Entered: `/cec/cstage?ecaction=ecsectview` Result: If this option is not selected, then `/cec/cstage?ecaction=ecsectview` will match and invalidate only `/cec/cstage?ecaction=ecsectview`. The "`?`" character is not interpreted as a regular expression character. If this option is selected, then `/cec/cstage?ecaction=ecsectview` is not invalidated. This is because the "`?`" in the file name is interpreted as a regular expression character to match zero or one occurrence of the character "`e`" it follows. If "`?`" is escaped, as in `/cec/cstage\?ecaction=ecsectview`, then all documents within the prefix `/cec/cstage?ecaction=ecsectview` are matched and invalidated.

4. In the Action section, specify how you want Oracle Web Cache to process invalid documents.

   Remove immediately | Select this option to have Oracle Web Cache mark documents as invalid and then remove them immediately. A document is refreshed from the application Web server when the cache receives the next request for it. Note: This is equivalent to a validity level of 0.
   Refresh on demand as application Web server capacity permits AND no later than <time> after submission | Select this option to have Oracle Web Cache mark documents as invalid and then refresh them based on application Web server capacity. Enter the maximum time in which the documents can reside in the cache. Optionally, select a validity level for the documents after they expire. Validity determines how long Oracle Web Cache will serve documents stale from the cache before marking them as invalid. The higher the validity level, the longer Oracle Web Cache serves documents stale from the cache before removing them. Oracle Web Cache serves documents with a low validity level for a short amount of time before removing them. After documents are removed, Oracle Web Cache retrieves new versions of the documents from the application Web servers.

   Note: Performance assurance heuristics apply when you configure documents to be refreshed based on when the application Web servers can refresh them; performance assurance heuristics do not apply when documents are immediately removed.

5. Choose Submit.

#### Automatic Invalidation Using Database Triggers

Database triggers are procedures that are stored in the database and activated ("fired") when specific conditions occur, such as adding a row to a table. You can use triggers to send invalidation messages. To this do, use the `UTL_TCP` Oracle supplied package to send invalidation messages through database triggers.

See Also: `README.examples.txt` in the `$ORACLE_HOME/webcache/examples` directory on UNIX and `ORACLE_HOME``\webcache\examples` directory on Windows NT for further information about using the `cre_invalid_trig.sql` script to create a database trigger and the `utl_proc.sql` script to demonstrate invalidation with database triggers PL/SQL User's Guide and Reference

#### Automatic Invalidation Using Scripts

Many Web sites use scripts for uploading new content to databases and file systems. A large online book retailer, for instance, might run a PERL script once a day in order to bulk load new book listings and price changes into its catalog database. The retailer would want the price changes and availability listings to be reflected in the item views and search results currently cached in Oracle Web Cache. To achieve this, the PERL script can be modified such that when the bulk loading operation has completed, the script will send an invalidation message to the cache invalidating all catalog views and search results. (Note that the invalidation message need not list every individual search page or item view that might be effected by the data change.) The performance assurance feature of Oracle Web Cache enables administrators to use broad brush strokes when invalidating content, making it safe to invalidate all catalog content even if only a fraction of that content has changed.

#### Automatic Invalidation Using Applications

Invalidation messages can also originate from a Web site's underlying application logic or from the content management application used to design Web pages. Oracle Web Cache ships with invalidation Java source that you can link with your applications for automatically generating invalidation messages.

See Also: `README.examples.txt` in the `$ORACLE_HOME/webcache/examples` directory on UNIX and `ORACLE_HOME``\webcache\examples` directory on Windows NT for further information about using the `Invalidate.java` file

### Invalidation Examples

These examples require utilizing the `POST` method which also requires sending the number of bytes (or characters) in the `content_length:` `#bytes` portion of the header. Please note that one carriage return is required after the `content_length:` `#bytes` line and before the XML message or `BODY` information.

#### Example: Invalidating One Document

Invalidation message:

    <?xml version="1.0" ?>

    <!DOCTYPE INVALIDATION SYSTEM "internal:///invalidation.dtd">
    <INVALIDATION>
        <URL EXP="/images/logo.gif" PREFIX="NO">
            <VALIDITY LEVEL="1"/>
        </URL>
    </INVALIDATION>

Invalidation response:

    <?xml version="1.0"?>
    <!DOCTYPE INVALIDATIONRESULT [
    <!ELEMENT INVALIDATIONRESULT (URL+)>
    <!ELEMENT URL   EMPTY>
    <!ATTLIST URL
              EXPR          CDATA   #REQUIRED
              ID            CDATA   #REQUIRED
              STATUS        CDATA   #REQUIRED
              NUMINV        CDATA   #REQUIRED
    >
    ]>
    <INVALIDATIONRESULT>
    <URL EXPR="/images/logo.gif" ID="1" STATUS="SUCCESS" NUMINV="1">
    </INVALIDATIONRESULT>

#### Example: Invalidating a Subtree of Documents

Invalidation message:

    <?xml version="1.0"?>

    <!DOCTYPE INVALIDATION SYSTEM "internal:///invalidation.dtd">
    <INVALIDATION>
        <URL EXP="/images/" PREFIX="YES">
            <VALIDITY LEVEL="1" REFRESHTIME="60"/>
        </URL>
    </INVALIDATION>

Invalidation response:

    <?xml version="1.0"?>
    <!DOCTYPE INVALIDATIONRESULT [
    <!ELEMENT INVALIDATIONRESULT (URL+)>
    <!ELEMENT URL   EMPTY>
    <!ATTLIST URL
              EXPR          CDATA   #REQUIRED
              ID            CDATA   #REQUIRED
              STATUS        CDATA   #REQUIRED
              NUMINV        CDATA   #REQUIRED
    >
    ]>
    <INVALIDATIONRESULT>
    <URL EXPR="/images/" ID="1" STATUS="SUCCESS" NUMINV="125">
    </INVALIDATIONRESULT>

#### Example: Invalidating All Documents for a Web Site

Invalidation message:

    <?xml version="1.0"?>

    <!DOCTYPE INVALIDATION SYSTEM "internal:///invalidation.dtd">
    <INVALIDATION>
        <URL EXP="/" PREFIX="YES">
            <VALIDITY LEVEL="0"/>
        </URL>
    </INVALIDATION>

Invalidation response:

    <?xml version="1.0"?>
    <!DOCTYPE INVALIDATIONRESULT [
    <!ELEMENT INVALIDATIONRESULT (URL+)>
    <!ELEMENT URL   EMPTY>
    <!ATTLIST URL
              EXPR          CDATA   #REQUIRED
              ID            CDATA   #REQUIRED
              STATUS        CDATA   #REQUIRED
              NUMINV        CDATA   #REQUIRED
    >
    ]>
    <INVALIDATIONRESULT>
    <URL EXPR="/" ID="1" STATUS="SUCCESS" NUMINV="5347">
    </INVALIDATIONRESULT>

## Evaluating Event Logs

Oracle Web Cache events and errors are stored in an event log. The event log can help you determine what documents or objects have been inserted into the cache. It can also identify listening port conflicts or startup and shutdown issues. The event log has a file name of `event_log` and is stored in `$ORACLE_HOME/webcache/logs` on UNIX and O `RACLE_HOME``\webcache\logs` on Windows NT.

See Also: Appendix D, "Event Log Messages" for descriptions of the most common event log messages

### Format of the Event Log File

Events are formatted into the following fields:

    Timestamp   Information/Warning/Error   Message

### Event Log Examples

#### Example: Event Log with Startup Entries

Figure 8-2 shows an event log excerpt with successful startup entries.

#### Figure 8-2 Event Log with Successful Startup Entries

    19/Sep/2000:10:20:56 -0500 -- Information: Max Connect Count exceeds compile
    time limit - defaulting to
    connect limit: ( 854 )
    19/Sep/2000:10:20:57 -0500 -- Information: Listening on ADMINISTRATION port 5000
    address 0.0.0.0
    19/Sep/2000:10:20:57 -0500 -- Information: The admin server started successfully
    19/Sep/2000:10:20:57 -0500 -- Information: Max Connect Count exceeds compile
    time limit - defaulting to
    connect limit: ( 854 )
    19/Sep/2000:10:20:57 -0500 -- Information: Listening on NORM port 1100 address
    0.0.0.0
    19/Sep/2000:10:20:57 -0500 -- Information: Listening on INVALIDATION port 5001
    address 0.0.0.0
    19/Sep/2000:10:20:57 -0500 -- Information: Listening on STATISTICS port 5002
    address 0.0.0.0
    19/Sep/2000:10:20:58 -0500 -- Information: The cache server started successfully
    19/Sep/2000:10:20:58 -0500 -- Information: The cache server is started by the
    admin server at startup

#### Example: Event Log with Unsuccessful Startup Entries

Figure 8-3 shows an event log excerpt with unsuccessful startup events. Oracle Web Cache is unable to listen on port 1100, because it is already in use. This can occur if Oracle Web Cache is already running and listening on that port or another application is using that port.

#### Figure 8-3 Event Log with an Unsuccessful Startup

    14/Sep/2000:16:37:41 -0800 -- Error: A failure occurred ( Address already in use
    ) when assigning a port ( domain: <NONE>, address: 0.0.0.0, port: 1100 ). Change
    PORT attribute of the LISTEN element in the configuration file to a suitable
    unused port.
    14/Sep/2000:16:37:41 -0800 -- Error: Failed to start the server.
    14/Sep/2000:16:37:41 -0800 -- Error: The server could not initialize
    14/Sep/2000:16:37:41 -0800 -- Information: The server is exiting

#### Example: Event Log with an Invalidation Entry

Figure 8-4 shows an event log excerpt with an event associated with an invalidation request for the removal of document `personal.htm`.

#### Figure 8-4 Event Log with an Invalidation Entry

    30/Sep/2000:22:52:52 -0500 -- Information: <Invalidation>1 URLs with prefix
    personal.htm have been successfully invalidated.

#### Example: Event Log with an Invalidation Message Error

Figure 8-5 shows an event log excerpt with an XML invalidation message error. In this example, Oracle Web Cache is unable to parse the message.

#### Figure 8-5 Event Log with an Invalidation Message Error

    Example: Errors in the XML parsing. Note: The configuration files and
    invalidation files use XML
    files.
    19/Sep/2000:10:55:26 -0500 -- Error: Invalidation XML Buffer cannot be parsed.
    19/Sep/2000:10:55:26 -0500 -- Error: XML parsing error.

#### Example: Event Log with Shutdown Entries

Figure 8-6 shows an event log excerpt with typical shutdown entries.

#### Figure 8-6 Event Log with Shutdown Entries

    14/Sep/2000:11:16:55 -0700 -- Information: SIGTERM caught - program will shut
    down once all connections are complete.
    14/Sep/2000:11:16:55 -0800 -- Information: SIGTERM caught - program will shut
    down once all connections are complete.
    14/Sep/2000:11:16:55 -0700 -- Information: The server is exiting
    14/Sep/2000:11:16:55 -0800 -- Information: The server is exiting

### Finding Errors in the Event Log

To list just the errors in the event log, use `grep` on UNIX. For example:

    grep  " Error:" error*

To list the errors by the current day, enter `grep " Error:" event_log "dd/mon/yyyy"`. For example:

    grep  " Error:" event_log | grep "19/Sep/2000"

To list errors by the current day and hour, enter `grep " Error:" event_log "dd/mon/yyyy:hh"`.

### Configuring Event Logs

To establish event log configuration settings:

1. Start Oracle Web Cache Manager.

   See Also: "Starting Oracle Web Cache Manager"

2. In the navigator pane, select Administering Oracle Web Cache > Event Logging.

   The Event Logging page appears in the right pane.

3. In the Event Logging page, choose Edit

   The Change Options for Event Logging dialog box appears.

4. In Logging Time Format, select either Local or GMT (Greenwich Mean Time) to modify the time stamp style associated with entries in the event log file.

   Note: Oracle Corporation recommends using GMT whenever possible. Local can be CPU-intensive, because of the conversion process from GMT to Local time. This conversion process is supplied by the operation system. As such, Oracle Web Cache has no mechanism to improve the performance of the conversion process.

5. In Verbose Logging, select either No to log typical events or Yes to log typical events, plus application Web server events. Verbose event logs are used for debugging purposes. Therefore, select Yes if recommended by Oracle Support Services.

6. Choose Submit.

7. Apply changes and restart Oracle Web Cache:

   1. In the Oracle Web Cache Manager main window, choose Apply Changes.

   1. In the navigator pane, select Administering Oracle Web Cache > Web Cache Operations.

      The Oracle Web Cache Operations page appears in the right pane.

   2. In the Oracle Web Cache Operations page, choose Stop and then Start to restart Oracle Web Cache.

## Evaluating Access Logs

Each Web site that Oracle Web Cache supports has its own access log. An access log contains information about the HTTP requests sent to Oracle Web Cache for a Web site. The access log has a file name of `access_log` and is stored by default in `$ORACLE_HOME/webcache/logs` on UNIX and O `RACLE_HOME``\webcache\logs` on Windows NT. Note that Oracle Web Cache uses buffered logging for the access log, that is, it writes to the access log after the buffer is full.

### Format of the Access Log File

You can configure the content of the access log file by defining the fields to appear for each HTTP request event. These fields are a part of the Extended LogFile Format (XLF), which is a superset of the Common LogFile Format (CLF).

Table 8-3 lists the XLF fields you can select.

##### Table 8-3 XLF Fields for Access Logs

Field | Description
--- | ---
`cs(User-Agent)` | Information about the user agent originating the request
`cs(Referer)` | Allows the client to specify the address (URI) of the resource from which the Request-URI was obtained
`c-auth-id` | Username if the request contained an attempt to authenticate
`bytes` | Content-length of the transferred document
`date` | Date at which the transaction completed
`time` | Time at which the transaction completed
`time-taken` | Amount of time taken (in seconds) for transaction to complete
`c-ip` | Client's IP address and port
`s-ip` | Oracle Web Cache's IP address and port
`sc-method` | Oracle Web Cache-to-client HTTP request method (`GET`, `POST`, or others)
`sc-status` | Oracle Web Cache-to-client HTTP status code: 1xx range messages are informational. 2xx range messages indicate success. 3xx range messages indicate redirection, indicating that further action must be taken in order to complete the request. 4xx range messages indicate a client error. 5xx range messages indicate a Oracle Web Cache error. See Also: `http://www.ietf.org/rfc/rfc2616.txt` for further information about HTTP status codes
`cs-uri` | Client-to-Oracle Web Cache URI
`cs-uri_stem` | Client-to-Oracle Web Cache stem portion of URI, omitting the query
`cs-uri-query` | Client-to-Oracle Web Cache query portion of URI, omitting the stem
`prefix``(``header``)` | `header` is a HTTP header field and `prefix` is one of the following: `c`: Client `s`: Oracle Web Cache `r`: Remote `cs`: Client-to-Oracle Web Cache `sc`: Oracle Web Cache-to-client

If no fields are specified, then the following default CLF fields are used in the access log file:

`c-ip cauth-id [clf-date] "request line" sc-status bytes`

### Access Log Examples

Figure 8-7 shows an example access log using the default CLF fields:

`c-ip cauth-id [clf-date] "request line" sc-status bytes`

The `"request line"` is represented by the `"GET ...HTTP/1.0"` portion of the request. The `"request line"` enables you to determine what is being accessed and the following `sc_status`, or HTTP status code, reports if the request was successfully completed.

#### Figure 8-7 Access Log

    138.2.213.146 - - [19/Sep/2000:10:27:42 -0500] "GET /~ssandrew/personal.htm
    HTTP/1.0" 200 2438
    138.2.213.146 - - [19/Sep/2000:10:27:54 -0500] "GET
    /~ssandrew/personal.htm?UserName=Bob HTTP/1.0"
    200 2438
    138.2.213.146 - - [19/Sep/2000:10:47:30 -0500] "GET /~ssandrew/count.sh
    HTTP/1.0" 403 289
    138.2.213.146 - - [19/Sep/2000:10:47:34 -0500] "GET /~ssandrew/sbin/count.sh
    HTTP/1.0" 200 321
    138.2.213.146 - - [19/Sep/2000:10:47:41 -0500] "GET /sbin/count.sh HTTP/1.0" 200
    321
    138.2.213.146 - - [19/Sep/2000:11:34:23 -0500] "GET /cache.htm HTTP/1.0" 200 250
    138.2.213.146 - - [19/Sep/2000:11:38:23 -0500] "GET /cache.htm HTTP/1.0" 304 0
    138.2.213.146 - - [19/Sep/2000:11:38:48 -0500] "GET /cache.htm HTTP/1.0" 304 0
    206.223.27.37 - - [19/Sep/2000:15:14:29 -0500] "GET
    /~ssandrew/personal.htm?UserName=Joe HTTP/1.0"
    200 2438
    206.223.27.37 - - [19/Sep/2000:15:17:12 -0500] "GET
    /~ssandrew/personal.htm?UserName=Shehzaad
     HTTP/1.0" 200 438
    144.25.223.39 - - [19/Sep/2000:15:30:34 -0500] "GET /htdocs/coelist.html
    HTTP/1.0" 200 4219
    144.25.223.39 - - [19/Sep/2000:15:30:34 -0500] "GET /images/redheaderbanner.gif
    HTTP/1.0" 200 1226
    138.2.213.146 - - [19/Sep/2000:10:49:44 -0500] "GET /pls/coe/find_via_post
    HTTP/1.0" 200 1119
    138.2.213.146 - - [19/Sep/2000:10:49:44 -0500] "GET /ows-img/chalk.jpg HTTP/1.0"
    404 284
    130.35.35.21 - - [20/Sep/2000:00:36:35 -0500] "GET /images/support.jpg HTTP/1.0"
    206 3106
    130.35.35.21 - - [20/Sep/2000:00:36:35 -0500] "GET /images/ani_coe.gif HTTP/1.0"
    206 73118

#### Example: Access Log with Reload Entries

Figure 8-8 shows an access log excerpt in which there are two Web browser reloads, followed by two shift reloads, and two more reloads.

#### Figure 8-8 Access Log with Reload Entries

    138.2.213.146 - - [19/Sep/2000:11:04:24 -0500] "GET /cache.htm HTTP/1.0" 200 250
    138.2.213.146 - - [19/Sep/2000:11:04:26 -0500] "GET /cache.htm HTTP/1.0" 200 250
    138.2.213.146 - - [19/Sep/2000:11:29:24 -0500] "GET /cache.htm HTTP/1.0" 304 0
    138.2.213.146 - - [19/Sep/2000:11:29:25 -0500] "GET /cache.htm HTTP/1.0" 304 0
    138.2.213.146 - - [19/Sep/2000:11:29:30 -0500] "GET /cache.htm HTTP/1.0" 200 250
    138.2.213.146 - - [19/Sep/2000:11:29:35 -0500] "GET /cache.htm HTTP/1.0" 200 250

#### Example: Access Log with Wrong Path Entry

Figure 8-9 shows an access log excerpt in which a browser requested the wrong path. This is indicated by HTTP status code 403. The browser then requested the correct path. This is indicated by HTTP status code 200.

#### Figure 8-9 Access Log with Wrong Path Entry

    38.2.213.146 - - [19/Sep/2000:10:47:30 -0500] "GET /~ssandrew/count.sh HTTP/1.0"
    403 289
    138.2.213.146 - - [19/Sep/2000:10:47:34 -0500] "GET /~ssandrew/sbin/count.sh
    HTTP/1.0" 200 321

#### Example: Access Log with Status Code 404 Entry

Figure 8-10 shows an access log excerpt in which a Oracle Web Cache cannot find any objects matching the requested URL `/ows-img/chalk.jpg`. This indicated by HTTP status code 404.

#### Figure 8-10 Access Log with HTTP Status Code 404 Entry

    138.2.213.146 - - [19/Sep/2000:10:49:44 -0500] "GET /pls/coe/find_via_post
    HTTP/1.0" 200 1119
    138.2.213.146 - - [19/Sep/2000:10:49:44 -0500] "GET /ows-img/chalk.jpg HTTP/1.0"
    404 284

#### Example: Access Log with Status Code 304 Entry

Figure 8-11 shows an access log excerpt in which the first entry shows a Web browser request for `/cache.htm` being successfully completed. The second and third entries return a HTTP status code of 304, indicating that document has not been modified and does not need to be returned again.

#### Figure 8-11 Access Log with HTTP Status Code 304 Entry

    138.2.213.146 - - [19/Sep/2000:11:34:23 -0500] "GET /cache.htm HTTP/1.0" 200 250
    138.2.213.146 - - [19/Sep/2000:11:38:23 -0500] "GET /cache.htm HTTP/1.0" 304 0
    138.2.213.146 - - [19/Sep/2000:11:38:48 -0500] "GET /cache.htm HTTP/1.0" 304 0

### Configuring Access Logs

To enable access logging:

1. Start Oracle Web Cache Manager.

   See Also: "Starting Oracle Web Cache Manager"

2. In the navigator pane, select Administering Web Sites > Access Logging.

   The Access Logs page appears in the right pane.

3. In the Access Logs page, choose Edit

   The Change Options for Access Logs dialog box appears.

4. In Logging Enabled, select YES.

5. In the Logging Directory field, enter the directory path where you want the log file written.

6. In Logging Time Format, select either Local or GMT (Greenwich Mean Time) to modify the time stamp style associated with entries in the access log file.

   Note: Oracle Corporation recommends using GMT whenever possible. Local can be CPU-intensive, because of the conversion process from GMT to Local time. This conversion process is supplied by the operation system. As such, Oracle Web Cache has no mechanism to improve the performance of the conversion process.

7. From the Rollover Frequency list, select how often you want to change the frequency at which Oracle Web Cache will save current log information to `access_log.``yyyymmdd` and write new log information to `access_log`. If you have a high-volume site, increase the frequency.

8. In the XLF Fields field, enter XLF fields to log. Separate fields by a space.

9. Choose Submit.

10. Apply changes and restart Oracle Web Cache:

    1. In the Oracle Web Cache Manager main window, choose Apply Changes.

    1. In the navigator pane, select Administering Oracle Web Cache > Web Cache Operations.

       The Oracle Web Cache Operations page appears in the right pane.

    2. In the Oracle Web Cache Operations page, choose Stop and then Start to restart Oracle Web Cache.

To disable access logging:

1. Start Oracle Web Cache Manager.

   See Also: "Starting Oracle Web Cache Manager"

2. In the navigator pane, select Administering Web Sites > Access Logging.

   The Access Logs page appears in the right pane.

3. In the Access Logs page, choose Edit

   The Change Options for Access Logs dialog box appears.

4. In Logging Enabled, select NO.

5. Choose Submit.

6. Apply changes and restart Oracle Web Cache:

   1. In the Oracle Web Cache Manager main window, choose Apply Changes.

   1. In the navigator pane, select Administering Oracle Web Cache > Web Cache Operations.

      The Oracle Web Cache Operations page appears in the right pane.

   2. In the Oracle Web Cache Operations page, choose Stop and then Start to restart Oracle Web Cache.

| Copyright © 1996-2001 Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index