feat(core): Allow metrics aggregator per client (#10949)

This PR adds the ability to override the client used for metrics rather
than being tied to using the single client `getClient()` returns.

```ts
Sentry.metrics.increment('counter', 1, { client });
```

It also adds a `getMetricsAggregatorForClient` exported function which
is required so the Electron SDK can access the current aggregator.

`sendEnvelope` was added to the `Client` type so that all usages of
`BaseClient<ClientOptions>` could be replaced with `Client`.

Author: timfish

packages/core/src/baseclient.ts

@@ -534,7 +534,7 @@ export abstract class BaseClient<O extends ClientOptions> implements Client<O> {
   /**
    * @inheritdoc
    */
-  public sendEnvelope(envelope: Envelope): PromiseLike<TransportMakeRequestResponse> | void {
+  public sendEnvelope(envelope: Envelope): PromiseLike<TransportMakeRequestResponse> {
     this.emit('beforeEnvelope', envelope);
 
     if (this._isEnabled() && this._transport) {
@@ -545,6 +545,8 @@ export abstract class BaseClient<O extends ClientOptions> implements Client<O> {
     }
 
     DEBUG_BUILD && logger.error('Transport disabled');
+
+    return resolvedSyncPromise({});
   }
 
   /* eslint-enable @typescript-eslint/unified-signatures */

packages/core/src/metrics/aggregator.ts

@@ -1,11 +1,5 @@
-import type {
-  ClientOptions,
-  MeasurementUnit,
-  MetricsAggregator as MetricsAggregatorBase,
-  Primitive,
-} from '@sentry/types';
+import type { Client, MeasurementUnit, MetricsAggregator as MetricsAggregatorBase, Primitive } from '@sentry/types';
 import { timestampInSeconds } from '@sentry/utils';
-import type { BaseClient } from '../baseclient';
 import { DEFAULT_FLUSH_INTERVAL, MAX_WEIGHT, NAME_AND_TAG_KEY_NORMALIZATION_REGEX, SET_METRIC_TYPE } from './constants';
 import { captureAggregateMetrics } from './envelope';
 import { METRIC_MAP } from './instance';
@@ -40,7 +34,7 @@ export class MetricsAggregator implements MetricsAggregatorBase {
   // Force flush is used on either shutdown, flush() or when we exceed the max weight.
   private _forceFlush: boolean;
 
-  public constructor(private readonly _client: BaseClient<ClientOptions>) {
+  public constructor(private readonly _client: Client) {
     this._buckets = new Map();
     this._bucketsTotalWeight = 0;
     this._interval = setInterval(() => this._flush(), DEFAULT_FLUSH_INTERVAL);

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

@@ -1,6 +1,5 @@
-import type { ClientOptions, MeasurementUnit, MetricsAggregator, Primitive } from '@sentry/types';
+import type { Client, MeasurementUnit, MetricsAggregator, Primitive } from '@sentry/types';
 import { timestampInSeconds } from '@sentry/utils';
-import type { BaseClient } from '../baseclient';
 import { DEFAULT_BROWSER_FLUSH_INTERVAL, NAME_AND_TAG_KEY_NORMALIZATION_REGEX, SET_METRIC_TYPE } from './constants';
 import { captureAggregateMetrics } from './envelope';
 import { METRIC_MAP } from './instance';
@@ -21,7 +20,7 @@ export class BrowserMetricsAggregator implements MetricsAggregator {
   private _buckets: MetricBucket;
   private readonly _interval: ReturnType<typeof setInterval>;
 
-  public constructor(private readonly _client: BaseClient<ClientOptions>) {
+  public constructor(private readonly _client: Client) {
     this._buckets = new Map();
     this._interval = setInterval(() => this.flush(), DEFAULT_BROWSER_FLUSH_INTERVAL);
   }

packages/core/src/metrics/envelope.ts

@@ -1,22 +1,11 @@
-import type {
-  ClientOptions,
-  DsnComponents,
-  MetricBucketItem,
-  SdkMetadata,
-  StatsdEnvelope,
-  StatsdItem,
-} from '@sentry/types';
+import type { Client, DsnComponents, MetricBucketItem, SdkMetadata, StatsdEnvelope, StatsdItem } from '@sentry/types';
 import { createEnvelope, dsnToString, logger } from '@sentry/utils';
-import type { BaseClient } from '../baseclient';
 import { serializeMetricBuckets } from './utils';
 
 /**
  * Captures aggregated metrics to the supplied client.
  */
-export function captureAggregateMetrics(
-  client: BaseClient<ClientOptions>,
-  metricBucketItems: Array<MetricBucketItem>,
-): void {
+export function captureAggregateMetrics(client: Client, metricBucketItems: Array<MetricBucketItem>): void {
   logger.log(`Flushing aggregated metrics, number of metrics: ${metricBucketItems.length}`);
   const dsn = client.getDsn();
   const metadata = client.getSdkMetadata();

packages/core/src/metrics/exports-default.ts

@@ -1,3 +1,4 @@
+import type { Client, MetricsAggregator as MetricsAggregatorInterface } from '@sentry/types';
 import { MetricsAggregator } from './aggregator';
 import type { MetricData } from './exports';
 import { metrics as metricsCore } from './exports';
@@ -38,9 +39,20 @@ function gauge(name: string, value: number, data?: MetricData): void {
   metricsCore.gauge(MetricsAggregator, name, value, data);
 }
 
+/**
+ * Returns the metrics aggregator for a given client.
+ */
+function getMetricsAggregatorForClient(client: Client): MetricsAggregatorInterface {
+  return metricsCore.getMetricsAggregatorForClient(client, MetricsAggregator);
+}
+
 export const metricsDefault = {
   increment,
   distribution,
   set,
   gauge,
+  /**
+   * @ignore This is for internal use only.
+   */
+  getMetricsAggregatorForClient,
 };

packages/core/src/metrics/exports.ts

@@ -1,11 +1,10 @@
 import type {
-  ClientOptions,
+  Client,
   MeasurementUnit,
   MetricsAggregator as MetricsAggregatorInterface,
   Primitive,
 } from '@sentry/types';
 import { logger } from '@sentry/utils';
-import type { BaseClient } from '../baseclient';
 import { getCurrentScope } from '../currentScopes';
 import { getClient } from '../currentScopes';
 import { DEBUG_BUILD } from '../debug-build';
@@ -17,18 +16,43 @@ export interface MetricData {
   unit?: MeasurementUnit;
   tags?: Record<string, Primitive>;
   timestamp?: number;
+  client?: Client;
 }
 
 type MetricsAggregatorConstructor = {
-  new (client: BaseClient<ClientOptions>): MetricsAggregatorInterface;
+  new (client: Client): MetricsAggregatorInterface;
 };
 
 /**
- * Global metrics aggregator instance.
- *
- * This is initialized on the first call to any `Sentry.metric.*` method.
+ * A metrics aggregator instance per Client.
  */
-let globalMetricsAggregator: MetricsAggregatorInterface | undefined;
+let globalMetricsAggregators: WeakMap<Client, MetricsAggregatorInterface> | undefined;
+
+/**
+ * Gets the metrics aggregator for a given client.
+ * @param client The client for which to get the metrics aggregator.
+ * @param Aggregator Optional metrics aggregator class to use to create an aggregator if one does not exist.
+ */
+function getMetricsAggregatorForClient(
+  client: Client,
+  Aggregator: MetricsAggregatorConstructor,
+): MetricsAggregatorInterface {
+  if (!globalMetricsAggregators) {
+    globalMetricsAggregators = new WeakMap();
+  }
+
+  const aggregator = globalMetricsAggregators.get(client);
+  if (aggregator) {
+    return aggregator;
+  }
+
+  const newAggregator = new Aggregator(client);
+  client.on('flush', () => newAggregator.flush());
+  client.on('close', () => newAggregator.close());
+  globalMetricsAggregators.set(client, newAggregator);
+
+  return newAggregator;
+}
 
 function addToMetricsAggregator(
   Aggregator: MetricsAggregatorConstructor,
@@ -37,38 +61,32 @@ function addToMetricsAggregator(
   value: number | string,
   data: MetricData | undefined = {},
 ): void {
-  const client = getClient<BaseClient<ClientOptions>>();
+  const client = data.client || getClient<Client>();
+
   if (!client) {
     return;
   }
 
-  if (!globalMetricsAggregator) {
-    const aggregator = (globalMetricsAggregator = new Aggregator(client));
-
-    client.on('flush', () => aggregator.flush());
-    client.on('close', () => aggregator.close());
+  const scope = getCurrentScope();
+  const { unit, tags, timestamp } = data;
+  const { release, environment } = client.getOptions();
+  // eslint-disable-next-line deprecation/deprecation
+  const transaction = scope.getTransaction();
+  const metricTags: Record<string, string> = {};
+  if (release) {
+    metricTags.release = release;
   }
-
-  if (client) {
-    const scope = getCurrentScope();
-    const { unit, tags, timestamp } = data;
-    const { release, environment } = client.getOptions();
-    // eslint-disable-next-line deprecation/deprecation
-    const transaction = scope.getTransaction();
-    const metricTags: Record<string, string> = {};
-    if (release) {
-      metricTags.release = release;
-    }
-    if (environment) {
-      metricTags.environment = environment;
-    }
-    if (transaction) {
-      metricTags.transaction = spanToJSON(transaction).description || '';
-    }
-
-    DEBUG_BUILD && logger.log(`Adding value of ${value} to ${metricType} metric ${name}`);
-    globalMetricsAggregator.add(metricType, name, value, unit, { ...metricTags, ...tags }, timestamp);
+  if (environment) {
+    metricTags.environment = environment;
+  }
+  if (transaction) {
+    metricTags.transaction = spanToJSON(transaction).description || '';
   }
+
+  DEBUG_BUILD && logger.log(`Adding value of ${value} to ${metricType} metric ${name}`);
+
+  const aggregator = getMetricsAggregatorForClient(client, Aggregator);
+  aggregator.add(metricType, name, value, unit, { ...metricTags, ...tags }, timestamp);
 }
 
 /**
@@ -112,4 +130,8 @@ export const metrics = {
   distribution,
   set,
   gauge,
+  /**
+   * @ignore This is for internal use only.
+   */
+  getMetricsAggregatorForClient,
 };

packages/types/src/client.ts

@@ -170,6 +170,9 @@ export interface Client<O extends ClientOptions = ClientOptions> {
   /** Submits the session to Sentry */
   sendSession(session: Session | SessionAggregates): void;
 
+  /** Sends an envelope to Sentry */
+  sendEnvelope(envelope: Envelope): PromiseLike<TransportMakeRequestResponse>;
+
   /**
    * Record on the client that an event got dropped (ie, an event that will not be sent to sentry).
    *