@Immutable public final class CacheStats extends Object
Cache
.
Cache statistics are incremented according to the following rules:
hitCount
is incremented.
missCount
and loadSuccessCount
are
incremented, and the total loading time, in nanoseconds, is added to
totalLoadTime
.
missCount
and loadFailureCount
are incremented, and the total loading time, in nanoseconds, is
added to totalLoadTime
.
missCount
.
loadSuccessCount
or loadFailureCount
is incremented.
evictionCount
is incremented and the
weight added to evictionWeight
.
A lookup is specifically defined as an invocation of one of the methods
LoadingCache.get(Object)
, Cache.get(Object, java.util.function.Function)
, or
LoadingCache.getAll(Iterable)
.
Constructor and Description |
---|
CacheStats(@NonNegative long hitCount,
@NonNegative long missCount,
@NonNegative long loadSuccessCount,
@NonNegative long loadFailureCount,
@NonNegative long totalLoadTime,
@NonNegative long evictionCount)
Deprecated.
This constructor is scheduled for removal in version 3.0.0.
|
CacheStats(@NonNegative long hitCount,
@NonNegative long missCount,
@NonNegative long loadSuccessCount,
@NonNegative long loadFailureCount,
@NonNegative long totalLoadTime,
@NonNegative long evictionCount,
@NonNegative long evictionWeight)
Constructs a new
CacheStats instance. |
Modifier and Type | Method and Description |
---|---|
@NonNegative double |
averageLoadPenalty()
Returns the average time spent loading new values.
|
static @NonNull CacheStats |
empty()
Returns a statistics instance where no cache events have been recorded.
|
boolean |
equals(Object o) |
@NonNegative long |
evictionCount()
Returns the number of times an entry has been evicted.
|
@NonNegative long |
evictionWeight()
Returns the sum of weights of evicted entries.
|
int |
hashCode() |
@NonNegative long |
hitCount()
Returns the number of times
Cache lookup methods have returned a cached value. |
@NonNegative double |
hitRate()
Returns the ratio of cache requests which were hits.
|
@NonNegative long |
loadCount()
Returns the total number of times that
Cache lookup methods attempted to load new
values. |
@NonNegative long |
loadFailureCount()
Returns the number of times
Cache lookup methods failed to load a new value, either
because no value was found or an exception was thrown while loading. |
@NonNegative double |
loadFailureRate()
Returns the ratio of cache loading attempts which threw exceptions.
|
@NonNegative long |
loadSuccessCount()
Returns the number of times
Cache lookup methods have successfully loaded a new value. |
@NonNull CacheStats |
minus(@NonNull CacheStats other)
Returns a new
CacheStats representing the difference between this CacheStats
and other . |
@NonNegative long |
missCount()
Returns the number of times
Cache lookup methods have returned an uncached (newly
loaded) value, or null. |
@NonNegative double |
missRate()
Returns the ratio of cache requests which were misses.
|
@NonNull CacheStats |
plus(@NonNull CacheStats other)
Returns a new
CacheStats representing the sum of this CacheStats and
other . |
@NonNegative long |
requestCount()
Returns the number of times
Cache lookup methods have returned either a cached or
uncached value. |
String |
toString() |
@NonNegative long |
totalLoadTime()
Returns the total number of nanoseconds the cache has spent loading new values.
|
@Deprecated public CacheStats(@NonNegative long hitCount, @NonNegative long missCount, @NonNegative long loadSuccessCount, @NonNegative long loadFailureCount, @NonNegative long totalLoadTime, @NonNegative long evictionCount)
CacheStats
instance.hitCount
- the number of cache hitsmissCount
- the number of cache missesloadSuccessCount
- the number of successful cache loadsloadFailureCount
- the number of failed cache loadstotalLoadTime
- the total load time (success and failure)evictionCount
- the number of entries evicted from the cachepublic CacheStats(@NonNegative long hitCount, @NonNegative long missCount, @NonNegative long loadSuccessCount, @NonNegative long loadFailureCount, @NonNegative long totalLoadTime, @NonNegative long evictionCount, @NonNegative long evictionWeight)
CacheStats
instance.
Many 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.
hitCount
- the number of cache hitsmissCount
- the number of cache missesloadSuccessCount
- the number of successful cache loadsloadFailureCount
- the number of failed cache loadstotalLoadTime
- the total load time (success and failure)evictionCount
- the number of entries evicted from the cacheevictionWeight
- the sum of weights of entries evicted from the cachepublic static @NonNull CacheStats empty()
public @NonNegative long requestCount()
Cache
lookup methods have returned either a cached or
uncached value. This is defined as hitCount + 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 + missCount
public @NonNegative long hitCount()
Cache
lookup methods have returned a cached value.Cache
lookup methods have returned a cached valuepublic @NonNegative double hitRate()
hitCount / requestCount
, or 1.0
when requestCount == 0
. Note that
hitRate + missRate =~ 1.0
.public @NonNegative long missCount()
Cache
lookup methods have returned an uncached (newly
loaded) value, or null. Multiple concurrent calls to Cache
lookup methods on an absent
value can result in multiple misses, all returning the results of a single cache load
operation.Cache
lookup methods have returned an uncached (newly
loaded) value, or nullpublic @NonNegative double missRate()
missCount / requestCount
, or 0.0
when requestCount == 0
.
Note that hitRate + 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
that missCount >= loadSuccessCount + loadFailureCount
. Multiple
concurrent misses for the same key will result in a single load operation.public @NonNegative long loadCount()
Cache
lookup methods attempted to load new
values. This includes both successful load operations, as well as those that threw exceptions.
This is defined as loadSuccessCount + loadFailureCount
.
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 + loadFailureCount
public @NonNegative long loadSuccessCount()
Cache
lookup methods have successfully loaded a new value.
This is always incremented in conjunction with missCount
, though missCount
is also incremented when an exception is encountered during cache loading (see
loadFailureCount
). Multiple concurrent misses for the same key will result in a
single load operation.Cache
lookup methods have successfully loaded a new valuepublic @NonNegative long loadFailureCount()
Cache
lookup methods failed to load a new value, either
because no value was found or an exception was thrown while loading. This is always incremented
in conjunction with missCount
, though missCount
is also incremented when cache
loading completes successfully (see loadSuccessCount
). Multiple concurrent misses for
the same key will result in a single load operation.Cache
lookup methods failed to load a new valuepublic @NonNegative double loadFailureRate()
loadFailureCount / (loadSuccessCount + loadFailureCount)
, or 0.0
when
loadSuccessCount + loadFailureCount == 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.
public @NonNegative long totalLoadTime()
loadSuccessCount
or loadFailureCount
is incremented.public @NonNegative double averageLoadPenalty()
totalLoadTime / (loadSuccessCount + loadFailureCount)
.
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.
public @NonNegative long evictionCount()
public @NonNegative long evictionWeight()
public @NonNull CacheStats minus(@NonNull CacheStats other)
CacheStats
representing the difference between this CacheStats
and other
. Negative values, which aren't supported by CacheStats
will be
rounded up to zero.other
- the statistics to subtract withother
public @NonNull CacheStats plus(@NonNull CacheStats other)
CacheStats
representing the sum of this CacheStats
and
other
.
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.
other
- the statistics to add with