ref(types): Add type for measurement unit (#5313)

Folks gave some feedback that we should be explicit about the units we support. Let's add TypeScript types for these so we don't add any runtime logic, but it should have helpful auto-complete for users.

Author: AbhiPrasad

packages/tracing/src/browser/metrics/index.ts

@@ -50,7 +50,7 @@ function _trackCLS(): void {
     }
 
     __DEBUG_BUILD__ && logger.log('[Measurements] Adding CLS');
-    _measurements['cls'] = { value: metric.value, unit: 'none' };
+    _measurements['cls'] = { value: metric.value, unit: '' };
     _clsEntry = entry as LayoutShift;
   });
 }

packages/tracing/src/transaction.ts

@@ -4,6 +4,7 @@ import {
   BaggageObj,
   Event,
   Measurements,
+  MeasurementUnit,
   Transaction as TransactionInterface,
   TransactionContext,
   TransactionMetadata,
@@ -77,7 +78,7 @@ export class Transaction extends SpanClass implements TransactionInterface {
   /**
    * @inheritDoc
    */
-  public setMeasurement(name: string, value: number, unit: string = ''): void {
+  public setMeasurement(name: string, value: number, unit: MeasurementUnit = ''): void {
     this._measurements[name] = { value, unit };
   }
 

packages/types/src/event.ts

@@ -4,13 +4,13 @@ import { Contexts } from './context';
 import { DebugMeta } from './debugMeta';
 import { Exception } from './exception';
 import { Extras } from './extra';
+import { Measurements } from './measurement';
 import { Primitive } from './misc';
 import { Request } from './request';
 import { CaptureContext } from './scope';
 import { SdkInfo } from './sdkinfo';
 import { Severity, SeverityLevel } from './severity';
 import { Span } from './span';
-import { Measurements } from './transaction';
 import { User } from './user';
 
 /** JSDoc */

packages/types/src/index.ts

@@ -65,14 +65,21 @@ export type { Stacktrace, StackParser, StackLineParser, StackLineParserFn } from
 export type { TextEncoderInternal } from './textencoder';
 export type {
   CustomSamplingContext,
-  Measurements,
   SamplingContext,
   TraceparentData,
   Transaction,
   TransactionContext,
   TransactionMetadata,
   TransactionSamplingMethod,
 } from './transaction';
+export type {
+  DurationUnit,
+  InformationUnit,
+  FractionUnit,
+  MeasurementUnit,
+  NoneUnit,
+  Measurements,
+} from './measurement';
 export type { Thread } from './thread';
 export type {
   Transport,

packages/types/src/measurement.ts

@@ -0,0 +1,43 @@
+// Based on https://getsentry.github.io/relay/relay_metrics/enum.MetricUnit.html
+// For more details, see measurement key in https://develop.sentry.dev/sdk/event-payloads/transaction/
+
+/**
+ * A time duration.
+ */
+export type DurationUnit = 'nanosecond' | 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week';
+
+/**
+ * Size of information derived from bytes.
+ */
+export type InformationUnit =
+  | 'bit'
+  | 'byte'
+  | 'kilobyte'
+  | 'kibibyte'
+  | 'megabyte'
+  | 'mebibyte'
+  | 'gigabyte'
+  | 'terabyte'
+  | 'tebibyte'
+  | 'petabyte'
+  | 'exabyte'
+  | 'exbibyte';
+
+/**
+ * Fractions such as percentages.
+ */
+export type FractionUnit = 'ratio' | 'percent';
+
+/**
+ * Untyped value without a unit.
+ */
+export type NoneUnit = '' | 'none';
+
+// See https://github.com/microsoft/TypeScript/issues/29729#issuecomment-1082546550
+// Needed to make sure auto-complete will work for the string union type while still
+// allowing for arbitrary strings as custom units (user-defined units without builtin conversion or default).
+type LiteralUnion<T extends string> = T | Omit<T, T>;
+
+export type MeasurementUnit = LiteralUnion<DurationUnit | InformationUnit | FractionUnit | NoneUnit>;
+
+export type Measurements = Record<string, { value: number; unit: MeasurementUnit }>;

packages/types/src/transaction.ts

@@ -1,4 +1,5 @@
 import { Baggage } from './baggage';
+import { MeasurementUnit } from './measurement';
 import { ExtractedNodeRequestData, Primitive, WorkerLocation } from './misc';
 import { Span, SpanContext } from './span';
 /**
@@ -80,7 +81,7 @@ export interface Transaction extends TransactionContext, Span {
    * @param value Value of the measurement
    * @param unit Unit of the measurement. (Defaults to an empty string)
    */
-  setMeasurement(name: string, value: number, unit: string): void;
+  setMeasurement(name: string, value: number, unit: MeasurementUnit): void;
 
   /** Returns the current transaction properties as a `TransactionContext` */
   toContext(): TransactionContext;
@@ -127,8 +128,6 @@ export interface SamplingContext extends CustomSamplingContext {
   request?: ExtractedNodeRequestData;
 }
 
-export type Measurements = Record<string, { value: number; unit: string }>;
-
 export type TransactionSamplingMethod = 'explicitly_set' | 'client_sampler' | 'client_rate' | 'inheritance';
 
 export interface TransactionMetadata {