Sun Java System Web Server 6.1 SP9 Performance Tuning, Sizing, and Scaling Guide

Tuning the File Cache

Sun Java System Web Server uses a file cache to serve static information faster. In previous versions of the server, there was also an accelerator cache that routed requests to the file cache, but the accelerator cache is no longer used. 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.

This section includes the following topics:

Configuring the File Cache

The file cache is turned on by default. The file cache settings are contained in a file called nsfc.conf. You can use the Server Manager to change the file cache settings. For more information about nsfc.conf, see the Sun Java System Web Server 6.1 SP9 Administrator’s Configuration File Reference.

ProcedureTo configure the cache

  1. From the Server Manager, select the Preferences tab.

  2. Select File Cache Configuration.

  3. Select Enable File Cache, if not already selected.

  4. Choose whether to transmit files.

    When you enable Transmit File, the server caches open file descriptors for files in the file cache, rather than the file contents, and PR_TransmitFile is used to send the file contents to a client. When Transmit File is enabled, the distinction normally made by the file cache between small, medium, and large files no longer applies, since only the open file descriptor is being cached. By default, Transmit File is enabled on Windows, and disabled on UNIX. On UNIX, only enable Transmit File for platforms that have native OS support for PR_TransmitFile, which currently includes HP-UX and AIX. It is not recommended for other UNIX/Linux platforms.

  5. Enter a size for the hash table.

    The default size is twice the maximum number of files plus 1. For example, if your maximum number of files is set to 1024, the default hash table size is 2049.

  6. Enter a maximum age in seconds for a valid cache entry.

    By default, this is set to 30.

    This setting controls how long cached information will continue to be used once a file has been cached. An entry older than MaxAge is replaced by a new entry for the same file, if the same file is referenced through the cache.

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

  7. Enter the Maximum Number of Files to be cached.

    By default, this is set to 1024.

  8. (UNIX/Linux only) Enter medium and small file size limits in bytes.

    By default, the Medium File Size Limit is set to 537600.

    By default, the Small File Size Limit is set to 2048.

    The cache treats small, medium, and large files differently. The contents of medium files are cached by mapping the file into virtual memory (currently only on UNIX/Linux platforms). The contents of small files are cached by allocating heap space and reading the file into it. The contents of large files (larger than medium) are not cached, although information about large files is cached.

    The advantage of distinguishing between small files and medium files is to avoid wasting part of many pages of virtual memory when there are lots of small files. So the Small File Size Limit is typically a slightly lower value than the VM page size.

  9. (UNIX/Linux only) Set the medium and small file space.

    The medium file space is the size in bytes of the virtual memory used to map all medium sized files. By default, this is set to 10485760.

    The small file space is the size of heap space in bytes used for the cache, including heap space used to cache small files. By default, this is set to 1048576 for UNIX/Linux.

  10. Click OK, and then click Apply.

  11. Select Apply Changes to restart your server and put your changes into effect.

Using the nocache Parameter

You can use the parameter nocache for the Service function send-file to specify that files in a certain directory should not be cached. 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.

Example

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

In the above example, the server does not cache static files from /export/mydir/ when requested by the URL prefix /myurl.

Monitoring the File Cache with the Server Manager

ProcedureTo view the file cache statistics with the Server Manager

  1. From the Server Manager, select Monitor.

  2. Select Monitor Current Activity.

    If you have not yet activated statistics, do so when the Enable Statistics/Profiling page displays, click OK, and then restart the server and return to this page.

  3. Select a refresh interval from the drop-down list.

  4. From the drop-down list of statistics to be displayed, choose Cache and then click Submit.

  5. The cache statistics display and are refreshed every 5-15 seconds, depending on the refresh interval.

    The statistics include information on your cache settings, how many hits the cache is getting, and so on.

File Cache Dynamic Control and Monitoring

You can add an object to obj.conf to dynamically monitor and control the nsfc.conf file cache while the server is running.

ProcedureTo add an object to obj.conf

  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 </Object>

    This enables the file cache control and monitoring function (nsfc-dump) to be accessed through the URI, "/nsfc." By changing the "from" parameter in the NameTrans directive, a different URI can be used.

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


    Sun Java System Web Server File Cache Status (pid 7960)
    
    The file cache is enabled.
    
     Cache resource utilization
    
    Number of cached file entries = 1039 (112 bytes each, 116368 total
    bytes)
    Heap space used for cache = 237641/1204228 bytes
    Mapped memory used for medium file contents = 5742797/10485760 bytes
    Number of cache lookup hits = 435877/720427 ( 60.50 %)
    Number of hits/misses on cached file info = 212125/128556
    Number of hits/misses on cached file content = 19426/502284
    Number of outdated cache entries deleted = 0
    Number of cache entry replacements = 127405
    Total number of cache entries deleted = 127407
    Number of busy deleted cache entries = 17
    
    Parameter settings
    
    HitOrder: false
    CacheFileInfo: true
    CacheFileContent: true
    TransmitFile: false
    MaxAge: 30 seconds
    MaxFiles: 1024 files
    SmallFileSizeLimit: 2048 bytes
    MediumFileSizeLimit: 537600 bytes
    CopyFiles: false
    Directory for temporary files: /tmp/netscape/https-axilla.mcom.com
    Hash table size: 2049 buckets

    You can include a query string when you access the "/nsfc" 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 (size, modify date, and so on) 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 (should appear on shtml files).

    • T: Cache entry has a temporary file.

    • W: Cache entry is locked for write access.

      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 will slow down, the server operates normally when the cache is off.