feat(browser): Add ingest_settings to span v2 envelope payload (#20411)

Adds `version: 2` and `ingest_settings` to the span streaming 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/spans/span-protocol/#version-and-ingest_settings-properties)).
This is only emitted by the browser SDK.

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

Closes #20275

Author: nicohrubec

dev-packages/browser-integration-tests/suites/public-api/startSpan/streamed/test.ts

@@ -56,6 +56,8 @@ sentryTest(
       [
         { content_type: 'application/vnd.sentry.items.span.v2+json', item_count: 4, type: 'span' },
         {
+          version: 2,
+          ingest_settings: { infer_ip: 'never', infer_user_agent: 'never' },
           items: expect.any(Array),
         },
       ],

packages/core/src/tracing/spans/envelope.ts

@@ -3,6 +3,7 @@ import type { DynamicSamplingContext, SpanContainerItem, StreamedSpanEnvelope }
 import type { SerializedStreamedSpan } from '../../types-hoist/span';
 import { dsnToString } from '../../utils/dsn';
 import { createEnvelope, getSdkMetadataForEnvelopeHeader } from '../../utils/envelope';
+import { isBrowser } from '../../utils/isBrowser';
 
 /**
  * Creates a span v2 span streaming envelope
@@ -12,9 +13,10 @@ export function createStreamedSpanEnvelope(
   dsc: Partial<DynamicSamplingContext>,
   client: Client,
 ): StreamedSpanEnvelope {
+  const options = client.getOptions();
   const dsn = client.getDsn();
-  const tunnel = client.getOptions().tunnel;
-  const sdk = getSdkMetadataForEnvelopeHeader(client.getOptions()._metadata);
+  const tunnel = options.tunnel;
+  const sdk = getSdkMetadataForEnvelopeHeader(options._metadata);
 
   const headers: StreamedSpanEnvelope[0] = {
     sent_at: new Date().toISOString(),
@@ -23,9 +25,17 @@ export function createStreamedSpanEnvelope(
     ...(!!tunnel && dsn && { dsn: dsnToString(dsn) }),
   };
 
+  const inferSetting = options.sendDefaultPii ? 'auto' : 'never';
+
   const spanContainer: SpanContainerItem = [
     { type: 'span', item_count: serializedSpans.length, content_type: 'application/vnd.sentry.items.span.v2+json' },
-    { items: serializedSpans },
+    {
+      version: 2,
+      ...(isBrowser() && {
+        ingest_settings: { infer_ip: inferSetting, infer_user_agent: inferSetting },
+      }),
+      items: serializedSpans,
+    },
   ];
 
   return createEnvelope<StreamedSpanEnvelope>(headers, [spanContainer]);

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

@@ -69,6 +69,11 @@ export type SerializedStreamedSpan = Omit<StreamedSpanJSON, 'attributes' | 'link
  * Envelope span item container.
  */
 export type SerializedStreamedSpanContainer = {
+  version?: number;
+  ingest_settings?: {
+    infer_ip?: 'auto' | 'never';
+    infer_user_agent?: 'auto' | 'never';
+  };
   items: Array<SerializedStreamedSpan>;
 };
 

packages/core/test/lib/tracing/spans/envelope.test.ts

@@ -1,9 +1,18 @@
-import { describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import { createStreamedSpanEnvelope } from '../../../../src/tracing/spans/envelope';
 import type { DynamicSamplingContext } from '../../../../src/types-hoist/envelope';
 import type { SerializedStreamedSpan } from '../../../../src/types-hoist/span';
+import { isBrowser } from '../../../../src/utils/isBrowser';
 import { getDefaultTestClientOptions, TestClient } from '../../../mocks/client';
 
+vi.mock('../../../../src/utils/isBrowser', () => ({
+  isBrowser: vi.fn(() => false),
+}));
+
+afterEach(() => {
+  vi.mocked(isBrowser).mockReturnValue(false);
+});
+
 function createMockSerializedSpan(overrides: Partial<SerializedStreamedSpan> = {}): SerializedStreamedSpan {
   return {
     trace_id: 'abc123',
@@ -181,6 +190,7 @@ describe('createStreamedSpanEnvelope', () => {
             type: 'span',
           },
           {
+            version: 2,
             items: [mockSpan],
           },
         ],
@@ -199,7 +209,7 @@ describe('createStreamedSpanEnvelope', () => {
       expect(envelopeItems).toEqual([
         [
           { type: 'span', item_count: 3, content_type: 'application/vnd.sentry.items.span.v2+json' },
-          { items: [mockSpan1, mockSpan2, mockSpan3] },
+          { version: 2, items: [mockSpan1, mockSpan2, mockSpan3] },
         ],
       ]);
     });
@@ -222,11 +232,72 @@ describe('createStreamedSpanEnvelope', () => {
               type: 'span',
             },
             {
+              version: 2,
               items: [],
             },
           ],
         ],
       ]);
     });
+
+    it("includes ingest_settings with 'auto' values when in browser and sendDefaultPii is true", () => {
+      vi.mocked(isBrowser).mockReturnValue(true);
+
+      const mockSpan = createMockSerializedSpan();
+      const mockClient = new TestClient(getDefaultTestClientOptions({ sendDefaultPii: true }));
+      const dsc: Partial<DynamicSamplingContext> = {};
+
+      const envelopeItems = createStreamedSpanEnvelope([mockSpan], dsc, mockClient)[1];
+
+      expect(envelopeItems).toEqual([
+        [
+          { type: 'span', item_count: 1, content_type: 'application/vnd.sentry.items.span.v2+json' },
+          {
+            version: 2,
+            ingest_settings: { infer_ip: 'auto', infer_user_agent: 'auto' },
+            items: [mockSpan],
+          },
+        ],
+      ]);
+    });
+
+    it("includes ingest_settings with 'never' values when in browser and sendDefaultPii is false", () => {
+      vi.mocked(isBrowser).mockReturnValue(true);
+
+      const mockSpan = createMockSerializedSpan();
+      const mockClient = new TestClient(getDefaultTestClientOptions({ sendDefaultPii: false }));
+      const dsc: Partial<DynamicSamplingContext> = {};
+
+      const envelopeItems = createStreamedSpanEnvelope([mockSpan], dsc, mockClient)[1];
+
+      expect(envelopeItems).toEqual([
+        [
+          { type: 'span', item_count: 1, content_type: 'application/vnd.sentry.items.span.v2+json' },
+          {
+            version: 2,
+            ingest_settings: { infer_ip: 'never', infer_user_agent: 'never' },
+            items: [mockSpan],
+          },
+        ],
+      ]);
+    });
+
+    it('omits ingest_settings when not in browser', () => {
+      const mockSpan = createMockSerializedSpan();
+      const mockClient = new TestClient(getDefaultTestClientOptions({ sendDefaultPii: true }));
+      const dsc: Partial<DynamicSamplingContext> = {};
+
+      const envelopeItems = createStreamedSpanEnvelope([mockSpan], dsc, mockClient)[1];
+
+      expect(envelopeItems).toEqual([
+        [
+          { type: 'span', item_count: 1, content_type: 'application/vnd.sentry.items.span.v2+json' },
+          {
+            version: 2,
+            items: [mockSpan],
+          },
+        ],
+      ]);
+    });
   });
 });