feat(core): [Cache Tracing 2] Add enableCacheTracing option

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: adinauer

sentry-spring-7/src/main/java/io/sentry/spring7/cache/SentryCacheWrapper.java

@@ -210,6 +210,10 @@ public boolean invalidate() {
   }
 
   private @Nullable ISpan startSpan(final @NotNull String operation, final @Nullable Object key) {
+    if (!scopes.getOptions().isEnableCacheTracing()) {
+      return null;
+    }
+
     final ISpan activeSpan = scopes.getSpan();
     if (activeSpan == null || activeSpan.isNoOp()) {
       return null;

sentry-spring-7/src/test/kotlin/io/sentry/spring7/cache/SentryCacheWrapperTest.kt

@@ -24,12 +24,14 @@ class SentryCacheWrapperTest {
 
   private lateinit var scopes: IScopes
   private lateinit var delegate: Cache
+  private lateinit var options: SentryOptions
 
   @BeforeTest
   fun setup() {
     scopes = mock()
     delegate = mock()
-    whenever(scopes.options).thenReturn(SentryOptions())
+    options = SentryOptions().apply { isEnableCacheTracing = true }
+    whenever(scopes.options).thenReturn(options)
     whenever(delegate.name).thenReturn("testCache")
   }
 
@@ -242,6 +244,21 @@ class SentryCacheWrapperTest {
     verify(delegate).get("myKey")
   }
 
+  // -- no span when option is disabled --
+
+  @Test
+  fun `does not create span when enableCacheTracing is false`() {
+    options.isEnableCacheTracing = false
+    val tx = createTransaction()
+    val wrapper = SentryCacheWrapper(delegate, scopes)
+    whenever(delegate.get("myKey")).thenReturn(null)
+
+    wrapper.get("myKey")
+
+    verify(delegate).get("myKey")
+    assertEquals(0, tx.spans.size)
+  }
+
   // -- error handling --
 
   @Test

sentry/api/sentry.api

@@ -520,6 +520,7 @@ public final class io/sentry/ExternalOptions {
 	public fun getTracesSampleRate ()Ljava/lang/Double;
 	public fun isCaptureOpenTelemetryEvents ()Ljava/lang/Boolean;
 	public fun isEnableBackpressureHandling ()Ljava/lang/Boolean;
+	public fun isEnableCacheTracing ()Ljava/lang/Boolean;
 	public fun isEnableDatabaseTransactionTracing ()Ljava/lang/Boolean;
 	public fun isEnableLogs ()Ljava/lang/Boolean;
 	public fun isEnableMetrics ()Ljava/lang/Boolean;
@@ -536,6 +537,7 @@ public final class io/sentry/ExternalOptions {
 	public fun setDist (Ljava/lang/String;)V
 	public fun setDsn (Ljava/lang/String;)V
 	public fun setEnableBackpressureHandling (Ljava/lang/Boolean;)V
+	public fun setEnableCacheTracing (Ljava/lang/Boolean;)V
 	public fun setEnableDatabaseTransactionTracing (Ljava/lang/Boolean;)V
 	public fun setEnableDeduplication (Ljava/lang/Boolean;)V
 	public fun setEnableLogs (Ljava/lang/Boolean;)V
@@ -3660,6 +3662,7 @@ public class io/sentry/SentryOptions {
 	public fun isEnableAppStartProfiling ()Z
 	public fun isEnableAutoSessionTracking ()Z
 	public fun isEnableBackpressureHandling ()Z
+	public fun isEnableCacheTracing ()Z
 	public fun isEnableDatabaseTransactionTracing ()Z
 	public fun isEnableDeduplication ()Z
 	public fun isEnableEventSizeLimiting ()Z
@@ -3718,6 +3721,7 @@ public class io/sentry/SentryOptions {
 	public fun setEnableAppStartProfiling (Z)V
 	public fun setEnableAutoSessionTracking (Z)V
 	public fun setEnableBackpressureHandling (Z)V
+	public fun setEnableCacheTracing (Z)V
 	public fun setEnableDatabaseTransactionTracing (Z)V
 	public fun setEnableDeduplication (Z)V
 	public fun setEnableEventSizeLimiting (Z)V

sentry/src/main/java/io/sentry/ExternalOptions.java

@@ -57,6 +57,7 @@ public final class ExternalOptions {
   private @Nullable Boolean sendDefaultPii;
   private @Nullable Boolean enableBackpressureHandling;
   private @Nullable Boolean enableDatabaseTransactionTracing;
+  private @Nullable Boolean enableCacheTracing;
   private @Nullable Boolean globalHubMode;
   private @Nullable Boolean forceInit;
   private @Nullable Boolean captureOpenTelemetryEvents;
@@ -162,6 +163,8 @@ public final class ExternalOptions {
     options.setEnableDatabaseTransactionTracing(
         propertiesProvider.getBooleanProperty("enable-database-transaction-tracing"));
 
+    options.setEnableCacheTracing(propertiesProvider.getBooleanProperty("enable-cache-tracing"));
+
     options.setGlobalHubMode(propertiesProvider.getBooleanProperty("global-hub-mode"));
 
     options.setCaptureOpenTelemetryEvents(
@@ -523,6 +526,14 @@ public void setEnableDatabaseTransactionTracing(
     return enableDatabaseTransactionTracing;
   }
 
+  public void setEnableCacheTracing(final @Nullable Boolean enableCacheTracing) {
+    this.enableCacheTracing = enableCacheTracing;
+  }
+
+  public @Nullable Boolean isEnableCacheTracing() {
+    return enableCacheTracing;
+  }
+
   public void setGlobalHubMode(final @Nullable Boolean globalHubMode) {
     this.globalHubMode = globalHubMode;
   }

sentry/src/main/java/io/sentry/SentryOptions.java

@@ -490,6 +490,9 @@ public class SentryOptions {
   /** Whether database transaction spans (BEGIN, COMMIT, ROLLBACK) should be traced. */
   private boolean enableDatabaseTransactionTracing = false;
 
+  /** Whether cache operations (get, put, evict, clear) should be traced. */
+  private boolean enableCacheTracing = false;
+
   /** Date provider to retrieve the current date from. */
   @ApiStatus.Internal
   private final @NotNull LazyEvaluator<SentryDateProvider> dateProvider =
@@ -2630,6 +2633,24 @@ public void setEnableDatabaseTransactionTracing(boolean enableDatabaseTransactio
     this.enableDatabaseTransactionTracing = enableDatabaseTransactionTracing;
   }
 
+  /**
+   * Whether cache operations (get, put, evict, clear) should be traced.
+   *
+   * @return true if cache operations should be traced
+   */
+  public boolean isEnableCacheTracing() {
+    return enableCacheTracing;
+  }
+
+  /**
+   * Whether cache operations (get, put, evict, clear) should be traced.
+   *
+   * @param enableCacheTracing true if cache operations should be traced
+   */
+  public void setEnableCacheTracing(boolean enableCacheTracing) {
+    this.enableCacheTracing = enableCacheTracing;
+  }
+
   /**
    * Whether Sentry is enabled.
    *
@@ -3468,6 +3489,9 @@ public void merge(final @NotNull ExternalOptions options) {
     if (options.isEnableDatabaseTransactionTracing() != null) {
       setEnableDatabaseTransactionTracing(options.isEnableDatabaseTransactionTracing());
     }
+    if (options.isEnableCacheTracing() != null) {
+      setEnableCacheTracing(options.isEnableCacheTracing());
+    }
     if (options.getMaxRequestBodySize() != null) {
       setMaxRequestBodySize(options.getMaxRequestBodySize());
     }

sentry/src/test/java/io/sentry/ExternalOptionsTest.kt

@@ -331,6 +331,20 @@ class ExternalOptionsTest {
     }
   }
 
+  @Test
+  fun `creates options with enableCacheTracing set to true`() {
+    withPropertiesFile("enable-cache-tracing=true") { options ->
+      assertTrue(options.isEnableCacheTracing == true)
+    }
+  }
+
+  @Test
+  fun `creates options with enableCacheTracing set to false`() {
+    withPropertiesFile("enable-cache-tracing=false") { options ->
+      assertTrue(options.isEnableCacheTracing == false)
+    }
+  }
+
   @Test
   fun `creates options with cron defaults`() {
     withPropertiesFile(

sentry/src/test/java/io/sentry/SentryOptionsTest.kt

@@ -400,6 +400,7 @@ class SentryOptionsTest {
     externalOptions.ignoredErrors = listOf("Some error", "Another .*")
     externalOptions.isEnableBackpressureHandling = false
     externalOptions.isEnableDatabaseTransactionTracing = true
+    externalOptions.isEnableCacheTracing = true
     externalOptions.maxRequestBodySize = SentryOptions.RequestSize.MEDIUM
     externalOptions.isSendDefaultPii = true
     externalOptions.isForceInit = true
@@ -465,6 +466,7 @@ class SentryOptionsTest {
     )
     assertFalse(options.isEnableBackpressureHandling)
     assertTrue(options.isEnableDatabaseTransactionTracing)
+    assertTrue(options.isEnableCacheTracing)
     assertTrue(options.isForceInit)
     assertNotNull(options.cron)
     assertEquals(10L, options.cron?.defaultCheckinMargin)
@@ -701,6 +703,11 @@ class SentryOptionsTest {
     assertFalse(SentryOptions().isEnableDatabaseTransactionTracing)
   }
 
+  @Test
+  fun `when options are initialized, enableCacheTracing is set to false by default`() {
+    assertFalse(SentryOptions().isEnableCacheTracing)
+  }
+
   @Test
   fun `when options are initialized, metrics is enabled by default`() {
     assertTrue(SentryOptions().metrics.isEnabled)