Provide API for attaching custom measurements to transactions

sentry-android-core/src/main/java/io/sentry/android/core/ActivityFramesTracker.java

@@ -4,6 +4,7 @@
 import android.util.SparseIntArray;
 import androidx.core.app.FrameMetricsAggregator;
 import io.sentry.ILogger;
+import io.sentry.MeasurementUnit;
 import io.sentry.protocol.MeasurementValue;
 import io.sentry.protocol.SentryId;
 import java.util.HashMap;
@@ -102,9 +103,9 @@ public synchronized void setMetrics(
       return;
     }
 
-    final MeasurementValue tfValues = new MeasurementValue(totalFrames, null);
-    final MeasurementValue sfValues = new MeasurementValue(slowFrames, null);
-    final MeasurementValue ffValues = new MeasurementValue(frozenFrames, null);
+    final MeasurementValue tfValues = new MeasurementValue(totalFrames, MeasurementUnit.NONE);
+    final MeasurementValue sfValues = new MeasurementValue(slowFrames, MeasurementUnit.NONE);
+    final MeasurementValue ffValues = new MeasurementValue(frozenFrames, MeasurementUnit.NONE);
     final Map<String, @NotNull MeasurementValue> measurements = new HashMap<>();
     measurements.put("frames_total", tfValues);
     measurements.put("frames_slow", sfValues);

sentry-android-core/src/main/java/io/sentry/android/core/PerformanceAndroidEventProcessor.java

@@ -6,8 +6,8 @@
 
 import io.sentry.EventProcessor;
 import io.sentry.Hint;
+import io.sentry.MeasurementUnit;
 import io.sentry.SentryEvent;
-import io.sentry.SentryMeasurementUnit;
 import io.sentry.SpanContext;
 import io.sentry.protocol.MeasurementValue;
 import io.sentry.protocol.SentryId;
@@ -68,7 +68,7 @@ public SentryEvent process(@NotNull SentryEvent event, @NotNull Hint hint) {
       if (appStartUpInterval != null) {
         final MeasurementValue value =
             new MeasurementValue(
-                (float) appStartUpInterval, SentryMeasurementUnit.Duration.MILLISECOND.apiName());
+                (float) appStartUpInterval, MeasurementUnit.Duration.MILLISECOND.apiName());
 
         final String appStartKey =
             AppStartState.getInstance().isColdStart() ? "app_start_cold" : "app_start_warm";

sentry-android-core/src/test/java/io/sentry/android/core/PerformanceAndroidEventProcessorTest.kt

@@ -5,7 +5,7 @@ import com.nhaarman.mockitokotlin2.mock
 import com.nhaarman.mockitokotlin2.whenever
 import io.sentry.Hint
 import io.sentry.IHub
-import io.sentry.SentryMeasurementUnit
+import io.sentry.MeasurementUnit
 import io.sentry.SentryTracer
 import io.sentry.TracesSamplingDecision
 import io.sentry.TransactionContext
@@ -156,7 +156,7 @@ class PerformanceAndroidEventProcessorTest {
         val tracer = SentryTracer(context, fixture.hub)
         var tr = SentryTransaction(tracer)
 
-        val metrics = mapOf("frames_total" to MeasurementValue(1f, SentryMeasurementUnit.Duration.MILLISECOND.apiName()))
+        val metrics = mapOf("frames_total" to MeasurementValue(1f, MeasurementUnit.Duration.MILLISECOND.apiName()))
         whenever(fixture.activityFramesTracker.takeMetrics(any())).thenReturn(metrics)
 
         tr = sut.process(tr, Hint())

sentry-samples/sentry-samples-android/src/main/java/io/sentry/samples/android/MainActivity.java

@@ -5,8 +5,8 @@
 import androidx.appcompat.app.AppCompatActivity;
 import io.sentry.Attachment;
 import io.sentry.ISpan;
+import io.sentry.MeasurementUnit;
 import io.sentry.Sentry;
-import io.sentry.SentryMeasurementUnit;
 import io.sentry.SpanStatus;
 import io.sentry.UserFeedback;
 import io.sentry.protocol.SentryId;
@@ -205,8 +205,7 @@ protected void onResume() {
     screenLoadCount++;
     final ISpan span = Sentry.getSpan();
     if (span != null) {
-      span.setMeasurement(
-          "screen_load_count", screenLoadCount, new SentryMeasurementUnit.Custom("test"));
+      span.setMeasurement("screen_load_count", screenLoadCount, new MeasurementUnit.Custom("test"));
       span.finish(SpanStatus.OK);
     }
   }

sentry/api/sentry.api

@@ -486,7 +486,7 @@ public abstract interface class io/sentry/ISpan {
 	public abstract fun setData (Ljava/lang/String;Ljava/lang/Object;)V
 	public abstract fun setDescription (Ljava/lang/String;)V
 	public abstract fun setMeasurement (Ljava/lang/String;Ljava/lang/Number;)V
-	public abstract fun setMeasurement (Ljava/lang/String;Ljava/lang/Number;Lio/sentry/SentryMeasurementUnit;)V
+	public abstract fun setMeasurement (Ljava/lang/String;Ljava/lang/Number;Lio/sentry/MeasurementUnit;)V
 	public abstract fun setOperation (Ljava/lang/String;)V
 	public abstract fun setStatus (Lio/sentry/SpanStatus;)V
 	public abstract fun setTag (Ljava/lang/String;Ljava/lang/String;)V
@@ -601,6 +601,56 @@ public final class io/sentry/MainEventProcessor : io/sentry/EventProcessor, java
 	public fun process (Lio/sentry/protocol/SentryTransaction;Lio/sentry/Hint;)Lio/sentry/protocol/SentryTransaction;
 }
 
+public abstract interface class io/sentry/MeasurementUnit {
+	public static final field NONE Ljava/lang/String;
+	public fun apiName ()Ljava/lang/String;
+	public abstract fun name ()Ljava/lang/String;
+}
+
+public final class io/sentry/MeasurementUnit$Custom : io/sentry/MeasurementUnit {
+	public fun <init> (Ljava/lang/String;)V
+	public fun name ()Ljava/lang/String;
+}
+
+public final class io/sentry/MeasurementUnit$Duration : java/lang/Enum, io/sentry/MeasurementUnit {
+	public static final field DAY Lio/sentry/MeasurementUnit$Duration;
+	public static final field HOUR Lio/sentry/MeasurementUnit$Duration;
+	public static final field MICROSECOND Lio/sentry/MeasurementUnit$Duration;
+	public static final field MILLISECOND Lio/sentry/MeasurementUnit$Duration;
+	public static final field MINUTE Lio/sentry/MeasurementUnit$Duration;
+	public static final field NANOSECOND Lio/sentry/MeasurementUnit$Duration;
+	public static final field SECOND Lio/sentry/MeasurementUnit$Duration;
+	public static final field WEEK Lio/sentry/MeasurementUnit$Duration;
+	public static fun valueOf (Ljava/lang/String;)Lio/sentry/MeasurementUnit$Duration;
+	public static fun values ()[Lio/sentry/MeasurementUnit$Duration;
+}
+
+public final class io/sentry/MeasurementUnit$Fraction : java/lang/Enum, io/sentry/MeasurementUnit {
+	public static final field PERCENT Lio/sentry/MeasurementUnit$Fraction;
+	public static final field RATIO Lio/sentry/MeasurementUnit$Fraction;
+	public static fun valueOf (Ljava/lang/String;)Lio/sentry/MeasurementUnit$Fraction;
+	public static fun values ()[Lio/sentry/MeasurementUnit$Fraction;
+}
+
+public final class io/sentry/MeasurementUnit$Information : java/lang/Enum, io/sentry/MeasurementUnit {
+	public static final field BIT Lio/sentry/MeasurementUnit$Information;
+	public static final field BYTE Lio/sentry/MeasurementUnit$Information;
+	public static final field EXABYTE Lio/sentry/MeasurementUnit$Information;
+	public static final field EXBIBYTE Lio/sentry/MeasurementUnit$Information;
+	public static final field GIBIBYTE Lio/sentry/MeasurementUnit$Information;
+	public static final field GIGABYTE Lio/sentry/MeasurementUnit$Information;
+	public static final field KIBIBYTE Lio/sentry/MeasurementUnit$Information;
+	public static final field KILOBYTE Lio/sentry/MeasurementUnit$Information;
+	public static final field MEBIBYTE Lio/sentry/MeasurementUnit$Information;
+	public static final field MEGABYTE Lio/sentry/MeasurementUnit$Information;
+	public static final field PEBIBYTE Lio/sentry/MeasurementUnit$Information;
+	public static final field PETABYTE Lio/sentry/MeasurementUnit$Information;
+	public static final field TEBIBYTE Lio/sentry/MeasurementUnit$Information;
+	public static final field TERABYTE Lio/sentry/MeasurementUnit$Information;
+	public static fun valueOf (Ljava/lang/String;)Lio/sentry/MeasurementUnit$Information;
+	public static fun values ()[Lio/sentry/MeasurementUnit$Information;
+}
+
 public final class io/sentry/NoOpEnvelopeReader : io/sentry/IEnvelopeReader {
 	public static fun getInstance ()Lio/sentry/NoOpEnvelopeReader;
 	public fun read (Ljava/io/InputStream;)Lio/sentry/SentryEnvelope;
@@ -673,7 +723,7 @@ public final class io/sentry/NoOpSpan : io/sentry/ISpan {
 	public fun setData (Ljava/lang/String;Ljava/lang/Object;)V
 	public fun setDescription (Ljava/lang/String;)V
 	public fun setMeasurement (Ljava/lang/String;Ljava/lang/Number;)V
-	public fun setMeasurement (Ljava/lang/String;Ljava/lang/Number;Lio/sentry/SentryMeasurementUnit;)V
+	public fun setMeasurement (Ljava/lang/String;Ljava/lang/Number;Lio/sentry/MeasurementUnit;)V
 	public fun setOperation (Ljava/lang/String;)V
 	public fun setStatus (Lio/sentry/SpanStatus;)V
 	public fun setTag (Ljava/lang/String;Ljava/lang/String;)V
@@ -710,7 +760,7 @@ public final class io/sentry/NoOpTransaction : io/sentry/ITransaction {
 	public fun setData (Ljava/lang/String;Ljava/lang/Object;)V
 	public fun setDescription (Ljava/lang/String;)V
 	public fun setMeasurement (Ljava/lang/String;Ljava/lang/Number;)V
-	public fun setMeasurement (Ljava/lang/String;Ljava/lang/Number;Lio/sentry/SentryMeasurementUnit;)V
+	public fun setMeasurement (Ljava/lang/String;Ljava/lang/Number;Lio/sentry/MeasurementUnit;)V
 	public fun setName (Ljava/lang/String;)V
 	public fun setName (Ljava/lang/String;Lio/sentry/protocol/TransactionNameSource;)V
 	public fun setOperation (Ljava/lang/String;)V
@@ -1276,55 +1326,6 @@ public final class io/sentry/SentryLevel : java/lang/Enum, io/sentry/JsonSeriali
 	public static fun values ()[Lio/sentry/SentryLevel;
 }
 
-public abstract interface class io/sentry/SentryMeasurementUnit {
-	public fun apiName ()Ljava/lang/String;
-	public abstract fun name ()Ljava/lang/String;
-}
-
-public final class io/sentry/SentryMeasurementUnit$Custom : io/sentry/SentryMeasurementUnit {
-	public fun <init> (Ljava/lang/String;)V
-	public fun name ()Ljava/lang/String;
-}
-
-public final class io/sentry/SentryMeasurementUnit$Duration : java/lang/Enum, io/sentry/SentryMeasurementUnit {
-	public static final field DAY Lio/sentry/SentryMeasurementUnit$Duration;
-	public static final field HOUR Lio/sentry/SentryMeasurementUnit$Duration;
-	public static final field MICROSECOND Lio/sentry/SentryMeasurementUnit$Duration;
-	public static final field MILLISECOND Lio/sentry/SentryMeasurementUnit$Duration;
-	public static final field MINUTE Lio/sentry/SentryMeasurementUnit$Duration;
-	public static final field NANOSECOND Lio/sentry/SentryMeasurementUnit$Duration;
-	public static final field SECOND Lio/sentry/SentryMeasurementUnit$Duration;
-	public static final field WEEK Lio/sentry/SentryMeasurementUnit$Duration;
-	public static fun valueOf (Ljava/lang/String;)Lio/sentry/SentryMeasurementUnit$Duration;
-	public static fun values ()[Lio/sentry/SentryMeasurementUnit$Duration;
-}
-
-public final class io/sentry/SentryMeasurementUnit$Fraction : java/lang/Enum, io/sentry/SentryMeasurementUnit {
-	public static final field PERCENT Lio/sentry/SentryMeasurementUnit$Fraction;
-	public static final field RATIO Lio/sentry/SentryMeasurementUnit$Fraction;
-	public static fun valueOf (Ljava/lang/String;)Lio/sentry/SentryMeasurementUnit$Fraction;
-	public static fun values ()[Lio/sentry/SentryMeasurementUnit$Fraction;
-}
-
-public final class io/sentry/SentryMeasurementUnit$Information : java/lang/Enum, io/sentry/SentryMeasurementUnit {
-	public static final field BIT Lio/sentry/SentryMeasurementUnit$Information;
-	public static final field BYTE Lio/sentry/SentryMeasurementUnit$Information;
-	public static final field EXABYTE Lio/sentry/SentryMeasurementUnit$Information;
-	public static final field EXBIBYTE Lio/sentry/SentryMeasurementUnit$Information;
-	public static final field GIBIBYTE Lio/sentry/SentryMeasurementUnit$Information;
-	public static final field GIGABYTE Lio/sentry/SentryMeasurementUnit$Information;
-	public static final field KIBIBYTE Lio/sentry/SentryMeasurementUnit$Information;
-	public static final field KILOBYTE Lio/sentry/SentryMeasurementUnit$Information;
-	public static final field MEBIBYTE Lio/sentry/SentryMeasurementUnit$Information;
-	public static final field MEGABYTE Lio/sentry/SentryMeasurementUnit$Information;
-	public static final field PEBIBYTE Lio/sentry/SentryMeasurementUnit$Information;
-	public static final field PETABYTE Lio/sentry/SentryMeasurementUnit$Information;
-	public static final field TEBIBYTE Lio/sentry/SentryMeasurementUnit$Information;
-	public static final field TERABYTE Lio/sentry/SentryMeasurementUnit$Information;
-	public static fun valueOf (Ljava/lang/String;)Lio/sentry/SentryMeasurementUnit$Information;
-	public static fun values ()[Lio/sentry/SentryMeasurementUnit$Information;
-}
-
 public class io/sentry/SentryOptions {
 	public fun <init> ()V
 	public fun addContextTag (Ljava/lang/String;)V
@@ -1553,7 +1554,7 @@ public final class io/sentry/SentryTracer : io/sentry/ITransaction {
 	public fun setData (Ljava/lang/String;Ljava/lang/Object;)V
 	public fun setDescription (Ljava/lang/String;)V
 	public fun setMeasurement (Ljava/lang/String;Ljava/lang/Number;)V
-	public fun setMeasurement (Ljava/lang/String;Ljava/lang/Number;Lio/sentry/SentryMeasurementUnit;)V
+	public fun setMeasurement (Ljava/lang/String;Ljava/lang/Number;Lio/sentry/MeasurementUnit;)V
 	public fun setName (Ljava/lang/String;)V
 	public fun setName (Ljava/lang/String;Lio/sentry/protocol/TransactionNameSource;)V
 	public fun setOperation (Ljava/lang/String;)V
@@ -1661,7 +1662,7 @@ public final class io/sentry/Span : io/sentry/ISpan {
 	public fun setData (Ljava/lang/String;Ljava/lang/Object;)V
 	public fun setDescription (Ljava/lang/String;)V
 	public fun setMeasurement (Ljava/lang/String;Ljava/lang/Number;)V
-	public fun setMeasurement (Ljava/lang/String;Ljava/lang/Number;Lio/sentry/SentryMeasurementUnit;)V
+	public fun setMeasurement (Ljava/lang/String;Ljava/lang/Number;Lio/sentry/MeasurementUnit;)V
 	public fun setOperation (Ljava/lang/String;)V
 	public fun setStatus (Lio/sentry/SpanStatus;)V
 	public fun setTag (Ljava/lang/String;Ljava/lang/String;)V

sentry/src/main/java/io/sentry/ISpan.java

@@ -171,7 +171,9 @@ ISpan startChild(
   Object getData(@NotNull String key);
 
   /**
-   * Set a measurement without unit.
+   * Set a measurement without unit. When setting the measurement without the unit, no formatting
+   * will be applied to the measurement value in the Sentry product, and the value will be shown as
+   * is.
    *
    * <p>NOTE: Setting a measurement with the same name on the same transaction multiple times only
    * keeps the last value.
@@ -191,6 +193,5 @@ ISpan startChild(
    * @param value the value of the measurement
    * @param unit the unit the value is measured in
    */
-  void setMeasurement(
-      @NotNull String name, @NotNull Number value, @NotNull SentryMeasurementUnit unit);
+  void setMeasurement(@NotNull String name, @NotNull Number value, @NotNull MeasurementUnit unit);
 }

sentry/src/main/java/io/sentry/SentryMeasurementUnit.java → sentry/src/main/java/io/sentry/MeasurementUnit.java

@@ -5,11 +5,25 @@
 import org.jetbrains.annotations.NotNull;
 
 /**
- * <a href="https://getsentry.github.io/relay/relay_metrics/enum.MetricUnit.html#">Develop Docs</a>
+ * The unit of measurement of a metric value.
+ *
+ * <p>Units augment metric values by giving them a magnitude and semantics. There are certain types
+ * of units that are subdivided in their precision, such as the {@link MeasurementUnit.Duration} for
+ * time measurements.
+ *
+ * <p>When using the units to custom measurements, Sentry will apply formatting to display
+ * measurement values in the UI.
+ *
+ * @see <a href="https://getsentry.github.io/relay/relay_metrics/enum.MetricUnit.html#">Develop
+ *     Docs</a>
  */
-public interface SentryMeasurementUnit {
+public interface MeasurementUnit {
 
-  enum Duration implements SentryMeasurementUnit {
+  /** Untyped value. */
+  String NONE = "none";
+
+  /** A time duration. */
+  enum Duration implements MeasurementUnit {
     /** Nanosecond (`"nanosecond"`), 10^-9 seconds. */
     NANOSECOND,
 
@@ -35,7 +49,8 @@ enum Duration implements SentryMeasurementUnit {
     WEEK;
   }
 
-  enum Information implements SentryMeasurementUnit {
+  /** Size of information derived from bytes. */
+  enum Information implements MeasurementUnit {
     /** Bit (`"bit"`), corresponding to 1/8 of a byte. */
     BIT,
 
@@ -79,15 +94,20 @@ enum Information implements SentryMeasurementUnit {
     EXBIBYTE;
   }
 
-  enum Fraction implements SentryMeasurementUnit {
+  /** Fractions such as percentages. */
+  enum Fraction implements MeasurementUnit {
     /** Floating point fraction of `1`. */
     RATIO,
 
     /** Ratio expressed as a fraction of `100`. `100%` equals a ratio of `1.0`. */
     PERCENT;
   }
 
-  final class Custom implements SentryMeasurementUnit {
+  /**
+   * Custom units without builtin conversion. No formatting will be applied to the measurement value
+   * in the Sentry product, and the value with the unit will be shown as is.
+   */
+  final class Custom implements MeasurementUnit {
 
     private final @NotNull String name;
 
@@ -104,6 +124,7 @@ public Custom(@NotNull String name) {
   @NotNull
   String name();
 
+  /** Unit adhering to the API spec. */
   @ApiStatus.Internal
   default @NotNull String apiName() {
     return name().toLowerCase(Locale.ROOT);

sentry/src/main/java/io/sentry/NoOpSpan.java

@@ -117,5 +117,5 @@ public void setMeasurement(@NotNull String name, @NotNull Number value) {}
 
   @Override
   public void setMeasurement(
-      @NotNull String name, @NotNull Number value, @NotNull SentryMeasurementUnit unit) {}
+      @NotNull String name, @NotNull Number value, @NotNull MeasurementUnit unit) {}
 }

sentry/src/main/java/io/sentry/NoOpTransaction.java

@@ -170,5 +170,5 @@ public void setMeasurement(@NotNull String name, @NotNull Number value) {}
 
   @Override
   public void setMeasurement(
-      @NotNull String name, @NotNull Number value, @NotNull SentryMeasurementUnit unit) {}
+      @NotNull String name, @NotNull Number value, @NotNull MeasurementUnit unit) {}
 }

sentry/src/main/java/io/sentry/SentryTracer.java

@@ -526,7 +526,7 @@ public void setMeasurement(final @NotNull String name, final @NotNull Number val
   public void setMeasurement(
       final @NotNull String name,
       final @NotNull Number value,
-      final @NotNull SentryMeasurementUnit unit) {
+      final @NotNull MeasurementUnit unit) {
     if (root.isFinished()) {
       return;
     }

sentry/src/main/java/io/sentry/Span.java

@@ -320,7 +320,7 @@ public void setMeasurement(@NotNull String name, @NotNull Number value) {
 
   @Override
   public void setMeasurement(
-      @NotNull String name, @NotNull Number value, @NotNull SentryMeasurementUnit unit) {
+      @NotNull String name, @NotNull Number value, @NotNull MeasurementUnit unit) {
     this.transaction.setMeasurement(name, value, unit);
   }