Skip to content

Commit a3595ae

Browse files
adinauerclaude
adinauer
and
claude
authored
docs(java): Add cache tracing integration pages (#16981)
Add integration docs for Java SDK cache tracing: JCache (JSR-107), Caffeine, Ehcache, and Redis (Jedis/Lettuce). - **JCache page** — full setup guide for `SentryJCacheWrapper` with traced operations table, span data reference - **Caffeine / Ehcache / Redis pages** — for Spring Boot: just enable `sentry.enable-cache-tracing=true`; for plain Java: link to JCache integration with provider-specific dependency snippets - **Configuration options** — adds `enableCacheTracing` to the tracing options reference Companion to the sentry-java cache tracing PR stack: - getsentry/sentry-java#5165 (collection) - getsentry/sentry-java#5172 — SentryCacheWrapper and SentryCacheManagerWrapper - getsentry/sentry-java#5173 — enableCacheTracing option - getsentry/sentry-java#5174 — BeanPostProcessor and auto-configuration - getsentry/sentry-java#5179 — SentryJCacheWrapper - getsentry/sentry-java#5182 — JCache console sample - getsentry/sentry-java#5183 — Spring Boot 4 samples - getsentry/sentry-java#5184 — reactive/async cache support - getsentry/sentry-java#5190 — Spring Boot 3 port - getsentry/sentry-java#5191 — Spring Boot 2 port - getsentry/sentry-java#5192 — NoOp span fix --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent e0316bf commit a3595ae

File tree

5 files changed

+259
-0
lines changed

5 files changed

+259
-0
lines changed

‎docs/platforms/java/common/configuration/options.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -297,6 +297,12 @@ Set this boolean to `false` to disable tracing for `OPTIONS` requests. This opti
297297

298298
</SdkOption>
299299

300+
<SdkOption name="enableCacheTracing" type="boolean" defaultValue="false">
301+
302+
Whether cache operations (`get`, `put`, `remove`, `flush`) should be traced. When enabled, the SDK creates spans for cache operations performed through the <PlatformLink to="/integrations/jcache/">JCache integration</PlatformLink> or Spring Cache (e.g. `@Cacheable`, `@CachePut`, `@CacheEvict`).
303+
304+
</SdkOption>
305+
300306
## Profiling Options
301307

302308
<SdkOption name="profileSessionSampleRate" type="float" availableSince="8.23.0">

‎docs/platforms/java/common/integrations/caffeine.mdx‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: Caffeine Integration
3+
description: "Learn how to trace Caffeine cache operations with Sentry."
4+
---
5+
6+
Sentry can trace cache operations performed by [Caffeine](https://github.com/ben-manes/caffeine), the high-performance in-memory caching library for Java. Cache spans appear in Sentry's [Caches dashboard](https://sentry.io/orgredirect/organizations/:orgslug/insights/backend/caches/).
7+
8+
<PlatformSection supported={["java.spring-boot"]}>
9+
10+
## Spring Boot
11+
12+
If you're using Caffeine as your Spring Boot cache provider, cache tracing is built into the Sentry Spring Boot starter. Enable it in your configuration:
13+
14+
```properties {tabTitle:application.properties}
15+
sentry.enable-cache-tracing=true
16+
sentry.traces-sample-rate=1.0
17+
```
18+
19+
```yaml {tabTitle:application.yml}
20+
sentry:
21+
enable-cache-tracing: true
22+
traces-sample-rate: 1.0
23+
```
24+
25+
All `@Cacheable`, `@CachePut`, and `@CacheEvict` operations will automatically produce Sentry spans — no additional dependencies or code changes required.
26+
27+
See <PlatformLink to="/configuration/options/#enableCacheTracing">`enableCacheTracing`</PlatformLink> for more details on this option.
28+
29+
</PlatformSection>
30+
31+
<PlatformSection notSupported={["java.spring-boot"]}>
32+
33+
## Plain Java
34+
35+
Caffeine provides a [JCache (JSR-107) adapter](https://github.com/ben-manes/caffeine/wiki/JCache). Use it together with the <PlatformLink to="/integrations/jcache/">Sentry JCache integration</PlatformLink> to trace cache operations.
36+
37+
</PlatformSection>

‎docs/platforms/java/common/integrations/ehcache.mdx‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: Ehcache Integration
3+
description: "Learn how to trace Ehcache cache operations with Sentry."
4+
---
5+
6+
Sentry can trace cache operations performed by [Ehcache](https://www.ehcache.org/), a widely-used Java caching library. Cache spans appear in Sentry's [Caches dashboard](https://sentry.io/orgredirect/organizations/:orgslug/insights/backend/caches/).
7+
8+
<PlatformSection supported={["java.spring-boot"]}>
9+
10+
## Spring Boot
11+
12+
If you're using Ehcache as your Spring Boot cache provider, cache tracing is built into the Sentry Spring Boot starter. Enable it in your configuration:
13+
14+
```properties {tabTitle:application.properties}
15+
sentry.enable-cache-tracing=true
16+
sentry.traces-sample-rate=1.0
17+
```
18+
19+
```yaml {tabTitle:application.yml}
20+
sentry:
21+
enable-cache-tracing: true
22+
traces-sample-rate: 1.0
23+
```
24+
25+
All `@Cacheable`, `@CachePut`, and `@CacheEvict` operations will automatically produce Sentry spans — no additional dependencies or code changes required.
26+
27+
See <PlatformLink to="/configuration/options/#enableCacheTracing">`enableCacheTracing`</PlatformLink> for more details on this option.
28+
29+
</PlatformSection>
30+
31+
<PlatformSection notSupported={["java.spring-boot"]}>
32+
33+
## Plain Java
34+
35+
Ehcache 3 implements the [JCache (JSR-107)](https://www.ehcache.org/documentation/3.0/107.html) API natively. Use it together with the <PlatformLink to="/integrations/jcache/">Sentry JCache integration</PlatformLink> to trace cache operations.
36+
37+
</PlatformSection>

‎docs/platforms/java/common/integrations/jcache.mdx‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
---
2+
title: JCache Integration
3+
description: "Learn how to trace cache operations using the Sentry JCache (JSR-107) integration."
4+
notSupported:
5+
- java.spring-boot
6+
---
7+
8+
Sentry's [JCache (JSR-107)](https://www.jcp.org/en/jsr/detail?id=107) integration automatically creates spans for cache operations like `get`, `put`, `remove`, and `clear`. It works with any JCache provider (Caffeine, Ehcache, Hazelcast, etc.).
9+
10+
Cache spans appear in Sentry's [Caches dashboard](https://sentry.io/orgredirect/organizations/:orgslug/insights/backend/caches/).
11+
12+
## Install
13+
14+
```groovy {tabTitle:Gradle}
15+
implementation 'io.sentry:sentry-jcache:{{@inject packages.version('sentry.java.jcache', '8.35.0') }}'
16+
```
17+
18+
```xml {tabTitle:Maven}
19+
<dependency>
20+
<groupId>io.sentry</groupId>
21+
<artifactId>sentry-jcache</artifactId>
22+
<version>{{@inject packages.version('sentry.java.jcache', '8.35.0') }}</version>
23+
</dependency>
24+
```
25+
26+
```scala {tabTitle: SBT}
27+
libraryDependencies += "io.sentry" % "sentry-jcache" % "{{@inject packages.version('sentry.java.jcache', '8.35.0') }}"
28+
```
29+
30+
For other dependency managers, check out the [central Maven repository](https://search.maven.org/artifact/io.sentry/sentry-jcache).
31+
32+
## Set Up
33+
34+
Enable cache tracing in your Sentry configuration:
35+
36+
```java {tabTitle:Java}
37+
Sentry.init(options -> {
38+
options.setDsn("___DSN___");
39+
options.setTracesSampleRate(1.0);
40+
options.setEnableCacheTracing(true);
41+
});
42+
```
43+
44+
```kotlin {tabTitle:Kotlin}
45+
Sentry.init { options ->
46+
options.dsn = "___DSN___"
47+
options.tracesSampleRate = 1.0
48+
options.isEnableCacheTracing = true
49+
}
50+
```
51+
52+
Wrap your `javax.cache.Cache` instance with `SentryJCacheWrapper`:
53+
54+
```java {tabTitle:Java}
55+
import io.sentry.jcache.SentryJCacheWrapper;
56+
import javax.cache.Cache;
57+
import javax.cache.CacheManager;
58+
import javax.cache.Caching;
59+
import javax.cache.spi.CachingProvider;
60+
61+
CachingProvider provider = Caching.getCachingProvider();
62+
CacheManager manager = provider.getCacheManager();
63+
64+
Cache<String, String> cache = manager.getCache("myCache");
65+
Cache<String, String> sentryCache = new SentryJCacheWrapper<>(cache);
66+
67+
// Use sentryCache — all operations produce Sentry spans
68+
sentryCache.put("key", "value"); // cache.put span
69+
String val = sentryCache.get("key"); // cache.get span (cache.hit = true)
70+
sentryCache.remove("key"); // cache.remove span
71+
sentryCache.clear(); // cache.clear span
72+
```
73+
74+
```kotlin {tabTitle:Kotlin}
75+
import io.sentry.jcache.SentryJCacheWrapper
76+
import javax.cache.Caching
77+
78+
val provider = Caching.getCachingProvider()
79+
val manager = provider.cacheManager
80+
81+
val cache = manager.getCache<String, String>("myCache")
82+
val sentryCache = SentryJCacheWrapper(cache)
83+
84+
// Use sentryCache — all operations produce Sentry spans
85+
sentryCache.put("key", "value") // cache.put span
86+
val value = sentryCache.get("key") // cache.get span (cache.hit = true)
87+
sentryCache.remove("key") // cache.remove span
88+
sentryCache.clear() // cache.clear span
89+
```
90+
91+
## Traced Operations
92+
93+
All JCache operations are traced. Each method creates a span with the operation `cache.<methodName>` (e.g. `cache.get`, `cache.putIfAbsent`, `cache.removeAll`).
94+
95+
## Span Data
96+
97+
| Key | Type | Description |
98+
|---|---|---|
99+
| `cache.hit` | boolean | Whether the cache lookup returned a value (read spans only) |
100+
| `cache.key` | list of strings | The cache key(s) involved in the operation |
101+
| `cache.operation` | string | The JCache method name (e.g. `get`, `putIfAbsent`, `removeAll`) |
102+
| `cache.write` | boolean | Whether the operation modified the cache. Always `true` for unconditional writes (`put`, `putAll`, `remove`, `clear`); reflects the actual outcome for conditional operations (`putIfAbsent`, `replace`, `getAndReplace`) and value-matched removes |
103+
104+
Bulk operations (`getAll`, `putAll`, `removeAll`) create a single span with all keys listed in `cache.key`.
105+
106+
## Verify
107+
108+
To verify, trigger a cache operation within an active transaction and check the [Caches dashboard](https://sentry.io/orgredirect/organizations/:orgslug/insights/backend/caches/) or the trace view in Sentry.
109+
110+
```java {tabTitle:Java}
111+
import io.sentry.ISentryLifecycleToken;
112+
import io.sentry.ITransaction;
113+
import io.sentry.Sentry;
114+
115+
ITransaction tx = Sentry.startTransaction("test-cache", "task");
116+
try (ISentryLifecycleToken ignored = tx.makeCurrent()) {
117+
sentryCache.put("greeting", "hello");
118+
String value = sentryCache.get("greeting");
119+
} finally {
120+
tx.finish();
121+
}
122+
```
123+
124+
```kotlin {tabTitle:Kotlin}
125+
import io.sentry.Sentry
126+
127+
val tx = Sentry.startTransaction("test-cache", "task")
128+
try {
129+
tx.makeCurrent().use {
130+
sentryCache.put("greeting", "hello")
131+
val value = sentryCache.get("greeting")
132+
}
133+
} finally {
134+
tx.finish()
135+
}
136+
```

‎docs/platforms/java/common/integrations/redis.mdx‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
title: Redis Integration
3+
description: "Learn how to trace Redis cache operations with Sentry."
4+
---
5+
6+
Sentry can trace cache operations performed through [Redis](https://redis.io/) using Jedis or Lettuce as the client library. Cache spans appear in Sentry's [Caches dashboard](https://sentry.io/orgredirect/organizations/:orgslug/insights/backend/caches/).
7+
8+
<PlatformSection supported={["java.spring-boot"]}>
9+
10+
## Spring Boot
11+
12+
If you're using Redis (via Spring Data Redis with Jedis or Lettuce) as your Spring Boot cache provider, cache tracing is built into the Sentry Spring Boot starter. Enable it in your configuration:
13+
14+
```properties {tabTitle:application.properties}
15+
sentry.enable-cache-tracing=true
16+
sentry.traces-sample-rate=1.0
17+
```
18+
19+
```yaml {tabTitle:application.yml}
20+
sentry:
21+
enable-cache-tracing: true
22+
traces-sample-rate: 1.0
23+
```
24+
25+
All `@Cacheable`, `@CachePut`, and `@CacheEvict` operations will automatically produce Sentry spans — no additional dependencies or code changes required.
26+
27+
See <PlatformLink to="/configuration/options/#enableCacheTracing">`enableCacheTracing`</PlatformLink> for more details on this option.
28+
29+
</PlatformSection>
30+
31+
<PlatformSection notSupported={["java.spring-boot"]}>
32+
33+
## Plain Java
34+
35+
Jedis provides a [JCache (JSR-107)](https://github.com/redis/jedis/wiki/JCache-Support) adapter. Use it together with the <PlatformLink to="/integrations/jcache/">Sentry JCache integration</PlatformLink> to trace cache operations.
36+
37+
<Alert>
38+
39+
Lettuce does not provide a JCache adapter, so the JCache-based approach described here only works with Jedis. For Lettuce-based cache tracing, use Spring Boot with Spring Data Redis.
40+
41+
</Alert>
42+
43+
</PlatformSection>

0 commit comments

Comments
 (0)