obj.hits

INTEGER, read-only.

Available inhitdeliverlog

The number of times the cache object has been read on this cache server.

Hits are counted independently on each cache server and incoming requests may be handled by any cache server in a data center; therefore, consecutive requests for the same resource may encounter values of obj.hits that are lower than previously encountered values.

Clustering effects

Due to the effects of clustering, every cache object will have one server within the data center that serves as the primary storage location for that object, determined using a consistent hashing algorithm. However, particularly popular objects may also be temporarily cached on other cache servers within the same data center to avoid overloading the primary.

The value of obj.hits is local to each server and is not passed from one to another during the clustering process. As a result, the value readable in vcl_deliver will often be 1 even if the object has experienced a large number of hits on the server on which it is stored. The value is more accurate when read in the vcl_hit subroutine, but in that case will still exclude hits handled by non-primary servers that happen to have the object in cache.

The possible clustering scenarios and effects on obj.hits are:

  1. A hit after clustering: In vcl_hit the value of obj.hits represents hits on the object on the primary storage node. In vcl_deliver the value of obj.hits is 1. The x-cache-hits response header value is 1.
  2. A hit without clustering where the delivery node is not the primary: This happens when an object is temporarily stored on servers other than the primary node, and a request encounters a hit on one of these servers, making it unnecessary to cluster the request to the primary. obj.hits will have a consistent value in all VCL subroutines, but it will be likely low since it is counting hits on an ephemeral copy of the object.
  3. A hit without clustering where the delivery node is the primary: If a request is initially handled by the server that happens to be the primary storage node for the object, then obj.hits will have a consistent value in all VCL subroutines, and will be higher than in scenario 2, since the object on the primary will collect more hits than a copy on a non-primary node.

In summary, obj.hits should be used with caution when clustering is enabled on a service.

User contributed notes

BETA

Do you see an error in this page? Do have an interesting use case, example or edge case people should know about? Share your knowledge and help people who are reading this page! (Comments are moderated; for support, please contact support@fastly.com)