Skip to content

feat(core): Export a reusable function to add tracing headers #20076

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JPeer264 merged 4 commits into from
Apr 9, 2026
+84 −48
Merged

feat(core): Export a reusable function to add tracing headers #20076

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
fb1e8a2
feat(core): Export a reusable function to add tracing headers
JPeer264 Apr 1, 2026
1622527
fixup! feat(core): Export a reusable function to add tracing headers
JPeer264 Apr 7, 2026
4e235e3
fixup! feat(core): Export a reusable function to add tracing headers
JPeer264 Apr 8, 2026
3d15dcf
feat: Loosen types and header check
JPeer264 Apr 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 15 additions & 9 deletions packages/core/src/fetch.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
type PolymorphicRequestHeaders =
| Record<string, string | undefined>
| Array<[string, string]>
| Iterable<Iterable<string>>
Copy link
Copy Markdown

@cursor cursor bot Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Accepted Iterable type lacks runtime handling in function

Low Severity

The new Iterable<Iterable<string>> variant was added to PolymorphicRequestHeaders, which is used as the type for fetchOptionsObj.headers. However, the function body only handles Headers instances (via isHeaders), arrays (via Array.isArray), and plain objects (the else branch). A non-array, non-Headers iterable (e.g. a Map) would silently fall into the else branch, where in operator checks and object spread would not correctly process the iterable's entries, producing malformed headers. Since this function is now exported for cross-package use, the type promises broader acceptance than the implementation supports.

Additional Locations (1)
Fix in Cursor Fix in Web

Copy link
Copy Markdown
Member Author

@JPeer264 JPeer264 Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This type is needed for Cloudflare headers. I've added a test to also check for that case.

// the below is not precisely the Header type used in Request, but it'll pass duck-typing
| {
append: (key: string, value: string) => void;
Expand Down Expand Up @@ -124,7 +125,7 @@
// Examples: users re-using same options object for multiple fetch calls, frozen objects
const options: { [key: string]: unknown } = { ...(handlerData.args[1] || {}) };

const headers = _addTracingHeadersToFetchRequest(
const headers = getTracingHeadersForFetchRequest(
request,
options,
// If performance is disabled (TWP) or there's no active root span (pageload/navigation/interaction),
Expand Down Expand Up @@ -176,17 +177,22 @@
}

/**
* Adds sentry-trace and baggage headers to the various forms of fetch headers.
* exported only for testing purposes
* Builds merged fetch headers that include `sentry-trace` and `baggage` (and optionally `traceparent`)
* for the given request and init, without mutating the original request or options.
* Returns `undefined` when there is no `sentry-trace` value to attach.
*
* When we determine if we should add a baggage header, there are 3 cases:
* 1. No previous baggage header -> add baggage
* 2. Previous baggage header has no sentry baggage values -> add our baggage
* 3. Previous baggage header has sentry baggage values -> do nothing (might have been added manually by users)
* @internal Exported for cross-package instrumentation (for example Cloudflare Workers fetcher bindings)
* and unit tests
* @hidden
Copy link
Copy Markdown
Member

@chargome chargome Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* @hidden

very logaf-L

*
* Baggage handling:
* 1. No previous baggage header → include Sentry baggage
* 2. Previous baggage has no Sentry entries → merge Sentry baggage in
* 3. Previous baggage already has Sentry entries → leave as-is (may be user-defined)
*/
// eslint-disable-next-line complexity -- yup it's this complicated :(
export function _addTracingHeadersToFetchRequest(
request: string | Request,
export function getTracingHeadersForFetchRequest(
request: string | URL | Request,
fetchOptionsObj: {
headers?:
| {
Expand Down Expand Up @@ -237,16 +243,16 @@
} else if (Array.isArray(originalHeaders)) {
const newHeaders = [...originalHeaders];

if (!originalHeaders.find(header => header[0] === 'sentry-trace')) {

Check failure on line 246 in packages/core/src/fetch.ts

View workflow job for this annotation

GitHub Actions / Lint

typescript-eslint(no-unsafe-member-access) 

Unsafe member access [0] on an `any` value.
newHeaders.push(['sentry-trace', sentryTrace]);
}

if (propagateTraceparent && traceparent && !originalHeaders.find(header => header[0] === 'traceparent')) {

Check failure on line 250 in packages/core/src/fetch.ts

View workflow job for this annotation

GitHub Actions / Lint

typescript-eslint(no-unsafe-member-access) 

Unsafe member access [0] on an `any` value.
newHeaders.push(['traceparent', traceparent]);
}

const prevBaggageHeaderWithSentryValues = originalHeaders.find(
header => header[0] === 'baggage' && baggageHeaderHasSentryBaggageValues(header[1]),

Check failure on line 255 in packages/core/src/fetch.ts

View workflow job for this annotation

GitHub Actions / Lint

typescript-eslint(no-unsafe-member-access) 

Unsafe member access [1] on an `any` value.

Check failure on line 255 in packages/core/src/fetch.ts

View workflow job for this annotation

GitHub Actions / Lint

typescript-eslint(no-unsafe-member-access) 

Unsafe member access [0] on an `any` value.
);

if (baggage && !prevBaggageHeaderWithSentryValues) {
Expand Down Expand Up @@ -282,7 +288,7 @@
baggage: string | undefined;
traceparent?: string;
} = {
...originalHeaders,

Check warning on line 291 in packages/core/src/fetch.ts

View workflow job for this annotation

GitHub Actions / Lint

typescript-eslint(no-misused-spread) 

Using the spread operator on an Iterable in an object can cause unexpected behavior.
'sentry-trace': (existingSentryTraceHeader as string | undefined) ?? sentryTrace,
baggage: newBaggageHeaders.length > 0 ? newBaggageHeaders.join(',') : undefined,
};
Expand Down
2 changes: 1 addition & 1 deletion packages/core/src/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,7 @@ export { profiler } from './profiling';
// eslint thinks the entire function is deprecated (while only one overload is actually deprecated)
// Therefore:
// eslint-disable-next-line deprecation/deprecation
export { instrumentFetchRequest } from './fetch';
export { instrumentFetchRequest, getTracingHeadersForFetchRequest } from './fetch';
export { trpcMiddleware } from './trpc';
export { wrapMcpServerWithSentry } from './integrations/mcp-server';
export { captureFeedback } from './feedback';
Expand Down
48 changes: 24 additions & 24 deletions packages/core/test/lib/fetch.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { beforeEach, describe, expect, it, vi } from 'vitest';
import type { HandlerDataFetch } from '../../src';
import { _addTracingHeadersToFetchRequest, instrumentFetchRequest } from '../../src/fetch';
import { getTracingHeadersForFetchRequest, instrumentFetchRequest } from '../../src/fetch';
import type { Span } from '../../src/types-hoist/span';

const { DEFAULT_SENTRY_TRACE, DEFAULT_BAGGAGE, hasSpansEnabled } = vi.hoisted(() => ({
Expand Down Expand Up @@ -31,7 +31,7 @@ vi.mock('../../src/utils/hasSpansEnabled', () => {
};
});

describe('_addTracingHeadersToFetchRequest', () => {
describe('getTracingHeadersForFetchRequest', () => {
beforeEach(() => {
vi.clearAllMocks();
hasSpansEnabled.mockReturnValue(false);
Expand All @@ -47,7 +47,7 @@ describe('_addTracingHeadersToFetchRequest', () => {
options: { headers: {} },
},
])('attaches sentry headers (options: $options)', ({ options }) => {
expect(_addTracingHeadersToFetchRequest('/api/test', options)).toEqual({
expect(getTracingHeadersForFetchRequest('/api/test', options)).toEqual({
'sentry-trace': DEFAULT_SENTRY_TRACE,
baggage: DEFAULT_BAGGAGE,
});
Expand All @@ -56,7 +56,7 @@ describe('_addTracingHeadersToFetchRequest', () => {

describe('and request headers are set in options', () => {
it('attaches sentry headers to headers object', () => {
expect(_addTracingHeadersToFetchRequest('/api/test', { headers: { 'custom-header': 'custom-value' } })).toEqual(
expect(getTracingHeadersForFetchRequest('/api/test', { headers: { 'custom-header': 'custom-value' } })).toEqual(
{
'sentry-trace': DEFAULT_SENTRY_TRACE,
baggage: DEFAULT_BAGGAGE,
Expand All @@ -66,7 +66,7 @@ describe('_addTracingHeadersToFetchRequest', () => {
});

it('attaches sentry headers to a Headers instance', () => {
const returnedHeaders = _addTracingHeadersToFetchRequest('/api/test', {
const returnedHeaders = getTracingHeadersForFetchRequest('/api/test', {
headers: new Headers({ 'custom-header': 'custom-value' }),
});

Expand All @@ -81,7 +81,7 @@ describe('_addTracingHeadersToFetchRequest', () => {
});

it('attaches sentry headers to headers array', () => {
const returnedHeaders = _addTracingHeadersToFetchRequest('/api/test', {
const returnedHeaders = getTracingHeadersForFetchRequest('/api/test', {
headers: [['custom-header', 'custom-value']],
});

Expand All @@ -96,7 +96,7 @@ describe('_addTracingHeadersToFetchRequest', () => {

describe('and 3rd party baggage header is set', () => {
it('adds additional sentry baggage values to Headers instance', () => {
const returnedHeaders = _addTracingHeadersToFetchRequest('/api/test', {
const returnedHeaders = getTracingHeadersForFetchRequest('/api/test', {
headers: new Headers({
baggage: 'custom-baggage=1,someVal=bar',
}),
Expand All @@ -112,7 +112,7 @@ describe('_addTracingHeadersToFetchRequest', () => {
});

it('adds additional sentry baggage values to headers array', () => {
const returnedHeaders = _addTracingHeadersToFetchRequest('/api/test', {
const returnedHeaders = getTracingHeadersForFetchRequest('/api/test', {
headers: [['baggage', 'custom-baggage=1,someVal=bar']],
});

Expand All @@ -126,7 +126,7 @@ describe('_addTracingHeadersToFetchRequest', () => {
});

it('adds additional sentry baggage values to headers object', () => {
const returnedHeaders = _addTracingHeadersToFetchRequest('/api/test', {
const returnedHeaders = getTracingHeadersForFetchRequest('/api/test', {
headers: {
baggage: 'custom-baggage=1,someVal=bar',
},
Expand All @@ -141,7 +141,7 @@ describe('_addTracingHeadersToFetchRequest', () => {
});

it('adds additional sentry baggage values to headers object with arrays', () => {
const returnedHeaders = _addTracingHeadersToFetchRequest('/api/test', {
const returnedHeaders = getTracingHeadersForFetchRequest('/api/test', {
headers: {
baggage: ['custom-baggage=1,someVal=bar', 'other-vendor-key=value'],
},
Expand All @@ -158,7 +158,7 @@ describe('_addTracingHeadersToFetchRequest', () => {

describe('and Sentry values are already set', () => {
it('does not override them (Headers instance)', () => {
const returnedHeaders = _addTracingHeadersToFetchRequest('/api/test', {
const returnedHeaders = getTracingHeadersForFetchRequest('/api/test', {
headers: new Headers({
'sentry-trace': CUSTOM_SENTRY_TRACE,
baggage: CUSTOM_BAGGAGE,
Expand All @@ -177,7 +177,7 @@ describe('_addTracingHeadersToFetchRequest', () => {
});

it('does not override them (headers array)', () => {
const returnedHeaders = _addTracingHeadersToFetchRequest('/api/test', {
const returnedHeaders = getTracingHeadersForFetchRequest('/api/test', {
headers: [
['sentry-trace', CUSTOM_SENTRY_TRACE],
['baggage', CUSTOM_BAGGAGE],
Expand All @@ -195,7 +195,7 @@ describe('_addTracingHeadersToFetchRequest', () => {
});

it('does not override them (headers object)', () => {
const returnedHeaders = _addTracingHeadersToFetchRequest('/api/test', {
const returnedHeaders = getTracingHeadersForFetchRequest('/api/test', {
headers: {
'sentry-trace': CUSTOM_SENTRY_TRACE,
baggage: CUSTOM_BAGGAGE,
Expand All @@ -218,7 +218,7 @@ describe('_addTracingHeadersToFetchRequest', () => {
describe('and no request headers are set', () => {
it('attaches sentry headers', () => {
const request = new Request('http://locahlost:3000/api/test');
const returnedHeaders = _addTracingHeadersToFetchRequest(request, {});
const returnedHeaders = getTracingHeadersForFetchRequest(request, {});

expect(returnedHeaders).toBeInstanceOf(Headers);

Expand All @@ -236,7 +236,7 @@ describe('_addTracingHeadersToFetchRequest', () => {
headers: new Headers({ 'custom-header': 'custom-value' }),
});

const returnedHeaders = _addTracingHeadersToFetchRequest(request, {});
const returnedHeaders = getTracingHeadersForFetchRequest(request, {});

expect(returnedHeaders).toBeInstanceOf(Headers);

Expand All @@ -253,7 +253,7 @@ describe('_addTracingHeadersToFetchRequest', () => {
headers: { 'custom-header': 'custom-value' },
});

const returnedHeaders = _addTracingHeadersToFetchRequest(request, {});
const returnedHeaders = getTracingHeadersForFetchRequest(request, {});

expect(returnedHeaders).toBeInstanceOf(Headers);

Expand All @@ -270,7 +270,7 @@ describe('_addTracingHeadersToFetchRequest', () => {
headers: [['custom-header', 'custom-value']],
});

const returnedHeaders = _addTracingHeadersToFetchRequest(request, {});
const returnedHeaders = getTracingHeadersForFetchRequest(request, {});

expect(returnedHeaders).toBeInstanceOf(Headers);

Expand All @@ -292,7 +292,7 @@ describe('_addTracingHeadersToFetchRequest', () => {
}),
});

const returnedHeaders = _addTracingHeadersToFetchRequest(request, {});
const returnedHeaders = getTracingHeadersForFetchRequest(request, {});

expect(returnedHeaders).toBeInstanceOf(Headers);

Expand All @@ -309,7 +309,7 @@ describe('_addTracingHeadersToFetchRequest', () => {
headers: [['baggage', 'custom-baggage=1,someVal=bar']],
});

const returnedHeaders = _addTracingHeadersToFetchRequest(request, {});
const returnedHeaders = getTracingHeadersForFetchRequest(request, {});

expect(returnedHeaders).toBeInstanceOf(Headers);

Expand All @@ -327,7 +327,7 @@ describe('_addTracingHeadersToFetchRequest', () => {
},
});

const returnedHeaders = _addTracingHeadersToFetchRequest(request, {});
const returnedHeaders = getTracingHeadersForFetchRequest(request, {});

expect(returnedHeaders).toBeInstanceOf(Headers);

Expand All @@ -345,7 +345,7 @@ describe('_addTracingHeadersToFetchRequest', () => {
},
});

const returnedHeaders = _addTracingHeadersToFetchRequest(request, {});
const returnedHeaders = getTracingHeadersForFetchRequest(request, {});

expect(returnedHeaders).toBeInstanceOf(Headers);

Expand All @@ -367,7 +367,7 @@ describe('_addTracingHeadersToFetchRequest', () => {
}),
});

const returnedHeaders = _addTracingHeadersToFetchRequest(request, {});
const returnedHeaders = getTracingHeadersForFetchRequest(request, {});

expect(returnedHeaders).toBeInstanceOf(Headers);

Expand All @@ -388,7 +388,7 @@ describe('_addTracingHeadersToFetchRequest', () => {
],
});

const returnedHeaders = _addTracingHeadersToFetchRequest(request, {});
const returnedHeaders = getTracingHeadersForFetchRequest(request, {});

expect(returnedHeaders).toBeInstanceOf(Headers);

Expand All @@ -409,7 +409,7 @@ describe('_addTracingHeadersToFetchRequest', () => {
},
});

const returnedHeaders = _addTracingHeadersToFetchRequest(request, {});
const returnedHeaders = getTracingHeadersForFetchRequest(request, {});

expect(returnedHeaders).toBeInstanceOf(Headers);

Expand Down
Loading