Product Documentation

Configure expressions for caching policies and selectors

A request-time expression examines data in request-time transaction, and a response-time expression examines data in a response-time transaction. In a policy for caching, if an expression matches data in a request or response, the Citrix ADC appliance takes the action associated with the policy. In a selector, request-time expressions are used to find matching responses that are stored in a content group.

Before configuring policies and selectors for the integrated cache, you need to know, at minimum, the host names, paths, and IP addresses that appear in HTTP request and response URLs. And you probably need to know the format of entire HTTP requests and responses. Programs such as Live HTTP Headers http://livehttpheaders.mozdev.org/) or HTTPFox https://addons.mozilla.org/en-US/firefox/addon/6647 can help you investigate the structure of the HTTP data that your organization works with.

Following is an example of an HTTP GET request for a stock quote program:

GET /quote.dll?page=dynamic&mode=data&mode=stock&symbol=CTXS&page=multi&selected=CTXS&random=0.00792039478975548 HTTP/1.1

Host: quotes.mystockquotes.com

User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.9) Gecko/2008052906 Firefox/3.0

Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8

Accept-Language: en-us,en;q=0.5

Accept-Encoding: gzip,deflate,compress,pack200-gzip

Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7

Keep-Alive: 300

Connection: keep-alive

Referer: http://quotes.mystockquotes.com/quote.dll?mode=stock&symbol=CTXS&page=multi&selected=CTXS

Cookie: __qca=1210021679-72161677-10297606

When configuring an expression, note the following limitations: |Expression Type|Restrictions| |— |— | |Request|Do not configure request-time expressions in a policy with a CACHE or NOCACHE action. Use MAY_CACHE or MAY_NOCACHE instead.| |Response|Configure response-time expressions in caching policies only. Selectors can use only request-time expressions, Do not configure response-time expressions in a policy with an INVAL action. Note: Do not configure response-time expressions in a policy with a CACHE action and a parameterized content group. Use the MAY_CACHE action.|

Note For a comprehensive discussion of advanced expressions, see “Policies and Expression.”

Expression syntax

Following are basic components of the syntax:

  • Separate keywords with periods (.), as follows:

http.req.url

  • Enclose string values in parentheses and quotes, as follows:

http.req.url.query.contains("this")

  • When configuring an expression from the command line, you must escape internal quote marks (the quotes that delimit values in the expression, as opposed to the quotes that delimit the expression). One method is to use a slash, as followings:

\"abc\"

Selector expressions are evaluated in order of appearance, and multiple expressions in a selector definition are joined by a logical AND. Unlike selector expressions, you can specify Boolean operators and modify the precedence in an advanced expression for a policy rule.

Configure an expression in a caching policy or a selector

Note The syntax for a policy expression is somewhat different from a selector expression. For a comprehensive discussion of advanced expressions, see “Policies and Expressions.”

To configure a policy expression by using the command line interface

  1. Start the policy definition as described in “Globally Binding an Integrated Caching Policy.”
  2. To configure the policy rule, delimit the entire rule in quotes, and delimit string values within the rule in escaped quotes.

The following is an example:

“http.req.url.contains("jpg")”

  1. To add Boolean values, insert &&,   , or ! operators.

The following are examples:

"http.req.url.contains(\"jpg\") || http.req.url.contains(\"jpeg\")"

"http.req.url.query.contains(\"IssuePage\")"

"http.req.header(\"Host\")contains(\"my.company.com\") && http.req.method.eq(\"GET\") && http.req.url.query.contains(\"v=7\")"

  1. To configure an order of evaluation for the constituent parts of a compound

"http.req.url.contains(\"jpg\") || (http.req.url.contains(\"jpeg\") && http.req.method.eq(\"GET\"))"

To configure a selector expression by using the command line interface

  1. Start the selector definition as described in “About Content Groups.”
  2. To configure the selector expression, delimit the entire rule in quotes, and delimit string values within the rule in escaped quotes.

The following is an example:

"http.req.url.contains(\"jpg\")"

  1. You cannot add Boolean values, insert &&,   , or ! operators. Enter each expression element delimited in quotes. Multiple expressions in the definition are treated as a compound expression joined by logical ANDs.

The following are examples:

“http.req.url.query.value("ProductId")” “http.req.url.query.value("BatchNum")” “http.req.url.query.value("depotLocation")”

To configure a policy or selector expression by using the GUI

  1. Start the policy or selector definition as described in “To configure a policy for caching or invalidation by using the configuration utility” or “To configure a selector by using the configuration utility.”
  2. In the Expression field, you can either manually type the default syntax by clicking Switch to Classic Syntax or create new expression using Expression Editor.
  3. To insert an operator between two parts of a compound expression, click the Operators button and select the operator type. The following is an example of a configured expression with a Boolean OR (signaled by double vertical bars,   ):
  4. Click Frequently Used Expressions drop-down to insert the commonly used expressions.
  5. To test the expression, click the Evaluate. In the Expression Evaluator dialog box, select the Flow Type that matches the expression. In the data field, paste the HTTP request or response that you hope to parse using the expression, and click Evaluate.

Display cached objects and cache statistics

You can view particular cached objects, and you can view summary statistics on cache hits, misses, and memory usage. The statistics provide insight on the amount of data that is being served from the cache, what items are responsible for the largest performance benefit, and what you can tune to improve cache performance.

This section includes the following details:

  • Viewing Cached Objects
  • Finding Particular Cached Responses
  • Viewing Cache Statistics

View cached objects

After enabling caching, you can view details for cached objects. For example, you can view the following items:

  • Response sizes and header sizes
  • Status codes
  • Content groups
  • ETag, Last-Modified, and Cache-Control headers
  • Request URLs
  • Hit parameters
  • Destination IP addresses
  • Request and response times

To view a list of cached objects by using the command line interface

At the command prompt, type:

show cache object

Properties Description
Response size (bytes) The size of the response header and body.
Response header size (bytes) The size of the header portion of the response.
Response status code The status code sent with the response.
ETag The ETag header inserted in the response. Typically, this header indicates whether the response has changed recently.
Last-Modified The Last-Modified header inserted in the response. This header indicates the date that the response was last changed.
Cache-Control The Cache-Control header inserted in the response.
Date The Date header that indicates when the response was sent.
Contentgroup The content group where the response is stored.
Complex match If this object was cached on the basis of parameterized values, this field value is YES.
Host The host specified in the URL that requested this response.
Host port The listen port for the host specified in the URL that requested this response
URL The URL issued for the stored response.
Destination IP The IP address of the server from which this response was fetched.
Destination port The listen port for the destination server.
Hit parameters If the content group that stores the response uses hit parameters, they are listed in this field.
Hit selector If this content group uses a hit selector, it is listed in this field.
Inval selector If this content group uses an invalidation selector, it is listed in this field.
Selector Expressions If this content group uses a selector, this field displays the expression that defines the selection rule.
Request time The time in milliseconds since the request was issued.
Response time The time in milliseconds since the cache started to receive the response.
Age Amount of time the object has been in the cache.
Expiry Amount of time after which the object is marked as expired.
Flushed Whether the response has been flushed after expiry.
Prefetch If Prefetch has been configured for this content group, the amount of time before expiry during which the object is fetched from the origin. Prefetch does not apply to negative objects (for example, 404 “object not found” responses).
Current readers Approximately the current number of hits being served. When a response with a Content-Length header object is being downloaded, the current misses and the current readers values are each typically 1. When a chunked response object is being downloaded, the current misses value is typically 1, but the current readers value is typically 0, because the chunked response that is served to the client does not come from the integrated caching buffers.
Current misses The current number of requests that resulted in a cache miss and fetching from the origin server. This value is typically 0 or 1. If Poll Every Time is enabled for a content group, the count can be greater than 1.
Hits The number of cache hits for this object.
Misses The number of cache misses for this object
Compression format The type of compression applied to this object. Compression formats include gzip, deflate, compress, and pack200-gzip.
HTTP version in response The version of HTTP that was used to send the response.
Weak etag present in response Strong etag headers change if the bits of an entity change. Strong headers are based on the octet values of an object. Weak etag headers change if the meaning of an entity changes. Weak etag values are based on semantic identity. Weak etags values start with a “W.”
Negative marker cell A marker object is cacheable, but it does not yet meet all the criteria for being cached. For example, the object may exceed the maximum response size for the content group. A marker cell is created for objects of this type. The next time a user sends a request for this object, a cache miss is served.
Reason marker created The reason a marker cell was created (for example, “Waiting for minhit,” “Content-length response data is not in group size limit”).
Auto poll every time If the integrated cache receives an already expired 200 OK response with validators (either the Last-Modified or the ETag response headers) it stores the response and marks it as Auto-PET (automatically poll every time).
Citrix ADC Etag inserted in response A variation of the ETag header generated by the Citrix ADC appliance. A value of YES appears if the Citrix ADC inserts an Etag in the response.
Full response present in cache Indicates whether this is a complete response.
Destination IP verified by DNS Indicates whether DNS resolution was performed when storing the object.
Object stored through a cache forward proxy Indicates whether this response was stored due to a forward proxy that is configured in the integrated cache.
Object is a Delta basefile A response that is delta-compressed.
Waiting for minhits Indicates whether this content group requires a minimum number of origin server hits before caching a response.
Minhit count If this content group requires a minimum number of origin server hits before caching an object, this field displays a count of the number of hits received so far.
HTTP Request Method The method, GET or POST, used in the request that obtained this object.
Stored by policy The name of the caching policy that caused this object to be stored. A value of NOT AVAILABLE indicates that the policy has been deactivated or deleted. A value of NONE indicates that the object did not match a visible policy, but was stored according to internal criteria for caching.
Application firewall metadata exists This parameter is used when the application firewall and the integrated cache are both enabled. The application firewall analyzes the contents of a response page, stores its metadata (for example, URLs and forms contained in page), and exports the metadata with the response to the cache. The cache stores the page and the metadata, and when the cache serves the page, it sends the metadata back to the request’s session.
HTTP callout object, name, type, response These cells indicate whether this data was stored as a result of an HTTP Callout expression, and provide information about various aspects of the callout and the corresponding response. For more information about HTTP callouts, see “HTTP Callouts”.

To view cached objects by using the GUI

Navigate to OptimizationIntegrated CachingCache Objects. You can view all the cached objects and sort them accordingly as per your requirement.

Find particular cached responses

You can find individual items in the cache based on search criteria. There are different methods for finding cached items, depending on whether the content group that contains the data uses hit and invalidation selectors, as follows:

  • If the content group uses selectors, you can only conduct the search using the Locator ID for the cached item.
  • If the content group does not use selectors, you conduct the search using criteria such as URL, host, content group name, and so on.

When searching for a cached response, you can locate some items by URL and host. If the response is in a content group that uses a selector, you can find it only by using a Locator number (for example, 0x00000000ad7af00000050). To save a Locator number for later use, right-click the entry and select Copy. For more information about selectors, see “Configuring Selectors and Basic Content Groups.”

To display cached responses in content groups that do not have a selector by using the command line interface

At the command prompt, type:

show cache object [-locator <positiveInteger>] | [(-url <URL> (-host <hostName> [-port <port>] [-groupName <contentGroupName>] [-httpMethod GET | POST ])) | [-httpStatus <positive integer>] | -group <contentGroupName> | -ignoreMarkerObjects (ON | OFF) | -includeNotReadyObjects (ON | OFF)]

To display cached responses in content groups that have a selector by using the command line interface

At the command prompt, type:

show cache object -locator <locatorString> MarkerObjects ( ON | OFF ) | -includeNotReadyObjects ( ON | OFF ) | [-httpStatus<positive integer>]

To display cached responses in content groups that do not have a selector by using the configuration utility

Navigate to Optimization > Integrated Caching > Cache Objects, click Search, and set the search criteria to view the required cached response.

If you have not yet configured any content groups, all of the objects are in the Default group.

To display cached responses in content groups that have a selector by using the configuration utility:

Navigate to Optimization > Integrated Caching > Cache Objects, click Search, and set the selector search criteria to view the required cached response.

View cache statistics

The following table summarizes the detailed cache statistics that you can view. |Counter|Description| |— |— | |Hits|Responses that are found in and served from the integrated cache. Includes static objects such as image files, pages with status codes 200, 203, 300, 301, 302, 304, 307, 403, 404, 410, and responses that match a user-defined policy with a CACHE action.| |Misses|Intercepted HTTP requests where the response was ultimately fetched from origin server.| |Requests|Total cache hits plus total cache misses.| |Non-304 hits|If the user requests an item more than once, and the item in the cache is unchanged since the last time the Citrix ADC appliance served it, the Citrix ADC appliance serves a 304 response instead of the cached object. This statistic indicates how many items the Citrix ADC appliance served from the cache, excluding 304 responses.| |304 hits|Number of 304 (object not modified) responses the Citrix ADC appliance served from the cache.| |304 hit ratio (%)|Percentage of 304 responses that the Citrix ADC appliance served, relative to other responses.| |Hit ratio (%)|Percentage of responses that the Citrix ADC appliance served from the cache (cache hits) relative to responses that could not be served from the cache.| |Origin bandwidth saved (%)|An estimate of the processing capacity that the Citrix ADC appliance saved on the origin server due to serving responses from the cache.| |Bytes served by the Citrix ADC|Total number of bytes that the Citrix ADC appliance served from the origin server and the cache.| |Bytes served by cache|Total number of bytes that the Citrix ADC appliance served from the cache.| |Byte hit ratio(%)|Percentage of data that the Citrix ADC appliance served from the cache, relative to all of the data in all served responses.| |Compressed bytes from cache|Amount of data, in bytes, that the Citrix ADC appliance served in compressed form.| |Storable misses|If the Citrix ADC appliance does not find a requested object in the cache, it fetches the object from the origin server. This is known as a cache miss. A storable cache miss can be stored in the cache.| |Non-storable misses|A non-storable cache miss cannot be stored in the cache.| |Misses|All cache misses.| |Revalidations|Max-Age setting in a Cache-Control header determines, in number of seconds, when an intervening cache must revalidate the content with the integrated cache before serving it to the user. For more information, see “Inserting a Cache-Control Header.”| |Successful revalidations|Number of re-validations that have been performed. For more information, see “Inserting a Cache-Control Header.”| |Conversions to conditional req|A user-agent request for a cached PET object is always converted to a conditional request and sent to the origin server. For more information, see “Polling the Origin Server Every Time a Request Is Received.”| |Storable miss ratio (%)|Storable cache misses as a percentage of non-storable cache misses.| |Successful reval ratio (%)|Successful revalidations as a percentage of all revalidation attempts. For more information, see “Inserting a Cache-Control Header.”| |Expire at last byte|Number of times that the cache expired content immediately after receiving the last body byte. Only applicable to positive responses, as described in the table “Cache Hits and Misses.” For more information, see “Example of Performance Optimization.”| |Flashcache misses|If you enable Flash Cache, the cache allows only one request to reach the server, eliminating flash crowds. This statistic indicates the number of Flash Cache requests that were cache misses. For more information, “Queuing Requests to the Cache.”| |Flashcache hits|Number of Flash Cache requests that were cache hits. For more information, see “Queuing Requests to the Cache.”| |Parameterized inval requests|Requests that match a policy with an invalidation (INVAL) action and a content group that uses an invalidation selector or parameters to selectively expire cached objects in the group.| |Full inval requests|Requests that match an invalidation policy where the invalGroups parameter is configured and expires one or more content groups.| |Inval requests|Requests that match an invalidation policy and result in expiration of specific cached responses or entire content groups.| |Parameterized requests|Number of cache requests that were processed using a policy with a parameterized content group.| |Parameterized non-304 hits|Number of cache requests that were processed using a policy with a parameterized content group, where full cached response was found, and the response was not a 304 (object not updated) response.| |Parameterized 304 hits|Number of cache requests that were processed using a policy with a parameterized content group, where the cached object was found, and the object was a 304 (object not updated) response.| |Total parameterized hits|Number of cache requests that were processed using a policy with a parameterized content group, where the cached object was found.| |Parameterized 304 hit ratio (%)|Percentage of 304 (object not updated) responses that were found using a parameterized policy, relative to all cache hits.| |Poll every time requests|If Poll Every Time is enabled, the Citrix ADC appliance always consults the origin server before serving a stored object. For more information, see “Polling the Origin Server Every Time a Request Is Received.”| |Poll every time hits|Number of times a cache hit was found using the Poll Every Time method. For more information, see “Polling the Origin Server Every Time a Request Is Received.”| |Poll every time hit ratio (%)|Percentage of cache hits using the Poll Every Time method, relative to all searches for cached objects using Poll Every Time. For more information, see “Polling the Origin Server Every Time a Request Is Received.”| |Maximum memory (KB)|Maximum amount of memory in the Citrix ADC appliance that is allocated to the cache. For more information, see “Configuring Global Attributes for Caching.”| |Maximum memory active value (KB)|Maximum amount of memory (active value) that will be set after the memory is actually allocated to the cache. For more information, see “How to Configure the Integrated Caching Feature of a Citrix ADC Appliance for various Scenarios.”| |Utilized memory (KB)|Amount of memory that is actually being used.| |Memory allocation failures|Number of failed attempts to utilize memory for the purpose of storing a response in the cache.| |Largest response so far|Largest response in bytes found in either the cache or the origin server and sent to the client.| |Cached objects|Number of objects in the cache, including responses that have not yet been fully downloaded and responses that have been expired but not yet flushed.| |Marker objects|Marker objects are created when a response exceeds the maximum or minimum response size for the content group, or has not yet received the minimum number of hits for the content group.| |Hits being served|Number of hits that have been served from the cache.| |Misses being handled|Responses that were fetched from the origin server, stored in the cache, and then served. Should approximate the number for storable misses. Does not include non-storable misses.|

To view summary cache statistics by using the command line interface:

At the command prompt, type:

stat cache

To view specific cache statistics by using the command line interface:

At the command prompt, type:

stat cache -detail

> stat cache -detail

Integrated Cache Statistics - Detail
Integrated Cache Statistics - Summary
                                          Rate (/s)                Total


Hits                                               0                    0

Misses                                             0                    0

Requests                                           0                    0

Hit ratio(%)                                      --                    0

Origin bandwidth saved(%)                         --                    0
Cached objects                                    --                    0

Marker objects                                    --                    0
                                          Rate (/s)                Total

Requests                                           0                    0


Hit Statistics

                                          Rate (/s)                Total


Non-304 hits                                       0                    0

304 hits                                           0                    0


Sql hits                                           0                    0


Hits                                               0                    0

304 hit ratio(%)                                  --                    0

Hit ratio(%)                                      --                    0

Origin bandwidth saved(%)                         --                    0
Byte Statistics
                                          Rate (/s)                Total


Bytes served by Citrix ADC                        648             55379204

Bytes served by cache                              0                    0
Byte hit ratio(%)                                 --                    0
Compressed bytes from cache                        0                    0

Miss Statistics

                                          Rate (/s)                Total


Storable misses                                    0                    0

Non-storable misses                                0                    0

Misses                                             0                    0

Revalidations                                      0                    0

Successful revalidations                           0                    0

Conversions to conditional req                     0                    0


Storable miss ratio(%)                            --                    0
Successful reval ratio(%)                         --                    0

Flashcache Statistics
                                          Rate (/s)                Total


Expire at last byte                                0                    0

Flashcache misses                                  0                    0
Flashcache hits                                    0                    0

Invalidation Statistics

                                          Rate (/s)                Total

Parameterized inval requests                       0                    0


Full inval requests                                0                    0



Inval requests                                     0                    0

Parameterized Caching Statistics

                                          Rate (/s)                Total


Parameterized requests                             0                    0

Parameterized non-304 hits                         0                    0

Parameterized 304 hits                             0                    0


Total parameterized hits                           0                    0

Parameterized 304 hit ratio(%)                    --                    0

Poll Every Time (PET) Statistics

                                          Rate (/s)                Total


Poll every time requests                           0                    0

Poll every time hits                               0                    0

Poll every time hit ratio(%)                      --                    0

Memory Usage Statistics
                                              Total

Maximum memory(KB)                                 0

Maximum memory active value(KB)                    0

Utilized memory(KB)                                0

Memory allocation failures                         0

Largest response so far(B)                         0

Cached objects                                     0

Marker objects                                     0

Hits being served                                  0
Misses being handled                               0
 Done

To view summary cache statistics by using the GUI

  1. Click the Dashboard tab at the top of the page.
  2. Scroll down to the Integrated Caching section of the window.
  3. To see detailed statistics, click the More… link at the bottom of the table.

To view specific cache statistics by using the GUI

  1. Click the Reporting tab at the top of the page.
  2. Under Built-In Reports, expand Integrated Cache, and then click the report with the statistics you want to view.
  3. To save the report as a template, click Save As and name the report. The saved report appears under Custom Reports.

Configure expressions for caching policies and selectors