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