feat(core): Add metric summaries to spans

dev-packages/node-integration-tests/suites/tracing/metric-summaries/scenario.js

@@ -0,0 +1,38 @@
+const { loggingTransport } = require('@sentry-internal/node-integration-tests');
+const Sentry = require('@sentry/node');
+
+Sentry.init({
+  dsn: 'https://[email protected]/1337',
+  release: '1.0',
+  tracesSampleRate: 1.0,
+  transport: loggingTransport,
+  _experiments: {
+    metricsAggregator: true,
+  },
+});
+
+// Stop the process from exiting before the transaction is sent
+setInterval(() => {}, 1000);
+
+Sentry.startSpan(
+  {
+    name: 'Test Transaction',
+    op: 'transaction',
+  },
+  () => {
+    Sentry.metrics.increment('root-counter');
+    Sentry.metrics.increment('root-counter');
+
+    Sentry.startSpan(
+      {
+        name: 'Some other span',
+        op: 'transaction',
+      },
+      () => {
+        Sentry.metrics.increment('root-counter');
+        Sentry.metrics.increment('root-counter');
+        Sentry.metrics.increment('root-counter', 2);
+      },
+    );
+  },
+);

dev-packages/node-integration-tests/suites/tracing/metric-summaries/test.ts

@@ -0,0 +1,39 @@
+import { createRunner } from '../../../utils/runner';
+
+const EXPECTED_TRANSACTION = {
+  transaction: 'Test Transaction',
+  _metrics_summary: {
+    'c:root-counter@none': {
+      min: 1,
+      max: 1,
+      count: 2,
+      sum: 2,
+      tags: {
+        release: '1.0',
+        transaction: 'Test Transaction',
+      },
+    },
+  },
+  spans: expect.arrayContaining([
+    expect.objectContaining({
+      description: 'Some other span',
+      op: 'transaction',
+      _metrics_summary: {
+        'c:root-counter@none': {
+          min: 1,
+          max: 2,
+          count: 3,
+          sum: 4,
+          tags: {
+            release: '1.0',
+            transaction: 'Test Transaction',
+          },
+        },
+      },
+    }),
+  ]),
+};
+
+test('Should add metric summaries to spans', done => {
+  createRunner(__dirname, 'scenario.js').expect({ transaction: EXPECTED_TRANSACTION }).start(done);
+});

packages/core/src/metrics/aggregator.ts

@@ -8,6 +8,7 @@ import type {
 import { timestampInSeconds } from '@sentry/utils';
 import { DEFAULT_FLUSH_INTERVAL, MAX_WEIGHT, NAME_AND_TAG_KEY_NORMALIZATION_REGEX } from './constants';
 import { METRIC_MAP } from './instance';
+import { updateMetricSummaryOnActiveSpan } from './metric-summary';
 import type { MetricBucket, MetricType } from './types';
 import { getBucketKey, sanitizeTags } from './utils';
 
@@ -62,7 +63,11 @@ export class MetricsAggregator implements MetricsAggregatorBase {
     const tags = sanitizeTags(unsanitizedTags);
 
     const bucketKey = getBucketKey(metricType, name, unit, tags);
+
     let bucketItem = this._buckets.get(bucketKey);
+    // If this is a set metric, we need to calculate the delta from the previous weight.
+    const previousWeight = bucketItem && metricType === 's' ? bucketItem.metric.weight : 0;
+
     if (bucketItem) {
       bucketItem.metric.add(value);
       // TODO(abhi): Do we need this check?
@@ -82,6 +87,10 @@ export class MetricsAggregator implements MetricsAggregatorBase {
       this._buckets.set(bucketKey, bucketItem);
     }
 
+    // If value is a string, it's a set metric so calculate the delta from the previous weight.
+    const val = typeof value === 'string' ? bucketItem.metric.weight - previousWeight : value;
+    updateMetricSummaryOnActiveSpan(metricType, name, val, unit, unsanitizedTags, bucketKey);
+
     // We need to keep track of the total weight of the buckets so that we can
     // flush them when we exceed the max weight.
     this._bucketsTotalWeight += bucketItem.metric.weight;

packages/core/src/metrics/browser-aggregator.ts

@@ -1,14 +1,8 @@
-import type {
-  Client,
-  ClientOptions,
-  MeasurementUnit,
-  MetricBucketItem,
-  MetricsAggregator,
-  Primitive,
-} from '@sentry/types';
+import type { Client, ClientOptions, MeasurementUnit, MetricsAggregator, Primitive } from '@sentry/types';
 import { timestampInSeconds } from '@sentry/utils';
 import { DEFAULT_BROWSER_FLUSH_INTERVAL, NAME_AND_TAG_KEY_NORMALIZATION_REGEX } from './constants';
 import { METRIC_MAP } from './instance';
+import { updateMetricSummaryOnActiveSpan } from './metric-summary';
 import type { MetricBucket, MetricType } from './types';
 import { getBucketKey, sanitizeTags } from './utils';
 
@@ -46,24 +40,33 @@ export class BrowserMetricsAggregator implements MetricsAggregator {
     const tags = sanitizeTags(unsanitizedTags);
 
     const bucketKey = getBucketKey(metricType, name, unit, tags);
-    const bucketItem: MetricBucketItem | undefined = this._buckets.get(bucketKey);
+
+    let bucketItem = this._buckets.get(bucketKey);
+    // If this is a set metric, we need to calculate the delta from the previous weight.
+    const previousWeight = bucketItem && metricType === 's' ? bucketItem.metric.weight : 0;
+
     if (bucketItem) {
       bucketItem.metric.add(value);
       // TODO(abhi): Do we need this check?
       if (bucketItem.timestamp < timestamp) {
         bucketItem.timestamp = timestamp;
       }
     } else {
-      this._buckets.set(bucketKey, {
+      bucketItem = {
         // @ts-expect-error we don't need to narrow down the type of value here, saves bundle size.
         metric: new METRIC_MAP[metricType](value),
         timestamp,
         metricType,
         name,
         unit,
         tags,
-      });
+      };
+      this._buckets.set(bucketKey, bucketItem);
     }
+
+    // If value is a string, it's a set metric so calculate the delta from the previous weight.
+    const val = typeof value === 'string' ? bucketItem.metric.weight - previousWeight : value;
+    updateMetricSummaryOnActiveSpan(metricType, name, val, unit, unsanitizedTags, bucketKey);
   }
 
   /**

packages/core/src/metrics/metric-summary.ts

@@ -0,0 +1,88 @@
+import type { MeasurementUnit, MetricSummaryAggregator as MetricSummaryAggregatorInterface } from '@sentry/types';
+import type { MetricSummary } from '@sentry/types';
+import type { Primitive } from '@sentry/types';
+import { dropUndefinedKeys } from '@sentry/utils';
+import { getActiveSpan } from '../tracing';
+
+/**
+ * Updates the metric summary on the currently active span
+ */
+export function updateMetricSummaryOnActiveSpan(
+  metricType: 'c' | 'g' | 's' | 'd',
+  sanitizedName: string,
+  value: number,
+  unit: MeasurementUnit,
+  tags: Record<string, Primitive>,
+  bucketKey: string,
+): void {
+  const span = getActiveSpan();
+  if (span) {
+    const summary = span.getMetricSummary() || new MetricSummaryAggregator();
+    summary.add(metricType, sanitizedName, value, unit, tags, bucketKey);
+    span.setMetricSummary(summary);
+  }
+}
+
+/**
+ * Summaries metrics for spans
+ */
+class MetricSummaryAggregator implements MetricSummaryAggregatorInterface {
+  /**
+   * key: bucketKey
+   * value: [exportKey, MetricSpanSummary]
+   */
+  private readonly _measurements: Map<string, [string, MetricSummary]>;
+
+  public constructor() {
+    this._measurements = new Map<string, [string, MetricSummary]>();
+  }
+
+  /** @inheritdoc */
+  public add(
+    metricType: 'c' | 'g' | 's' | 'd',
+    sanitizedName: string,
+    value: number,
+    unit: MeasurementUnit,
+    tags: Record<string, Primitive>,
+    bucketKey: string,
+  ): void {
+    const exportKey = `${metricType}:${sanitizedName}@${unit}`;
+    const bucketItem = this._measurements.get(bucketKey);
+
+    if (bucketItem) {
+      const [, summary] = bucketItem;
+      this._measurements.set(bucketKey, [
+        exportKey,
+        {
+          min: Math.min(summary.min, value),
+          max: Math.max(summary.max, value),
+          count: (summary.count += 1),
+          sum: (summary.sum += value),
+          tags: summary.tags,
+        },
+      ]);
+    } else {
+      this._measurements.set(bucketKey, [
+        exportKey,
+        {
+          min: value,
+          max: value,
+          count: 1,
+          sum: value,
+          tags,
+        },
+      ]);
+    }
+  }
+
+  /** @inheritdoc */
+  public getJson(): Record<string, MetricSummary> {
+    const output: Record<string, MetricSummary> = {};
+
+    for (const [, [exportKey, summary]] of this._measurements) {
+      output[exportKey] = dropUndefinedKeys(summary);
+    }
+
+    return output;
+  }
+}

packages/core/src/tracing/span.ts

@@ -1,6 +1,7 @@
 /* eslint-disable max-lines */
 import type {
   Instrumenter,
+  MetricSummaryAggregator,
   Primitive,
   Span as SpanInterface,
   SpanAttributeValue,
@@ -114,6 +115,7 @@ export class Span implements SpanInterface {
   protected _endTime?: number;
   /** Internal keeper of the status */
   protected _status?: SpanStatusType | string;
+  protected _metricSummary: MetricSummaryAggregator | undefined;
 
   private _logMessage?: string;
 
@@ -602,6 +604,16 @@ export class Span implements SpanInterface {
     return spanToTraceContext(this);
   }
 
+  /** @inheritdoc */
+  public getMetricSummary(): MetricSummaryAggregator | undefined {
+    return this._metricSummary;
+  }
+
+  /** @inheritdoc */
+  public setMetricSummary(metricSummary: MetricSummaryAggregator): void {
+    this._metricSummary = metricSummary;
+  }
+
   /**
    * Get JSON representation of this span.
    *
@@ -624,6 +636,7 @@ export class Span implements SpanInterface {
       timestamp: this._endTime,
       trace_id: this._traceId,
       origin: this._attributes[SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN] as SpanOrigin | undefined,
+      _metrics_summary: this._metricSummary ? this._metricSummary.getJson() : undefined,
     });
   }
 

packages/core/src/tracing/transaction.ts

@@ -333,6 +333,10 @@ export class Transaction extends SpanClass implements TransactionInterface {
       }),
     };
 
+    if (this._metricSummary) {
+      transaction._metrics_summary = this._metricSummary.getJson();
+    }
+
     const hasMeasurements = Object.keys(this._measurements).length > 0;
 
     if (hasMeasurements) {

packages/types/src/event.ts

@@ -11,7 +11,7 @@ import type { Request } from './request';
 import type { CaptureContext } from './scope';
 import type { SdkInfo } from './sdkinfo';
 import type { Severity, SeverityLevel } from './severity';
-import type { Span, SpanJSON } from './span';
+import type { MetricSummary, Span, SpanJSON } from './span';
 import type { Thread } from './thread';
 import type { TransactionSource } from './transaction';
 import type { User } from './user';
@@ -73,6 +73,7 @@ export interface ErrorEvent extends Event {
 }
 export interface TransactionEvent extends Event {
   type: 'transaction';
+  _metrics_summary?: Record<string, MetricSummary>;
 }
 
 /** JSDoc */

packages/types/src/index.ts

@@ -99,6 +99,7 @@ export type {
   SpanJSON,
   SpanContextData,
   TraceFlag,
+  MetricSummary,
 } from './span';
 export type { StackFrame } from './stackframe';
 export type { Stacktrace, StackParser, StackLineParser, StackLineParserFn } from './stacktrace';
@@ -150,5 +151,10 @@ export type {
 
 export type { BrowserClientReplayOptions, BrowserClientProfilingOptions } from './browseroptions';
 export type { CheckIn, MonitorConfig, FinishedCheckIn, InProgressCheckIn, SerializedCheckIn } from './checkin';
-export type { MetricsAggregator, MetricBucketItem, MetricInstance } from './metrics';
+export type {
+  MetricsAggregator,
+  MetricBucketItem,
+  MetricInstance,
+  MetricSummaryAggregator,
+} from './metrics';
 export type { ParameterizedString } from './parameterize';

packages/types/src/metrics.ts

@@ -1,5 +1,6 @@
 import type { MeasurementUnit } from './measurement';
 import type { Primitive } from './misc';
+import type { MetricSummary } from './span';
 
 /**
  * An abstract definition of the minimum required API
@@ -62,3 +63,18 @@ export interface MetricsAggregator {
    */
   toString(): string;
 }
+
+export interface MetricSummaryAggregator {
+  /** Adds a metric to the summary */
+  add(
+    metricType: 'c' | 'g' | 's' | 'd',
+    sanitizedName: string,
+    value: number,
+    unit: MeasurementUnit,
+    tags: Record<string, Primitive>,
+    bucketKey: string,
+  ): void;
+
+  /** Gets the JSON representation of the metric summary */
+  getJson(): Record<string, MetricSummary>;
+}