From a0ea3ecfb2a6ada842d6e0a33a4ff2d135b47650 Mon Sep 17 00:00:00 2001 From: Marcin Grzejszczak Date: Tue, 16 Jan 2024 03:55:51 +0100 Subject: [PATCH] Added examples of cache usage (#4569) --- docs/modules/ROOT/pages/reference/cache.adoc | 94 +++++++++++++++++++ .../cache/CaffeineCacheMetricsTest.java | 13 ++- .../binder/cache/EhCache2MetricsTest.java | 11 ++- .../binder/cache/GuavaCacheMetricsTest.java | 13 ++- .../cache/HazelcastCacheMetricsTest.java | 11 ++- .../binder/cache/JCacheMetricsTest.java | 17 +++- 6 files changed, 146 insertions(+), 13 deletions(-) diff --git a/docs/modules/ROOT/pages/reference/cache.adoc b/docs/modules/ROOT/pages/reference/cache.adoc index df9e9677b4..81f0d81beb 100644 --- a/docs/modules/ROOT/pages/reference/cache.adoc +++ b/docs/modules/ROOT/pages/reference/cache.adoc @@ -1,5 +1,11 @@ +[[overview]] += Micrometer Cache Instrumentations + Micrometer supports binding metrics to a variety of different popular caching libraries. Each implementation supports basic features, such as cache hits versus misses, from which you can derive basic information about the cache hit ratio over a period of time. Micrometer uses a function tracking counter to monitor such things as hits and misses, giving you a notion not only of hits and misses over the total life of the cache (the basic metric exposed from Guava's `CacheStats`, for example) but hits and misses inside a given interval. +[[cache-example]] +== Example + To demonstrate the features of cache monitoring, we start with a simple program that uses `reactor-netty` to read the entirety of Mary Shelley's _Frankenstein_ and put each word in the cache if it has not yet been seen: ==== @@ -42,3 +48,91 @@ The following image shows the miss ratio when it exceeds 10%: .Alerting when the miss ratio exceeds 10% image::reference/cache/grafana-guava-miss-ratio.png[Miss ratio (alerted),width=800] + +== Cache implementations + +Micrometer can instrument various cache implementations + +* <> +* <> +* <> +* <> +* <> + +[[cache-caffeine]] +=== Caffeine + +[source,java,subs=+attributes] +----- +// Setting up instrumentation +include::{include-core-test-java}/io/micrometer/core/instrument/binder/cache/CaffeineCacheMetricsTest.java[tags=setup, indent=0] + +// Binding manually +include::{include-core-test-java}/io/micrometer/core/instrument/binder/cache/CaffeineCacheMetricsTest.java[tags=register, indent=0] + +// Binding through a static method +include::{include-core-test-java}/io/micrometer/core/instrument/binder/cache/CaffeineCacheMetricsTest.java[tags=monitor, indent=0] +----- + +[[cache-ehcache]] +=== EhCache2 + +[source,java,subs=+attributes] +----- +// Setting up instrumentation +include::{include-core-test-java}/io/micrometer/core/instrument/binder/cache/EhCache2MetricsTest.java[tags=setup, indent=0] + +// Binding manually +include::{include-core-test-java}/io/micrometer/core/instrument/binder/cache/EhCache2MetricsTest.java[tags=register, indent=0] + +// Binding through a static method +include::{include-core-test-java}/io/micrometer/core/instrument/binder/cache/EhCache2MetricsTest.java[tags=monitor, indent=0] +----- + +[[cache-guava]] +=== Guava + +[source,java,subs=+attributes] +----- +// Setting up instrumentation +include::{include-core-test-java}/io/micrometer/core/instrument/binder/cache/GuavaCacheMetricsTest.java[tags=setup, indent=0] + +// Binding manually +include::{include-core-test-java}/io/micrometer/core/instrument/binder/cache/GuavaCacheMetricsTest.java[tags=register, indent=0] + +// Binding through a static method +include::{include-core-test-java}/io/micrometer/core/instrument/binder/cache/GuavaCacheMetricsTest.java[tags=monitor, indent=0] +----- + +[[cache-hazelcast]] +=== Hazelcast + +[source,java,subs=+attributes] +----- +// Setting up instrumentation +include::{include-core-test-java}/io/micrometer/core/instrument/binder/cache/HazelcastCacheMetricsTest.java[tags=setup, indent=0] + +// Binding manually +include::{include-core-test-java}/io/micrometer/core/instrument/binder/cache/HazelcastCacheMetricsTest.java[tags=register, indent=0] + +// Binding through a static method +include::{include-core-test-java}/io/micrometer/core/instrument/binder/cache/HazelcastCacheMetricsTest.java[tags=monitor, indent=0] +----- + +[[cache-jcache]] +=== JCache + +[source,java,subs=+attributes] +----- +// Setting up instrumentation +include::{include-core-test-java}/io/micrometer/core/instrument/binder/cache/JCacheMetricsTest.java[tags=setup, indent=0] + +include::{include-core-test-java}/io/micrometer/core/instrument/binder/cache/JCacheMetricsTest.java[tags=setup_2, indent=0] + +// Binding manually +include::{include-core-test-java}/io/micrometer/core/instrument/binder/cache/JCacheMetricsTest.java[tags=register, indent=0] + +// Binding through a static method +include::{include-core-test-java}/io/micrometer/core/instrument/binder/cache/JCacheMetricsTest.java[tags=monitor, indent=0] +----- + diff --git a/micrometer-core/src/test/java/io/micrometer/core/instrument/binder/cache/CaffeineCacheMetricsTest.java b/micrometer-core/src/test/java/io/micrometer/core/instrument/binder/cache/CaffeineCacheMetricsTest.java index 350e989355..515a8097ef 100644 --- a/micrometer-core/src/test/java/io/micrometer/core/instrument/binder/cache/CaffeineCacheMetricsTest.java +++ b/micrometer-core/src/test/java/io/micrometer/core/instrument/binder/cache/CaffeineCacheMetricsTest.java @@ -35,15 +35,20 @@ */ class CaffeineCacheMetricsTest extends AbstractCacheMetricsTest { - private LoadingCache cache = Caffeine.newBuilder().build(key -> ""); + // tag::setup[] + LoadingCache cache = Caffeine.newBuilder().build(key -> ""); - private CaffeineCacheMetrics> metrics = new CaffeineCacheMetrics<>(cache, - "testCache", expectedTag); + CaffeineCacheMetrics> metrics = new CaffeineCacheMetrics<>(cache, "testCache", + expectedTag); + + // end::setup[] @Test void reportExpectedGeneralMetrics() { + // tag::register[] MeterRegistry registry = new SimpleMeterRegistry(); metrics.bindTo(registry); + // end::register[] verifyCommonCacheMetrics(registry, metrics); @@ -64,8 +69,10 @@ void reportExpectedGeneralMetrics() { @Test void constructInstanceViaStaticMethodMonitor() { + // tag::monitor[] MeterRegistry meterRegistry = new SimpleMeterRegistry(); CaffeineCacheMetrics.monitor(meterRegistry, cache, "testCache", expectedTag); + // end::monitor[] meterRegistry.get("cache.eviction.weight").tags(expectedTag).functionCounter(); } diff --git a/micrometer-core/src/test/java/io/micrometer/core/instrument/binder/cache/EhCache2MetricsTest.java b/micrometer-core/src/test/java/io/micrometer/core/instrument/binder/cache/EhCache2MetricsTest.java index f43f54cc70..b0f3e005bd 100644 --- a/micrometer-core/src/test/java/io/micrometer/core/instrument/binder/cache/EhCache2MetricsTest.java +++ b/micrometer-core/src/test/java/io/micrometer/core/instrument/binder/cache/EhCache2MetricsTest.java @@ -41,14 +41,19 @@ class EhCache2MetricsTest extends AbstractCacheMetricsTest { private static CacheManager cacheManager; - private static Cache cache; + // tag::setup[] + static Cache cache; - private EhCache2Metrics metrics = new EhCache2Metrics(cache, expectedTag); + EhCache2Metrics metrics = new EhCache2Metrics(cache, expectedTag); + + // end::setup[] @Test void reportMetrics() { + // tag::register[] MeterRegistry registry = new SimpleMeterRegistry(); metrics.bindTo(registry); + // end::register[] verifyCommonCacheMetrics(registry, metrics); @@ -117,8 +122,10 @@ void reportMetrics() { @Test void constructInstanceViaStaticMethodMonitor() { + // tag::monitor[] MeterRegistry meterRegistry = new SimpleMeterRegistry(); EhCache2Metrics.monitor(meterRegistry, cache, expectedTag); + // end::monitor[] meterRegistry.get("cache.remoteSize").tags(expectedTag).gauge(); } diff --git a/micrometer-core/src/test/java/io/micrometer/core/instrument/binder/cache/GuavaCacheMetricsTest.java b/micrometer-core/src/test/java/io/micrometer/core/instrument/binder/cache/GuavaCacheMetricsTest.java index cab755dc3c..56f07b271f 100644 --- a/micrometer-core/src/test/java/io/micrometer/core/instrument/binder/cache/GuavaCacheMetricsTest.java +++ b/micrometer-core/src/test/java/io/micrometer/core/instrument/binder/cache/GuavaCacheMetricsTest.java @@ -29,19 +29,24 @@ */ class GuavaCacheMetricsTest extends AbstractCacheMetricsTest { - private LoadingCache cache = CacheBuilder.newBuilder().build(new CacheLoader() { + // tag::setup[] + LoadingCache cache = CacheBuilder.newBuilder().build(new CacheLoader() { public String load(String key) throws Exception { return ""; } }); - private GuavaCacheMetrics> metrics = new GuavaCacheMetrics<>(cache, - "testCache", expectedTag); + GuavaCacheMetrics> metrics = new GuavaCacheMetrics<>(cache, "testCache", + expectedTag); + + // end::setup[] @Test void reportExpectedMetrics() { + // tag::register[] MeterRegistry registry = new SimpleMeterRegistry(); metrics.bindTo(registry); + // end::register[] verifyCommonCacheMetrics(registry, metrics); @@ -74,8 +79,10 @@ void reportExpectedMetrics() { @Test void constructInstanceViaStaticMethodMonitor() { + // tag::monitor[] MeterRegistry meterRegistry = new SimpleMeterRegistry(); GuavaCacheMetrics.monitor(meterRegistry, cache, "testCache", expectedTag); + // end::monitor[] meterRegistry.get("cache.load.duration").tags(expectedTag).timeGauge(); } diff --git a/micrometer-core/src/test/java/io/micrometer/core/instrument/binder/cache/HazelcastCacheMetricsTest.java b/micrometer-core/src/test/java/io/micrometer/core/instrument/binder/cache/HazelcastCacheMetricsTest.java index 2576c4518f..8da61062d2 100644 --- a/micrometer-core/src/test/java/io/micrometer/core/instrument/binder/cache/HazelcastCacheMetricsTest.java +++ b/micrometer-core/src/test/java/io/micrometer/core/instrument/binder/cache/HazelcastCacheMetricsTest.java @@ -43,14 +43,19 @@ */ class HazelcastCacheMetricsTest extends AbstractCacheMetricsTest { - private static IMap cache; + // tag::setup[] + static IMap cache; - private HazelcastCacheMetrics metrics = new HazelcastCacheMetrics(cache, expectedTag); + HazelcastCacheMetrics metrics = new HazelcastCacheMetrics(cache, expectedTag); + + // end::setup[] @Test void reportMetrics() { + // tag::register[] MeterRegistry meterRegistry = new SimpleMeterRegistry(); metrics.bindTo(meterRegistry); + // end::register[] verifyCommonCacheMetrics(meterRegistry, metrics); @@ -102,8 +107,10 @@ void reportMetrics() { @Test void constructInstanceViaStaticMethodMonitor() { + // tag::monitor[] MeterRegistry meterRegistry = new SimpleMeterRegistry(); HazelcastCacheMetrics.monitor(meterRegistry, cache, expectedTag); + // end::monitor[] meterRegistry.get("cache.partition.gets").tags(expectedTag).functionCounter(); } diff --git a/micrometer-core/src/test/java/io/micrometer/core/instrument/binder/cache/JCacheMetricsTest.java b/micrometer-core/src/test/java/io/micrometer/core/instrument/binder/cache/JCacheMetricsTest.java index 8acfa4b4a8..568bd540eb 100644 --- a/micrometer-core/src/test/java/io/micrometer/core/instrument/binder/cache/JCacheMetricsTest.java +++ b/micrometer-core/src/test/java/io/micrometer/core/instrument/binder/cache/JCacheMetricsTest.java @@ -41,11 +41,14 @@ class JCacheMetricsTest extends AbstractCacheMetricsTest { @SuppressWarnings("unchecked") - private Cache cache = mock(Cache.class); + // tag::setup[] + Cache cache; - private CacheManager cacheManager = mock(CacheManager.class); + JCacheMetrics> metrics; - private JCacheMetrics> metrics; + // end::setup[] + + private CacheManager cacheManager; private MBeanServer mbeanServer; @@ -53,10 +56,14 @@ class JCacheMetricsTest extends AbstractCacheMetricsTest { @BeforeEach void setup() throws Exception { + cache = mock(Cache.class); + cacheManager = mock(CacheManager.class); when(cache.getCacheManager()).thenReturn(cacheManager); when(cache.getName()).thenReturn("testCache"); when(cacheManager.getURI()).thenReturn(new URI("http://localhost")); + // tag::setup_2[] metrics = new JCacheMetrics<>(cache, expectedTag); + // end::setup_2[] // emulate MBean server with MBean used for statistic lookup mbeanServer = MBeanServerFactory.createMBeanServer(); @@ -75,8 +82,10 @@ void tearDown() { @Test void reportExpectedMetrics() { + // tag::register[] MeterRegistry meterRegistry = new SimpleMeterRegistry(); metrics.bindTo(meterRegistry); + // end::register[] verifyCommonCacheMetrics(meterRegistry, metrics); @@ -86,8 +95,10 @@ void reportExpectedMetrics() { @Test void constructInstanceViaStaticMethodMonitor() { + // tag::monitor[] MeterRegistry meterRegistry = new SimpleMeterRegistry(); JCacheMetrics.monitor(meterRegistry, cache, expectedTag); + // end::monitor[] meterRegistry.get("cache.removals").tags(expectedTag).gauge(); }