Add documentation for onDiscard callback in Java, Android, and Spring Boot (#14632)

Author: alexander-alderman-webb

docs/platforms/android/configuration/options.mdx

@@ -231,7 +231,7 @@ This can be used to disable integrations that are enabled by default if the SDK
 
 ## Hooks
 
-These options can be used to hook the SDK in various ways to customize the reporting of events.
+These options can be used to hook the SDK in various ways to customize the reporting of events or to monitor the type and amount of discarded data.
 
 <ConfigKey name="before-send">
 
@@ -255,6 +255,12 @@ The callback typically gets a second argument (called a "hint") which contains t
 
 </ConfigKey>
 
+<ConfigKey name="on-discard">
+
+This function is called when data is discarded, for reasons including sampling, network errors, or queue overflows. The function arguments give the user insight into the reason for discarding, the type of data discarded, and the number of items discarded.
+
+</ConfigKey>
+
 ## Transport Options
 
 Transports are used to send events to Sentry. Transports can be customized to some degree to better support highly specific deployments.

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

@@ -190,7 +190,7 @@ In some SDKs, the integrations are configured through this parameter on library
 
 ## Hooks
 
-These options can be used to hook the SDK in various ways to customize the reporting of events.
+These options can be used to hook the SDK in various ways to customize the reporting of events or to monitor the type and amount of discarded data.
 
 <ConfigKey name="before-send">
 
@@ -213,6 +213,12 @@ The callback typically gets a second argument (called a "hint") which contains t
 
 </ConfigKey>
 
+<ConfigKey name="on-discard">
+
+This function is called when data is discarded, for reasons including sampling, network errors, or queue overflows. The function arguments give the user insight into the reason for discarding, the type of data discarded, and the number of items discarded.
+
+</ConfigKey>
+
 ## Transport Options
 
 Transports are used to send events to Sentry. Transports can be customized to some degree to better support highly specific deployments.

docs/platforms/java/guides/spring-boot/advanced-usage.mdx

@@ -136,3 +136,46 @@ class CustomBeforeBreadcrumbCallback : SentryOptions.BeforeBreadcrumbCallback {
   }
 }
 ```
+
+## Registering Custom On Discard Callback
+
+Any Spring bean implementing the `OnDiscardCallback` will be automatically set on `SentryOptions` during the SDK's auto-configuration. Note that there can be only a single bean set this way.
+
+```java
+import io.sentry.SentryOptions;
+import io.sentry.clientreport.DiscardReason;
+import io.sentry.DataCategory;
+import org.springframework.stereotype.Component;
+
+@Component
+class CustomOnDiscardCallback implements SentryOptions.OnDiscardCallback {
+  @Override 
+  public void execute(DiscardReason reason, DataCategory category, Long count) {
+    // Only record the number of lost spans due to overflow conditions
+    if ((reason == DiscardReason.CACHE_OVERFLOW
+            || reason == DiscardReason.QUEUE_OVERFLOW)
+        && category == DataCategory.Span) {
+      System.out.println("Discarded " + number + " spans due to overflow.");
+    }
+  }
+}
+```
+
+```kotlin
+import io.sentry.SentryOptions
+import io.sentry.clientreport.DiscardReason
+import io.sentry.DataCategory
+import org.springframework.stereotype.Component
+
+@Component
+class CustomOnDiscardCallback : SentryOptions.OnDiscardCallback {
+  override fun execute(reason: DiscardReason, category: DataCategory, countToAdd: Long) {
+    // Only record the number of lost spans due to overflow conditions
+    if ((reason == DiscardReason.CACHE_OVERFLOW
+            || reason == DiscardReason.QUEUE_OVERFLOW)
+        && category == DataCategory.Span) {
+      println("Discarded " + number + " spans due to overflow.")
+    }
+  }
+}
+```