Sun Java System Web Server 7.0 Update 4 Performance Tuning, Sizing, and Scaling Guide

File Cache Statistics Information

The cache information section provides statistics on how your file cache is being used. The file cache caches static content so that the server handles requests for static content quickly. The file cache contains information about files and static file content. The file cache also caches information that is used to speed up processing of server-parsed HTML. For servlets and JSPs, other kinds of caching are used.

For sites with scheduled updates to content, consider shutting down the cache while the content is being updated, and starting it again after the update is complete. Although performance slows down, the server operates normally when the cache is off.

For performance reasons, Web Server caches as follows:

The following is an example of how the cache statistics are displayed in perfdump:

File Cache Enabled       yes
File Cache Entries       141/1024
File Cache Hit Ratio     652/664 ( 98.19%)
Maximum Age              30
Accelerator Entries      120/1024
Acceleratable Requests   281/328 ( 85.67%)
Acceleratable Responses  131/144 ( 90.97%)
Accelerator Hit Ratio    247/281 ( 87.90%)

The following table shows the file cache statistics as displayed in the Admin Console:

Table 2–4 File Cache Statistics

Total Cache Hits 


Total Cache Misses 


Total Cache Content Hits 

Number of File Lookup Failures 

Number of File Information Lookups 


Number of File Information Lookup Failures 


Number of Entries 


Maximum Cache Size 


Number of Open File Entries 

Number of Maximum Open Files Allowed 


Heap Size 


Maximum Heap Cache Size 


Size of Memory Mapped File Content 

Maximum Memory Mapped File Size 

Maximum Age of Entries 


Accelerator Entries

The number of files that have been cached in the accelerator cache.


You can increase the maximum number of accelerator cache entries by increasing the number of file cache entries as described in File Cache Entries. Note that this number will typically be smaller than the File Cache Entries number because the accelerator cache only caches information about files and not directories. If the number is significantly lower than the File Cache Entries number, you can improve the accelerator cache utilization by following the tuning information described in Acceleratable Requests and Acceleratable Responses.

Acceleratable Requests

The number of client requests that were eligible for processing by the accelerator cache. Only simple GET requests are processed by the accelerator cache. The accelerator cache does not process requests that explicitly disable caching, for example, requests sent when a user clicks Reload in the browser and requests that include a query string, that is, requests for URLs that include a ? character.


To maximize the number of acceleratable requests, structure your web sites to use static files when possible and avoid using query strings in requests for static files.

Acceleratable Responses

The number of times the response to an acceleratable request was eligible for addition to the accelerator cache.


When the server serves a static file from the file cache, the accelerator cache may be able to cache the response for faster processing on subsequent requests. To maximize performance, maximize the number of responses that can be accelerated. In the default configuration, all responses to requests for static files can be cached in the accelerator cache. The following configuration changes may prevent a response from being accelerated:

To maximize the number of responses that can be accelerated, avoid such configurations.

Accelerator Hit Ratio

The number of times the response for a request that can be accelerated was found in the accelerator cache. Web Server can also serve requests from the accelerator cache asynchronously directly from the keep-alive threads thereby bypassing the connection queue altogether. This leads to improved performance for these requests and at the same time reduces contention on the connection queue.


Higher hit ratios result in better performance. To maximize the hit ratio, see the tuning information for Acceleratable Responses.

File Cache Enabled

If the cache is disabled, the rest of this section is not displayed in perdump. In the Admin Console, the File Cache Statistics section shows zeros for the values.


The cache is enabled by default. You can disable it in the Admin Console by deselecting the File Cache Enabled box on the configuration's Performance tab ⇒ Cache sub tab, under File Cache. To disable it using the command-line-interface, use wadm set-file-cache-prop and set the enabled property to false.

File Cache Entries

The number of current cache entries and the maximum number of cache entries are both displayed in perfdump. In the Admin Console, they are called the Number of Entries and the Maximum Cache Size. A single cache entry represents a single URI.


The optimal file cache size is dependent on whether you are running a 32-bit or a 64-bit server. The available address space for a 32–bit server is limited to 4GB. The max-entries for file cache is based on the amount of Java heap, the number of threads (as specified by thread-pool/max-threads), and the connection queue size. It is recommended to cache small, frequently accessed static files in the file cache and use perfdump to ensure that the file cache hit ratio is close to 100%. To achieve this, you may increase file cache size and fine tune the max-entries for optimal performance. In a 64-bit server, due to the increased availability of address space, you can cache more static content in the file cache.

You can set the maximum number of cached entries in the Admin Console in the Maximum Entries field on the configuration's Performance tab ⇒ Cache tab, under File Cache. In the command-line interface, use wadm set-file-cache-prop and set the max-entries property. The default is 1024. The range of values is 1-1048576.

File Cache Hit Ratio (Cache Hits / Cache Lookups)

The hit ratio available through perfdump gives you the number of file cache hits compared to cache lookups. Numbers approaching 100% indicate that the file cache is operating effectively, while numbers approaching 0% indicate that the file cache is not serving many requests.

To figure this number yourself using the statistics provided through the Admin Console, divide the Total Cache Hits by the sum of the Total Cache Hits and the Total Cache Misses.

This setting is not tunable.

Maximum Age

This field displays the maximum age of a valid cache entry. The parameter controls how long cached information is used after a file has been cached. An entry older than the maximum age is replaced by a new entry for the same file.


Set the maximum age based on whether the content is updated (existing files are modified) on a regular schedule. For example, if content is updated four times a day at regular intervals, you can set the maximum age to 21600 seconds (6 hours). Otherwise, consider setting the maximum age to the longest time you are willing to serve the previous version of a content file after the file has been modified. If your web site’s content changes infrequently, you might want to increase this value for improved performance.

Set the maximum age in the Admin Console in the Maximum Age field on the configuration's Performance tab ⇒ Cache tab, under File Cache. In the command-line interface, use wadm set-file-cache-prop and change the max-age property. The default value is 30 seconds. The range of values is 0.001-3600.

Maximum Heap Cache Size

The optimal cache heap size depends upon how much system memory is free. A larger heap size means that the Web Server can cache more content and therefore obtain a better hit ratio. However, the heap size should not be so large that the operating system starts paging cached files.


Set the maximum heap size in the Admin Console in the Maximum Heap Space Size field on the configuration's Performance tab ⇒ Cache tab, under File Cache. In the command-line interface, use wadm set-file-cache-prop and change the max-heap-space property. The default value is 10485760 bytes. The range of values is 0-9223372036854775807. In a 32–bit Web Server, since processes have four GBs of address space for the file cache, the value should be well under four GB.

Using the nocache Parameter

You can use the parameter nocache for the Service function send-file to specify that files in a certain directory are not cached. Make this change by editing obj.conf. For example, if you have a set of files that changes too rapidly for caching to be useful, you can put them into a directory and instruct the server not to cache files in that directory by editing obj.conf.


<Object name=default>
NameTrans fn="pfx2dir" from="/myurl" dir="/export/mydir"
Service method=(GET|HEAD|POST) type=*~magnus-internal/*
<Object name="myname">
Service method=(GET|HEAD) type=*~magnus-internal/* fn=send-file

In the previous example, the server does not cache static files from /export/mydir/ when requested by the URL prefix /myurl. For more information on editing obj.conf, see Sun Java System Web Server 7.0 Update 4 Administrator’s Configuration File Reference.

Using sendfile-size to Pace Large Files

When file-cache/sendfile is set to true, Web Server uses the operating system sendfile call to service large static files from the file cache. The performance of serving such files from the file cache can be improved by limiting the number of bytes sent by a single sendfile call. Using a non zero value for file-cache/sendfile-size will send the file in chunks, where the chunk size is at the most the size of sendfile-size.


While serving large files, for example, movie files, consider tuning the file-cache/sendfile-size. A sendfile-size of 1MB can provide improved performance compared to the default sendfile-size of zero. You can set the sendfile-size in Admin Console by editing Sendfile Size field on the configuration's Performance tab ⇒ Cache tab, under File Cache. In the command-line interface, use wadm set-file-cache-prop command's sendfile-size property.

File Cache Dynamic Control and Monitoring

File Cache stores file contents in the memory. You can add an object to obj.conf to dynamically monitor and control the file cache while the server is running.

ProcedureTo Control and Monitor the File Cache

  1. Add a NameTrans directive to the default object:

    NameTrans fn="assign-name" from="/nsfc" name="nsfc"

  2. Add an nsfc object definition:

    <Object name="nsfc">
    Service fn="service-nsfc-dump"

    This configuration enables the file cache control and monitoring function (nsfc-dump) to be accessed through the URI /nfsc. To use a different URI, change the from parameter in the NameTrans directive.

    The following is an example of the information you receive when you access the URI:

    Sun Java System File Cache Status (pid 3602)
    The file cache is enabled.
    Cache resource utilization
    Number of cached file entries = 174968 (152 bytes each, 26595136 total bytes)
    Heap space used for cache = 1882632616/1882632760 bytes
    Mapped memory used for medium file contents = 0/1 bytes
    Number of cache lookup hits = 47615653/48089040 ( 99.02 %)
    Number of hits/misses on cached file info = 23720344/324195
    Number of hits/misses on cached file content = 16247503/174985
    Number of outdated cache entries deleted = 0
    Number of cache entry replacements = 0
    Total number of cache entries deleted = 0
    Parameter settings
    ReplaceFiles: false
    ReplaceInterval: 1 milliseconds
    HitOrder: false
    CacheFileContent: true
    TransmitFile: false
    MaxAge: 3600 seconds
    MaxFiles: 600000 files
    SmallFileSizeLimit: 500000 bytes
    MediumFileSizeLimit: 1000001 bytes
    BufferSize: 8192 bytes
    CopyFiles: false
    Directory for temporary files: /tmp
    Hash table size: 1200007 buckets

    You can include a query string when you access the URI. The following values are recognized:

    • ?list: Lists the files in the cache.

    • ?refresh=n: Causes the client to reload the page every n seconds.

    • ?restart: Causes the cache to be shut down and then restarted.

    • ?start: Starts the cache.

    • ?stop: Shuts down the cache.

    If you choose the ?list option, the file listing includes the file name, a set of flags, the current number of references to the cache entry, the size of the file, and an internal file ID value. The flags are as follows:

    • C: File contents are cached.

    • D: Cache entry is marked for delete.

    • E: PR_GetFileInfo() returned an error for this file.

    • I: File information including size and modification date is cached.

    • M: File contents are mapped into virtual memory.

    • O: File descriptor is cached (when TransmitFile is set to true).

    • P: File has associated private data and appears on shtml files.

    • T: Cache entry has a temporary file.

    • W: Cache entry is locked for write access.