feat(tracemetrics): Add trace metrics behind an experiments flag

This allows the js sdk to send in new trace metric protocol items, although this code is experimental since the schema may still change. Most of this has been copied from logs so some parts may need to be modified / removed later (eg. buffer) but this should allow us to start on UI work by sending in larger amounts of data from sentry js app to test grouping / aggregations etc.

Author: k-fish

dev-packages/browser-integration-tests/suites/public-api/metrics/init.js

@@ -0,0 +1,11 @@
+import * as Sentry from '@sentry/browser';
+
+window.Sentry = Sentry;
+
+Sentry.init({
+  dsn: 'https://[email protected]/1337',
+  _enableTraceMetrics: true,
+  release: '1.0.0',
+  environment: 'test',
+  autoSessionTracking: false, // Was causing session envelopes to be sent
+});

dev-packages/browser-integration-tests/suites/public-api/metrics/simple/subject.js

@@ -0,0 +1,12 @@
+Sentry.metrics.count('test.counter', 1, { attributes: { endpoint: '/api/test' } });
+Sentry.metrics.gauge('test.gauge', 42, { unit: 'millisecond', attributes: { server: 'test-1' } });
+Sentry.metrics.distribution('test.distribution', 200, { unit: 'second', attributes: { priority: 'high' } });
+
+Sentry.startSpan({ name: 'test-span', op: 'test' }, () => {
+  Sentry.metrics.count('test.span.counter', 1, { attributes: { operation: 'test' } });
+});
+
+Sentry.setUser({ id: 'user-123', email: '[email protected]', username: 'testuser' });
+Sentry.metrics.count('test.user.counter', 1, { attributes: { action: 'click' } });
+
+Sentry.flush();

dev-packages/browser-integration-tests/suites/public-api/metrics/simple/test.ts

@@ -0,0 +1,104 @@
+import { expect } from '@playwright/test';
+import type { MetricEnvelope } from '@sentry/core';
+import { sentryTest } from '../../../../utils/fixtures';
+import { getFirstSentryEnvelopeRequest, properFullEnvelopeRequestParser } from '../../../../utils/helpers';
+
+sentryTest('should capture all metric types', async ({ getLocalTestUrl, page }) => {
+  const bundle = process.env.PW_BUNDLE || '';
+  if (bundle.startsWith('bundle') || bundle.startsWith('loader')) {
+    sentryTest.skip();
+  }
+
+  const url = await getLocalTestUrl({ testDir: __dirname });
+
+  const event = await getFirstSentryEnvelopeRequest<MetricEnvelope>(page, url, properFullEnvelopeRequestParser);
+  const envelopeItems = event[1];
+
+  expect(envelopeItems[0]).toEqual([
+    {
+      type: 'metric',
+      item_count: 5,
+      content_type: 'application/vnd.sentry.items.trace-metric+json',
+    },
+    {
+      items: [
+        {
+          timestamp: expect.any(Number),
+          trace_id: expect.any(String),
+          name: 'test.counter',
+          type: 'counter',
+          value: 1,
+          attributes: {
+            endpoint: { value: '/api/test', type: 'string' },
+            'sentry.release': { value: '1.0.0', type: 'string' },
+            'sentry.environment': { value: 'test', type: 'string' },
+            'sentry.sdk.name': { value: 'sentry.javascript.browser', type: 'string' },
+            'sentry.sdk.version': { value: expect.any(String), type: 'string' },
+          },
+        },
+        {
+          timestamp: expect.any(Number),
+          trace_id: expect.any(String),
+          name: 'test.gauge',
+          type: 'gauge',
+          unit: 'millisecond',
+          value: 42,
+          attributes: {
+            server: { value: 'test-1', type: 'string' },
+            'sentry.release': { value: '1.0.0', type: 'string' },
+            'sentry.environment': { value: 'test', type: 'string' },
+            'sentry.sdk.name': { value: 'sentry.javascript.browser', type: 'string' },
+            'sentry.sdk.version': { value: expect.any(String), type: 'string' },
+          },
+        },
+        {
+          timestamp: expect.any(Number),
+          trace_id: expect.any(String),
+          name: 'test.distribution',
+          type: 'distribution',
+          unit: 'second',
+          value: 200,
+          attributes: {
+            priority: { value: 'high', type: 'string' },
+            'sentry.release': { value: '1.0.0', type: 'string' },
+            'sentry.environment': { value: 'test', type: 'string' },
+            'sentry.sdk.name': { value: 'sentry.javascript.browser', type: 'string' },
+            'sentry.sdk.version': { value: expect.any(String), type: 'string' },
+          },
+        },
+        {
+          timestamp: expect.any(Number),
+          trace_id: expect.any(String),
+          span_id: expect.any(String),
+          name: 'test.span.counter',
+          type: 'counter',
+          value: 1,
+          attributes: {
+            operation: { value: 'test', type: 'string' },
+            'sentry.release': { value: '1.0.0', type: 'string' },
+            'sentry.environment': { value: 'test', type: 'string' },
+            'sentry.sdk.name': { value: 'sentry.javascript.browser', type: 'string' },
+            'sentry.sdk.version': { value: expect.any(String), type: 'string' },
+          },
+        },
+        {
+          timestamp: expect.any(Number),
+          trace_id: expect.any(String),
+          name: 'test.user.counter',
+          type: 'counter',
+          value: 1,
+          attributes: {
+            action: { value: 'click', type: 'string' },
+            'user.id': { value: 'user-123', type: 'string' },
+            'user.email': { value: '[email protected]', type: 'string' },
+            'user.name': { value: 'testuser', type: 'string' },
+            'sentry.release': { value: '1.0.0', type: 'string' },
+            'sentry.environment': { value: 'test', type: 'string' },
+            'sentry.sdk.name': { value: 'sentry.javascript.browser', type: 'string' },
+            'sentry.sdk.version': { value: expect.any(String), type: 'string' },
+          },
+        },
+      ],
+    },
+  ]);
+});

dev-packages/node-integration-tests/utils/assertions.ts

@@ -4,6 +4,7 @@ import type {
   Event,
   SerializedCheckIn,
   SerializedLogContainer,
+  SerializedMetricContainer,
   SerializedSession,
   SessionAggregates,
   TransactionEvent,
@@ -76,6 +77,15 @@ export function assertSentryLogContainer(
   });
 }
 
+export function assertSentryMetricContainer(
+  actual: SerializedMetricContainer,
+  expected: Partial<SerializedMetricContainer>,
+): void {
+  expect(actual).toMatchObject({
+    ...expected,
+  });
+}
+
 export function assertEnvelopeHeader(actual: Envelope[0], expected: Partial<Envelope[0]>): void {
   expect(actual).toEqual({
     event_id: expect.any(String),

dev-packages/node-integration-tests/utils/runner.ts

@@ -7,6 +7,7 @@ import type {
   EventEnvelope,
   SerializedCheckIn,
   SerializedLogContainer,
+  SerializedMetricContainer,
   SerializedSession,
   SessionAggregates,
   TransactionEvent,
@@ -25,6 +26,7 @@ import {
   assertSentryClientReport,
   assertSentryEvent,
   assertSentryLogContainer,
+  assertSentryMetricContainer,
   assertSentrySession,
   assertSentrySessions,
   assertSentryTransaction,
@@ -130,6 +132,7 @@ type ExpectedSessions = Partial<SessionAggregates> | ((event: SessionAggregates)
 type ExpectedCheckIn = Partial<SerializedCheckIn> | ((event: SerializedCheckIn) => void);
 type ExpectedClientReport = Partial<ClientReport> | ((event: ClientReport) => void);
 type ExpectedLogContainer = Partial<SerializedLogContainer> | ((event: SerializedLogContainer) => void);
+type ExpectedMetricContainer = Partial<SerializedMetricContainer> | ((event: SerializedMetricContainer) => void);
 
 type Expected =
   | {
@@ -152,6 +155,9 @@ type Expected =
     }
   | {
       log: ExpectedLogContainer;
+    }
+  | {
+      metric: ExpectedMetricContainer;
     };
 
 type ExpectedEnvelopeHeader =
@@ -380,6 +386,11 @@ export function createRunner(...paths: string[]) {
       expectedEnvelopeHeaders.push(expected);
       return this;
     },
+    expectMetricEnvelope: function () {
+      // Unignore metric envelopes
+      ignored.delete('metric');
+      return this;
+    },
     withEnv: function (env: Record<string, string>) {
       withEnv = env;
       return this;
@@ -514,6 +525,9 @@ export function createRunner(...paths: string[]) {
             } else if ('log' in expected) {
               expectLog(item[1] as SerializedLogContainer, expected.log);
               expectCallbackCalled();
+            } else if ('metric' in expected) {
+              expectMetric(item[1] as SerializedMetricContainer, expected.metric);
+              expectCallbackCalled();
             } else {
               throw new Error(
                 `Unhandled expected envelope item type: ${JSON.stringify(expected)}\nItem: ${JSON.stringify(item)}`,
@@ -769,6 +783,14 @@ function expectLog(item: SerializedLogContainer, expected: ExpectedLogContainer)
   }
 }
 
+function expectMetric(item: SerializedMetricContainer, expected: ExpectedMetricContainer): void {
+  if (typeof expected === 'function') {
+    expected(item);
+  } else {
+    assertSentryMetricContainer(item, expected);
+  }
+}
+
 /**
  * Converts ESM import statements to CommonJS require statements
  * @param content The content of an ESM file

packages/browser/src/client.ts

@@ -11,6 +11,7 @@ import type {
 } from '@sentry/core';
 import {
   _INTERNAL_flushLogsBuffer,
+  _INTERNAL_flushMetricsBuffer,
   addAutoIpAddressToSession,
   applySdkMetadata,
   Client,
@@ -85,6 +86,7 @@ export type BrowserClientOptions = ClientOptions<BrowserTransportOptions> & Brow
  */
 export class BrowserClient extends Client<BrowserClientOptions> {
   private _logFlushIdleTimeout: ReturnType<typeof setTimeout> | undefined;
+  private _metricFlushIdleTimeout: ReturnType<typeof setTimeout> | undefined;
   /**
    * Creates a new Browser SDK instance.
    *
@@ -106,9 +108,9 @@ export class BrowserClient extends Client<BrowserClientOptions> {
 
     super(opts);
 
-    const { sendDefaultPii, sendClientReports, enableLogs } = this._options;
+    const { sendDefaultPii, sendClientReports, enableLogs, _enableTraceMetrics } = this._options;
 
-    if (WINDOW.document && (sendClientReports || enableLogs)) {
+    if (WINDOW.document && (sendClientReports || enableLogs || _enableTraceMetrics)) {
       WINDOW.document.addEventListener('visibilitychange', () => {
         if (WINDOW.document.visibilityState === 'hidden') {
           if (sendClientReports) {
@@ -117,6 +119,9 @@ export class BrowserClient extends Client<BrowserClientOptions> {
           if (enableLogs) {
             _INTERNAL_flushLogsBuffer(this);
           }
+          if (_enableTraceMetrics) {
+            _INTERNAL_flushMetricsBuffer(this);
+          }
         }
       });
     }
@@ -137,6 +142,22 @@ export class BrowserClient extends Client<BrowserClientOptions> {
       });
     }
 
+    if (_enableTraceMetrics) {
+      this.on('flush', () => {
+        _INTERNAL_flushMetricsBuffer(this);
+      });
+
+      this.on('afterCaptureMetric', () => {
+        if (this._metricFlushIdleTimeout) {
+          clearTimeout(this._metricFlushIdleTimeout);
+        }
+
+        this._metricFlushIdleTimeout = setTimeout(() => {
+          _INTERNAL_flushMetricsBuffer(this);
+        }, DEFAULT_FLUSH_INTERVAL);
+      });
+    }
+
     if (sendDefaultPii) {
       this.on('beforeSendSession', addAutoIpAddressToSession);
     }

packages/browser/src/exports.ts

@@ -65,6 +65,7 @@ export {
   spanToTraceHeader,
   spanToBaggageHeader,
   updateSpanName,
+  metrics,
 } from '@sentry/core';
 
 export {

packages/core/src/carrier.ts

@@ -3,6 +3,7 @@ import type { AsyncContextStrategy } from './asyncContext/types';
 import type { Client } from './client';
 import type { Scope } from './scope';
 import type { SerializedLog } from './types-hoist/log';
+import type { SerializedMetric } from './types-hoist/metric';
 import { SDK_VERSION } from './utils/version';
 import { GLOBAL_OBJ } from './utils/worldwide';
 
@@ -32,6 +33,12 @@ export interface SentryCarrier {
    */
   clientToLogBufferMap?: WeakMap<Client, Array<SerializedLog>>;
 
+  /**
+   * A map of Sentry clients to their metric buffers.
+   * This is used to store metrics that are sent to Sentry.
+   */
+  clientToMetricBufferMap?: WeakMap<Client, Array<SerializedMetric>>;
+
   /** Overwrites TextEncoder used in `@sentry/core`, need for `[email protected]` and older */
   encodePolyfill?: (input: string) => Uint8Array;
   /** Overwrites TextDecoder used in `@sentry/core`, need for `[email protected]` and older */

packages/core/src/client.ts

@@ -24,6 +24,7 @@ import type { EventProcessor } from './types-hoist/eventprocessor';
 import type { FeedbackEvent } from './types-hoist/feedback';
 import type { Integration } from './types-hoist/integration';
 import type { Log } from './types-hoist/log';
+import type { Metric } from './types-hoist/metric';
 import type { ClientOptions } from './types-hoist/options';
 import type { ParameterizedString } from './types-hoist/parameterize';
 import type { SdkMetadata } from './types-hoist/sdkmetadata';
@@ -687,6 +688,20 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
    */
   public on(hook: 'flushLogs', callback: () => void): () => void;
 
+  /**
+   * A hook that is called after capturing a metric. This hooks runs after `beforeSendMetric` is fired.
+   *
+   * @returns {() => void} A function that, when executed, removes the registered callback.
+   */
+  public on(hook: 'afterCaptureMetric', callback: (metric: Metric) => void): () => void;
+
+  /**
+   * A hook that is called when the client is flushing metrics
+   *
+   * @returns {() => void} A function that, when executed, removes the registered callback.
+   */
+  public on(hook: 'flushMetrics', callback: () => void): () => void;
+
   /**
    * Register a hook on this client.
    */
@@ -875,6 +890,16 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
    */
   public emit(hook: 'flushLogs'): void;
 
+  /**
+   * Emit a hook event for client after capturing a metric.
+   */
+  public emit(hook: 'afterCaptureMetric', metric: Metric): void;
+
+  /**
+   * Emit a hook event for client flush metrics
+   */
+  public emit(hook: 'flushMetrics'): void;
+
   /**
    * Emit a hook that was previously registered via `on()`.
    */

packages/core/src/index.ts

@@ -126,6 +126,13 @@ export type { ReportDialogOptions } from './report-dialog';
 export { _INTERNAL_captureLog, _INTERNAL_flushLogsBuffer, _INTERNAL_captureSerializedLog } from './logs/internal';
 export * as logger from './logs/public-api';
 export { consoleLoggingIntegration } from './logs/console-integration';
+export {
+  _INTERNAL_captureMetric,
+  _INTERNAL_flushMetricsBuffer,
+  _INTERNAL_captureSerializedMetric,
+} from './metrics/internal';
+export * as metrics from './metrics/public-api';
+export type { MetricOptions } from './metrics/public-api';
 export { createConsolaReporter } from './integrations/consola';
 export { addVercelAiProcessors } from './utils/vercel-ai';
 export { _INTERNAL_getSpanForToolCallId, _INTERNAL_cleanupToolCallSpan } from './utils/vercel-ai/utils';
@@ -355,6 +362,7 @@ export type {
   SpanEnvelope,
   SpanItem,
   LogEnvelope,
+  MetricEnvelope,
 } from './types-hoist/envelope';
 export type { ExtendedError } from './types-hoist/error';
 export type { Event, EventHint, EventType, ErrorEvent, TransactionEvent } from './types-hoist/event';
@@ -416,6 +424,13 @@ export type {
 } from './types-hoist/span';
 export type { SpanStatus } from './types-hoist/spanStatus';
 export type { Log, LogSeverityLevel } from './types-hoist/log';
+export type {
+  Metric,
+  MetricType,
+  SerializedMetric,
+  SerializedMetricContainer,
+  SerializedMetricAttributeValue,
+} from './types-hoist/metric';
 export type { TimedEvent } from './types-hoist/timedEvent';
 export type { StackFrame } from './types-hoist/stackframe';
 export type { Stacktrace, StackParser, StackLineParser, StackLineParserFn } from './types-hoist/stacktrace';