Add client report recorder and rate limiting case

Author: buenaflor

sentry/src/main/java/io/sentry/clientreport/ClientReportRecorder.java

@@ -215,6 +215,9 @@ private DataCategory categoryFromItemType(SentryItemType itemType) {
     if (SentryItemType.Log.equals(itemType)) {
       return DataCategory.LogItem;
     }
+    if (SentryItemType.Span.equals(itemType)) {
+      return DataCategory.Span;
+    }
 
     return DataCategory.Default;
   }

sentry/src/main/java/io/sentry/transport/RateLimiter.java

@@ -213,6 +213,8 @@ private boolean isRetryAfter(final @NotNull String itemType) {
         return Collections.singletonList(DataCategory.Feedback);
       case "log":
         return Collections.singletonList(DataCategory.LogItem);
+      case "span":
+        return Collections.singletonList(DataCategory.Span);
       default:
         return Collections.singletonList(DataCategory.Unknown);
     }

sentry/src/test/java/io/sentry/protocol/SentryItemTypeSerializationTest.kt

@@ -72,3 +72,103 @@ class SentryItemTypeSerializationTest {
     return SentryItemType.Deserializer().deserialize(reader, fixture.logger)
   }
 }
+
+
+
+## 1. **Sentinel Object Pattern**
+
+```dart
+// Create a private sentinel marker
+const _undefined = Object();
+
+static Span startSpan(String name, {
+    Map<String, SentryAttribute>? attributes,
+    Object? parentSpan = _undefined, // Uses Object? to accept Span?, null, or undefined
+    bool active = true,
+}) {
+  final Span? actualParentSpan;
+  if (identical(parentSpan, _undefined)) {
+    // Not provided - use default behavior (e.g., get from current scope)
+    actualParentSpan = _getCurrentSpan();
+  } else {
+    // Explicitly provided (could be null or a Span)
+    actualParentSpan = parentSpan as Span?;
+  }
+  // ...
+}
+```
+
+## 2. **Wrapper Class (Optional/Maybe)**
+
+```dart
+class Optional<T> {
+  final T? value;
+  final bool isSet;
+  
+  const Optional.absent() : value = null, isSet = false;
+  const Optional.of(this.value) : isSet = true;
+}
+
+static Span startSpan(String name, {
+    Optional<Span> parentSpan = const Optional.absent(),
+}) {
+  if (parentSpan.isSet) {
+    // Explicitly provided (value could be null or a Span)
+  } else {
+    // Not provided
+  }
+}
+```
+
+## 3. **Sealed Classes (Dart 3+)** — Most Type-Safe
+
+```dart
+sealed class ParentSpanOption {}
+class UseCurrentSpan extends ParentSpanOption {} // undefined - use default
+class ExplicitSpan extends ParentSpanOption {
+  final Span? span; // can be null or a span
+  ExplicitSpan(this.span);
+}
+
+static Span startSpan(String name, {
+    ParentSpanOption parentSpan = const UseCurrentSpan(),
+}) {
+  switch (parentSpan) {
+    case UseCurrentSpan():
+      // Not provided - use default behavior
+    case ExplicitSpan(span: final span):
+      // Explicitly provided (span or null)
+  }
+}
+```
+
+## 4. **Separate Boolean Flag**
+
+```dart
+static Span startSpan(String name, {
+    Span? parentSpan,
+    bool parentSpanProvided = false, // true means parentSpan was explicitly set
+    bool active = true,
+}) {
+  if (parentSpanProvided) {
+    // Use parentSpan (even if null)
+  } else {
+    // Not provided - use default
+  }
+}
+```
+
+## 5. **Record Type (Dart 3+)**
+
+```dart
+static Span startSpan(String name, {
+    (bool isSet, Span? value)? parentSpan, // null = undefined, (true, x) = explicit
+}) {
+  if (parentSpan == null) {
+    // undefined
+  } else {
+    final (_, span) = parentSpan;
+    // explicitly set to `span` (which could be null)
+  }
+}
+```

sentry/src/test/java/io/sentry/transport/RateLimiterTest.kt

@@ -15,7 +15,9 @@ import io.sentry.ReplayRecording
 import io.sentry.SentryEnvelope
 import io.sentry.SentryEnvelopeHeader
 import io.sentry.SentryEnvelopeItem
+import io.sentry.SentryEnvelopeItemHeader
 import io.sentry.SentryEvent
+import io.sentry.SentryItemType
 import io.sentry.SentryLogEvent
 import io.sentry.SentryLogEvents
 import io.sentry.SentryLogLevel
@@ -534,6 +536,42 @@ class RateLimiterTest {
     verifyNoMoreInteractions(fixture.clientReportRecorder)
   }
 
+  @Test
+  fun `drop span items as lost`() {
+    val rateLimiter = fixture.getSUT()
+
+    // There is no span API yet so we'll create the envelope manually
+    val spanItemHeader =
+      SentryEnvelopeItemHeader(
+        SentryItemType.Span,
+        10,
+        "application/vnd.sentry.items.span.v2+json",
+        null,
+        null,
+        null,
+        1,
+      )
+    val spanItem = SentryEnvelopeItem(spanItemHeader, ByteArray(10))
+    val attachmentItem =
+      SentryEnvelopeItem.fromAttachment(
+        fixture.serializer,
+        NoOpLogger.getInstance(),
+        Attachment("{ \"number\": 10 }".toByteArray(), "log.json"),
+        1000,
+      )
+    val envelope = SentryEnvelope(SentryEnvelopeHeader(), arrayListOf(spanItem, attachmentItem))
+
+    rateLimiter.updateRetryAfterLimits("60:span:key", null, 1)
+    val result = rateLimiter.filter(envelope, Hint())
+
+    assertNotNull(result)
+    assertEquals(1, result.items.toList().size)
+
+    verify(fixture.clientReportRecorder, times(1))
+      .recordLostEnvelopeItem(eq(DiscardReason.RATELIMIT_BACKOFF), same(spanItem))
+    verifyNoMoreInteractions(fixture.clientReportRecorder)
+  }
+
   @Test
   fun `apply rate limits notifies observers`() {
     val rateLimiter = fixture.getSUT()