feat: add trace_metric_byte to DataCategory enum (#5626)

* feat: add trace_metric_byte to DataCategory enum

* chore: regenerate API dump with TraceMetricByte in DataCategory

* feat: record TraceMetricByte in client reports when trace metrics are discarded

Mirrors the LogByte pattern: records byte-level data category alongside the
item-level one when trace metrics are dropped by beforeSendMetrics, queue
overflow, or envelope discard.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* changelog: add trace_metric_byte data category entry

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: apply spotless formatting

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Roman Zavarnitsyn <rom4ek93@gmail.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 3 people

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Features
+
+- Add `trace_metric_byte` data category and record byte-level client reports when trace metrics are discarded ([#5626](https://github.com/getsentry/sentry-java/pull/5626))
+
 ### Fixes
 
 - Name the device-info caching thread `SentryDeviceInfoCache` so all threads spawned by the SDK are identifiable ([#5684](https://github.com/getsentry/sentry-java/pull/5684))

sentry/api/sentry.api

@@ -373,6 +373,7 @@ public final class io/sentry/DataCategory : java/lang/Enum {
 	public static final field Session Lio/sentry/DataCategory;
 	public static final field Span Lio/sentry/DataCategory;
 	public static final field TraceMetric Lio/sentry/DataCategory;
+	public static final field TraceMetricByte Lio/sentry/DataCategory;
 	public static final field Transaction Lio/sentry/DataCategory;
 	public static final field Unknown Lio/sentry/DataCategory;
 	public static final field UserReport Lio/sentry/DataCategory;

sentry/src/main/java/io/sentry/DataCategory.java

@@ -12,6 +12,7 @@ public enum DataCategory {
   LogItem("log_item"),
   LogByte("log_byte"),
   TraceMetric("trace_metric"),
+  TraceMetricByte("trace_metric_byte"),
   Monitor("monitor"),
   Profile("profile"),
   ProfileChunkUi("profile_chunk_ui"),

sentry/src/main/java/io/sentry/SentryClient.java

@@ -1336,6 +1336,7 @@ public void captureMetric(
     }
 
     if (metricsEvent != null) {
+      final @NotNull SentryMetricsEvent tmpMetricsEvent = metricsEvent;
       metricsEvent = executeBeforeSendMetric(metricsEvent, hint);
 
       if (metricsEvent == null) {
@@ -1345,6 +1346,13 @@ public void captureMetric(
         options
             .getClientReportRecorder()
             .recordLostEvent(DiscardReason.BEFORE_SEND, DataCategory.TraceMetric);
+        final long metricsEventNumberOfBytes =
+            JsonSerializationUtils.byteSizeOf(
+                options.getSerializer(), options.getLogger(), tmpMetricsEvent);
+        options
+            .getClientReportRecorder()
+            .recordLostEvent(
+                DiscardReason.BEFORE_SEND, DataCategory.TraceMetricByte, metricsEventNumberOfBytes);
         return;
       }
 

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

@@ -124,6 +124,9 @@ public void recordLostEnvelopeItem(
             final @NotNull List<SentryMetricsEvent> items = metrics.getItems();
             final long count = items.size();
             recordLostEventInternal(reason.getReason(), itemCategory.getCategory(), count);
+            final long metricBytes = envelopeItem.getData().length;
+            recordLostEventInternal(
+                reason.getReason(), DataCategory.TraceMetricByte.getCategory(), metricBytes);
             executeOnDiscard(reason, itemCategory, count);
           } else {
             options

sentry/src/main/java/io/sentry/metrics/MetricsBatchProcessor.java

@@ -13,6 +13,7 @@
 import io.sentry.clientreport.DiscardReason;
 import io.sentry.transport.ReusableCountLatch;
 import io.sentry.util.AutoClosableReentrantLock;
+import io.sentry.util.JsonSerializationUtils;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Queue;
@@ -58,6 +59,12 @@ public void add(final @NotNull SentryMetricsEvent metricsEvent) {
       options
           .getClientReportRecorder()
           .recordLostEvent(DiscardReason.QUEUE_OVERFLOW, DataCategory.TraceMetric);
+      final long lostBytes =
+          JsonSerializationUtils.byteSizeOf(
+              options.getSerializer(), options.getLogger(), metricsEvent);
+      options
+          .getClientReportRecorder()
+          .recordLostEvent(DiscardReason.QUEUE_OVERFLOW, DataCategory.TraceMetricByte, lostBytes);
       return;
     }
     pendingCount.increment();

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

@@ -388,7 +388,10 @@ class SentryClientTest {
 
     assertClientReport(
       fixture.sentryOptions.clientReportRecorder,
-      listOf(DiscardedEvent(DiscardReason.BEFORE_SEND.reason, DataCategory.TraceMetric.category, 1)),
+      listOf(
+        DiscardedEvent(DiscardReason.BEFORE_SEND.reason, DataCategory.TraceMetric.category, 1),
+        DiscardedEvent(DiscardReason.BEFORE_SEND.reason, DataCategory.TraceMetricByte.category, 120),
+      ),
     )
   }
 
@@ -408,7 +411,10 @@ class SentryClientTest {
 
     assertClientReport(
       fixture.sentryOptions.clientReportRecorder,
-      listOf(DiscardedEvent(DiscardReason.BEFORE_SEND.reason, DataCategory.TraceMetric.category, 1)),
+      listOf(
+        DiscardedEvent(DiscardReason.BEFORE_SEND.reason, DataCategory.TraceMetric.category, 1),
+        DiscardedEvent(DiscardReason.BEFORE_SEND.reason, DataCategory.TraceMetricByte.category, 120),
+      ),
     )
   }
 

sentry/src/test/java/io/sentry/clientreport/ClientReportTest.kt

@@ -412,6 +412,9 @@ class ClientReportTest {
     val metricItem =
       clientReport!!.discardedEvents!!.first { it.category == DataCategory.TraceMetric.category }
     assertEquals(3, metricItem.quantity)
+    val metricByteItem =
+      clientReport.discardedEvents!!.first { it.category == DataCategory.TraceMetricByte.category }
+    assertEquals(envelope.items.first().data.size.toLong(), metricByteItem.quantity)
   }
 
   private fun givenClientReportRecorder(

sentry/src/test/java/io/sentry/metrics/MetricsBatchProcessorTest.kt

@@ -12,6 +12,7 @@ import io.sentry.clientreport.DiscardedEvent
 import io.sentry.protocol.SentryId
 import io.sentry.test.DeferredExecutorService
 import io.sentry.test.injectForField
+import io.sentry.util.JsonSerializationUtils
 import kotlin.test.Test
 import kotlin.test.assertEquals
 import kotlin.test.assertFalse
@@ -80,9 +81,16 @@ class MetricsBatchProcessorTest {
     processor.add(droppedMetricsEvent)
 
     // verify that a client report was recorded for the dropped metrics item
+    val droppedBytes =
+      JsonSerializationUtils.byteSizeOf(options.serializer, options.logger, droppedMetricsEvent)
     val expectedEvents =
       mutableListOf(
-        DiscardedEvent(DiscardReason.QUEUE_OVERFLOW.reason, DataCategory.TraceMetric.category, 1)
+        DiscardedEvent(DiscardReason.QUEUE_OVERFLOW.reason, DataCategory.TraceMetric.category, 1),
+        DiscardedEvent(
+          DiscardReason.QUEUE_OVERFLOW.reason,
+          DataCategory.TraceMetricByte.category,
+          droppedBytes,
+        ),
       )
 
     ClientReportTestHelper.assertClientReport(options.clientReportRecorder, expectedEvents)