feat(metrics): Add interfaces for metrics (#9698)

Not adding any tests for `createMetricEnvelope` yet because the type for
`metricAggregate` is going to change, just added it as boilerplate.

In the next PR I'll be implementing a metrics aggregator class which
lives on the client. This is responsible for bucketing metrics and
incrementally flushing them out.

https://develop.sentry.dev/delightful-developer-metrics/
https://develop.sentry.dev/delightful-developer-metrics/sending-metrics-sdk/

packages/core/src/metrics/index.ts

@@ -0,0 +1,43 @@
+import type { DsnComponents, DynamicSamplingContext, SdkMetadata, StatsdEnvelope, StatsdItem } from '@sentry/types';
+import { createEnvelope, dropUndefinedKeys, dsnToString } from '@sentry/utils';
+
+/**
+ * Create envelope from a metric aggregate.
+ */
+export function createMetricEnvelope(
+  // TODO(abhi): Add type for this
+  metricAggregate: string,
+  dynamicSamplingContext?: Partial<DynamicSamplingContext>,
+  metadata?: SdkMetadata,
+  tunnel?: string,
+  dsn?: DsnComponents,
+): StatsdEnvelope {
+  const headers: StatsdEnvelope[0] = {
+    sent_at: new Date().toISOString(),
+  };
+
+  if (metadata && metadata.sdk) {
+    headers.sdk = {
+      name: metadata.sdk.name,
+      version: metadata.sdk.version,
+    };
+  }
+
+  if (!!tunnel && !!dsn) {
+    headers.dsn = dsnToString(dsn);
+  }
+
+  if (dynamicSamplingContext) {
+    headers.trace = dropUndefinedKeys(dynamicSamplingContext) as DynamicSamplingContext;
+  }
+
+  const item = createMetricEnvelopeItem(metricAggregate);
+  return createEnvelope<StatsdEnvelope>(headers, [item]);
+}
+
+function createMetricEnvelopeItem(metricAggregate: string): StatsdItem {
+  const metricHeaders: StatsdItem[0] = {
+    type: 'statsd',
+  };
+  return [metricHeaders, metricAggregate];
+}

packages/types/src/envelope.ts

@@ -109,5 +109,11 @@ export type ReplayEnvelope = [ReplayEnvelopeHeaders, [ReplayEventItem, ReplayRec
 export type CheckInEnvelope = BaseEnvelope<CheckInEnvelopeHeaders, CheckInItem>;
 export type StatsdEnvelope = BaseEnvelope<StatsdEnvelopeHeaders, StatsdItem>;
 
-export type Envelope = EventEnvelope | SessionEnvelope | ClientReportEnvelope | ReplayEnvelope | CheckInEnvelope;
+export type Envelope =
+  | EventEnvelope
+  | SessionEnvelope
+  | ClientReportEnvelope
+  | ReplayEnvelope
+  | CheckInEnvelope
+  | StatsdEnvelope;
 export type EnvelopeItem = Envelope[1][number];

packages/types/src/index.ts

@@ -42,6 +42,8 @@ export type {
   UserFeedbackItem,
   CheckInItem,
   CheckInEnvelope,
+  StatsdItem,
+  StatsdEnvelope,
 } from './envelope';
 export type { ExtendedError } from './error';
 export type { Event, EventHint, EventType, ErrorEvent, TransactionEvent } from './event';
@@ -136,3 +138,4 @@ export type {
 
 export type { BrowserClientReplayOptions, BrowserClientProfilingOptions } from './browseroptions';
 export type { CheckIn, MonitorConfig, FinishedCheckIn, InProgressCheckIn, SerializedCheckIn } from './checkin';
+export type { Metric, CounterMetric, GaugeMetric, DistributionMetric, SetMetric } from './metrics';

packages/types/src/metrics.ts

@@ -0,0 +1,32 @@
+import type { MeasurementUnit } from './measurement';
+import type { Primitive } from './misc';
+
+export interface BaseMetric {
+  name: string;
+  timestamp: number;
+  unit?: MeasurementUnit;
+  tags?: { [key: string]: Primitive };
+}
+
+export interface CounterMetric extends BaseMetric {
+  value: number;
+}
+
+export interface GaugeMetric extends BaseMetric {
+  value: number;
+  first: number;
+  min: number;
+  max: number;
+  sum: number;
+  count: number;
+}
+
+export interface DistributionMetric extends BaseMetric {
+  value: number[];
+}
+
+export interface SetMetric extends BaseMetric {
+  value: Set<number>;
+}
+
+export type Metric = CounterMetric | GaugeMetric | DistributionMetric | SetMetric;