15 Using Diagnostics Tools

Listing Popular Requests

To view the list of URLs of the most popular requests with Application Server Control Console, navigate to Web Cache Home page > Performance tab > All Sites section > Popular Requests link.

To view the list of URLs of the most popular requests with OracleAS Web Cache Manager:

1. In the navigation pane, select Monitoring > Popular Requests.

   The Popular Requests page appears in the right pane.

2. From the For Cache list, select a cache and click View. (More than one cache is listed only if you configured a cache cluster.)

3. In the List Most Popular Requests area, for Number of Objects, enter the maximum number of URLs you want displayed.

4. For Filter Objects, select one of the following options:

   • All: All requests received by the cache.

   • Cached: Only those requests stored in the cache.

   • Not Cached: Only those requests not stored in the cache.

5. Click Update.

   OracleAS Web Cache Manager displays a table containing the list of URLs of requests since the cache was last started. The table contains the following columns:

   • Rank: A ranking, from 1 to 100, based on the score of the object. A rank of 1 represents the object with the highest score; that is, the most popular object.

   • Object Name: The URL of the object. The URLs may contain additional descriptive information, such as cookie or session information.

   • Size: The size of the object. The size is represented in bytes, kilobytes (KB), or megabytes (MB).

   • Cached: Whether or not the object is cached. The possible values are:

     • Yes: The object is cached.

     • Yes, but expired: The object is cached, but it is expired. (To lessen the performance impact of invalidation and expiration, OracleAS Web Cache serves some stale objects until the origin servers have the capacity to refresh them.)

     • No: The object is not cached.

   • Cache Reason: The reason that the object is cached or not cached. Possible values are:

     • BY_CACHING_RULE: Cached or not cached because of the caching rule.

     • BY_HTTP_HEADERS: Cached or not cached because of information in the HTTP header.

     • BY_PRESEEDING: Cached because the objects were preseeded for use by end-user performance monitoring.

     • BY_REFERENCE_TTL: Cached because of the nonzero value of the reference TTL (time-to-live parameters) specified in the ESI tag.

     • BY_SURROGATE_CONTROL_HEADER: Cached or not cached because of information in the Surrogate-Control response header.

     • BY_VALIDATION: Cached because of the ETag response header.

     • BY_X_ORACLE_HEADERS: Cached or not cached because of information in the X-Oracle-Cache response header.

     • NC_COOKIE_MISMATCH: Not cached because the response contains a cookie that is not present in the request or that has a different value than the same cookie in the request.

     • NC_HTTP_RESPONSE_CODE: Not cached because the response was not an HTTP status code of 200.

     • NC_NO_DIRECTIVE: Not cached because no directive or rule has stated that the object should be cached.

     • NC_POST_BODY_TOO_BIG: Not cached because the POST body was too large to be cached.

     • NC_REQUEST_METHOD: Not cached because the request method was other than a GET or POST.

     • NC_SIZE_TOO_LARGE: Not cached because the object is larger than the size specified as the Maximum Object Size.

     • NC_WITH_QUERYSTRING: Not cached because the request contains a query string but the request did not match any caching rules.

   • Caching Rule: If a caching rule is associated with the object, this column displays a link to the Cacheability Rule Details page. That page shows the regular expression and site information for the URL.

   • Compressed: Whether or not the object is compressed.

Listing All Contents

Using OracleAS Web Cache Manager, you can also generate a list of the URLs of all of the objects currently stored in the cache. Application Server Control Console does not support this feature.

1. In the navigation pane, select Monitoring > Popular Requests.

   The Popular Requests page appears in the right pane.

2. From the For Cache list, select a cache and click View. (More than one cache is listed only if you have a cache cluster.)

3. For List All Contents in Cache, click Export to File.

   The Export Cache Contents dialog box appears. It lists the file to which OracleAS Web Cache will write the URLs. The file is written to the OracleAS Web Cache log directory and is named webcache_contents.txt.

4. To write the list to a different location, enter a complete file specification in the text box.

5. Click Submit.

OracleAS Web Cache writes the list of URLs to the text file you specified. Each time you generate the list, OracleAS Web Cache appends the data to the existing file. It lists the date that the data was appended to the file, followed by the URLs of the objects currently cached. The following example shows an excerpt of the webcache_contents.txt file:

Cache Contents at Wed Jul 20 11:47:03 2005
www.company.com:80/images/lnav/lnav_products.gif
www.company.com:80/images/rnav/rnav_red_line_1.gif
www.company.com:80/images/bullets_and_symbols/blk_line_bullet_10.gif
.
.
.
Cache Contents at Wed Jul 20 13:01:24 2005
www.company.com:80/images/white_spacer_xp.gif
www.company.com:80/images/white_spacer.gif
www.company.com:80/images/miniappsnet.gif
.
.
.

Oracle-ECID Request-Header Field

The Oracle-ECID request header is used to track requests as they move through the Oracle Application Server architecture. This information is especially useful for diagnostic purposes. Because OracleAS Web Cache is the initial receiver of client requests, it sets the request header before forwarding a cache miss to an origin server. The Oracle-ECID request header takes the following format:

Oracle-ECID: request_id, sequence_number

In the format, request_id is a 64-bit unique integer for the request, and sequence_number is the hop number of the request as it passes through Oracle Application Server. OracleAS Web Cache typically assigns an initial sequence number of 0 to a request. As a request passes from OracleAS Web Cache to other Oracle Application Server components, the request ID remains constant, but the sequence number increments with each hop.

You can configure OracleAS Web Cache to log the request ID and sequence number from the Oracle-ECID request header in the event and access logs. To display the Oracle-ECID request header in the logs, you enable Include Request Details for the event log, and select the x-ecid field for the access logs. The x-ecid field is provided by default with the Enhanced CLF (ECLF), Enhanced Combined Log Format, and End-User Performance Monitoring Format. Additionally, you can configure Oracle HTTP Server to log the Oracle-ECID request header information, enabling you to correlate events at different Oracle Application Server stops for the same request.

OracleAS Web Cache also includes Oracle-ECID request header information whenever you configure to display diagnostic information in the Server response-header field or the HTML response body.

Format of the Event Log File

Event messages are written using either of the following formats:

• The default format displays a typical log message for each instance of an event. It displays the request ID and sequence number of the Oracle-ECID request header so that you can easily find the matching request detail line.

  [Timestamp][severity message_id][ecid: request_id, serial_number] Event_Log_Message
  
  

• The request detail format is displayed when you enable Include Request Details. The field [detail] indicates that the event is for a request. This format is logged the first time an event is logged for a request. In addition to the IP address, site name, and URL of the request, the ID and sequence number of the Oracle-ECID request header is logged. The Oracle-ECID request header is used to track requests.

  [Timestamp][module_name][detail][ecid: request_id, hop_number] [client: IP_address] [host: site] [url: URL]
  
  

Table 15-1 describes the fields for the default event log format.

Table 15-2 describes the fields for the request detail format.

Configuring Event Logs

To configure the event log settings with Application Server Control Console, navigate to Web Cache Home page > Administration tab > Properties > Web Cache > Logging.

To configure event log settings with OracleAS Web Cache Manager:

1. In the navigator frame, select Logging and Diagnostics > Event Logs.

   The Event Logs page appears.

2. Specify cache-specific event log settings:

   1. From the Cache-Specific Event Log Configuration table, select a cache, and then click Edit Selected.

      The Edit Cache-Specific Event Log Configuration dialog box appears.

   2. In the Directory field, enter the directory in which to write event logs.

      The default is $ORACLE_HOME/webcache/logs on UNIX and ORACLE_HOME\webcache\logs on Windows.

   3. In the Buffering field, select Enabled to enable buffered logging or Disabled to disable buffered logging.

      With buffered logging, OracleAS Web Cache writes to the event log after the buffer is full. The buffer size is set to 2048 bytes. When the limit is reached, OracleAS Web Cache writes buffered events to the event log file.

      Oracle recommends disabling buffering when you need to see the event log results immediately, such as when you are debugging OracleAS Web Cache.

   4. If buffering is enabled, in the Flush Interval field, enter the maximum threshold, in seconds, when contents of the buffer are written to the event log file.

      The default is 10 seconds. When the maximum threshold is reached, OracleAS Web Cache writes buffered events to the event log file. Even if the buffer is not full, the event log is updated at least every 10 seconds. Oracle recommends not changing the default unless you need to lower the interval to see results more frequently.

   5. From the Verbosity list, select the needed level of detail for the event log. The levels are described in Table 15-3.

      Table 15-3 Verbosity Levels

      Level	Description
      WARNING	Provides abnormal-operation events.
      NOTIFICATION	Provides normal-operation events, such as startup and shutdown. This is the default.
      TRACE	Provides events for debugging caching rules.
      DEBUG	Provides detailed events for troubleshooting. This level is intended for Oracle Support Services.

      
      

   6. Click Submit.

3. Set the global event log settings:

   1. From the Global Event Log Configuration table, click Edit.

      The Edit Global Event Log Configuration dialog box appears.

   2. In the File Name field, enter a name for the event log file.

      The default file name is event_log.

   3. From the Time Style list, select either LOCAL or GMT (Greenwich Mean Time) to modify the time stamp style associated with entries in the event log file.

      
      

      Note: Oracle 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, OracleAS Web Cache has no mechanism to improve the performance of the conversion process.

      
      

   4. In Include Request Details, select Yes to enable the logging of request details or No to disable logging of requests.

      Oracle recommends selecting No if either of the following conditions apply:

      • You are concerned about the performance impact of event log entries for request details

      • You are running OracleAS Web Cache in a standalone environment without Oracle HTTP Server

        
        

        See Also: "Format of the Event Log File" for further information about how request details are logged Appendix B for information about running OracleAS Web Cache in a standalone environment

        
        

   5. In the Rollover Policy section, select Weekly, Daily, Hourly, or Never to specify how often you want OracleAS Web Cache to save current log information to event_log_file.yyyymmdd_hhmm and write future log information to a new log file with the configured log file name.

      Table 15-4 describes additional configuration instructions for Weekly, Daily, and Hourly.

      Table 15-4 Configuring Weekly, Daily and Hourly Rollover Policies

      Policy	To configure:
      Weekly	Select a day of the week. Use the Time fields to enter the hour and minutes. From the Time Style list, select either Local or GMT.
      Daily	From the Rollover times - each day list, select a time. If the time you require does not exist, use the Time fields to enter the hour and minutes. From the Time Style list, select either Local or GMT.
      Hourly	From the Rollover times - minutes past the hour list, select a time. If the time you require does not exist, use the Minutes past the hour field to enter the number of minutes, and then click Add. From the Time Style list, select either Local or GMT.

      
      

      If you have a high-volume site, create a daily or hourly policy.

      
      

      See Also: "Rolling Over Event and Access Logs" for instructions on immediately rolling over log files

      
      

   6. Click Submit.

4. Apply changes and restart OracleAS Web Cache:

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

   2. In the Cache Operations page, choose Restart to restart OracleAS Web Cache.

Event Log Examples

This section contains the following event log examples:

• Example: Event Log with Startup Entries

• Example: Event Log with Unsuccessful Startup Entries

• Example: Event Log with Shutdown Entries

• Example: Event Log with Cache Miss and Cache Hit Entries

• Example: Event Log with an Invalidation Entry

• Example: Event Log with Invalidation Request Errors

• Example: Event Log with ESI Parsing Errors

• Example: Event Log with ESI Processing Errors

Example: Event Log with Startup Entries

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

[25/Jul/2005:19:08:52 +0000] [notification 9612] [ecid: -]  OracleAS Web Cache 10g (10.1.2)
[25/Jul/2005:19:08:52 +0000] [notification 9403] [ecid: -] Maximum number of file/socket descriptors set to 900.
[25/Jul/2005:19:08:52 +0000] [notification 13002] [ecid: -] Maximum allowed incoming connections are 700
[25/Jul/2005:16:43:31 -0700] [notification 9607] [ecid: -] The admin server started successfully.
[25/Jul/2005:20:44:37 +0000] [notification 12209] [ecid: -] A 1 node cluster successfully initialized
[25/Jul/2005:19:08:52 +0000] [notification 9608] [ecid: -]  The cache server process started successfully.

Example: Event Log with Unsuccessful Startup Entries

The following shows an event log excerpt with unsuccessful startup events. OracleAS Web Cache is unable to listen on port 7777, because it is already in use. This can occur if OracleAS Web Cache is already running and listening on that port or another application is using that port.

[25/Jul/2005:19:12:40 +0000] [notification 9612] [ecid: -]  OracleAS Web Cache 10g (10.1.2)
[25/Jul/2005:19:12:40 +0000] [notification 9403] [ecid: -] Maximum number of file/socket descriptors set to 900.
[25/Jul/2005:19:12:40 +0000] [notification 13002] [ecid: -] Maximum allowed incoming connections are 700
[25/Jul/2005:19:12:40 +0000] [alert 13305] [ecid: -] Failed to assign port 7777: Address already in use
[25/Jul/2005:19:12:40 +0000] [alert 9707] [ecid: -]  Failed to start the server.
[25/Jul/2005:19:12:40 +0000] [alert 9609] [ecid: -] The server could not initialize.
[25/Jul/2005:19:12:40 +0000] [notification 9610] [ecid: -]  The server is exiting.

Example: Event Log with Shutdown Entries

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

[25/Jul/2005:19:09:49 +0000] [notification 9703] [ecid: -] Stop Issued. The program will shut down after all accepted requests are served, or a timeout occurs. 
[25/Jul/2005:19:09:49 +0000] [notification 9610] [ecid: -]  The server is exiting.

Example: Event Log with Cache Miss and Cache Hit Entries

The following shows an event log excerpt containing events for a cache-miss request:

[25/Jul/2005:10:30:40 -0700] [req-info] [ecid: 23998683674,0] [client: 10.10.150.35] [host: www.company.com:80] [url: /index.html] 
[25/Jul/2005:10:30:40 -0700] [trace 11331] [ecid: 23998683674,0] Request matches configured site www.company.com:80.
[25/Jul/2005:10:30:40 -0700] [trace 11414] [ecid: 23998683674,0] Initial cache key is composed: www.company.com:80/index.html 
[25/Jul/2005:10:30:40 -0700] [trace 11304] [ecid: 23998683674,0] Cache miss request.
[25/Jul/2005:10:30:40 -0700] [trace 11224] [ecid: 23998683674,0] Site www.company.com:80 matches site-to-server mapping www.company.com:80.
[25/Jul/2005:10:30:40 -0700] [trace 11227] [ecid: 23998683674,0] Request is routed to origin server host-server:7778 using load balancing.
[25/Jul/2005:10:30:40 -0700] [trace 11403] [ecid: 23998683674,0] begin cacheability decision for following url: www.company.com:80/index.html
[25/Jul/2005:10:30:40 -0700] [trace 11407] [ecid: 23998683674,0] URL matches caching rule "\.html?$".
[25/Jul/2005:10:30:40 -0700] [trace 11446] [ecid: 23998683674,0] URL which will be cached is: www.company.com:80/index.html
[25/Jul/2005:10:30:40 -0700] [trace 11415] [ecid: 23998683674,0] Final cache key is composed: www.company.com:80/index.html 
[25/Jul/2005:10:30:40 -0700] [trace 11088] [ecid: 23998683674,0] Following URL is now in cache: www.company.com:80/index.html

The following shows an event log excerpt containing events for a subsequent cache-hit request:

[25/Jul/2005:10:32:22 -0700] [req-info] [ecid: 23998788806,0] [client: 10.10.150.35] [host: www.company.com:80] [url: /index.html] 
[25/Jul/2005:10:32:22 -0700] [trace 11331] [ecid: 23998788806,0] Request matches configured site www.company.com:80.
[25/Jul/2005:10:32:22 -0700] [trace 11414] [ecid: 23998788806,0] Initial cache key is composed: www.company.com:80/index.html 
[25/Jul/2005:10:32:22 -0700] [trace 11415] [ecid: 23998788806,0] Final cache key is composed: www.company.com:80/index.html 
[25/Jul/2005:10:32:22 -0700] [trace 11338] [ecid: 23998788806,0] URL is in the cache
[25/Jul/2005:10:32:22 -0700] [trace 11344] [ecid: 23998788806,0] Returning a freshly cached object.

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 object cache.htm.

[25/Jul/2005:19:26:46 +0000] [notification 11706][ecid: 21085932167,0] 10 object (s) matching prefix '/cache/' are invalidated.
[25/Jul/2005:19:26:46 +0000] [notification 11748] [ecid: 21085932167,0] Invalidation with INFO 'removing 15k object' has returned with status ' SUCCESS'; number of objects invalidated: '10'.

Example: Event Log with Invalidation Request Errors

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

[25/Jul/2005:19:37:36 +0000] [alert 13109] [ecid: 21086599201,0] XML parsing error in N/A. Error code 210: LPX-00210: expected '=' instead of 'H'
[25/Jul/2005:19:37:36 +0000] [error 13112] [ecid: 21086599201,0] XML parsing failed. Error Code: 210
[25/Jul/2005:19:37:36 +0000] [error 11716] [ecid: 21086599201,0]
Invalidation XML message cannot be parsed.

Example: Event Log with ESI Parsing Errors

The following shows an event log excerpt with ESI parsing errors that indicate a problem with the src attribute and variable syntax:

[25/Jul/2005:01:59:48 +0000] [detail] [ecid: 19734744942,0] [client: 127.0.0.1] [host: www.company.com:80] [url: /cgi-bin/esi-headers.sh?err1.htm] 
[25/Jul/2005:01:59:48 +0000] [error 12086] [ecid: 19734744942,0] ESI syntax error. Unrecognized keyword src is at line 3.
[25/Jul/2005:01:59:48 +0000] [warning 11064] [ecid: 19734744942,0] ESI object www.company.com:80/cgi-bin/esi-headers.sh?err1.htm parsing error
...
[25/Jul/2005:02:11:57 +0000] [detail] [ecid: 19735486051,0] [client: 127.0.0.1] [host: www.company.com] [url: /cgi-bin/esi-headers.sh?err1.htm] 
[25/Jul/2005:02:11:57 +0000] [error 12095] [ecid: 19735486051,0]  ESI syntax error. A variable requires a key at line 3.
[25/Jul/2005:02:11:57 +0000] [warning 11064] [ecid: 19735486051,0] ESI object www.company.com:80/cgi-bin/esi-headers.sh?err1.htm parsing error

Example: Event Log with ESI Processing Errors

The following shows an event log excerpt with ESI processing errors that indicate an error fetching an ESI fragment named a.html and an unknown fragment for an undefined site:

[25/Jul/2005:02:02:37 +0000] [detail] [ecid: 19734914560,0] [client: 127.0.0.1] [host: www.company.com:80] [url: /cgi-bin/esi-headers.sh?err1.htm] 
[25/Jul/2005:02:02:37 +0000] [warning 12005] [ecid: 19734914560,0] HTTP Client Error 4xx exception in ESI template www.company.com:80/cgi-bin/esi-headers.sh?err1.htm, 
fragment www.company.com:80/cgi-bin/a.html
....
[25/Jul/2005:02:03:38 +0000] [detail] [ecid: 19734980113,0] [client: 127.0.0.1] [host: -] [url: /cgi-bin/esi-headers.sh?err1.htm] 
[25/Jul/2005:02:03:38 +0000] [warning 11295] [ecid: 19734980113,0] OracleAS Web Cache failed in DNS lookup for host www.company2.com:80. 
[25/Jul/2005:02:03:38 +0000] [warning 12003] [ecid: 19734980113,0] No connection exception in ESI template www.company.com:80/cgi-bin/esi-headers.sh?err1.htm, fragment www.company2.com:80/a.html

Web Cache Debug Info: diagnostic_information

<!-- Web Cache Debug Info: diagnostic_information-->

Server Response-Header Field

For objects sent to browsers, OracleAS Web Cache adds diagnostic information to the Server response-header field of the HTTP response message:

Server: Oracle Application Server 10g (version) Server_header_from_origin_server OracleAS-Web-Cache-10g/10.1.2.0.2 (diagnostic_information)

The Server response-header field specifies name/value pairs for Oracle HTTP Server and OracleAS Web Cache. The information for OracleAS Web Cache includes version and diagnostic information.

where diagnostic_information has the following format:

{ESI_processing_type}{cache_request_type}[;max-age=expiration_time[+removal_time];age=object_age;]{ecid=request_ID,sequence_number}

Table 15-5 describes the diagnostic fields.

Using the Server response header information, you can determine whether a request was served from the cache or the origin server. In the following example, the Server field specifies that the object was a cache hit:

Server: Oracle Application Server 10g (10.1.2) Oracle-HTTP-Server
OracleAS-Web-Cache-10g/10.1.2.0.2 (TH;max-age=60+30;age=55;ecid=23248098121,0)

(TH;max-age=60+30;age=55;ecid=23248098121,0) is the diagnostic information.

• T means this page is composed by ESI

• H means this request resulted in cache hit

• max-age=60+30 means that the object is to expire in 60 seconds from population and to be removed from the cache 30 seconds from the expiration. This provides a total of 90 seconds from population.

• age=55 in age means that 55 seconds have passed since population of the cache, meaning there are 5 seconds to expiration and 35 seconds to removal

• ecid=23248098121,0 specifies the request ID and sequence number from the Oracle-ECID request header.

To display the Server response header in the access logs, you select the sc(Server) field. You must configure the sc(Server) field as a user-defined access log format.

Configuring Where to Display Diagnostic Information

To configure diagnostic information in the Server response-header field or the HTML response body with Application Server Control Console, navigate to Web Cache Home page > Administration tab > Properties > Web Cache > Diagnostics.

To configure diagnostic information in the Server response-header field or the HTML response body with OracleAS Web Cache Manager:

1. In the navigator frame, select Logging and Diagnostics > Diagnostics.

   The Diagnostics page appears.

2. From the Cache-Specific Page Body Diagnostics table, select a cache, and then click Enable to display diagnostic information in the HTML response body or Disable to disable the display of diagnostic information in the HTML response body.

3. To set diagnostic settings for the HTML response body:

   1. Click Edit.

      The Edit Global Page Body Diagnostics Configuration dialog box displays.

   2. In the URL Flag field, enter the string to append to the URL of the object.

      By default, the string is set to +wcdebug.

   3. In the Display Event Log Entries for Request field, select Yes to display diagnostic information and TRACE event log entries in the HTML response body, or select No to only display diagnostic information.

   4. Click Submit.

4. To enable or disable diagnostic settings in the Server response header, from the Global Server Header Diagnostics table, click Enable or Disable.

To display diagnostic information in HTML comment tags:

1. Use a text editor to open the webcache.xml file.

2. Locate the <DEBUGINFO> subelement of SECURITY .

   <DEBUGINFO HEADER="YES" EVENTLOG="NO" HTMLCOMMENT="NO" SWITCHSTRING="+wcdebug"/>
   
   

3. Change the value for HTMLCOMMENT from NO to YES.

4. Save webcache.xml.

5. Restart OracleAS Web Cache with the following command:

   opmnctl restartproc ias-component=WebCache
   

Format of the Access Log Files

You can configure the content of the access log files by defining the fields to appear for each HTTP request event. These fields are based on the standard Extended LogFile Format (XLF). By default, OracleAS Web Cache provides support for the following log formats:

• Common Log Format (CLF)

  This format is the default format applied to access logs. This format is appropriate for most configurations. The CLF format provides support for the following fields:

  • c-ip

  • x-log-id

  • x-auth-id

  • x-clf-date

  • x-req-line

  • sc-status

  • bytes

• Enhanced CLF (ECLF)

  This format uses many of the CLF fields and includes the x-ecid field for tracking the request ID and sequence number specified in Oracle-ECID request header:

  • c-ip

  • x-log-id

  • x-auth-id

  • x-clf-date

  • x-req-line

  • sc-status

  • bytes

  • x-ecid

• Combined Log Format

  This format provides support for the CLF fields with the addition of the cs(Referer) and cs(User-Agent) fields:

  • c-ip

  • x-log-id

  • x-auth-id

  • x-clf-date

  • x-req-line

  • sc-status

  • bytes

  • cs(Referer)

  • cs(User-Agent)

  Select this format when you need to determine what kind of browser is sending the request, and where the browser was visiting before the request was forwarded to OracleAS Web Cache.

• Enhanced Combined Log Format

  This format uses many of the Combined Log Format fields and includes the x-ecid field for tracking the ID of the specified in Oracle-ECID request header:

  • c-ip

  • x-log-id

  • x-auth-id

  • x-clf-date

  • x-req-line

  • sc-status

  • bytes

  • cs(Referer)

  • cs(User-Agent)

  • x-ecid

• End-User Performance Monitoring Format

  This format provides support for the following fields intended for end-user performance monitoring features:

  • x-req-type

  • x-date-start

  • x-time-start

  • c-ip

  • s-ip

  • x-auth-id

  • cs(Host)

  • cs-method

  • cs-uri

  • x-protocol

  • sc-status

  • bytes

  • cs-bytes

  • x-cache

  • time-taken

  • r-time-taken

  • x-time-delay

  • x-os-timeout

  • x-ecid

  • x-cookie(ORACLE_SMP_CHRONOS_ST)

  • x-cookie(ORACLE_SMP_CHRONOS_LT)

  • x-cookie(ORACLE_SMP_CHRONOS_GL)

  • x-glcookie-set

  • cs(Referer)

  • cs(User-Agent)

  • x-esi-info

  • x-conn-abrt

  • sc(Content-Type)

If the default formats are not suitable for your environment, you can create custom log formats by specifying the fields that you require. Table 15-6 describes the supported fields. Fields prefixed with x or r are proprietary to OracleAS Web Cache.

Configuring Access Logs

To configure the access log settings with Application Server Control Console, navigate to Web Cache Home page > Administration tab > Properties > Logging.

To establish access log configuration settings with OracleAS Web Cache Manager:

1. In the navigator frame, select Logging and Diagnostics > Access Logs.

   The Access Logs page appears.

2. Specify cache-specific access log settings:

   1. From the Cache-Specific Access Log Configuration table, select a cache, and then click Edit Selected.

      The Edit Cache-Specific Access Log Configuration dialog box appears.

   2. In the Directory field, enter the directory in which to write access logs.

      The default is $ORACLE_HOME/webcache/logs on UNIX and ORACLE_HOME\webcache\logs on Windows.

   3. In the Enabled field, select Yes to enable logging, or No to disable logging.

   4. In the Buffering field, select Enabled to enable buffered logging or Disabled to disable buffered logging.

      With buffered logging, OracleAS Web Cache writes to the access log after the buffer is full. The buffer size is set to 2048 bytes. When the limit is reached, OracleAS Web Cache writes buffered events to the access log file.

      Oracle recommends disabling buffering when you need to see the access log results immediately.

   5. If buffering is enabled, in the Flush Interval field, enter the maximum threshold, in seconds, when contents of the buffer are written to the access log file.

      The default is 10 seconds. When the maximum threshold is reached, OracleAS Web Cache writes buffered information to the access log file. Even if the buffer is not full, the access log is updated at least every 10 seconds. Oracle recommends not changing the default, unless you need to lower the interval to see results more frequently.

   6. Click Submit.

3. Specify site-specific log settings:

   1. From the Site-Specific Access Log Configuration table, click Add.

      The Edit/Add Site Specific Access Log Configuration dialog box appears.

   2. From the For Site list, select the Web site for which to specify access log settings.

   3. In the File Name field, enter a name for the access log file.

      The default file name is access_log.

   4. In the Enabled field, select Yes to enable logging for the site or No to disable logging for the site.

      Site-specific logging only takes effect if logging is enabled for the cache. If you select Yes, ensure that Yes is also selected for the cache in Step 2c.

   5. In the ESI Fragment Requests field, select Log to log the ESI fragment log messages from the log element of <esi:environment> or <esi:include> in the access_log_file.fragment file.

      If the x-esi-info field is selected, select Log to log the events to the access_log_file.fragment file. The x-esi-info field is automatically selected if the Format Style is End-User Performance Monitoring Format. If the x-esi-info field is not selected, select Don't Log.

   6. From the Format Style list, select an access log format.

      
      

      See Also: "Format of the Access Log Files" for a description of the default formats

      
      

   7. From the Rollover Policy list, select a rollover policy to specify how often you want to change the frequency at which OracleAS Web Cache saves current log information to access_log_file.yyyymmdd_hhmm and writes future log information to a new log file with the configured log file name.

      For high-volume sites, select a policy with a high frequency.

   8. Click Submit.

4. If the default formats are not suitable for your environment, create a log format that is:

   1. From the User-Defined Log Formats table, click Add.

      The Edit/Add User-Defined Access Log Format dialog box displays.

   2. In the Format Name field, enter a unique name for the format.

   3. From the Separator list, select the separator to use for separating access log fields.

   4. In Print XLF Directive field, select Yes to include XLF directive information at the top of the access log or No to not include directive information in the access log.

      Directive information typically consists of version, date, and field information. For example:

      #Version: 1.0
      #Date: 12-Jul-2005 00:00:00
      #Fields: c-ip x-auth-id x-clf-date cs(Host x-req-line sc-status bytes
      

      
      

      See Also: http://www.w3.org/TR/WD-logfile.html for further information about XLF directives

      
      

   5. In the XLF Fields section, select an access log field name from the Field name list.

      
      

      See Also: Table 15-6 for a listing of the supported access logs fields

      
      

   6. If you selected field cs(header_name), sc(header_name), or x-cookie(cookie_name), then enter the header or cookie name in the Header/Cookie name field.

      
      

      See Also: Table 15-7, Table 15-8, and Table 15-9 for a description of the headers allowed for cs(header_name) and sc(header_name)

      
      

   7. Click Add.

   8. Perform Steps e and f for each format you want in the access log, and then use the Move Up and Move Down buttons to order the fields. The order in which fields are entered determines the order in which the fields are logged.

   9. Click Submit.

5. Optionally, modify or create rollover policies:

   1. Select an existing policy and click Edit Selected to modify and existing rollover policy, or click Add to create a new policy.

      The Edit/Add Access Log Rollover Policy dialog box appears.

   2. In the Rollover Policy Name field, enter a unique name for the rollover policy.

   3. In Rollover Policy section, select Weekly, Daily, Hourly, or Never to specify how often you want OracleAS Web Cache to save current log information to access_log_file.yyyymmdd_hhmm and write future log information to a new log file with the configured log file name.

      Table 15-10 describes additional configuration instructions for Weekly, Daily, and Hourly.

      Table 15-10 Configuring Weekly, Daily and Hourly Rollover Policies

      Policy	To configure:
      Weekly	Select a day of the week. Use the Time fields to enter the hour and minutes. From the Time Style list, select either Local or GMT (Greenwich Mean Time).
      Daily	From the Rollover times - each day list, select a time. If the time you require does not exist, use the Time fields to enter the hour and minutes, and then click Add. From the Time Style list, select either Local or GMT.
      Hourly	From the Rollover times - minutes past the hour list, select a time. If the time you require does not exist, use the Minutes past the hour field to enter the number of minutes, and then click Add. From the Time Style list, select either Local or GMT.

      
      

      If you have a high-volume site, create a daily or hourly policy.

      
      

      See Also: "Rolling Over Event and Access Logs" for instructions on immediately rolling over log files

      
      

   4. Click Submit.

6. Apply changes and restart OracleAS Web Cache:

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

   2. In the Cache Operations page, choose Restart.

Logging Cache Cluster Peer Requests

By default, peer requests between two members of a cache cluster are not logged in the access log. Only client requests to the cluster are logged. Peer request logging can be enabled for individual cache cluster members by adding the ACCESSLOGIGNOREPEERREQUEST attribute to the MISCELLANEOUS element in the internal.xml configuration file.

The valid values for this attribute are: YES and NO.

The following example shows the MISCELLANEOUS element with peer-to-peer logging enabled:

<MISCELLANEOUS ACCESSLOGIGNOREPEERREQUEST="NO"/>

Analyzing an Access Log File

The following code shows an excerpt of an access log file:

10.10.150.35 - - [25/Jul/2005:10:27:42 -0500] "GET /~user/personal.htm HTTP/1.1" 200 2438 
10.10.150.35 - - [25/Jul/2005:10:27:54 -0500] "GET /~user/personal.htm?UserName=Bob HTTP/1.1" 200 2438 
10.10.150.35 - - [25/Jul/2005:10:47:30 -0500] "GET /~user/count.sh HTTP/1.1" 403 289 
10.10.150.35 - - [25/Jul/2005:10:47:34 -0500] "GET /~user/sbin/count.sh HTTP/1.1" 200 321 

In the first line of the output, the fields have the following meaning:

• 10.10.150.35 is the browser's IP address (c-ip)

• [25/Jul/2005:10:27:42 -0500] is the date ([x-clf-date])

• "GET /~user/personal.htm HTTP/1.1" is the request line ("x-req-line")

• 200 is the HTTP status code (sc-status)

• 2438 is the size of the object sent (bytes)

Access Log Examples

This section contains the following access log examples:

• Example: Access Log with Reload Entries

• Example: Access Log with Status Code 404 Entry

• Example: Access Log in Combined Format

• Example: Access Log with Site Information

• Example: Access Log with ESI Diagnostic Information

• Example: Access Log with ESI Log Information

Except where noted otherwise, the access log examples use the CLF format:

c-ip x-log-id x-auth-id x-clf-date x-req-line sc-status bytes

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:

10.10.150.35 - - [25/Jul/2005:11:04:24 -0500] "GET /cache.htm HTTP/1.1" 200 250 
10.10.150.35 - - [25/Jul/2005:11:04:26 -0500] "GET /cache.htm HTTP/1.1" 200 250 
10.10.150.35 - - [25/Jul/2005:11:29:24 -0500] "GET /cache.htm HTTP/1.1" 304 0 
10.10.150.35 - - [25/Jul/2005:11:29:25 -0500] "GET /cache.htm HTTP/1.1" 304 0 
10.10.150.35 - - [25/Jul/2005:11:29:30 -0500] "GET /cache.htm HTTP/1.1" 200 250 
10.10.150.35 - - [25/Jul/2005:11:29:35 -0500] "GET /cache.htm HTTP/1.1" 200 250

The third and forth entries return an HTTP status code of 304, indicating that object has not been modified and does not need to be returned again.

Example: Access Log with Status Code 404 Entry

The following shows an access log excerpt in which OracleAS Web Cache cannot find any objects matching the requested URL /ows-img/chalk.jpg. This error is indicated by HTTP status code 404.

10.10.150.35 - - [25/Jul/2005:10:49:44 -0500] "GET /pls/coe/find_via_post HTTP/1.1" 200 1119 
10.10.150.35 - - [25/Jul/2005:10:49:44 -0500] "GET /ows-img/chalk.jpg HTTP/1.1" 404 284 

Example: Access Log in Combined Format

The following shows an access log excerpt in which the combined format is specified:

c-ip x-log-id x-auth-id x-clf-date x-req-line sc-status bytes cs(Referer)
 cs(User-Agent)

10.10.150.35 - - [25/Jul/2005:20:09:47 +0000] "GET /manual/sections.html HTTP/1.1" 200 -1 "http://www.company.com:80/manual/mod/directive-dict.html#Syntax" "Mozilla/4.78 [ja] (Win98; U)"
10.10.150.35 - - [25/Jul/2005:20:09:50 +0000] "GET /manual/mod/core.html HTTP/1.1" 200 -1 "http://www.company.com:80/manual/sections.html" "Mozilla/4.78 [ja] (Win98; U)"
10.10.150.35 - - [25/Jul/2005:20:10:06 +0000] "GET / HTTP/1.1" 200 -1 - "Mozilla/4.78 [ja] (Win98; U)"
10.10.150.35 - - [25/Jul/2005:20:10:14 +0000] "GET /manual/LICENSE HTTP/1.1" 200 -1 "http://www.company.com:80/manual/index.html" "Mozilla/4.78 [ja] (Win98; U)"

Example: Access Log with Site Information

The following shows an access log excerpt in which the following fields are specified:

c-ip x-auth-id x-clf-date cs(Host) x-req-line sc-status bytes

cs(Host) displays the output of Host request-header field, which specifies the site information. In this example, requests are sent to OracleAS Web Cache for site www.company.com:80.

10.10.150.35 - [25/Jul/2005:20:05:51 +0000] "www.company.com:80" "GET / HTTP/1.1" 200 -1
10.10.150.35 - [25/Jul/2005:20:05:56 +0000] "www.company.com:80" "GET /manual/index.html HTTP/1.1" 200 -1
10.10.150.35 - [25/Jul/2005:20:05:59 +0000] "www.company.com:80" "GET /manual/upgrading_to_1_3.html HTTP/1.1" 200 -1
10.10.150.35 - [25/Jul/2005:20:06:02 +0000] "www.company2.com:80" "GET /manual/mod/mod_dir.html HTTP/1.1" 200 -1
10.10.150.35 - [25/Jul/2005:20:06:05 +0000] "www.company2.com:80" "GET /manual/mod/directive-dict.html HTTP/1.1" 200 -1

Example: Access Log with ESI Diagnostic Information

The following shows an access log excerpt in which the following fields are specified:

c-ip x-clf-date x-req-line sc-status bytes x-cache-detail

x-cache-detail displays diagnostic information. In the following example:

• T means that this request is for an ESI template

• H means that this request resulted in cache hit

• max-age=10+15 means that the object is to expire in 10 seconds from population and to be removed from the cache 15 seconds from the expiration. This provides a total of 25 seconds from population.

• age=0 means that 0 seconds have passed since population of the cache, meaning there is 10 seconds to expiration and 15 seconds to removal

[25/Jul/2005:02:35:37 +0000] "GET /cgi-bin/esi-headers.sh?err1.htm HTTP/1.0" 200 42 TM;max-age=10+15;age=0

Example: Access Log with ESI Log Information

The following shows an access log excerpt in which the following fields are specified:

c-ip x-clf-date x-req-line sc-status bytes x-esi-info

x-esi-info displays log information from the log element of <esi:environment> or <esi:include> tags.

[25/Jul/2005:03:03:35 +0000] "GET /b.html HTTP/1.0" 200 4 "This is a sample fragment."