Class CacheStats
- java.lang.Object
-
- com.google.common.cache.CacheStats
-
@GwtCompatible public final class CacheStats extends java.lang.Object
Statistics about the performance of aCache
. Instances of this class are immutable.Cache statistics are incremented according to the following rules:
- When a cache lookup encounters an existing cache entry
hitCount
is incremented. - When a cache lookup first encounters a missing cache entry, a new entry is loaded.
- After successfully loading an entry
missCount
andloadSuccessCount
are incremented, and the total loading time, in nanoseconds, is added tototalLoadTime
. - When an exception is thrown while loading an entry,
missCount
andloadExceptionCount
are incremented, and the total loading time, in nanoseconds, is added tototalLoadTime
. - Cache lookups that encounter a missing cache entry that is still loading will wait
for loading to complete (whether successful or not) and then increment
missCount
.
- After successfully loading an entry
- When an entry is evicted from the cache,
evictionCount
is incremented. - No stats are modified when a cache entry is invalidated or manually removed.
- No stats are modified by operations invoked on the asMap view of the cache.
A lookup is specifically defined as an invocation of one of the methods
LoadingCache.get(Object)
,LoadingCache.getUnchecked(Object)
,Cache.get(Object, Callable)
, orLoadingCache.getAll(Iterable)
.- Since:
- 10.0
- Author:
- Charles Fry
- When a cache lookup encounters an existing cache entry
-
-
Constructor Summary
Constructors Constructor Description CacheStats(long hitCount, long missCount, long loadSuccessCount, long loadExceptionCount, long totalLoadTime, long evictionCount)
Constructs a newCacheStats
instance.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description double
averageLoadPenalty()
Returns the average time spent loading new values.boolean
equals(java.lang.Object object)
long
evictionCount()
Returns the number of times an entry has been evicted.int
hashCode()
long
hitCount()
Returns the number of timesCache
lookup methods have returned a cached value.double
hitRate()
Returns the ratio of cache requests which were hits.long
loadCount()
Returns the total number of times thatCache
lookup methods attempted to load new values.long
loadExceptionCount()
Returns the number of timesCache
lookup methods threw an exception while loading a new value.double
loadExceptionRate()
Returns the ratio of cache loading attempts which threw exceptions.long
loadSuccessCount()
Returns the number of timesCache
lookup methods have successfully loaded a new value.CacheStats
minus(CacheStats other)
Returns a newCacheStats
representing the difference between thisCacheStats
andother
.long
missCount()
Returns the number of timesCache
lookup methods have returned an uncached (newly loaded) value, or null.double
missRate()
Returns the ratio of cache requests which were misses.CacheStats
plus(CacheStats other)
Returns a newCacheStats
representing the sum of thisCacheStats
andother
.long
requestCount()
Returns the number of timesCache
lookup methods have returned either a cached or uncached value.java.lang.String
toString()
long
totalLoadTime()
Returns the total number of nanoseconds the cache has spent loading new values.
-
-
-
Constructor Detail
-
CacheStats
public CacheStats(long hitCount, long missCount, long loadSuccessCount, long loadExceptionCount, long totalLoadTime, long evictionCount)
Constructs a newCacheStats
instance.Five parameters of the same type in a row is a bad thing, but this class is not constructed by end users and is too fine-grained for a builder.
-
-
Method Detail
-
requestCount
public long requestCount()
Returns the number of timesCache
lookup methods have returned either a cached or uncached value. This is defined ashitCount + missCount
.Note: the values of the metrics are undefined in case of overflow (though it is guaranteed not to throw an exception). If you require specific handling, we recommend implementing your own stats collector.
-
hitCount
public long hitCount()
Returns the number of timesCache
lookup methods have returned a cached value.
-
hitRate
public double hitRate()
Returns the ratio of cache requests which were hits. This is defined ashitCount / requestCount
, or1.0
whenrequestCount == 0
. Note thathitRate + missRate =~ 1.0
.
-
missCount
public long missCount()
-
missRate
public double missRate()
Returns the ratio of cache requests which were misses. This is defined asmissCount / requestCount
, or0.0
whenrequestCount == 0
. Note thathitRate + missRate =~ 1.0
. Cache misses include all requests which weren't cache hits, including requests which resulted in either successful or failed loading attempts, and requests which waited for other threads to finish loading. It is thus the case thatmissCount >= loadSuccessCount + loadExceptionCount
. Multiple concurrent misses for the same key will result in a single load operation.
-
loadCount
public long loadCount()
Returns the total number of times thatCache
lookup methods attempted to load new values. This includes both successful load operations and those that threw exceptions. This is defined asloadSuccessCount + loadExceptionCount
.Note: the values of the metrics are undefined in case of overflow (though it is guaranteed not to throw an exception). If you require specific handling, we recommend implementing your own stats collector.
-
loadSuccessCount
public long loadSuccessCount()
Returns the number of timesCache
lookup methods have successfully loaded a new value. This is usually incremented in conjunction withmissCount
, thoughmissCount
is also incremented when an exception is encountered during cache loading (seeloadExceptionCount
). Multiple concurrent misses for the same key will result in a single load operation. This may be incremented not in conjunction withmissCount
if the load occurs as a result of a refresh or if the cache loader returned more items than was requested.missCount
may also be incremented not in conjunction with this (norloadExceptionCount
) on calls togetIfPresent
.
-
loadExceptionCount
public long loadExceptionCount()
Returns the number of timesCache
lookup methods threw an exception while loading a new value. This is usually incremented in conjunction withmissCount
, thoughmissCount
is also incremented when cache loading completes successfully (seeloadSuccessCount
). Multiple concurrent misses for the same key will result in a single load operation. This may be incremented not in conjunction withmissCount
if the load occurs as a result of a refresh or if the cache loader returned more items than was requested.missCount
may also be incremented not in conjunction with this (norloadSuccessCount
) on calls togetIfPresent
.
-
loadExceptionRate
public double loadExceptionRate()
Returns the ratio of cache loading attempts which threw exceptions. This is defined asloadExceptionCount / (loadSuccessCount + loadExceptionCount)
, or0.0
whenloadSuccessCount + loadExceptionCount == 0
.Note: the values of the metrics are undefined in case of overflow (though it is guaranteed not to throw an exception). If you require specific handling, we recommend implementing your own stats collector.
-
totalLoadTime
public long totalLoadTime()
Returns the total number of nanoseconds the cache has spent loading new values. This can be used to calculate the miss penalty. This value is increased every timeloadSuccessCount
orloadExceptionCount
is incremented.
-
averageLoadPenalty
public double averageLoadPenalty()
Returns the average time spent loading new values. This is defined astotalLoadTime / (loadSuccessCount + loadExceptionCount)
.Note: the values of the metrics are undefined in case of overflow (though it is guaranteed not to throw an exception). If you require specific handling, we recommend implementing your own stats collector.
-
evictionCount
public long evictionCount()
Returns the number of times an entry has been evicted. This count does not include manual invalidations.
-
minus
public CacheStats minus(CacheStats other)
Returns a newCacheStats
representing the difference between thisCacheStats
andother
. Negative values, which aren't supported byCacheStats
will be rounded up to zero.
-
plus
public CacheStats plus(CacheStats other)
Returns a newCacheStats
representing the sum of thisCacheStats
andother
.Note: the values of the metrics are undefined in case of overflow (though it is guaranteed not to throw an exception). If you require specific handling, we recommend implementing your own stats collector.
- Since:
- 11.0
-
hashCode
public int hashCode()
- Overrides:
hashCode
in classjava.lang.Object
-
equals
public boolean equals(@CheckForNull java.lang.Object object)
- Overrides:
equals
in classjava.lang.Object
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
-