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

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

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

      The Change Invalidation/Statistics Port dialog box appears.

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

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

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

    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.