feat(browser): Add ingest_settings to v2 metrics envelope payload (#20454)

Adds `version: 2` and `ingest_settings` to the metrics envelope payload
so Relay can infer the end-user IP address and User-Agent from the
incoming request ([link to
spec](https://develop.sentry.dev/sdk/telemetry/logs/#wire-format)). This
is only emitted by browser SDKs.

Both settings are gated behind `sendDefaultPii` (modeled after how
`event.sdk.settings.infer_ip` works today).

Closes #20276

Author: nicohrubec

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

@@ -27,6 +27,8 @@ sentryTest('should capture all metric types', async ({ getLocalTestUrl, page })
       content_type: 'application/vnd.sentry.items.trace-metric+json',
     },
     {
+      version: 2,
+      ingest_settings: { infer_ip: 'never', infer_user_agent: 'never' },
       items: [
         {
           timestamp: expect.any(Number),

dev-packages/node-core-integration-tests/suites/light-mode/metrics/test.ts

@@ -11,6 +11,7 @@ describe('light mode metrics', () => {
       .unignore('trace_metric')
       .expect({
         trace_metric: {
+          version: 2,
           items: [
             {
               timestamp: expect.any(Number),

dev-packages/node-core-integration-tests/suites/public-api/metrics/test.ts

@@ -11,6 +11,7 @@ describe('metrics', () => {
       .unignore('trace_metric')
       .expect({
         trace_metric: {
+          version: 2,
           items: [
             {
               timestamp: expect.any(Number),

dev-packages/node-integration-tests/suites/public-api/metrics/server-address-option/test.ts

@@ -10,6 +10,7 @@ describe('metrics server.address', () => {
     const runner = createRunner(__dirname, 'scenario.ts')
       .expect({
         trace_metric: {
+          version: 2,
           items: [
             {
               timestamp: expect.any(Number),

dev-packages/node-integration-tests/suites/public-api/metrics/server-address/test.ts

@@ -10,6 +10,7 @@ describe('metrics server.address', () => {
     const runner = createRunner(__dirname, 'scenario.ts')
       .expect({
         trace_metric: {
+          version: 2,
           items: [
             {
               timestamp: expect.any(Number),

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

@@ -10,6 +10,7 @@ describe('metrics', () => {
     const runner = createRunner(__dirname, 'scenario.ts')
       .expect({
         trace_metric: {
+          version: 2,
           items: [
             {
               timestamp: expect.any(Number),

packages/core/src/metrics/envelope.ts

@@ -4,21 +4,32 @@ import type { SerializedMetric } from '../types-hoist/metric';
 import type { SdkMetadata } from '../types-hoist/sdkmetadata';
 import { dsnToString } from '../utils/dsn';
 import { createEnvelope } from '../utils/envelope';
+import { isBrowser } from '../utils/isBrowser';
 
 /**
  * Creates a metric container envelope item for a list of metrics.
  *
  * @param items - The metrics to include in the envelope.
+ * @param inferUserData - If true, tells Relay to infer the end-user IP and User-Agent from the incoming request.
+ *                        Only emitted as `ingest_settings` in browser environments.
  * @returns The created metric container envelope item.
  */
-export function createMetricContainerEnvelopeItem(items: Array<SerializedMetric>): MetricContainerItem {
+export function createMetricContainerEnvelopeItem(
+  items: Array<SerializedMetric>,
+  inferUserData?: boolean,
+): MetricContainerItem {
+  const inferSetting = inferUserData ? 'auto' : 'never';
   return [
     {
       type: 'trace_metric',
       item_count: items.length,
       content_type: 'application/vnd.sentry.items.trace-metric+json',
     } as MetricContainerItem[0],
     {
+      version: 2,
+      ...(isBrowser() && {
+        ingest_settings: { infer_ip: inferSetting, infer_user_agent: inferSetting },
+      }),
       items,
     },
   ];
@@ -33,13 +44,15 @@ export function createMetricContainerEnvelopeItem(items: Array<SerializedMetric>
  * @param metadata - The metadata to include in the envelope.
  * @param tunnel - The tunnel to include in the envelope.
  * @param dsn - The DSN to include in the envelope.
+ * @param inferUserData - If true, tells Relay to infer the end-user IP and User-Agent from the incoming request.
  * @returns The created envelope.
  */
 export function createMetricEnvelope(
   metrics: Array<SerializedMetric>,
   metadata?: SdkMetadata,
   tunnel?: string,
   dsn?: DsnComponents,
+  inferUserData?: boolean,
 ): MetricEnvelope {
   const headers: MetricEnvelope[0] = {};
 
@@ -54,5 +67,5 @@ export function createMetricEnvelope(
     headers.dsn = dsnToString(dsn);
   }
 
-  return createEnvelope<MetricEnvelope>(headers, [createMetricContainerEnvelopeItem(metrics)]);
+  return createEnvelope<MetricEnvelope>(headers, [createMetricContainerEnvelopeItem(metrics, inferUserData)]);
 }

packages/core/src/metrics/internal.ts

@@ -225,7 +225,13 @@ export function _INTERNAL_flushMetricsBuffer(client: Client, maybeMetricBuffer?:
   }
 
   const clientOptions = client.getOptions();
-  const envelope = createMetricEnvelope(metricBuffer, clientOptions._metadata, clientOptions.tunnel, client.getDsn());
+  const envelope = createMetricEnvelope(
+    metricBuffer,
+    clientOptions._metadata,
+    clientOptions.tunnel,
+    client.getDsn(),
+    clientOptions.sendDefaultPii,
+  );
 
   // Clear the metric buffer after envelopes have been constructed.
   _getBufferMap().set(client, []);

packages/core/src/types-hoist/metric.ts

@@ -77,5 +77,10 @@ export interface SerializedMetric {
 }
 
 export type SerializedMetricContainer = {
+  version?: number;
+  ingest_settings?: {
+    infer_ip?: 'auto' | 'never';
+    infer_user_agent?: 'auto' | 'never';
+  };
   items: Array<SerializedMetric>;
 };

packages/core/test/lib/metrics/envelope.test.ts

@@ -5,16 +5,24 @@ import type { SerializedMetric } from '../../../src/types-hoist/metric';
 import type { SdkMetadata } from '../../../src/types-hoist/sdkmetadata';
 import * as utilsDsn from '../../../src/utils/dsn';
 import * as utilsEnvelope from '../../../src/utils/envelope';
+import { isBrowser } from '../../../src/utils/isBrowser';
 
 vi.mock('../../../src/utils/dsn', () => ({
   dsnToString: vi.fn(dsn => `https://${dsn.publicKey}@${dsn.host}/`),
 }));
 vi.mock('../../../src/utils/envelope', () => ({
   createEnvelope: vi.fn((_headers, items) => [_headers, items]),
 }));
+vi.mock('../../../src/utils/isBrowser', () => ({
+  isBrowser: vi.fn(() => false),
+}));
+
+afterEach(() => {
+  vi.mocked(isBrowser).mockReturnValue(false);
+});
 
 describe('createMetricContainerEnvelopeItem', () => {
-  it('creates an envelope item with correct structure', () => {
+  it('emits version: 2 without ingest_settings when not in browser', () => {
     const mockMetric: SerializedMetric = {
       timestamp: 1713859200,
       trace_id: '3d9355f71e9c444b81161599adac6e29',
@@ -26,15 +34,63 @@ describe('createMetricContainerEnvelopeItem', () => {
       attributes: {},
     };
 
-    const result = createMetricContainerEnvelopeItem([mockMetric, mockMetric]);
+    const result = createMetricContainerEnvelopeItem([mockMetric], true);
 
-    expect(result).toHaveLength(2);
     expect(result[0]).toEqual({
       type: 'trace_metric',
-      item_count: 2,
+      item_count: 1,
       content_type: 'application/vnd.sentry.items.trace-metric+json',
     });
-    expect(result[1]).toEqual({ items: [mockMetric, mockMetric] });
+    expect(result[1]).toEqual({
+      version: 2,
+      items: [mockMetric],
+    });
+  });
+
+  it("includes ingest_settings with 'auto' values when in browser and inferUserData is true", () => {
+    vi.mocked(isBrowser).mockReturnValue(true);
+
+    const mockMetric: SerializedMetric = {
+      timestamp: 1713859200,
+      trace_id: '3d9355f71e9c444b81161599adac6e29',
+      span_id: '8b5f5e5e5e5e5e5e',
+      name: 'test.metric',
+      type: 'counter',
+      value: 1,
+      unit: 'count',
+      attributes: {},
+    };
+
+    const result = createMetricContainerEnvelopeItem([mockMetric], true);
+
+    expect(result[1]).toEqual({
+      version: 2,
+      ingest_settings: { infer_ip: 'auto', infer_user_agent: 'auto' },
+      items: [mockMetric],
+    });
+  });
+
+  it("includes ingest_settings with 'never' values when in browser and inferUserData is false", () => {
+    vi.mocked(isBrowser).mockReturnValue(true);
+
+    const mockMetric: SerializedMetric = {
+      timestamp: 1713859200,
+      trace_id: '3d9355f71e9c444b81161599adac6e29',
+      span_id: '8b5f5e5e5e5e5e5e',
+      name: 'test.metric',
+      type: 'counter',
+      value: 1,
+      unit: 'count',
+      attributes: {},
+    };
+
+    const result = createMetricContainerEnvelopeItem([mockMetric], false);
+
+    expect(result[1]).toEqual({
+      version: 2,
+      ingest_settings: { infer_ip: 'never', infer_user_agent: 'never' },
+      items: [mockMetric],
+    });
   });
 });
 
@@ -165,7 +221,7 @@ describe('createMetricEnvelope', () => {
       expect.arrayContaining([
         expect.arrayContaining([
           { type: 'trace_metric', item_count: 2, content_type: 'application/vnd.sentry.items.trace-metric+json' },
-          { items: mockMetrics },
+          { version: 2, items: mockMetrics },
         ]),
       ]),
     );