feat(core): Send user-agent header with envelope requests

Lms24 · Lms24 · commit 304d5acf3833 · 2025-10-14T16:54:26.000+02:00
diff --git a/dev-packages/browser-integration-tests/suites/transport/userAgent/init.js b/dev-packages/browser-integration-tests/suites/transport/userAgent/init.js
@@ -0,0 +1,12 @@
+import * as Sentry from '@sentry/browser';
+
+window.Sentry = Sentry;
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  transportOptions: {
+    headers: {
+      'x-custom-header': 'custom-value',
+    },
+  },
+});
diff --git a/dev-packages/browser-integration-tests/suites/transport/userAgent/subject.js b/dev-packages/browser-integration-tests/suites/transport/userAgent/subject.js
@@ -0,0 +1 @@
+Sentry.captureException(new Error('test'));
diff --git a/dev-packages/browser-integration-tests/suites/transport/userAgent/test.ts b/dev-packages/browser-integration-tests/suites/transport/userAgent/test.ts
@@ -0,0 +1,32 @@
+import { expect } from '@playwright/test';
+import { SDK_VERSION } from '@sentry/browser';
+import { sentryTest } from '../../../utils/fixtures';
+
+sentryTest('adds X-Sentry-User-Agent header to envelope requests', async ({ getLocalTestUrl, page }) => {
+  const url = await getLocalTestUrl({ testDir: __dirname });
+
+  const requestHeadersPromise = new Promise<Record<string, string>>(resolve => {
+    page.route('https://dsn.ingest.sentry.io/**/*', (route, request) => {
+      resolve(request.headers());
+      return route.fulfill({
+        status: 200,
+        body: JSON.stringify({}),
+      });
+    });
+  });
+
+  await page.goto(url);
+
+  const requestHeaders = await requestHeadersPromise;
+
+  expect(requestHeaders).toMatchObject({
+    // this is the browser's user-agent header (which we don't modify)
+    'user-agent': expect.any(String),
+
+    // this is the SDK's user-agent header (in browser)
+    'x-sentry-user-agent': `sentry.javascript.browser/${SDK_VERSION}`,
+
+    // this is a custom header users add via `transportOptions.headers`
+    'x-custom-header': 'custom-value',
+  });
+});
diff --git a/dev-packages/e2e-tests/test-applications/cloudflare-workers/tests/index.test.ts b/dev-packages/e2e-tests/test-applications/cloudflare-workers/tests/index.test.ts
@@ -1,5 +1,6 @@
 import { expect, test } from '@playwright/test';
-import { waitForError } from '@sentry-internal/test-utils';
+import { waitForError, waitForRequest } from '@sentry-internal/test-utils';
+import { SDK_VERSION } from '@sentry/cloudflare';
 import { WebSocket } from 'ws';
 
 test('Index page', async ({ baseURL }) => {
@@ -69,3 +70,15 @@ test('Websocket.webSocketClose', async ({ baseURL }) => {
   expect(event.exception?.values?.[0]?.value).toBe('Should be recorded in Sentry: webSocketClose');
   expect(event.exception?.values?.[0]?.mechanism?.type).toBe('auto.faas.cloudflare.durable_object');
 });
+
+test('sends user-agent header with SDK name and version in envelope requests', async ({ baseURL }) => {
+  const requestPromise = waitForRequest('cloudflare-workers', () => true);
+
+  await fetch(`${baseURL}/throwException`);
+
+  const request = await requestPromise;
+
+  expect(request.rawProxyRequestHeaders).toMatchObject({
+    'user-agent': `sentry.javascript.cloudflare/${SDK_VERSION}`,
+  });
+});
diff --git a/dev-packages/e2e-tests/test-applications/node-express/tests/misc.test.ts b/dev-packages/e2e-tests/test-applications/node-express/tests/misc.test.ts
@@ -0,0 +1,15 @@
+import { expect, test } from '@playwright/test';
+import { waitForRequest } from '@sentry-internal/test-utils';
+import { SDK_VERSION } from '@sentry/node';
+
+test('sends user-agent header with SDK name and version in envelope requests', async ({ baseURL }) => {
+  const requestPromise = waitForRequest('node-express', () => true);
+
+  await fetch(`${baseURL}/test-exception/123`);
+
+  const request = await requestPromise;
+
+  expect(request.rawProxyRequestHeaders).toMatchObject({
+    'user-agent': `sentry.javascript.node/${SDK_VERSION}`,
+  });
+});
diff --git a/dev-packages/test-utils/src/event-proxy-server.ts b/dev-packages/test-utils/src/event-proxy-server.ts
@@ -24,6 +24,7 @@ interface EventProxyServerOptions {
 interface SentryRequestCallbackData {
   envelope: Envelope;
   rawProxyRequestBody: string;
+  rawProxyRequestHeaders: Record<string, string | string[] | undefined>;
   rawSentryResponseBody: string;
   sentryResponseStatusCode?: number;
 }
@@ -182,6 +183,7 @@ export async function startEventProxyServer(options: EventProxyServerOptions): P
     const data: SentryRequestCallbackData = {
       envelope: parseEnvelope(proxyRequestBody),
       rawProxyRequestBody: proxyRequestBody,
+      rawProxyRequestHeaders: proxyRequest.headers,
       rawSentryResponseBody: '',
       sentryResponseStatusCode: 200,
     };
diff --git a/packages/browser/src/client.ts b/packages/browser/src/client.ts
@@ -13,6 +13,7 @@ import {
   _INTERNAL_flushLogsBuffer,
   _INTERNAL_flushMetricsBuffer,
   addAutoIpAddressToSession,
+  addUserAgentToTransportHeaders,
   applySdkMetadata,
   Client,
   getSDKSource,
@@ -97,6 +98,8 @@ export class BrowserClient extends Client<BrowserClientOptions> {
     const sdkSource = WINDOW.SENTRY_SDK_SOURCE || getSDKSource();
     applySdkMetadata(opts, 'browser', ['browser'], sdkSource);
 
+    addUserAgentToTransportHeaders(opts, 'x-Sentry-User-Agent');
+
     // Only allow IP inferral by Relay if sendDefaultPii is true
     if (opts._metadata?.sdk) {
       opts._metadata.sdk.settings = {
diff --git a/packages/browser/src/transports/types.ts b/packages/browser/src/transports/types.ts
@@ -3,6 +3,4 @@ import type { BaseTransportOptions } from '@sentry/core';
 export interface BrowserTransportOptions extends BaseTransportOptions {
   /** Fetch API init parameters. Used by the FetchTransport */
   fetchOptions?: RequestInit;
-  /** Custom headers for the transport. Used by the XHRTransport and FetchTransport */
-  headers?: { [key: string]: string };
 }
diff --git a/packages/browser/test/client.test.ts b/packages/browser/test/client.test.ts
@@ -3,7 +3,7 @@
  */
 
 import * as sentryCore from '@sentry/core';
-import { Scope } from '@sentry/core';
+import { Scope, SDK_VERSION } from '@sentry/core';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { applyDefaultOptions, BrowserClient } from '../src/client';
 import { WINDOW } from '../src/helpers';
@@ -289,3 +289,33 @@ describe('SDK metadata', () => {
     });
   });
 });
+
+describe('user agent header', () => {
+  it('adds X-Sentry-User-Agent header to transport options', () => {
+    const options = getDefaultBrowserClientOptions({});
+    const client = new BrowserClient(options);
+
+    expect(client.getOptions().transportOptions?.headers).toEqual({
+      'x-Sentry-User-Agent': `sentry.javascript.browser/${SDK_VERSION}`,
+    });
+  });
+
+  it('respects user-passed headers', () => {
+    const options = getDefaultBrowserClientOptions({
+      transportOptions: {
+        headers: {
+          'x-custom-header': 'custom-value',
+          'x-Sentry-User-Agent': 'custom-user-agent',
+          'user-agent': 'custom-user-agent-2',
+        },
+      },
+    });
+    const client = new BrowserClient(options);
+
+    expect(client.getOptions().transportOptions?.headers).toEqual({
+      'x-custom-header': 'custom-value',
+      'x-Sentry-User-Agent': 'custom-user-agent',
+      'user-agent': 'custom-user-agent-2',
+    });
+  });
+});
diff --git a/packages/bun/src/transports/index.ts b/packages/bun/src/transports/index.ts
@@ -1,15 +1,10 @@
 import type { BaseTransportOptions, Transport, TransportMakeRequestResponse, TransportRequest } from '@sentry/core';
 import { createTransport, suppressTracing } from '@sentry/core';
 
-export interface BunTransportOptions extends BaseTransportOptions {
-  /** Custom headers for the transport. Used by the XHRTransport and FetchTransport */
-  headers?: { [key: string]: string };
-}
-
 /**
  * Creates a Transport that uses the Fetch API to send events to Sentry.
  */
-export function makeFetchTransport(options: BunTransportOptions): Transport {
+export function makeFetchTransport(options: BaseTransportOptions): Transport {
   function makeRequest(request: TransportRequest): PromiseLike<TransportMakeRequestResponse> {
     const requestOptions: RequestInit = {
       body: request.body,
diff --git a/packages/bun/src/types.ts b/packages/bun/src/types.ts
@@ -1,5 +1,4 @@
-import type { ClientOptions, Options, TracePropagationTargets } from '@sentry/core';
-import type { BunTransportOptions } from './transports';
+import type { BaseTransportOptions, ClientOptions, Options, TracePropagationTargets } from '@sentry/core';
 
 export interface BaseBunOptions {
   /**
@@ -43,10 +42,10 @@ export interface BaseBunOptions {
  * Configuration options for the Sentry Bun SDK
  * @see @sentry/core Options for more information.
  */
-export interface BunOptions extends Options<BunTransportOptions>, BaseBunOptions {}
+export interface BunOptions extends Options<BaseTransportOptions>, BaseBunOptions {}
 
 /**
  * Configuration options for the Sentry Bun SDK Client class
  * @see BunClient for more information.
  */
-export interface BunClientOptions extends ClientOptions<BunTransportOptions>, BaseBunOptions {}
+export interface BunClientOptions extends ClientOptions<BaseTransportOptions>, BaseBunOptions {}
diff --git a/packages/cloudflare/src/transport.ts b/packages/cloudflare/src/transport.ts
@@ -4,8 +4,6 @@ import { createTransport, SENTRY_BUFFER_FULL_ERROR, suppressTracing } from '@sen
 export interface CloudflareTransportOptions extends BaseTransportOptions {
   /** Fetch API init parameters. */
   fetchOptions?: RequestInit;
-  /** Custom headers for the transport. */
-  headers?: { [key: string]: string };
 }
 
 const DEFAULT_TRANSPORT_BUFFER_SIZE = 30;
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
@@ -4,6 +4,7 @@ export type { ClientClass as SentryCoreCurrentScopes } from './sdk';
 export type { AsyncContextStrategy } from './asyncContext/types';
 export type { Carrier } from './carrier';
 export type { OfflineStore, OfflineTransportOptions } from './transports/offline';
+export { addUserAgentToTransportHeaders } from './transports/userAgent';
 export type { ServerRuntimeClientOptions } from './server-runtime-client';
 export type { IntegrationIndex } from './integration';
 
diff --git a/packages/core/src/server-runtime-client.ts b/packages/core/src/server-runtime-client.ts
@@ -6,6 +6,7 @@ import { _INTERNAL_flushLogsBuffer } from './logs/internal';
 import { _INTERNAL_flushMetricsBuffer } from './metrics/internal';
 import type { Scope } from './scope';
 import { registerSpanErrorInstrumentation } from './tracing';
+import { addUserAgentToTransportHeaders } from './transports/userAgent';
 import type { CheckIn, MonitorConfig, SerializedCheckIn } from './types-hoist/checkin';
 import type { Event, EventHint } from './types-hoist/event';
 import type { Log } from './types-hoist/log';
@@ -49,6 +50,8 @@ export class ServerRuntimeClient<
     // Server clients always support tracing
     registerSpanErrorInstrumentation();
 
+    addUserAgentToTransportHeaders(options);
+
     super(options);
 
     this._logWeight = 0;
diff --git a/packages/core/src/transports/userAgent.ts b/packages/core/src/transports/userAgent.ts
@@ -0,0 +1,22 @@
+import type { ClientOptions } from '../types-hoist/options';
+
+/**
+ * Takes the SDK metadata and adds the user-agent header to the transport options.
+ * This ensures that the SDK sends the user-agent header with SDK name and version to
+ * all requests made by the transport.
+ *
+ * @see https://develop.sentry.dev/sdk/overview/#user-agent
+ */
+export function addUserAgentToTransportHeaders(options: ClientOptions, userAgentHeaderName = 'user-agent'): void {
+  const sdkMetadata = options._metadata?.sdk;
+  const sdkUserAgent =
+    sdkMetadata?.name && sdkMetadata?.version ? `${sdkMetadata?.name}/${sdkMetadata?.version}` : undefined;
+
+  options.transportOptions = {
+    ...options.transportOptions,
+    headers: {
+      ...(sdkUserAgent && { [userAgentHeaderName]: sdkUserAgent }),
+      ...options.transportOptions?.headers,
+    },
+  };
+}
diff --git a/packages/core/src/types-hoist/transport.ts b/packages/core/src/types-hoist/transport.ts
@@ -30,6 +30,11 @@ export interface BaseTransportOptions extends InternalBaseTransportOptions {
   // transport does not care about dsn specific - client should take care of
   // parsing and figuring that out
   url: string;
+
+  /**
+   * Custom headers to be added to requests made by the transport.
+   */
+  headers?: { [key: string]: string };
 }
 
 export interface Transport {
diff --git a/packages/core/test/lib/server-runtime-client.test.ts b/packages/core/test/lib/server-runtime-client.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it, test, vi } from 'vitest';
-import { createTransport, Scope } from '../../src';
+import { applySdkMetadata, createTransport, Scope } from '../../src';
 import { _INTERNAL_captureLog, _INTERNAL_flushLogsBuffer } from '../../src/logs/internal';
 import type { ServerRuntimeClientOptions } from '../../src/server-runtime-client';
 import { ServerRuntimeClient } from '../../src/server-runtime-client';
@@ -308,4 +308,35 @@ describe('ServerRuntimeClient', () => {
       expect(client['_logWeight']).toBe(0); // Weight should be reset after flush
     });
   });
+
+  describe('user-agent header', () => {
+    it('sends user-agent header with SDK name and version', () => {
+      const options = getDefaultClientOptions({ dsn: PUBLIC_DSN });
+
+      // this is done in all `init` functions of the respective SDKs:
+      applySdkMetadata(options, 'core');
+
+      client = new ServerRuntimeClient(options);
+
+      expect(client.getOptions().transportOptions?.headers).toEqual({
+        'user-agent': 'sentry.javascript.core/0.0.0-unknown.0',
+      });
+    });
+
+    it('prefers user-passed headers (including user-agent)', () => {
+      const options = getDefaultClientOptions({
+        dsn: PUBLIC_DSN,
+        transportOptions: { headers: { 'x-custom-header': 'custom-value', 'user-agent': 'custom-user-agent' } },
+      });
+
+      applySdkMetadata(options, 'core');
+
+      client = new ServerRuntimeClient(options);
+
+      expect(client.getOptions().transportOptions?.headers).toEqual({
+        'user-agent': 'custom-user-agent',
+        'x-custom-header': 'custom-value',
+      });
+    });
+  });
 });
diff --git a/packages/deno/src/transports/index.ts b/packages/deno/src/transports/index.ts
@@ -9,7 +9,7 @@ export interface DenoTransportOptions extends BaseTransportOptions {
 /**
  * Creates a Transport that uses the Fetch API to send events to Sentry.
  */
-export function makeFetchTransport(options: DenoTransportOptions): Transport {
+export function makeFetchTransport(options: BaseTransportOptions): Transport {
   const url = new URL(options.url);
 
   Deno.permissions
diff --git a/packages/deno/src/types.ts b/packages/deno/src/types.ts
@@ -1,5 +1,4 @@
-import type { ClientOptions, Options, TracePropagationTargets } from '@sentry/core';
-import type { DenoTransportOptions } from './transports';
+import type { BaseTransportOptions, ClientOptions, Options, TracePropagationTargets } from '@sentry/core';
 
 export interface BaseDenoOptions {
   /**
@@ -44,10 +43,10 @@ export interface BaseDenoOptions {
  * Configuration options for the Sentry Deno SDK
  * @see @sentry/core Options for more information.
  */
-export interface DenoOptions extends Options<DenoTransportOptions>, BaseDenoOptions {}
+export interface DenoOptions extends Options<BaseTransportOptions>, BaseDenoOptions {}
 
 /**
  * Configuration options for the Sentry Deno SDK Client class
  * @see DenoClient for more information.
  */
-export interface DenoClientOptions extends ClientOptions<DenoTransportOptions>, BaseDenoOptions {}
+export interface DenoClientOptions extends ClientOptions<BaseTransportOptions>, BaseDenoOptions {}
diff --git a/packages/node-core/src/transports/http.ts b/packages/node-core/src/transports/http.ts
@@ -14,8 +14,6 @@ import { HttpsProxyAgent } from '../proxy';
 import type { HTTPModule } from './http-module';
 
 export interface NodeTransportOptions extends BaseTransportOptions {
-  /** Define custom headers */
-  headers?: Record<string, string>;
   /** Set a proxy that should be used for outbound requests. */
   proxy?: string;
   /** HTTPS proxy CA certificates */
diff --git a/packages/vercel-edge/src/transports/index.ts b/packages/vercel-edge/src/transports/index.ts
@@ -4,8 +4,6 @@ import { createTransport, SENTRY_BUFFER_FULL_ERROR, suppressTracing } from '@sen
 export interface VercelEdgeTransportOptions extends BaseTransportOptions {
   /** Fetch API init parameters. */
   fetchOptions?: RequestInit;
-  /** Custom headers for the transport. */
-  headers?: { [key: string]: string };
 }
 
 const DEFAULT_TRANSPORT_BUFFER_SIZE = 30;

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+Sentry.captureException(new Error('test'));`
Original file line number	Diff line number	Diff line change
`@@ -3,6 +3,4 @@ import type { BaseTransportOptions } from '@sentry/core';`
`3`	`3`	`export interface BrowserTransportOptions extends BaseTransportOptions {`
`4`	`4`	`/** Fetch API init parameters. Used by the FetchTransport */`
`5`	`5`	`fetchOptions?: RequestInit;`
`6`		`- /** Custom headers for the transport. Used by the XHRTransport and FetchTransport */`
`7`		`- headers?: { [key: string]: string };`
`8`	`6`	`}`