diff --git a/docs/platforms/java/common/configuration/options.mdx b/docs/platforms/java/common/configuration/options.mdx index 68022111be1adb..73849c33c8ca46 100644 --- a/docs/platforms/java/common/configuration/options.mdx +++ b/docs/platforms/java/common/configuration/options.mdx @@ -297,6 +297,12 @@ Set this boolean to `false` to disable tracing for `OPTIONS` requests. This opti + + +Whether cache operations (`get`, `put`, `remove`, `flush`) should be traced. When enabled, the SDK creates spans for cache operations performed through the JCache integration or Spring Cache (`@Cacheable`, `@CachePut`, `@CacheEvict`). + + + ## Profiling Options diff --git a/docs/platforms/java/common/integrations/caffeine.mdx b/docs/platforms/java/common/integrations/caffeine.mdx new file mode 100644 index 00000000000000..6eb5fc1235558c --- /dev/null +++ b/docs/platforms/java/common/integrations/caffeine.mdx @@ -0,0 +1,59 @@ +--- +title: Caffeine Integration +description: "Learn how to trace Caffeine cache operations with Sentry." +--- + +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/). + + + +## Spring Boot + +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: + +```properties {tabTitle:application.properties} +sentry.enable-cache-tracing=true +sentry.traces-sample-rate=1.0 +``` + +```yaml {tabTitle:application.yml} +sentry: + enable-cache-tracing: true + traces-sample-rate: 1.0 +``` + +All `@Cacheable`, `@CachePut`, and `@CacheEvict` operations will automatically produce Sentry spans — no additional dependencies or code changes required. + +See `enableCacheTracing` for more details on this option. + + + + + +## Plain Java + +Caffeine provides a [JCache (JSR-107) adapter](https://github.com/ben-manes/caffeine/wiki/JCache). Use it together with the Sentry JCache integration to trace cache operations. + +Add the dependencies: + +```groovy {tabTitle:Gradle} +implementation 'io.sentry:sentry-jcache:{{@inject packages.version('sentry.java.jcache', '8.35.0') }}' +implementation 'com.github.ben-manes.caffeine:jcache:3.2.0' +``` + +```xml {tabTitle:Maven} + + io.sentry + sentry-jcache + {{@inject packages.version('sentry.java.jcache', '8.35.0') }} + + + com.github.ben-manes.caffeine + jcache + 3.2.0 + +``` + +Then wrap your cache with `SentryJCacheWrapper`. See the JCache integration docs for setup and usage details. + + diff --git a/docs/platforms/java/common/integrations/ehcache.mdx b/docs/platforms/java/common/integrations/ehcache.mdx new file mode 100644 index 00000000000000..797b43542a604c --- /dev/null +++ b/docs/platforms/java/common/integrations/ehcache.mdx @@ -0,0 +1,59 @@ +--- +title: Ehcache Integration +description: "Learn how to trace Ehcache cache operations with Sentry." +--- + +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/). + + + +## Spring Boot + +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: + +```properties {tabTitle:application.properties} +sentry.enable-cache-tracing=true +sentry.traces-sample-rate=1.0 +``` + +```yaml {tabTitle:application.yml} +sentry: + enable-cache-tracing: true + traces-sample-rate: 1.0 +``` + +All `@Cacheable`, `@CachePut`, and `@CacheEvict` operations will automatically produce Sentry spans — no additional dependencies or code changes required. + +See `enableCacheTracing` for more details on this option. + + + + + +## Plain Java + +Ehcache 3 implements the [JCache (JSR-107)](https://www.ehcache.org/documentation/3.0/107.html) API natively. Use it together with the Sentry JCache integration to trace cache operations. + +Add the dependencies: + +```groovy {tabTitle:Gradle} +implementation 'io.sentry:sentry-jcache:{{@inject packages.version('sentry.java.jcache', '8.35.0') }}' +implementation 'org.ehcache:ehcache:3.10.8' +``` + +```xml {tabTitle:Maven} + + io.sentry + sentry-jcache + {{@inject packages.version('sentry.java.jcache', '8.35.0') }} + + + org.ehcache + ehcache + 3.10.8 + +``` + +Then wrap your cache with `SentryJCacheWrapper`. See the JCache integration docs for setup and usage details. + + diff --git a/docs/platforms/java/common/integrations/jcache.mdx b/docs/platforms/java/common/integrations/jcache.mdx new file mode 100644 index 00000000000000..536819da457cfe --- /dev/null +++ b/docs/platforms/java/common/integrations/jcache.mdx @@ -0,0 +1,136 @@ +--- +title: JCache Integration +description: "Learn how to trace cache operations using the Sentry JCache (JSR-107) integration." +--- + +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.). + +Cache spans appear in Sentry's [Caches dashboard](https://sentry.io/orgredirect/organizations/:orgslug/insights/backend/caches/). + + + +If you're using Spring Boot with `@Cacheable` / `@CachePut` / `@CacheEvict`, you don't need this integration — cache tracing is built into the Spring Boot starter. Just enable the `enableCacheTracing` option (or set `sentry.enable-cache-tracing=true` in `application.properties`) and all Spring Cache operations will be traced automatically. + + + +## Install + +```groovy {tabTitle:Gradle} +implementation 'io.sentry:sentry-jcache:{{@inject packages.version('sentry.java.jcache', '8.35.0') }}' +``` + +```xml {tabTitle:Maven} + + io.sentry + sentry-jcache + {{@inject packages.version('sentry.java.jcache', '8.35.0') }} + +``` + +```scala {tabTitle: SBT} +libraryDependencies += "io.sentry" % "sentry-jcache" % "{{@inject packages.version('sentry.java.jcache', '8.35.0') }}" +``` + +For other dependency managers, check out the [central Maven repository](https://search.maven.org/artifact/io.sentry/sentry-jcache). + +## Set Up + +Enable cache tracing in your Sentry configuration: + +```java {tabTitle:Java} +Sentry.init(options -> { + options.setDsn("___DSN___"); + options.setTracesSampleRate(1.0); + options.setEnableCacheTracing(true); +}); +``` + +```kotlin {tabTitle:Kotlin} +Sentry.init { options -> + options.dsn = "___DSN___" + options.tracesSampleRate = 1.0 + options.isEnableCacheTracing = true +} +``` + +Wrap your `javax.cache.Cache` instance with `SentryJCacheWrapper`: + +```java {tabTitle:Java} +import io.sentry.jcache.SentryJCacheWrapper; +import javax.cache.Cache; +import javax.cache.CacheManager; +import javax.cache.Caching; +import javax.cache.spi.CachingProvider; + +CachingProvider provider = Caching.getCachingProvider(); +CacheManager manager = provider.getCacheManager(); + +Cache cache = manager.getCache("myCache"); +Cache sentryCache = new SentryJCacheWrapper<>(cache); + +// Use sentryCache — all operations produce Sentry spans +sentryCache.put("key", "value"); // cache.put span +String val = sentryCache.get("key"); // cache.get span (cache.hit = true) +sentryCache.remove("key"); // cache.remove span +sentryCache.clear(); // cache.clear span +``` + +```kotlin {tabTitle:Kotlin} +import io.sentry.jcache.SentryJCacheWrapper +import javax.cache.Caching + +val provider = Caching.getCachingProvider() +val manager = provider.cacheManager + +val cache = manager.getCache("myCache") +val sentryCache = SentryJCacheWrapper(cache) + +// Use sentryCache — all operations produce Sentry spans +sentryCache.put("key", "value") // cache.put span +val value = sentryCache.get("key") // cache.get span (cache.hit = true) +sentryCache.remove("key") // cache.remove span +sentryCache.clear() // cache.clear span +``` + +## Traced Operations + +All JCache operations are traced. Each method creates a span with the operation `cache.` (e.g. `cache.get`, `cache.putIfAbsent`, `cache.removeAll`). + +## Span Data + +| Key | Type | Description | +|---|---|---| +| `cache.hit` | boolean | Whether the cache lookup returned a value (read spans only) | +| `cache.key` | list of strings | The cache key(s) involved in the operation | +| `cache.operation` | string | The JCache method name (e.g. `get`, `putIfAbsent`, `removeAll`) | +| `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 | + +Bulk operations (`getAll`, `putAll`, `removeAll`) create a single span with all keys listed in `cache.key`. + +## Verify + +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. + +```java {tabTitle:Java} +import io.sentry.ITransaction; +import io.sentry.Sentry; + +ITransaction tx = Sentry.startTransaction("test-cache", "task"); +try (ISentryLifecycleToken ignored = tx.makeCurrent()) { + sentryCache.put("greeting", "hello"); + String value = sentryCache.get("greeting"); +} finally { + tx.finish(); +} +``` + +```kotlin {tabTitle:Kotlin} +import io.sentry.Sentry + +val tx = Sentry.startTransaction("test-cache", "task") +tx.makeCurrent().use { + sentryCache.put("greeting", "hello") + val value = sentryCache.get("greeting") +} +tx.finish() +``` diff --git a/docs/platforms/java/common/integrations/redis.mdx b/docs/platforms/java/common/integrations/redis.mdx new file mode 100644 index 00000000000000..f651a4cac7afeb --- /dev/null +++ b/docs/platforms/java/common/integrations/redis.mdx @@ -0,0 +1,81 @@ +--- +title: Redis Integration +description: "Learn how to trace Redis cache operations with Sentry." +--- + +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/). + + + +## Spring Boot + +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: + +```properties {tabTitle:application.properties} +sentry.enable-cache-tracing=true +sentry.traces-sample-rate=1.0 +``` + +```yaml {tabTitle:application.yml} +sentry: + enable-cache-tracing: true + traces-sample-rate: 1.0 +``` + +All `@Cacheable`, `@CachePut`, and `@CacheEvict` operations will automatically produce Sentry spans — no additional dependencies or code changes required. + +See `enableCacheTracing` for more details on this option. + + + + + +## Plain Java + +Both Jedis and Lettuce provide [JCache (JSR-107)](https://github.com/redis/jedis/wiki/JCache-Support) adapters. Use them together with the Sentry JCache integration to trace cache operations. + +Add the dependencies for your Redis client: + +### Jedis + +```groovy {tabTitle:Gradle} +implementation 'io.sentry:sentry-jcache:{{@inject packages.version('sentry.java.jcache', '8.35.0') }}' +implementation 'redis.clients:jedis:5.2.0' +``` + +```xml {tabTitle:Maven} + + io.sentry + sentry-jcache + {{@inject packages.version('sentry.java.jcache', '8.35.0') }} + + + redis.clients + jedis + 5.2.0 + +``` + +### Lettuce + +```groovy {tabTitle:Gradle} +implementation 'io.sentry:sentry-jcache:{{@inject packages.version('sentry.java.jcache', '8.35.0') }}' +implementation 'io.lettuce:lettuce-core:6.5.5.RELEASE' +``` + +```xml {tabTitle:Maven} + + io.sentry + sentry-jcache + {{@inject packages.version('sentry.java.jcache', '8.35.0') }} + + + io.lettuce + lettuce-core + 6.5.5.RELEASE + +``` + +Then wrap your cache with `SentryJCacheWrapper`. See the JCache integration docs for setup and usage details. + +