.. 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 ` logging field is used. For even more detail, see :ref:`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-cf-hit: TCP_CF_HIT ---------- A valid copy of the requested object is being updated 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`