doc/admin-guide/logging/cache-results.en.rst - trafficserver - Git at Google

 .. Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.

 .. include:: ../../common.defs

 .. _admin-logging-cache-results:

 Logging Cache Results
 *********************

 In addition to recording information about client and origin requests and
 responses, |TS| exposes detailed information about cache interactions for every
 request which passes through a node. This information is incredibly important
 to establishing an efficient caching configuration, though it is only present
 in your logging output if the :ref:`crc <crc>` logging field is used. For even
 more detail, see :ref:`crsc <crsc>`.

 Interpreting Cache Results
 ==========================

 An immediate benefit to including cache result codes in your logging output is
 the ability to trace and diagnose specific problems. You may be able to tell
 without any help that a particular request takes much longer than it should,
 and HTTP response inspection reveals a very small (or possibly zero)
 value for the Age header, but you may still be left wondering why. If it's
 possible to correlate the problematic request(s) with access log entries, the
 cache result code may help shed significant light.

 Misconfigured headers from your origin may be resulting in clients aggressively
 sending ``no-cache`` requests, or cache objects may be going stale too rapidly
 and IMS (``If-Modified-Since``) requests are reaching back to the origin server
 more often than you anticipated. Perhaps this isn't a regular web browser
 request, but part of an application's API and the HTTP method being used isn't
 understood by |TS| and instead just gets passed blindly through to the origin.
 These and other situations can all be revealed pretty quickly by logging and
 inspecting |TS| cache results.

 Even more useful as an overall monitoring and optimization strategy is to log
 the cache results, and then produce reports through log aggregation and
 analysis tools. Such an approach can reveal larger trends and unearth problems
 or inefficiencies that don't necessarily result in outright client errors or
 bug reports from users.

 A high ratio of :ref:`crc-tcp-miss` to :ref:`crc-tcp-hit` events can indicate
 that your cache is sized too small and objects are being evicted too quickly
 for your |TS| cache to reduce traffic to your origin servers - largely
 defeating the purpose of having a caching layer at all. Here *too small* could
 be anything from simply not sized appropriately despite your hopes and
 intentions otherwise (hopefully because you're still fine-tuning your
 configuration based on monitoring and reporting results) to the difficult
 situation in which you operate very large sets of cacheable data that see too
 sparse access patterns to easily create a single cache policy.

 In the latter scenario, you may need to investigate tiered caching policies on
 subsets of your data to better tune the eviction rates, or partition data
 across different storage volumes to keep less-frequently, but very large
 objects (e.g. hours-long, archived training videos from years past) from
 suddenly evicting large numbers of more moderately visited, much smaller, but
 infrequently-changing objects (e.g. costly HTML pages of your semester course
 schedules generated by an unruly SQL query in your aging CMS).

 Large numbers of :ref:`crc-tcp-client-refresh` events for objects which are supposed to be
 served primarily (or perhaps almost exclusively) from your |TS| cache may
 indicate that something, possibly a misconfiguration of the caching headers in
 your origin server responses, is triggering clients to submit requests with
 ``no-cache`` enabled.

 Almost any non-trivial occurrence of :ref:`crc-tcp-ref-fail-hit` requests is a
 signal that your origin servers are not responding to proxied requests from
 |TS| when they should. |TS| has found an object in its cache, but determining
 it to be stale attempted to refresh the object from an origin and was met with
 failure. The client still received an object back, but there was a chance it
 may have been outdated as a result of the origin failure.

 .. _admin-logging-crc:

 Cache Result Codes
 ==================

 The following are all possible cache result codes you will currently encounter
 in |TS| logging output, and what each one means.

 .. _crc-tcp-hit:

 TCP_HIT
 -------

 A valid copy of the requested object was in the cache and Traffic Server sent
 the object to the client.

 .. _crc-tcp-miss:

 TCP_MISS
 --------

 The requested object was not in cache, so |TS| retrieved
 the object from the origin server (or a parent proxy) and sent it to
 the client.

 .. _crc-tcp-refresh-hit:

 TCP_REFRESH_HIT
 ---------------

 The object was in the cache, but it was stale. |TS| made an
 ``if-modified-since`` request to the origin server and the
 origin server sent a ``304`` not-modified response. Traffic
 Server sent the cached object to the client.

 .. _crc-tcp-ref-fail-hit:

 TCP_REF_FAIL_HIT
 ----------------

 The object was in the cache but was stale. |TS| made an
 ``if-modified-since`` request to the origin server but the server
 did not respond. |TS| sent the cached object to the
 client.

 .. _crc-tcp-refresh-miss:

 TCP_REFRESH_MISS
 ----------------

 The object was in the cache but was stale. |TS| made an
 ``if-modified-since`` request to the origin server and the server
 returned a new object. |TS| served the new object to the
 client.

 .. _crc-tcp-client-refresh:

 TCP_CLIENT_REFRESH
 ------------------

 The client issued a request with a ``no-cache`` header. Traffic
 Server obtained the requested object from the origin server and sent
 a copy to the client. |TS| deleted the previous copy of
 the object from cache.

 .. _crc-tcp-ims-hit:

 TCP_IMS_HIT
 -----------

 The client issued an ``if-modified-since`` request and the object
 was in cache and fresher than the IMS date, or an
 ``if-modified-since`` request to the origin server revealed the
 cached object was fresh. |TS| served the cached object to
 the client.

 .. _crc-tcp-ims-miss:

 TCP_IMS_MISS
 ------------

 The client issued an
 ``if-modified-since request`` and the object was either not in
 cache or was stale in cache. |TS| sent an
 ``if-modified-since request`` to the origin server and received the
 new object. |TS| sent the updated object to the client.

 .. _crc-tcp-swapfail:

 TCP_SWAPFAIL
 ------------

 The object was in the cache but could not be accessed. The client
 did not receive the object.

 .. _crc-err-client-abort:

 ERR_CLIENT_ABORT
 ----------------

 The client disconnected before the complete object was sent.

 .. _crc-err-client-read-error:

 ERR_CLIENT_READ_ERROR
 ---------------------

 The client had read errors (network problems).

 .. _crc-err-connect-fail:

 ERR_CONNECT_FAIL
 ----------------

 |TS| could not reach the origin server.

 .. _crc-err-dns-fail:

 ERR_DNS_FAIL
 ------------

 The Domain Name Server (DNS) could not resolve the origin server
 name, or no DNS could be reached.

 .. _crc-err-invalid-req:

 ERR_INVALID_REQ
 ---------------

 The client HTTP request was invalid. (|TS| forwards
 requests with unknown methods to the origin server.)

 .. _crc-err-read-timeout:

 ERR_READ_TIMEOUT
 ----------------

 The origin server did not respond to |TS|'s request within
 the timeout interval.

 .. _crc-err-proxy-denied:

 ERR_PROXY_DENIED
 ----------------

 Client service was denied.

 .. _crc-err-unknown:

 ERR_UNKNOWN
 -----------

 The client connected, but subsequently disconnected without sending
 a request.

 .. _admin-logging-crsc:

 Cache Result Sub-Codes
 ======================

 The following are all possible cache result sub-codes you will currently
 encounter in |TS| logging output, and what each one means. These sub-codes can
 offer more specific details that are not exposed in cache result codes.

 .. _crsc-num-redirects-exceeded:

 NUM_REDIRECTIONS_EXCEEDED
 -------------------------

 The origin server responded with a redirect, but following this redirect would
 exceed the configured maximum number of redirects allowed:
 :ts:cv:`proxy.config.http.number_of_redirections`
	.. Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.

	.. include:: ../../common.defs

	.. _admin-logging-cache-results:

	Logging Cache Results
	*********************

	In addition to recording information about client and origin requests and
	responses, \|TS\| exposes detailed information about cache interactions for every
	request which passes through a node. This information is incredibly important
	to establishing an efficient caching configuration, though it is only present
	in your logging output if the :ref:`crc <crc>` logging field is used. For even
	more detail, see :ref:`crsc <crsc>`.

	Interpreting Cache Results
	==========================

	An immediate benefit to including cache result codes in your logging output is
	the ability to trace and diagnose specific problems. You may be able to tell
	without any help that a particular request takes much longer than it should,
	and HTTP response inspection reveals a very small (or possibly zero)
	value for the Age header, but you may still be left wondering why. If it's
	possible to correlate the problematic request(s) with access log entries, the
	cache result code may help shed significant light.

	Misconfigured headers from your origin may be resulting in clients aggressively
	sending ``no-cache`` requests, or cache objects may be going stale too rapidly
	and IMS (``If-Modified-Since``) requests are reaching back to the origin server
	more often than you anticipated. Perhaps this isn't a regular web browser
	request, but part of an application's API and the HTTP method being used isn't
	understood by \|TS\| and instead just gets passed blindly through to the origin.
	These and other situations can all be revealed pretty quickly by logging and
	inspecting \|TS\| cache results.

	Even more useful as an overall monitoring and optimization strategy is to log
	the cache results, and then produce reports through log aggregation and
	analysis tools. Such an approach can reveal larger trends and unearth problems
	or inefficiencies that don't necessarily result in outright client errors or
	bug reports from users.

	A high ratio of :ref:`crc-tcp-miss` to :ref:`crc-tcp-hit` events can indicate
	that your cache is sized too small and objects are being evicted too quickly
	for your \|TS\| cache to reduce traffic to your origin servers - largely
	defeating the purpose of having a caching layer at all. Here too small could
	be anything from simply not sized appropriately despite your hopes and
	intentions otherwise (hopefully because you're still fine-tuning your
	configuration based on monitoring and reporting results) to the difficult
	situation in which you operate very large sets of cacheable data that see too
	sparse access patterns to easily create a single cache policy.

	In the latter scenario, you may need to investigate tiered caching policies on
	subsets of your data to better tune the eviction rates, or partition data
	across different storage volumes to keep less-frequently, but very large
	objects (e.g. hours-long, archived training videos from years past) from
	suddenly evicting large numbers of more moderately visited, much smaller, but
	infrequently-changing objects (e.g. costly HTML pages of your semester course
	schedules generated by an unruly SQL query in your aging CMS).

	Large numbers of :ref:`crc-tcp-client-refresh` events for objects which are supposed to be
	served primarily (or perhaps almost exclusively) from your \|TS\| cache may
	indicate that something, possibly a misconfiguration of the caching headers in
	your origin server responses, is triggering clients to submit requests with
	``no-cache`` enabled.

	Almost any non-trivial occurrence of :ref:`crc-tcp-ref-fail-hit` requests is a
	signal that your origin servers are not responding to proxied requests from
	\|TS\| when they should. \|TS\| has found an object in its cache, but determining
	it to be stale attempted to refresh the object from an origin and was met with
	failure. The client still received an object back, but there was a chance it
	may have been outdated as a result of the origin failure.

	.. _admin-logging-crc:

	Cache Result Codes
	==================

	The following are all possible cache result codes you will currently encounter
	in \|TS\| logging output, and what each one means.

	.. _crc-tcp-hit:

	TCP_HIT
	-------

	A valid copy of the requested object was in the cache and Traffic Server sent
	the object to the client.

	.. _crc-tcp-miss:

	TCP_MISS
	--------

	The requested object was not in cache, so \|TS\| retrieved
	the object from the origin server (or a parent proxy) and sent it to
	the client.

	.. _crc-tcp-refresh-hit:

	TCP_REFRESH_HIT
	---------------

	The object was in the cache, but it was stale. \|TS\| made an
	``if-modified-since`` request to the origin server and the
	origin server sent a ``304`` not-modified response. Traffic
	Server sent the cached object to the client.

	.. _crc-tcp-ref-fail-hit:

	TCP_REF_FAIL_HIT
	----------------

	The object was in the cache but was stale. \|TS\| made an
	``if-modified-since`` request to the origin server but the server
	did not respond. \|TS\| sent the cached object to the
	client.

	.. _crc-tcp-refresh-miss:

	TCP_REFRESH_MISS
	----------------

	The object was in the cache but was stale. \|TS\| made an
	``if-modified-since`` request to the origin server and the server
	returned a new object. \|TS\| served the new object to the
	client.

	.. _crc-tcp-client-refresh:

	TCP_CLIENT_REFRESH
	------------------

	The client issued a request with a ``no-cache`` header. Traffic
	Server obtained the requested object from the origin server and sent
	a copy to the client. \|TS\| deleted the previous copy of
	the object from cache.

	.. _crc-tcp-ims-hit:

	TCP_IMS_HIT
	-----------

	The client issued an ``if-modified-since`` request and the object
	was in cache and fresher than the IMS date, or an
	``if-modified-since`` request to the origin server revealed the
	cached object was fresh. \|TS\| served the cached object to
	the client.

	.. _crc-tcp-ims-miss:

	TCP_IMS_MISS
	------------

	The client issued an
	``if-modified-since request`` and the object was either not in
	cache or was stale in cache. \|TS\| sent an
	``if-modified-since request`` to the origin server and received the
	new object. \|TS\| sent the updated object to the client.

	.. _crc-tcp-swapfail:

	TCP_SWAPFAIL
	------------

	The object was in the cache but could not be accessed. The client
	did not receive the object.

	.. _crc-err-client-abort:

	ERR_CLIENT_ABORT
	----------------

	The client disconnected before the complete object was sent.

	.. _crc-err-client-read-error:

	ERR_CLIENT_READ_ERROR
	---------------------

	The client had read errors (network problems).

	.. _crc-err-connect-fail:

	ERR_CONNECT_FAIL
	----------------

	\|TS\| could not reach the origin server.

	.. _crc-err-dns-fail:

	ERR_DNS_FAIL
	------------

	The Domain Name Server (DNS) could not resolve the origin server
	name, or no DNS could be reached.

	.. _crc-err-invalid-req:

	ERR_INVALID_REQ
	---------------

	The client HTTP request was invalid. (\|TS\| forwards
	requests with unknown methods to the origin server.)

	.. _crc-err-read-timeout:

	ERR_READ_TIMEOUT
	----------------

	The origin server did not respond to \|TS\|'s request within
	the timeout interval.

	.. _crc-err-proxy-denied:

	ERR_PROXY_DENIED
	----------------

	Client service was denied.

	.. _crc-err-unknown:

	ERR_UNKNOWN
	-----------

	The client connected, but subsequently disconnected without sending
	a request.

	.. _admin-logging-crsc:

	Cache Result Sub-Codes
	======================

	The following are all possible cache result sub-codes you will currently
	encounter in \|TS\| logging output, and what each one means. These sub-codes can
	offer more specific details that are not exposed in cache result codes.

	.. _crsc-num-redirects-exceeded:

	NUM_REDIRECTIONS_EXCEEDED
	-------------------------

	The origin server responded with a redirect, but following this redirect would
	exceed the configured maximum number of redirects allowed:
	:ts:cv:`proxy.config.http.number_of_redirections`