Provide API for attaching custom measurements to transactions

CHANGELOG.md

@@ -6,6 +6,7 @@
 
 - Make user segment a top level property ([#2257](https://github.com/getsentry/sentry-java/pull/2257))
 - Replace user `other` with `data` ([#2258](https://github.com/getsentry/sentry-java/pull/2258))
+- Provide API for attaching custom measurements to transactions ([#2260](https://github.com/getsentry/sentry-java/pull/2260))
 
 ## 6.5.0-beta.1
 

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

@@ -1,11 +1,10 @@
 package io.sentry.android.core;
 
-import static io.sentry.protocol.MeasurementValue.NONE_UNIT;
-
 import android.app.Activity;
 import android.util.SparseIntArray;
 import androidx.core.app.FrameMetricsAggregator;
 import io.sentry.ILogger;
+import io.sentry.SentryMeasurementUnit;
 import io.sentry.protocol.MeasurementValue;
 import io.sentry.protocol.SentryId;
 import java.util.HashMap;
@@ -104,9 +103,12 @@ public synchronized void setMetrics(
       return;
     }
 
-    final MeasurementValue tfValues = new MeasurementValue(totalFrames, NONE_UNIT);
-    final MeasurementValue sfValues = new MeasurementValue(slowFrames, NONE_UNIT);
-    final MeasurementValue ffValues = new MeasurementValue(frozenFrames, NONE_UNIT);
+    final MeasurementValue tfValues =
+        new MeasurementValue(totalFrames, SentryMeasurementUnit.Duration.NONE.apiName());
+    final MeasurementValue sfValues =
+        new MeasurementValue(slowFrames, SentryMeasurementUnit.Duration.NONE.apiName());
+    final MeasurementValue ffValues =
+        new MeasurementValue(frozenFrames, SentryMeasurementUnit.Duration.NONE.apiName());
     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

@@ -3,11 +3,11 @@
 import static io.sentry.android.core.ActivityLifecycleIntegration.APP_START_COLD;
 import static io.sentry.android.core.ActivityLifecycleIntegration.APP_START_WARM;
 import static io.sentry.android.core.ActivityLifecycleIntegration.UI_LOAD_OP;
-import static io.sentry.protocol.MeasurementValue.MILLISECOND_UNIT;
 
 import io.sentry.EventProcessor;
 import io.sentry.Hint;
 import io.sentry.SentryEvent;
+import io.sentry.SentryMeasurementUnit;
 import io.sentry.SpanContext;
 import io.sentry.protocol.MeasurementValue;
 import io.sentry.protocol.SentryId;
@@ -67,7 +67,8 @@ public SentryEvent process(@NotNull SentryEvent event, @NotNull Hint hint) {
       // if appStartUpInterval is null, metrics are not ready to be sent
       if (appStartUpInterval != null) {
         final MeasurementValue value =
-            new MeasurementValue((float) appStartUpInterval, MILLISECOND_UNIT);
+            new MeasurementValue(
+                (float) appStartUpInterval, SentryMeasurementUnit.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,12 +5,12 @@ 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.SentryTracer
 import io.sentry.TracesSamplingDecision
 import io.sentry.TransactionContext
 import io.sentry.android.core.ActivityLifecycleIntegration.UI_LOAD_OP
 import io.sentry.protocol.MeasurementValue
-import io.sentry.protocol.MeasurementValue.MILLISECOND_UNIT
 import io.sentry.protocol.SentryTransaction
 import java.util.Date
 import kotlin.test.BeforeTest
@@ -156,7 +156,7 @@ class PerformanceAndroidEventProcessorTest {
         val tracer = SentryTracer(context, fixture.hub)
         var tr = SentryTransaction(tracer)
 
-        val metrics = mapOf("frames_total" to MeasurementValue(1f, MILLISECOND_UNIT))
+        val metrics = mapOf("frames_total" to MeasurementValue(1f, SentryMeasurementUnit.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

@@ -6,6 +6,7 @@
 import io.sentry.Attachment;
 import io.sentry.ISpan;
 import io.sentry.Sentry;
+import io.sentry.SentryMeasurementUnit;
 import io.sentry.SpanStatus;
 import io.sentry.UserFeedback;
 import io.sentry.protocol.SentryId;
@@ -27,6 +28,7 @@
 public class MainActivity extends AppCompatActivity {
 
   private int crashCount = 0;
+  private int screenLoadCount = 0;
 
   @Override
   protected void onCreate(Bundle savedInstanceState) {
@@ -200,8 +202,10 @@ protected void onCreate(Bundle savedInstanceState) {
   @Override
   protected void onResume() {
     super.onResume();
+    screenLoadCount++;
     final ISpan span = Sentry.getSpan();
     if (span != null) {
+      span.setMeasurement("screen_load_count", screenLoadCount, new SentryMeasurementUnit.Custom("test"));
       span.finish(SpanStatus.OK);
     }
   }

sentry-samples/sentry-samples-spring-boot/src/main/java/io/sentry/samples/spring/boot/PersonService.java

@@ -1,5 +1,7 @@
 package io.sentry.samples.spring.boot;
 
+import io.sentry.ISpan;
+import io.sentry.Sentry;
 import io.sentry.spring.tracing.SentrySpan;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -16,12 +18,19 @@ public class PersonService {
   private static final Logger LOGGER = LoggerFactory.getLogger(PersonService.class);
 
   private final JdbcTemplate jdbcTemplate;
+  private int createCount = 0;
 
   public PersonService(JdbcTemplate jdbcTemplate) {
     this.jdbcTemplate = jdbcTemplate;
   }
 
   Person create(Person person) {
+    createCount++;
+    final ISpan span = Sentry.getSpan();
+    if (span != null) {
+      span.setMeasurement("create_count", createCount);
+    }
+
     jdbcTemplate.update(
         "insert into person (firstName, lastName) values (?, ?)",
         person.getFirstName(),

sentry/api/sentry.api

@@ -483,6 +483,8 @@ public abstract interface class io/sentry/ISpan {
 	public abstract fun isFinished ()Z
 	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;F)V
+	public abstract fun setMeasurement (Ljava/lang/String;FLio/sentry/SentryMeasurementUnit;)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
@@ -668,6 +670,8 @@ public final class io/sentry/NoOpSpan : io/sentry/ISpan {
 	public fun isFinished ()Z
 	public fun setData (Ljava/lang/String;Ljava/lang/Object;)V
 	public fun setDescription (Ljava/lang/String;)V
+	public fun setMeasurement (Ljava/lang/String;F)V
+	public fun setMeasurement (Ljava/lang/String;FLio/sentry/SentryMeasurementUnit;)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
@@ -703,6 +707,8 @@ public final class io/sentry/NoOpTransaction : io/sentry/ITransaction {
 	public fun scheduleFinish ()V
 	public fun setData (Ljava/lang/String;Ljava/lang/Object;)V
 	public fun setDescription (Ljava/lang/String;)V
+	public fun setMeasurement (Ljava/lang/String;F)V
+	public fun setMeasurement (Ljava/lang/String;FLio/sentry/SentryMeasurementUnit;)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
@@ -1268,6 +1274,21 @@ public final class io/sentry/SentryLevel : java/lang/Enum, io/sentry/JsonSeriali
 	public static fun values ()[Lio/sentry/SentryLevel;
 }
 
+public final class io/sentry/SentryMeasurementUnit : java/lang/Enum {
+	public static final field DAY Lio/sentry/SentryMeasurementUnit;
+	public static final field HOUR Lio/sentry/SentryMeasurementUnit;
+	public static final field MICROSECOND Lio/sentry/SentryMeasurementUnit;
+	public static final field MILLISECOND Lio/sentry/SentryMeasurementUnit;
+	public static final field MINUTE Lio/sentry/SentryMeasurementUnit;
+	public static final field NANOSECOND Lio/sentry/SentryMeasurementUnit;
+	public static final field NONE Lio/sentry/SentryMeasurementUnit;
+	public static final field SECOND Lio/sentry/SentryMeasurementUnit;
+	public static final field WEEK Lio/sentry/SentryMeasurementUnit;
+	public fun apiName ()Ljava/lang/String;
+	public static fun valueOf (Ljava/lang/String;)Lio/sentry/SentryMeasurementUnit;
+	public static fun values ()[Lio/sentry/SentryMeasurementUnit;
+}
+
 public class io/sentry/SentryOptions {
 	public fun <init> ()V
 	public fun addContextTag (Ljava/lang/String;)V
@@ -1492,6 +1513,8 @@ public final class io/sentry/SentryTracer : io/sentry/ITransaction {
 	public fun scheduleFinish ()V
 	public fun setData (Ljava/lang/String;Ljava/lang/Object;)V
 	public fun setDescription (Ljava/lang/String;)V
+	public fun setMeasurement (Ljava/lang/String;F)V
+	public fun setMeasurement (Ljava/lang/String;FLio/sentry/SentryMeasurementUnit;)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
@@ -1598,6 +1621,8 @@ public final class io/sentry/Span : io/sentry/ISpan {
 	public fun isSampled ()Ljava/lang/Boolean;
 	public fun setData (Ljava/lang/String;Ljava/lang/Object;)V
 	public fun setDescription (Ljava/lang/String;)V
+	public fun setMeasurement (Ljava/lang/String;F)V
+	public fun setMeasurement (Ljava/lang/String;FLio/sentry/SentryMeasurementUnit;)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
@@ -2444,8 +2469,6 @@ public final class io/sentry/protocol/Gpu$JsonKeys {
 }
 
 public final class io/sentry/protocol/MeasurementValue : io/sentry/JsonSerializable, io/sentry/JsonUnknown {
-	public static final field MILLISECOND_UNIT Ljava/lang/String;
-	public static final field NONE_UNIT Ljava/lang/String;
 	public fun <init> (FLjava/lang/String;)V
 	public fun <init> (FLjava/lang/String;Ljava/util/Map;)V
 	public fun getUnit ()Ljava/lang/String;

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

@@ -169,4 +169,27 @@ ISpan startChild(
    */
   @Nullable
   Object getData(@NotNull String key);
+
+  /**
+   * Set a measurement without unit.
+   *
+   * <p>NOTE: Setting a measurement with the same name on the same transaction multiple times only
+   * keeps the last value.
+   *
+   * @param name the name of the measurement
+   * @param value the value of the measurement
+   */
+  void setMeasurement(@NotNull String name, float value);
+
+  /**
+   * Set a measurement with specific unit.
+   *
+   * <p>NOTE: Setting a measurement with the same name on the same transaction multiple times only
+   * keeps the last value.
+   *
+   * @param name the name of the measurement
+   * @param value the value of the measurement
+   * @param unit the unit the value is measured in
+   */
+  void setMeasurement(@NotNull String name, float value, @NotNull SentryMeasurementUnit unit);
 }

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

@@ -111,4 +111,11 @@ public void setData(@NotNull String key, @NotNull Object value) {}
   public @Nullable Object getData(@NotNull String key) {
     return null;
   }
+
+  @Override
+  public void setMeasurement(@NotNull String name, float value) {}
+
+  @Override
+  public void setMeasurement(
+      @NotNull String name, float value, @NotNull SentryMeasurementUnit unit) {}
 }

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

@@ -164,4 +164,11 @@ public void setData(@NotNull String key, @NotNull Object value) {}
   public @Nullable Object getData(@NotNull String key) {
     return null;
   }
+
+  @Override
+  public void setMeasurement(@NotNull String name, float value) {}
+
+  @Override
+  public void setMeasurement(
+      @NotNull String name, float value, @NotNull SentryMeasurementUnit unit) {}
 }

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

@@ -0,0 +1,98 @@
+package io.sentry;
+
+import java.util.Locale;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * <a href="https://getsentry.github.io/relay/relay_metrics/enum.DurationUnit.html">Develop Docs</a>
+ */
+public interface SentryMeasurementUnit {
+  enum Duration implements SentryMeasurementUnit {
+    /** Nanosecond (`"nanosecond"`), 10^-9 seconds. */
+    NANOSECOND,
+
+    /** Microsecond (`"microsecond"`), 10^-6 seconds. */
+    MICROSECOND,
+
+    /** Millisecond (`"millisecond"`), 10^-3 seconds. */
+    MILLISECOND,
+
+    /** Full second (`"second"`). */
+    SECOND,
+
+    /** Minute (`"minute"`), 60 seconds. */
+    MINUTE,
+
+    /** Hour (`"hour"`), 3600 seconds. */
+    HOUR,
+
+    /** Day (`"day"`), 86,400 seconds. */
+    DAY,
+
+    /** Week (`"week"`), 604,800 seconds. */
+    WEEK,
+
+    /** Untyped value without a unit. */
+    NONE;
+  }
+
+  enum Information implements SentryMeasurementUnit {
+    /// Bit (`"bit"`), corresponding to 1/8 of a byte.
+    ///
+    /// Note that there are computer systems with a different number of bits per byte.
+    BIT,
+    /// Byte (`"byte"`).
+    BYTE,
+    /// Kilobyte (`"kilobyte"`), 10^3 bytes.
+    KILOBYTE,
+    /// Kibibyte (`"kibibyte"`), 2^10 bytes.
+    KIBIBYTE,
+    /// Megabyte (`"megabyte"`), 10^6 bytes.
+    MEGABYTE,
+    /// Mebibyte (`"mebibyte"`), 2^20 bytes.
+    MEBIBYTE,
+    /// Gigabyte (`"gigabyte"`), 10^9 bytes.
+    GIGABYTE,
+    /// Gibibyte (`"gibibyte"`), 2^30 bytes.
+    GIBIBYTE,
+    /// Terabyte (`"terabyte"`), 10^12 bytes.
+    TERABYTE,
+    /// Tebibyte (`"tebibyte"`), 2^40 bytes.
+    TEBIBYTE,
+    /// Petabyte (`"petabyte"`), 10^15 bytes.
+    PETABYTE,
+    /// Pebibyte (`"pebibyte"`), 2^50 bytes.
+    PEBIBYTE,
+    /// Exabyte (`"exabyte"`), 10^18 bytes.
+    EXABYTE,
+    /// Exbibyte (`"exbibyte"`), 2^60 bytes.
+    EXBIBYTE,
+  }
+
+  enum Fraction implements SentryMeasurementUnit {
+    /// 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 {
+
+    private final @NotNull String name;
+
+    public Custom(@NotNull String name) {
+      this.name = name;
+    }
+
+    @Override public @NotNull String name() {
+      return name;
+    }
+  }
+
+  @NotNull String name();
+
+  default @NotNull String apiName() {
+    return name().toLowerCase(Locale.ROOT);
+  }
+}