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

Open
JPeer264 wants to merge 2 commits into
base: develop
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 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
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
40 changes: 29 additions & 11 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 @@ import {
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 @@ export function instrumentFetchRequest(
// 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 @@ export function _callOnRequestSpanEnd(
}

/**
* 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
*
* 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,
Copy link
Copy Markdown

@cursor cursor bot Apr 7, 2026

Choose a reason for hiding this comment

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

feat PR lacks integration or E2E test

Low Severity

This feat PR exports getTracingHeadersForFetchRequest as a new public API from @sentry/core but only includes unit tests. Per project review guidelines, feat PRs need at least one integration or E2E test. Given this function is explicitly being exported for cross-package instrumentation (e.g., Cloudflare Workers fetcher bindings), an integration test demonstrating the intended cross-package usage would help validate the API contract.

Additional Locations (1)
Fix in Cursor Fix in Web

Triggered by project rule: PR Review Guidelines for Cursor Bot

Reviewed by Cursor Bugbot for commit 1622527. Configure here.

fetchOptionsObj: {
headers?:
| {
Expand Down Expand Up @@ -234,7 +240,7 @@ export function _addTracingHeadersToFetchRequest(
}

return newHeaders;
} else if (Array.isArray(originalHeaders)) {
} else if (isHeadersInitTupleArray(originalHeaders)) {
const newHeaders = [...originalHeaders];

if (!originalHeaders.find(header => header[0] === 'sentry-trace')) {
Expand All @@ -255,7 +261,7 @@ export function _addTracingHeadersToFetchRequest(
newHeaders.push(['baggage', baggage]);
}

return newHeaders as PolymorphicRequestHeaders;
return newHeaders;
} else {
const existingSentryTraceHeader = 'sentry-trace' in originalHeaders ? originalHeaders['sentry-trace'] : undefined;
const existingTraceparentHeader = 'traceparent' in originalHeaders ? originalHeaders.traceparent : undefined;
Expand Down Expand Up @@ -321,6 +327,18 @@ function isHeaders(headers: unknown): headers is Headers {
return typeof Headers !== 'undefined' && isInstanceOf(headers, Headers);
}

/** `HeadersInit` array form: each entry is a [name, value] pair of strings. */
function isHeadersInitTupleArray(headers: unknown): headers is [string, string][] {
if (!Array.isArray(headers)) {
return false;
}

return headers.every(
(item): item is [string, string] =>
Array.isArray(item) && item.length === 2 && typeof item[0] === 'string' && typeof item[1] === 'string',
);
}

function getSpanStartOptions(
url: string,
method: string,
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
63 changes: 39 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 @@ -92,11 +92,26 @@ describe('_addTracingHeadersToFetchRequest', () => {
['baggage', DEFAULT_BAGGAGE],
]);
});

it('treats array with non-tuple items as headers object', () => {
const returnedHeaders = getTracingHeadersForFetchRequest('/api/test', {
headers: ['not-a-tuple', 'also-not-a-tuple'],
});

// Falls through to the else branch (headers object handling)
// since the array items are not [string, string] tuples
expect(returnedHeaders).toEqual({
'0': 'not-a-tuple',
'1': 'also-not-a-tuple',
'sentry-trace': DEFAULT_SENTRY_TRACE,
baggage: DEFAULT_BAGGAGE,
});
});
});

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 +127,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 +141,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 +156,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 +173,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 +192,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 +210,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 +233,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 +251,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 +268,7 @@ describe('_addTracingHeadersToFetchRequest', () => {
headers: { 'custom-header': 'custom-value' },
});

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

expect(returnedHeaders).toBeInstanceOf(Headers);

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

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

expect(returnedHeaders).toBeInstanceOf(Headers);

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

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

expect(returnedHeaders).toBeInstanceOf(Headers);

Expand All @@ -309,7 +324,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 +342,7 @@ describe('_addTracingHeadersToFetchRequest', () => {
},
});

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

expect(returnedHeaders).toBeInstanceOf(Headers);

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

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

expect(returnedHeaders).toBeInstanceOf(Headers);

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

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

expect(returnedHeaders).toBeInstanceOf(Headers);

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

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

expect(returnedHeaders).toBeInstanceOf(Headers);

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

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

expect(returnedHeaders).toBeInstanceOf(Headers);

Expand Down
Loading