8
Administering Oracle Web Cache

This chapter explains how to perform administrative tasks to Oracle Web Cache.

This chapter 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, you must stop and restart Oracle Web Cache. To start, stop, or restart Oracle Web Cache, use either Oracle Web Cache Manager or the webcachectl utility.

When you stop Oracle Web Cache, all objects are cleared from the cache. In addition, all statistics are cleared.

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. 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...

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, then 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, then Oracle Web Cache is already running. Oracle Web Cache admin server is running (pid=pid). Oracle Web Cache cache server is running (pid=pid). 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, Oracle Web Cache can also be started through the Control Panel:

1. Select the Services icon in the Control Panel window.

   The Services window appears.

2. Select the OracleHOME_NAMEWebCacheAdmin service to start the admin server, and then choose Start to start the service.

3. Select the OracleHOME_NAMEWebCache service to start the cache server, and then choose Start to start the service.

4. 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 on HTTP.

To change the default port number or protocol:

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.

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

      The Change Invalidation/Statistics Port dialog box appears.

   3. In the Invalidation Port field, enter the new port.

   4. From the Protocol list, select either HTTP or HTTPS to accept invalidation requests from one of the following URLs:

      http://web_cache_hostname:http_port 
      https://web_cache_hostname:https_port 
      

Note: If you enable HTTPS for invalidation requests, you cannot use the Oracle Web Cache Manager interface to send the requests. You must submit requests through the URL.

5. Choose Submit.

3. Apply changes and restart Oracle Web Cache:
   1. In the Oracle Web Cache Manager main window, choose Apply Changes.

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

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

   3. 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 messages written in Extensible Markup Language (XML) syntax. The contents of the XML message body tell 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 owcag025.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 an 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 web_cache_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 encoding of invalidator:invalidator_password> 
   content-length:#bytes
   
   

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

Authorization: BASIC aW52YWxpZGF0b3I6YWRtaW4= 

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

See Also: http://rfc.net/rfc1421.html for information about password base64 encoding "Task 2: Modify Security Settings" for further information about changing the invalidation password

Enter one carriage return.

Send the invalidation message with XML syntax.

Invalidation Message

Note: Oracle Web Cache continues to support invalidation messages sent in the following release 1.0 format: <?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>

Use the following syntax to invalidate document(s) contained within an exact URL that includes the complete path and file name:

<?xml version="1.0" ?>
<!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATION VERSION="WCS-1.0">
   <OBJECT>
     <BASICSELECTOR URI="URL"/>
     <ACTION REMOVALTTL="TTL"/>
   </OBJECT>
</INVALIDATION>

Use the following syntax to invalidate document(s) based on more advanced invalidation selectors:

<?xml version="1.0" ?>
<!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATION VERSION="WCS-1.0">
  <OBJECT>
    <ADVANCEDSELECTOR URIPREFIX="prefix"
                      URIEXP="URL_expression">
                      METHOD="HTTP_request_method">
      <COOKIE NAME="cookie_name" VALUE="value"/>
      <HEADER NAME="HTTP_request_header" VALUE="value"/>
    </ADVANCEDSELECTOR>
    <ACTION REMOVALTTL="TTL"/>
  </OBJECT>
</INVALIDATION>

Table 8-1 describes the invalidation message elements and attributes.

Table 8-1 Invalidation Message Syntax

Invalidation Element/Attribute	Description
OBJECT	Required element in the invalidation message. You can specify more than one OBJECT element in the message.
BASICSELECTOR
	URI: Required attribute of the BASICSELECTOR element. Specify the URL of the document(s) to be invalidated. Include the complete path and file name.
ADVANCEDSELECTOR
	URIPREFIX Required attribute for the ADVANCEDSELECTOR element. Specify the prefix path (beginning and ending with "/") of the document(s) to be invalidated. The prefix is interpreted literally, including reserved regular expression characters. Reserved regular expression characters include periods (.), question marks (?), asterisks (*), brackets ([]), curly braces ({}), carets (^), dollar signs ($), and backslashes (\). URIEXP Optional attribute for the ADVANCEDSELECTOR element. Specify the URL of the document(s) to be invalidated underneath the URIPREFIX. If no value is entered, then everything under the URIPREFIX will be matched. Regular expression characters are permitted.To interpret these characters literally, escape them with a backslash (\). METHOD Optional attribute for the ADVANCEDSELECTOR element. Specify HTTP request method (GET or POST) of the document(s) to be invalidated. BODYEXP Optional attribute for the ADVANCEDSELECTOR element. If the METHOD is POST, specify HTTP POST body message of the document(s) to be invalidated.
	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 a cookie name associated with a cacheability rule or session/personalized attribute caching rule for the URL. VALUE: Optional attribute for the COOKIE element. Specify the value of the cookie. If no value is present, then only documents with the named cookie but without value are invalidated. 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 header must match a header associated with a cacheability rule for the URL. VALUE: Optional attribute for the HEADER element. Specify the value of the header.
ACTION	Required element in the invalidation message
REMOVALTTL	Optional attribute for the ACTION element Specify the maximum time that documents can reside in the cache before they are invalidated. The default is 0 seconds.

Note: The following special XML characters must be escaped in the URI, URIPREFIX, and URIEXP fields: ampersand (&) with "&amp;", greater than sign (>) with "&gt", less than sign (<) with "&lt", double quotes (") with "&quot", and single quotes (') with "&apos;".

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

Invalidation Response

Invalidation responses are returned in the following format for BASICSELECTOR invalidation messages:

<?xml version="1.0"?> 
<!DOCTYPE INVALIDATIONRESULT SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATIONRESULT VERSION="WCS-1.0">
   <OBJECTRESULT>
     <BASICSELECTOR URI="URL">
     </BASICSELECTOR>
     <RESULT ID="ID" STATUS="status" NUMINV="number"/>
   </OBJECTRESULT>
</INVALIDATIONRESULT>

Invalidation responses are returned in the following format for ADVANCEDSELECTOR invalidation messages:

<?xml version="1.0"?> 
<!DOCTYPE INVALIDATIONRESULT SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATIONRESULT VERSION="WCS-1.0">
   <OBJECTRESULT>
     <ADVANCEDSELECTOR URIPREFIX="prefix"
                      URIEXP="URL_expression">
                      METHOD="HTTP_request_method">
      <COOKIE NAME="cookie_name" VALUE="value"/>
      <HEADER NAME="HTTP_request_header" VALUE="value"/>
     </ADVANCEDSELECTOR>
     <RESULT ID="ID" STATUS="status" NUMINV="number"/>
   </OBJECTRESULT>
</INVALIDATIONRESULT>

Table 8-2 describes the invalidation response syntax. Note that BASICSELECTOR and ADVANCEDSELECTOR are described in Table 8-1.

Table 8-2 Invalidation Response Syntax

Invalidation Element/Attribute	Description
RESULT	Invalidation result
ID	Sequence number of all the invalidation objects sent in the invalidation response. If there are multiple selectors specified in the invalidation message, then the sequence number starts at 1 for the first URL and continues sequentially for each additional selector.
STATUS	Status of the invalidation. Status can be one of the following: SUCCESS for successful invalidations URI NOT CACHEABLE for documents that are not cacheable 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. 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. Specify which documents to invalidate:

   Note: When using Oracle Web Cache Manager, the following characters are permitted in the Enter exact URL for removal, URL Path Prefix, and URL Regular Expression fields: ampersand (&), greater than sign (>), less than sign (<), double quotes ("), and single quotes (').

   Basic Invalidation
   Remove all cached documents.	Select to remove all documents from the cache.
   Enter exact URL for removal	Specify the URL of the document(s) to be invalidated. Include the complete path and file name.
   Advanced Invalidation
   URL Path Prefix	Required. Specify the prefix path (beginning and ending with "/") of the document(s) to be invalidated. The prefix is interpreted literally, including reserved regular expression characters. These characters include periods (.), question marks (?), asterisks (*), brackets ([]), curly braces ({}), carets (^), dollar signs ($), and backslashes (\).
   URL Regular Expression	Optional. Specify the URL of the document(s) to be invalidated underneath the URL Path Prefix. If no value is entered, then everything under the URL Path Prefix will be matched. Regular expression characters are permitted. To interpret these characters literally, escape them with a backslash (\).
   HTTP Method	Optional. Select the HTTP request method (GET or POST) of the document(s) to be invalidated.
   POST Body Expression	Optional. If POST is selected for the HTTP Method, enter the HTTP body message of the document(s) to be invalidated.
   Cookie Information	Optional. On UNIX, select the cookie name for the document(s) to be invalidated from the list, and enter its value in the Value field. On Windows, enter the cookie name for the document(s) to be invalidated in the Name field, and enter its value in the Value field.
   Header Information	Optional. Enter the HTTP request header for the document(s) to be invalidated in the Name field, and enter its value in the Value field. The name must match the header associated with a cacheability rule associated for the URL.

4. In the Action section, specify how 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.
   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.

   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.

   Oracle Web Cache processes the invalidation request, and returns a Cache Cleanup dialog box the shows the invalidation status and the number of objects invalidated. For example:

   
   
   Text description of the illustration invalid.gif

   For prefix-based invalidations that require Oracle Web Cache to traverse a complex directory structure, invalidation can take some time. Therefore, do not choose Submit again until the Cache Cleanup Result dialog box appears. Creating a queue of invalidation requests can degrade the performance of Oracle Web Cache.

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 do this, use the UTL_TCP Oracle supplied package to send invalidation messages through database triggers.

See Also: readme.examples.html in the $ORACLE_HOME/webcache/examples directory on UNIX and ORACLE_HOME\webcache\examples directory on Windows 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 Oracle PL/SQL documentation

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 or C source that you can link with your applications for generating invalidation messages.

See Also: readme.examples.html in the $ORACLE_HOME/webcache/examples directory on UNIX and ORACLE_HOME\webcache\examples directory on Windows for further information about using the Invalidate.java or invalidate.c file

Invalidation Examples

This section contains the following invalidation message examples:

• Example: Invalidating One Document

• Example: Invalidating Multiple Objects

• Example: Invalidating a Subtree of Documents

• Example: Invalidating All Documents for a Web Site

• Example: Invalidating Documents with the Prefix

The examples in this section 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

The following message invalidate file /images/logo.gif:

<?xml version="1.0" ?>
<!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATION VERSION="WCS-1.0">
   <OBJECT>
     <BASICSELECTOR URI="/images/logo.gif"/>
     <ACTION/>
   </OBJECT>
</INVALIDATION>

Invalidation response:

<?xml version="1.0"?> 
<!DOCTYPE INVALIDATIONRESULT SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATIONRESULT VERSION="WCS-1.0">
   <OBJECTRESULT>
     <BASICSELECTOR URI="/images/logo.gif"/>
     <RESULT ID="1" STATUS="SUCCESS" NUMINV="1"/>
     </OBJECTRESULT>
</INVALIDATIONRESULT>

The following message invalidates a document exactly matching /contacts/contacts.html using the BASICSELECTOR element:

<?xml version="1.0" ?>
<!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATION VERSION="WCS-1.0">
  <OBJECT>
    <BASICSELECTOR URI="/contacts/contacts.html"/>
    <ACTION REMOVALTTL="0"/>
  </OBJECT>
</INVALIDATION>
    

This is equivalent to the following using the ADVANCEDSELECTOR element:

<?xml version="1.0" ?>
<!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATION VERSION="WCS-1.0">
  <OBJECT>
    <ADVANCEDSELECTOR URIPREFIX="/contacts/"
                      URIEXP="^/contacts/contacts\.html$"/>
    <ACTION REMOVALTTL="0"/>
  </OBJECT>
</INVALIDATION>
    

The ADVANCEDSELECTOR element uses the URIPREFIX attribute. This attribute is used to traverse the directory structure. The quicker invalidation reaches the right tree level, the quicker the invalidation process is done. The message with the BASICSELECTOR element is the more efficient of the two examples because there is no directory structure traversal involved.

Example: Invalidating Multiple Objects

The following message invalidates two different objects, summary.jsp and summary.gif:

<?xml version="1.0" ?>
<!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATION VERSION="WCS-1.0">
  <OBJECT>
    <ADVANCEDSELECTOR URIPREFIX="/global/sales/" 
                      URIEXP="summary.jsp\?year=2001">
      <COOKIE NAME="group" VALUE="asia" />
    </ADVANCEDSELECTOR>
    <ACTION />
  </OBJECT>
  <OBJECT>
    <ADVANCEDSELECTOR URIPREFIX="/image/" 
                      URIEXP="summary.*\.gif$" />
    <ACTION />
  </OBJECT>
</INVALIDATION>

Invalidation response:

<?xml version="1.0"?> 
<!DOCTYPE INVALIDATIONRESULT SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATIONRESULT VERSION="WCS-1.0">
  <OBJECTRESULT>
    <ADVANCEDSELECTOR URIPREFIX="/global/sales/" 
URIEXP="summary.jsp\?year=2001" >
      <COOKIE  NAME="group"  VALUE="asia"  />
    </ADVANCEDSELECTOR>
    <RESULT ID="1" STATUS="SUCCESS" NUMINV="2"/>
  </OBJECTRESULT>
  <OBJECTRESULT>
    <ADVANCEDSELECTOR URIPREFIX="/image/"  URIEXP="summary.*\.gif$" >
    </ADVANCEDSELECTOR>
    <RESULT ID="2" STATUS="SUCCESS" NUMINV="14"/>
  </OBJECTRESULT>
</INVALIDATIONRESULT>

Example: Invalidating a Subtree of Documents

The following message invalidates all documents under the /images/ directory:

<?xml version="1.0" ?>
<!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATION VERSION="WCS-1.0">
   <OBJECT>
     <ADVANCEDSELECTOR URIPREFIX="/images/"/>
     <ACTION REMOVALTTL="0"/>
   </OBJECT>
</INVALIDATION>

Invalidation response:

<?xml version="1.0"?> 
<!DOCTYPE INVALIDATIONRESULT SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATIONRESULT VERSION="WCS-1.0">
   <OBJECTRESULT>
     <ADVANCEDSELECTOR URIPREFIX="/images/"/>
     <RESULT ID="1" STATUS="SUCCESS" NUMINV="125"/>
   </OBJECTRESULT>
</INVALIDATIONRESULT>

The following message invalidates all documents under /contacts/ directory whose file names ends in .html and uses cookie name cust with a value of oracle:

<?xml version="1.0" ?>
<!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATION VERSION="WCS-1.0">
  <OBJECT>
    <ADVANCEDSELECTOR URIPREFIX="/contacts/"
                      URIEXP="\.html$">
      <COOKIE NAME="cust" VALUE="oracle"/>
    </ADVANCEDSELECTOR>
    <ACTION REMOVALTTL="0"/>
  </OBJECT>
</INVALIDATION>

Invalidation response:

<?xml version="1.0"?> 
<!DOCTYPE INVALIDATIONRESULT SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATIONRESULT VERSION="WCS-1.0">
   <OBJECTRESULT>
     <ADVANCEDSELECTOR URIPREFIX="/contacts"/>
                      URIEXP="\.html$">
      <COOKIE NAME="cust" VALUE="oracle"/>
     </ADVANCEDSELECTOR>
      <RESULT ID="1" STATUS="SUCCESS" NUMINV="45"/>
   </OBJECTRESULT>
</INVALIDATIONRESULT>

Example: Invalidating All Documents for a Web Site

The following message invalidates all documents under /.

<?xml version="1.0" ?>
<!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATION VERSION="WCS-1.0">
   <OBJECT>
     <ADVANCEDSELECTOR URIPREFIX="/"/>
     <ACTION REMOVALTTL="0"/>
   </OBJECT>
</INVALIDATION>

Invalidation response:

<?xml version="1.0"?> 
<!DOCTYPE INVALIDATIONRESULT SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATIONRESULT VERSION="WCS-1.0">
   <OBJECTRESULT>
     <ADVANCEDSELECTOR URIPREFIX="/"/>
      <RESULT ID="1" STATUS="SUCCESS" NUMINV="17"/>
   </OBJECTRESULT>
</INVALIDATIONRESULT>

Example: Invalidating Documents with the Prefix

To better understand the relationship of the URIPREFIX and URIEXP attributes, consider the examples that follow.

To invalidate sample.gif files within /cec/cstage/graphic* directories, use the following syntax:

<ADVANCEDSELECTOR URIPREFIX="/cec/cstage/"
   URIEXP="graphic.*/sample\.gif">
</ADVANCEDSELECTOR>

Note that ".*" in "graphic.*/sample\.gif" are regular expression characters that match all directories starting with graphic. The "." in "sample\.gif" is escaped for a literal interpretation.

If you used the following syntax, Oracle Web Cache would try to locate a directory named graphic*:

<ADVANCEDSELECTOR URIPREFIX="/cec/cstage/graphic*/"
   URIEXP="sample\.gif">
</ADVANCEDSELECTOR>

To invalidate documents contained within /cec/cstage?ecaction=viewitem, use the following syntax:

<ADVANCEDSELECTOR URIPREFIX="/cec/"
   URIEXP="cstage\?ecaction=viewitem">
</ADVANCEDSELECTOR>

Note that "?" is escaped with a backslash.

URLs such as /cec/cstage?ecaction=viewitem&zip=94405 and /cec/cstage?ecaction=viewitem&zip=94305 match and are invalidated, but /usa/cec/cstage?ecaction=viewitem&zip=94209 does not match and is not invalidated.  

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 ORACLE_HOME\webcache\logs on Windows.

See Also: Appendix E, "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

The following shows an event log excerpt with successful startup entries:

14/May/2001:11:34:15 -0800 -- Information: Maximum number of file/socket 
descriptors set to 950.
14/May/2001:18:34:15 +0000 -- Information: Maximum connections possible are 900
14/May/2001:18:34:15 +0000 -- Information: Listening on ADMINISTRATION port 4000 
address 0.0.0.0
14/May/2001:18:34:15 +0000 -- Information: The admin server started successfully
14/May/2001:11:34:15 -0800 -- Information: Maximum number of file/socket 
descriptors set to 950.
14/May/2001:18:34:15 +0000 -- Information: Maximum connections possible are 900
14/May/2001:18:34:18 +0000 -- Information: Listening on NORM port 1100 address 
0.0.0.0
14/May/2001:18:34:18 +0000 -- Information: Listening on INVALIDATION port 4001 
address 0.0.0.0
14/May/2001:18:34:18 +0000 -- Information: Listening on STATISTICS port 4002 
address 0.0.0.0
14/May/2001:18:34:21 +0000 -- Information: The cache server started successfully
14/May/2001:18:34:22 +0000 -- Information: The cache server is started by the 
admin server at startup

Example: Event Log with Unsuccessful Startup Entries

The following 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.

14/May/2001: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/May/2001:16:37:41 -0800 -- Error: Failed to start the server.
14/May/2001:16:37:41 -0800 -- Error: The server could not initialize
14/May/2001:16:37:41 -0800 -- Information: The server is exiting

Example: Event Log with an Invalidation Entry

The following shows an event log excerpt with an event associated with an invalidation request for the removal of document personal.htm:

14/May/2001:22:52:52 -0500 -- Information: <Invalidation>1 URLs with prefix 
personal.htm have been successfully invalidated. 

Example: Event Log with an Invalidation Message Error

The following shows an event log excerpt with an XML invalidation message error. In this example, Oracle Web Cache is unable to parse the message:

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

Example: Event Log with Shutdown Entries

The following shows an event log excerpt with typical shutdown entries:

14/May/2001:11:16:55 -0700 -- Information: SIGTERM caught - program will shut 
down once all connections are complete.
14/May/2001:11:16:55 -0800 -- Information: SIGTERM caught - program will shut 
down once all connections are complete.
14/May/2001:11:16:55 -0700 -- Information: The server is exiting
14/May/2001: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 errors by the current day, enter grep " Error:" event_log | grep "dd/mon/yyyy". For example:

grep  " Error:" event_log | grep "19/May/2001" 
 

To list errors by the current day and hour, enter grep " Error:" event_log | grep "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.

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

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

   3. 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 ORACLE_HOME\webcache\logs on Windows. 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 enter.

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-end	Time at which the transaction ended
time-start	Time at which the transaction started
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://rfc.net/rfc2616.html 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 an HTTP header field and prefix is one of the following: cs: Client-to-Oracle Web Cache sc: Oracle Web Cache-to-client

The order in which fields are entered determines the order in which the fields are logged.

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

Note that entered XLF fields are not added to the CLF default. If you want to use the CLF fields in addition to XLF fields, you must enter them.

Access Log Examples

The access log that follows uses 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.

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

Example: Access Log with Reload Entries

The following shows an access log excerpt in which there are two Web browser reloads, followed by two shift reloads, and two more reloads:

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

Example: Access Log with Wrong Path Entry

The following 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.

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

Example: Access Log with Status Code 404 Entry

The following 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.

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

Example: Access Log with Status Code 304 Entry

The following 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 an HTTP status code of 304, indicating that document has not been modified and does not need to be returned again.

138.2.213.146 - - [19/May/2001:11:34:23 -0500] "GET /cache.htm HTTP/1.0" 200 250 
138.2.213.146 - - [19/May/2001:11:38:23 -0500] "GET /cache.htm HTTP/1.0" 304 0 
138.2.213.146 - - [19/May/2001: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 Logs.

   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.

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

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

    3. 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.

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

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

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