Add callback to record the type and amount of data discarded before reaching Sentry

alexander-alderman-webb · alexander-alderman-webb · commit dd8f7bbe17fb · 2025-08-07T13:21:41.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,6 +13,10 @@
 - Remove unused method in ManifestMetadataReader ([#4585](https://github.com/getsentry/sentry-java/pull/4585))
 - Have single `NetworkCallback` registered at a time to reduce IPC calls ([#4562](https://github.com/getsentry/sentry-java/pull/4562))
 
+### Features
+
+- Add onDiscard to enable users to track the type and amount of data discarded before reaching Sentry ([#3652](https://github.com/getsentry/sentry-java/issues/3652))
+
 ## 8.18.0
 
 ### Features
diff --git a/sentry-samples/sentry-samples-console/src/main/java/io/sentry/samples/console/Main.java b/sentry-samples/sentry-samples-console/src/main/java/io/sentry/samples/console/Main.java
@@ -1,20 +1,15 @@
 package io.sentry.samples.console;
 
-import io.sentry.Breadcrumb;
-import io.sentry.EventProcessor;
-import io.sentry.Hint;
-import io.sentry.ISpan;
-import io.sentry.ITransaction;
-import io.sentry.Sentry;
-import io.sentry.SentryEvent;
-import io.sentry.SentryLevel;
-import io.sentry.SpanStatus;
+import io.sentry.*;
+import io.sentry.clientreport.DiscardReason;
 import io.sentry.protocol.Message;
 import io.sentry.protocol.User;
 import java.util.Collections;
 
 public class Main {
 
+  private static int numberOfDiscardedSpansDueToOverflow = 0;
+
   public static void main(String[] args) throws InterruptedException {
     Sentry.init(
         options -> {
@@ -59,6 +54,18 @@ public static void main(String[] args) throws InterruptedException {
                 return breadcrumb;
               });
 
+          // Record data being discarded, including the reason, type of data, and the number of
+          // items dropped
+          options.setOnDiscard(
+              (reason, category, number) -> {
+                // Only record the number of lost spans due to overflow conditions
+                if ((reason.equals(DiscardReason.CACHE_OVERFLOW.getReason())
+                        || reason.equals(DiscardReason.QUEUE_OVERFLOW.getReason()))
+                    && category.equals(DataCategory.Span.getCategory())) {
+                  numberOfDiscardedSpansDueToOverflow += number;
+                }
+              });
+
           // Configure the background worker which sends events to sentry:
           // Wait up to 5 seconds before shutdown while there are events to send.
           options.setShutdownTimeoutMillis(5000);
diff --git a/sentry-samples/sentry-samples-servlet/src/main/java/io/sentry/samples/servlet/SentryInitializer.java b/sentry-samples/sentry-samples-servlet/src/main/java/io/sentry/samples/servlet/SentryInitializer.java
@@ -1,6 +1,8 @@
 package io.sentry.samples.servlet;
 
+import io.sentry.DataCategory;
 import io.sentry.Sentry;
+import io.sentry.clientreport.DiscardReason;
 import javax.servlet.ServletContextEvent;
 import javax.servlet.ServletContextListener;
 import javax.servlet.annotation.WebListener;
@@ -9,6 +11,8 @@
 @WebListener
 public final class SentryInitializer implements ServletContextListener {
 
+  private static int numberOfDiscardedSpansDueToOverflow = 0;
+
   @Override
   public void contextInitialized(ServletContextEvent sce) {
     Sentry.init(
@@ -57,6 +61,18 @@ public void contextInitialized(ServletContextEvent sce) {
                 return breadcrumb;
               });
 
+          // Record data being discarded, including the reason, type of data, and the number of
+          // items dropped
+          options.setOnDiscard(
+              (reason, category, number) -> {
+                // Only record the number of lost spans due to overflow conditions
+                if ((reason.equals(DiscardReason.CACHE_OVERFLOW.getReason())
+                        || reason.equals(DiscardReason.QUEUE_OVERFLOW.getReason()))
+                    && category.equals(DataCategory.Span.getCategory())) {
+                  numberOfDiscardedSpansDueToOverflow += number;
+                }
+              });
+
           // Configure the background worker which sends events to sentry:
           // Wait up to 5 seconds before shutdown while there are events to send.
           options.setShutdownTimeoutMillis(5000);
diff --git a/sentry-spring-boot-jakarta/src/main/java/io/sentry/spring/boot/jakarta/SentryAutoConfiguration.java b/sentry-spring-boot-jakarta/src/main/java/io/sentry/spring/boot/jakarta/SentryAutoConfiguration.java
@@ -107,6 +107,7 @@ static class HubConfiguration {
                 beforeSendLogsCallback,
         final @NotNull ObjectProvider<SentryOptions.BeforeBreadcrumbCallback>
                 beforeBreadcrumbCallback,
+        final @NotNull ObjectProvider<SentryOptions.OnDiscardCallback> onDiscardCallback,
         final @NotNull ObjectProvider<SentryOptions.TracesSamplerCallback> tracesSamplerCallback,
         final @NotNull List<EventProcessor> eventProcessors,
         final @NotNull List<Integration> integrations,
@@ -118,6 +119,7 @@ static class HubConfiguration {
         beforeSendTransactionCallback.ifAvailable(options::setBeforeSendTransaction);
         beforeSendLogsCallback.ifAvailable(callback -> options.getLogs().setBeforeSend(callback));
         beforeBreadcrumbCallback.ifAvailable(options::setBeforeBreadcrumb);
+        onDiscardCallback.ifAvailable(options::setOnDiscard);
         tracesSamplerCallback.ifAvailable(options::setTracesSampler);
         eventProcessors.forEach(options::addEventProcessor);
         integrations.forEach(options::addIntegration);
diff --git a/sentry-spring-boot-jakarta/src/test/kotlin/io/sentry/spring/boot/jakarta/SentryAutoConfigurationTest.kt b/sentry-spring-boot-jakarta/src/test/kotlin/io/sentry/spring/boot/jakarta/SentryAutoConfigurationTest.kt
@@ -373,6 +373,17 @@ class SentryAutoConfigurationTest {
       }
   }
 
+  @Test
+  fun `registers onDiscardCallback on SentryOptions`() {
+    contextRunner
+      .withPropertyValues("sentry.dsn=http://key@localhost/proj")
+      .withUserConfiguration(CustomOnDiscardCallbackConfiguration::class.java)
+      .run {
+        assertThat(it.getBean(SentryOptions::class.java).onDiscard)
+          .isInstanceOf(CustomOnDiscardCallback::class.java)
+      }
+  }
+
   @Test
   fun `registers event processor on SentryOptions`() {
     contextRunner
@@ -1137,6 +1148,16 @@ class SentryAutoConfigurationTest {
     override fun execute(breadcrumb: Breadcrumb, hint: Hint): Breadcrumb? = null
   }
 
+  @Configuration(proxyBeanMethods = false)
+  open class CustomOnDiscardCallbackConfiguration {
+
+    @Bean open fun onDiscardCallback() = CustomOnDiscardCallback()
+  }
+
+  class CustomOnDiscardCallback : SentryOptions.OnDiscardCallback {
+    override fun execute(reason: String, category: String, countToAdd: Long) {}
+  }
+
   @Configuration(proxyBeanMethods = false)
   open class CustomEventProcessorConfiguration {
 
diff --git a/sentry-spring-boot/src/main/java/io/sentry/spring/boot/SentryAutoConfiguration.java b/sentry-spring-boot/src/main/java/io/sentry/spring/boot/SentryAutoConfiguration.java
@@ -105,6 +105,7 @@ static class HubConfiguration {
                 beforeSendLogsCallback,
         final @NotNull ObjectProvider<SentryOptions.BeforeBreadcrumbCallback>
                 beforeBreadcrumbCallback,
+        final @NotNull ObjectProvider<SentryOptions.OnDiscardCallback> onDiscardCallback,
         final @NotNull ObjectProvider<SentryOptions.TracesSamplerCallback> tracesSamplerCallback,
         final @NotNull List<EventProcessor> eventProcessors,
         final @NotNull List<Integration> integrations,
@@ -116,6 +117,7 @@ static class HubConfiguration {
         beforeSendTransactionCallback.ifAvailable(options::setBeforeSendTransaction);
         beforeSendLogsCallback.ifAvailable(callback -> options.getLogs().setBeforeSend(callback));
         beforeBreadcrumbCallback.ifAvailable(options::setBeforeBreadcrumb);
+        onDiscardCallback.ifAvailable(options::setOnDiscard);
         tracesSamplerCallback.ifAvailable(options::setTracesSampler);
         eventProcessors.forEach(options::addEventProcessor);
         integrations.forEach(options::addIntegration);
diff --git a/sentry-spring-boot/src/test/kotlin/io/sentry/spring/boot/SentryAutoConfigurationTest.kt b/sentry-spring-boot/src/test/kotlin/io/sentry/spring/boot/SentryAutoConfigurationTest.kt
@@ -372,6 +372,17 @@ class SentryAutoConfigurationTest {
       }
   }
 
+  @Test
+  fun `registers onDiscardCallback on SentryOptions`() {
+    contextRunner
+      .withPropertyValues("sentry.dsn=http://key@localhost/proj")
+      .withUserConfiguration(CustomOnDiscardCallbackConfiguration::class.java)
+      .run {
+        assertThat(it.getBean(SentryOptions::class.java).onDiscard)
+          .isInstanceOf(CustomOnDiscardCallback::class.java)
+      }
+  }
+
   @Test
   fun `registers event processor on SentryOptions`() {
     contextRunner
@@ -1063,6 +1074,16 @@ class SentryAutoConfigurationTest {
     override fun execute(breadcrumb: Breadcrumb, hint: Hint): Breadcrumb? = null
   }
 
+  @Configuration(proxyBeanMethods = false)
+  open class CustomOnDiscardCallbackConfiguration {
+
+    @Bean open fun onDiscardCallback() = CustomOnDiscardCallback()
+  }
+
+  class CustomOnDiscardCallback : SentryOptions.OnDiscardCallback {
+    override fun execute(reason: String, category: String, countToAdd: Long) {}
+  }
+
   @Configuration(proxyBeanMethods = false)
   open class CustomEventProcessorConfiguration {
 
diff --git a/sentry-spring-jakarta/src/main/java/io/sentry/spring/jakarta/SentryInitBeanPostProcessor.java b/sentry-spring-jakarta/src/main/java/io/sentry/spring/jakarta/SentryInitBeanPostProcessor.java
@@ -61,6 +61,9 @@ public SentryInitBeanPostProcessor() {
         applicationContext
             .getBeanProvider(SentryOptions.BeforeBreadcrumbCallback.class)
             .ifAvailable(options::setBeforeBreadcrumb);
+        applicationContext
+            .getBeanProvider(SentryOptions.OnDiscardCallback.class)
+            .ifAvailable(options::setOnDiscard);
         applicationContext
             .getBeansOfType(EventProcessor.class)
             .values()
diff --git a/sentry-spring-jakarta/src/test/kotlin/io/sentry/spring/jakarta/EnableSentryTest.kt b/sentry-spring-jakarta/src/test/kotlin/io/sentry/spring/jakarta/EnableSentryTest.kt
@@ -223,6 +223,11 @@ class EnableSentryTest {
     @Bean fun beforeBreadcrumbCallback() = mock<SentryOptions.BeforeBreadcrumbCallback>()
   }
 
+  @EnableSentry(dsn = "http://key@localhost/proj")
+  class AppConfigWithCustomOnDiscardCallback {
+    @Bean fun onDiscardCallback() = mock<SentryOptions.OnDiscardCallback>()
+  }
+
   @EnableSentry(dsn = "http://key@localhost/proj")
   class AppConfigWithCustomEventProcessors {
     @Bean fun firstProcessor() = mock<EventProcessor>()
diff --git a/sentry-spring/src/main/java/io/sentry/spring/SentryInitBeanPostProcessor.java b/sentry-spring/src/main/java/io/sentry/spring/SentryInitBeanPostProcessor.java
@@ -61,6 +61,9 @@ public SentryInitBeanPostProcessor() {
         applicationContext
             .getBeanProvider(SentryOptions.BeforeBreadcrumbCallback.class)
             .ifAvailable(options::setBeforeBreadcrumb);
+        applicationContext
+            .getBeanProvider(SentryOptions.OnDiscardCallback.class)
+            .ifAvailable(options::setOnDiscard);
         applicationContext
             .getBeansOfType(EventProcessor.class)
             .values()
diff --git a/sentry-spring/src/test/kotlin/io/sentry/spring/EnableSentryTest.kt b/sentry-spring/src/test/kotlin/io/sentry/spring/EnableSentryTest.kt
@@ -223,6 +223,11 @@ class EnableSentryTest {
     @Bean fun beforeBreadcrumbCallback() = mock<SentryOptions.BeforeBreadcrumbCallback>()
   }
 
+  @EnableSentry(dsn = "http://key@localhost/proj")
+  class AppConfigWithCustomOnDiscardCallback {
+    @Bean fun onDiscardCallback() = mock<SentryOptions.OnDiscardCallback>()
+  }
+
   @EnableSentry(dsn = "http://key@localhost/proj")
   class AppConfigWithCustomEventProcessors {
     @Bean fun firstProcessor() = mock<EventProcessor>()
diff --git a/sentry/api/sentry.api b/sentry/api/sentry.api
@@ -3337,6 +3337,7 @@ public class io/sentry/SentryOptions {
 	public fun getMaxSpans ()I
 	public fun getMaxTraceFileSize ()J
 	public fun getModulesLoader ()Lio/sentry/internal/modules/IModulesLoader;
+	public fun getOnDiscard ()Lio/sentry/SentryOptions$OnDiscardCallback;
 	public fun getOpenTelemetryMode ()Lio/sentry/SentryOpenTelemetryMode;
 	public fun getOptionsObservers ()Ljava/util/List;
 	public fun getOutboxPath ()Ljava/lang/String;
@@ -3479,6 +3480,7 @@ public class io/sentry/SentryOptions {
 	public fun setMaxSpans (I)V
 	public fun setMaxTraceFileSize (J)V
 	public fun setModulesLoader (Lio/sentry/internal/modules/IModulesLoader;)V
+	public fun setOnDiscard (Lio/sentry/SentryOptions$OnDiscardCallback;)V
 	public fun setOpenTelemetryMode (Lio/sentry/SentryOpenTelemetryMode;)V
 	public fun setPrintUncaughtStackTrace (Z)V
 	public fun setProfileLifecycle (Lio/sentry/ProfileLifecycle;)V
@@ -3572,6 +3574,10 @@ public abstract interface class io/sentry/SentryOptions$Logs$BeforeSendLogCallba
 	public abstract fun execute (Lio/sentry/SentryLogEvent;)Lio/sentry/SentryLogEvent;
 }
 
+public abstract interface class io/sentry/SentryOptions$OnDiscardCallback {
+	public abstract fun execute (Ljava/lang/String;Ljava/lang/String;Ljava/lang/Long;)V
+}
+
 public abstract interface class io/sentry/SentryOptions$ProfilesSamplerCallback {
 	public abstract fun sample (Lio/sentry/SamplingContext;)Ljava/lang/Double;
 }
diff --git a/sentry/src/main/java/io/sentry/SentryOptions.java b/sentry/src/main/java/io/sentry/SentryOptions.java
@@ -179,6 +179,9 @@ public class SentryOptions {
    */
   private @Nullable BeforeBreadcrumbCallback beforeBreadcrumb;
 
+  /** Invoked when some payload sent from the SDK is dropped before consumed by Sentry, */
+  private @Nullable OnDiscardCallback onDiscard;
+
   /** The cache dir. path for caching offline events */
   private @Nullable String cacheDirPath;
 
@@ -904,6 +907,24 @@ public void setBeforeBreadcrumb(@Nullable BeforeBreadcrumbCallback beforeBreadcr
     this.beforeBreadcrumb = beforeBreadcrumb;
   }
 
+  /**
+   * Returns the onDiscard callback
+   *
+   * @return the onDiscard callback or null if not set
+   */
+  public @Nullable OnDiscardCallback getOnDiscard() {
+    return onDiscard;
+  }
+
+  /**
+   * Sets the onDiscard callback
+   *
+   * @param onDiscard the onDiscard callback
+   */
+  public void setOnDiscard(@Nullable OnDiscardCallback onDiscard) {
+    this.onDiscard = onDiscard;
+  }
+
   /**
    * Returns the cache dir. path if set
    *
@@ -2982,6 +3003,19 @@ public interface BeforeBreadcrumbCallback {
     Breadcrumb execute(@NotNull Breadcrumb breadcrumb, @NotNull Hint hint);
   }
 
+  /** The OnDiscard callback */
+  public interface OnDiscardCallback {
+
+    /**
+     * Best-effort record of data discarded before reaching Sentry
+     *
+     * @param reason the reason data was dropped, corresponding to a DiscardReason
+     * @param category the type of data discarded, corresponding to a DataCategory
+     * @param number the number of discarded data items
+     */
+    void execute(@NotNull String reason, @NotNull String category, @NotNull Long number);
+  }
+
   /** The traces sampler callback. */
   public interface TracesSamplerCallback {
 
diff --git a/sentry/src/main/java/io/sentry/clientreport/ClientReportRecorder.java b/sentry/src/main/java/io/sentry/clientreport/ClientReportRecorder.java
@@ -124,6 +124,9 @@ private void recordLostEventInternal(
       @NotNull String reason, @NotNull String category, @NotNull Long countToAdd) {
     final ClientReportKey key = new ClientReportKey(reason, category);
     storage.addCount(key, countToAdd);
+    if (options.getOnDiscard() != null) {
+      options.getOnDiscard().execute(reason, category, countToAdd);
+    }
   }
 
   @Nullable
diff --git a/sentry/src/test/java/io/sentry/SentryClientTest.kt b/sentry/src/test/java/io/sentry/SentryClientTest.kt
diff --git a/sentry/src/test/java/io/sentry/clientreport/ClientReportRecorderTest.kt b/sentry/src/test/java/io/sentry/clientreport/ClientReportRecorderTest.kt
