8 Using Diagnostic Features

This chapter describes the diagnostic features available with Oracle Web Cache.

This chapter includes the following topics:

Section 8.1, "Introduction to Diagnostic Solutions"
Section 8.2, "Introduction to Listing Popular Requests and Cache Contents"
Section 8.3, "Introduction to Displaying Diagnostic and Event Log Information in the HTML Body or Server Response-Header Field"
Section 8.4, "Viewing General and Detailed Statistics"
Section 8.5, "Viewing Configuration Statistics"
Section 8.6, "Listing Popular Requests"
Section 8.7, "Listing Cache Contents to a File"
Section 8.8, "Configuring Where to Display Diagnostic Information"

8.1 Introduction to Diagnostic Solutions

Oracle Web Cache provides a number diagnostic tools to enable to you evaluate performance and optimal configuration settings. These tools include:

Popular requests reporting. See Section 8.2.
Varying levels of statistics monitoring through Fusion Middleware Control. See Section 8.4 and Section 8.5.
Displaying diagnostics information in the Server response-header field or as a textual string in the HTML response body of an object. See Section 8.3.

8.2 Introduction to Listing Popular Requests and Cache Contents

You can view a list of the most popular requests and a list of the contents of the cache, as well as requests that were not cache, generating the following types of lists:

A list of the URLs of the most popular requests received by the cache since the cache was last started

Popularity is calculated using two factors: how many times the request was made and how recently the requests were made. You can specify: only objects stored in the cache, only objects not stored in the cache, or all requests received by the cache. See Section 8.6.
A list of the requested URLs for objects not stored in the cache.

You can use this list to verify that the caching rules are caching the correct objects. See Section 8.6.
A list of the cached or non-cached URLs of the objects to an exported file

Oracle Web Cache can write a list of content of the cache to a file. See Section 8.7.

8.3 Introduction to Displaying Diagnostic and Event Log Information in the HTML Body or Server Response-Header Field

By default, Oracle Web Cache adds diagnostics information to the Server response-header field. For diagnostics purposes, it can be useful to also display this information as a textual string in the HTML response body of an object. When enabled, you simply append a string to the URL of the object into the browser to see the diagnostic information string embedded in the response body:

Web Cache Debug Info: diagnostic_information

You can also select to display event log information, with a verbosity level of TRACE, in the HTML response.

You can additionally configure the diagnostic information to be within HTML comment tags for pages having a Content-Type: text/html response-header field. When enabled, the diagnostic information appears within HTML comment tags:

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

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

Server: Oracle Fusion Middleware 11g (multiple_version_object_version_number) Server_header_from_origin_server Oracle-Web-Cache-11g/11.1.1.0.0 (diagnostic_information)

The Server response-header field specifies name/value pairs for Oracle HTTP Server and Oracle Web Cache. The information for Oracle 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 8-1 describes the diagnostic fields.

Table 8-1 Control Directives for Server

Control Directive	Description
`ESI_processing_type`	`ESI_processing_type` is: `T` specifies that the object is an ESI template `F` specifies that the object is an ESI fragment empty specifies that the response does not require ESI processing
`cache_request_type`	`cache_request_type` is: `H` specifies a cache hit `S` specifies a cache hit of a stale object `U` specifies a cache update of a stale object `G` specifies a cache update of an object that was marked for removal but still physically resides in the cache `M` specifies a cache miss `N` specifies a non-cacheable cache miss
`max-age="expiration_time[+removal_time]`	Specifies the time, in seconds, to expire the object, and optionally, the time, in seconds, to remove the object from the cache after the expiration time. `max_age` does not appear if the `cache_request_type` is `N`.
`age=object_age`	Shows how long, in seconds, the object has been in the cache. `age` does not appear if the object is non-cacheable
`ecid=request_ID`, `sequence_number`	Specifies the request ID and sequence number specified in `Oracle-ECID` request header:

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 Fusion Middleware 11g (11.1.1.0.0) Oracle-HTTP-Server
Oracle-Web-Cache-11g/11.1.1.0.0 (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.

For more information, see:

Section 9.4 for further information about creating a user-defined access log format that includes the sc(Server) field
Section 8.8 for configuring the display of diagnostics information

8.4 Viewing General and Detailed Statistics

To view general statistics, navigate to the Web Cache Home page. See Section 2.6.3 for further information about the statistics provided in the Web Cache Home page.

You can also view detailed statistics about a specific cache instance:

Navigate to the Web Cache Home page in Fusion Middleware Control. See Section 2.6.2.
From the Web Cache menu, select Monitoring and then Performance Summary.

The Performance Summary page displays with performance metrics.
To see additional metrics, click Show Metric Palette and expand the metric categories.

The following figure show the Performance Summary page with the Metric Palette displayed:

Description of the illustration perform.gif
Select additional metrics and add them to the Performance Summary.

To obtain a definition of a performance metric, and information about the actions you should take when the metric is out of range, right-click the name of the metric and select Help from the context menu.

If after monitoring metrics, you need additional performance metrics, point your browser to the following URL:

http://web_cache_hostname:stat_port

This URL takes you to the Oracle Web Cache Internal Diagnosability Monitor page, which provides additional information about cache hits and misses. See Section 2.11.1 for further information about determining the statistics monitoring port.

8.5 Viewing Configuration Statistics

Table 8-2 explains where to find information for evaluating the effectiveness of configuring rules.

Table 8-2 Configuration Statistics

Type of Statistic	See Also
Request filters and rules	Section 4.13
Caching rules	Section 6.9

8.6 Listing Popular Requests

To understand how evaluating the most popular requests can help determine if the caching rules are caching the correct objects, see Section 8.2.

To view the list of URLs of the most popular requests:

Navigate to the Web Cache Home page in Fusion Middleware Control. See Section 2.6.2.
From the Web Cache menu, select Monitoring and then Popular Requests.

The Popular Request page displays.
From the Show Popular Requests list, select an option:
- All: Select to display all requests received by the cache.
- Cache Popular Requests: Select to display only those requests stored in the cache.
- Non Cache Popular Requests: Select to display only those requests not stored in the cache.
In Number of Popular Requests, enter the maximum number of URLs you want displayed.
Click Go.

The table updates with the list of URLs of requests since the cache was last started. The table contains the following columns for each request:
- Site: This column displays the requested site name.
- HTTP Method: This column displays if the request was using a GET, GET with query string, or POST HTTP request method.
- URL: The column displays the URL of the object. The URLs may contain additional descriptive information, such as cookie or session information.
- POST Body: This column displays the POST body contents.
- Cached?: This column display whether 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, Oracle Web Cache serves some stale objects until the origin servers have the capacity to refresh them.)
  - Yes, but needs validation: The object is cached, but it requires validation by the origin server to be served out of the cache. Validation is done through a simple conditional request from Oracle Web Cache to the origin server using the cached object's unique validator.
  - No: The object is not cached.
- Caching Reason: The reason that the object is cached or not cached. Possible values are:
  - ACL document: Cached or not cached because the object is an Access Control List (ACL) document for authorizing the access of a user to ACL-protected pages.
  - By caching <rule>: Cached or not cached because of a caching rule.
  - By ETag response header: Cached or not cached because of the ETag response header.
  - By HTTP headers: Cached or not cached because of information in the HTTP header.
  - By HTTP response code: Cached or not cached because of the HTTP response code. Normally any response code that is not 200 is not cached, but some non-200 responses can get cached because of a caching rule specifically allowing for it.
  - By reference TTL in ESI tag: Cached or not cached because of the nonzero value of the reference TTL (time-to-live parameters) specified in the ESI tag.
  - By Surrogate-Control response header: Cached or not cached because of information in the Surrogate-Control response header.
  - By X-Oracle-Cache response header: Cached or not cached because of information in the X-Oracle-Cache response header.
  - Cookie mismatch: Cached or 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.
  - No directive or rule: Cached or not cached because no directive or rule has stated that the object should be cached.
  - Not a GET or POST method: Not cached because the object was not a GET or POST method.
  - Object is too large: Not cached because the object is larger than the size specified as the Maximum Size of Single Cached Object specified in the Resource Limits and Timeout page.
  - POST body too large: Cached or not cached because the POST body was too large to be cached.
  - URL contains query string: Cached or not cached because the request contains a query string but the request did not match any caching rules.
- Size: The column displays the size of the requested object. The size is represented in bytes, kilobytes (KB), or megabytes (MB).
- Compressed?: This column displays the reason the object was compressed or not compressed:
  - Yes, by caching rule: Compressed because the object matched a caching rule that enabled or disabled compression.
  - Yes, by MIME type: Compressed because the object's MIME content type.
  - No, by default setting: Compression is enabled for the site and the browser accepts GZIP compressed response, but there is no matching caching rule and the response does not contain a compress control header in the Surrogate-Control response header or a MIME type.
  - Yes, by Surrogate-Control header: Compressed or not compressed because of the setting of the compress control directive in the Surrogate-Control response header.
  - Yes, by caching rule: Compressed or not compressed because the object matched a caching rule that enabled or disabled compression.
  - No, by MIME type: Not compressed because the object's MIME content type.
  - No, by default setting: Compression is enabled for the site and the browser accepts GZIP compressed responses, but there is no matching caching rule and the response does not contain a compress control header in the Surrogate-Control response header or a MIME type. See Section 1.2.5 to better understand when Oracle Web Cache automatically disables compression.
  - No, by Surrogate-Control header: Not compressed because of the setting of the compress control directive in the Surrogate-Control response header.
  - No, limited browser support: Not compressed because the client's browser has bugs and cannot handle receiving compressed objects.
  - No, needs Web Cache processing: Not compressed because the object requires parsing and tag process. For example, objects containing ESI tag requiring processing before there can be any cache hits.
  - No, browser capability: Not compressed because the client's browser did not indicate to Oracle Web Cache that it could accept GZIP compressed responses. Therefore, Oracle Web Cache does not compress any responses sent to this browser.
  - No, disabled for site: Not compressed because compression was disabled for the entire site. Section 2.11.3 to enable compression for a site.
  - No, object too small: Not compressed because the object was less than 23 bytes for compression to be beneficial.
  - No, routing only mode: Not compressed because the ROUTINGONLY attribute is set to YES in the webcache.xml file. See Section 3.8 for further information about this attribute.

8.7 Listing Cache Contents to a File

To generate a list of the URLs of all of the objects currently stored in the cache to a file named webache_contents.txt:

Navigate to the Web Cache Home page in Fusion Middleware Control. See Section 2.6.2.
From the Web Cache menu, select Monitoring and then Popular Requests.

The Popular Request page displays.
From the Filter Popular Request By list, select an option:
- All: Select to display all requests received by the cache.
- Cache Popular Requests: Select to display only those requests stored in the cache.
- Non Cache Popular Requests: Select to display only those requests not stored in the cache.
In Number of Popular Requests, enter the maximum number of URLs you want displayed.
Click Export File.
In the message dialog, click OK to export the contents.

Oracle Web Cache writes the list of URLs to webcache_contents.txt in this directories:
```
(UNIX) ORACLE_INSTANCE/diagnostics/logs/WebCache/<webcache_name>
(Windows) ORACLE_INSTANCE\diagnostics\logs\WebCache\<webcache_name>
```

Each time you generate the list, Oracle 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 Oct 20 11:47:03 2008
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 Oct 25 13:01:24 2008
www.company.com:80/images/white_spacer_xp.gif
www.company.com:80/images/white_spacer.gif
www.company.com:80/images/miniappsnet.gif
.
.
.

8.8 Configuring Where to Display Diagnostic Information

To understand how Oracle Web Cache can add diagnostic information to the Server response-header field or as a textual string in the HTML response body of an object, see Section 8.3.

To configure diagnostic information in the Server response-header field or the HTML response body:

From Oracle Web Cache Manager, in the navigator frame, select Logging and Diagnostics > Diagnostics. See Section 2.7.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.
To set diagnostic settings for the HTML response body:
1. From the Global Page Body Diagnostics Configuration table, 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.
To enable or disable diagnostic settings in the Server response header, from the Global Server Header Diagnostics table, click Enable or Disable.
Click Apply Changes.