feat(core): Send sentry.is_localhost on every streamed span

Author: Lms24

dev-packages/bun-integration-tests/suites/is-localhost/index.ts

@@ -0,0 +1,18 @@
+import * as Sentry from '@sentry/bun';
+
+Sentry.init({
+  dsn: process.env.SENTRY_DSN,
+  tracesSampleRate: 1.0,
+});
+
+const server = Bun.serve({
+  port: 0,
+  fetch() {
+    Sentry.startSpan({ name: 'child-span' }, () => {
+      // noop
+    });
+    return new Response('Hello from Bun!');
+  },
+});
+
+process.send?.(JSON.stringify({ event: 'READY', port: server.port }));

dev-packages/bun-integration-tests/suites/is-localhost/test.ts

@@ -0,0 +1,27 @@
+import type { Envelope, SerializedStreamedSpan, SerializedStreamedSpanContainer } from '@sentry/core';
+import { expect, it } from 'vitest';
+import { createRunner } from '../../runner';
+
+function getSpans(envelope: Envelope): SerializedStreamedSpan[] {
+  return (envelope[1][0][1] as SerializedStreamedSpanContainer).items;
+}
+
+// The runner always requests `http://localhost:<port>`, so only the `true` case is reachable here.
+// The `false` case is covered by the unit tests for `isLocalhostRequest`.
+it('sets sentry.is_localhost on every streamed span', async ({ signal }) => {
+  const runner = createRunner(__dirname)
+    .expect(envelope => {
+      const spans = getSpans(envelope);
+
+      expect(spans.some(span => span.is_segment)).toBe(true);
+      expect(spans.some(span => span.name === 'child-span')).toBe(true);
+
+      for (const span of spans) {
+        expect(span.attributes['sentry.is_localhost']).toEqual({ value: true, type: 'boolean' });
+      }
+    })
+    .start(signal);
+
+  await runner.makeRequest('get', '/');
+  await runner.completed();
+});

dev-packages/cloudflare-integration-tests/suites/tracing/is-localhost/index.ts

@@ -0,0 +1,20 @@
+import * as Sentry from '@sentry/cloudflare';
+
+interface Env {
+  SENTRY_DSN: string;
+}
+
+export default Sentry.withSentry(
+  (env: Env) => ({
+    dsn: env.SENTRY_DSN,
+    tracesSampleRate: 1,
+  }),
+  {
+    async fetch(_request, _env, _ctx) {
+      Sentry.startSpan({ name: 'child-span' }, () => {
+        // noop
+      });
+      return Response.json({ status: 'ok' });
+    },
+  },
+);

dev-packages/cloudflare-integration-tests/suites/tracing/is-localhost/test.ts

@@ -0,0 +1,21 @@
+import { expect, it } from 'vitest';
+import { createRunner } from '../../../runner';
+
+it('sets sentry.is_localhost on every streamed span', async ({ signal }) => {
+  const runner = createRunner(__dirname)
+    .expect(envelope => {
+      const items = envelope[1].filter(item => item[0].type === 'span').flatMap(item => (item[1] as any).items);
+
+      expect(items.length).toBeGreaterThan(0);
+      expect(items.some((s: any) => s.is_segment)).toBe(true);
+      expect(items.some((s: any) => s.name === 'child-span')).toBe(true);
+
+      for (const span of items) {
+        expect(span.attributes['sentry.is_localhost']).toEqual({ type: 'boolean', value: true });
+      }
+    })
+    .start(signal);
+
+  await runner.makeRequest('get', '/');
+  await runner.completed();
+});

dev-packages/cloudflare-integration-tests/suites/tracing/is-localhost/wrangler.jsonc

@@ -0,0 +1,6 @@
+{
+  "name": "is-localhost",
+  "compatibility_date": "2025-06-17",
+  "main": "index.ts",
+  "compatibility_flags": ["nodejs_compat"],
+}

dev-packages/node-integration-tests/suites/tracing/is-localhost/instrument.mjs

@@ -0,0 +1,9 @@
+import * as Sentry from '@sentry/node';
+import { loggingTransport } from '@sentry-internal/node-integration-tests';
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  release: '1.0',
+  tracesSampleRate: 1.0,
+  transport: loggingTransport,
+});

dev-packages/node-integration-tests/suites/tracing/is-localhost/server.mjs

@@ -0,0 +1,14 @@
+import { startExpressServerAndSendPortToRunner } from '@sentry-internal/node-integration-tests';
+import * as Sentry from '@sentry/node';
+import express from 'express';
+
+const app = express();
+
+app.get('/test', (_req, res) => {
+  Sentry.startSpan({ name: 'child-span' }, () => {
+    // noop
+  });
+  res.send({ response: 'ok' });
+});
+
+startExpressServerAndSendPortToRunner(app);

dev-packages/node-integration-tests/suites/tracing/is-localhost/test.ts

@@ -0,0 +1,35 @@
+import { afterAll, describe, expect } from 'vitest';
+import { cleanupChildProcesses, createEsmAndCjsTests } from '../../../utils/runner';
+
+describe('sentry.is_localhost', () => {
+  afterAll(() => {
+    cleanupChildProcesses();
+  });
+
+  createEsmAndCjsTests(__dirname, 'server.mjs', 'instrument.mjs', (createRunner, test) => {
+    // The runner always requests `http://localhost:<port>`, so only the `true` case is reachable
+    // here. The `false` case is covered by the unit tests for `isLocalhostRequest`.
+    test('is set on every span of a request served from localhost', async () => {
+      const runner = createRunner()
+        .unordered()
+        .expect({
+          span: container => {
+            const segmentSpan = container.items.find(s => !!s.is_segment);
+            const childSpan = container.items.find(s => s.name === 'child-span');
+
+            expect(segmentSpan).toBeDefined();
+            expect(childSpan).toBeDefined();
+
+            for (const span of container.items) {
+              expect(span.attributes['sentry.is_localhost']).toEqual({ type: 'boolean', value: true });
+            }
+          },
+        })
+        .start();
+
+      await runner.makeRequest('get', '/test');
+
+      await runner.completed();
+    });
+  });
+});

packages/browser/src/integrations/httpcontext.ts

@@ -51,12 +51,22 @@ export const httpContextIntegration = defineIntegration(() => {
         client.getDataCollectionOptions().httpHeaders.request,
       );
       const referer = headers['Referer'];
+      const { hostname, protocol } = WINDOW.location || {};
 
       safeSetSpanJSONAttributes(span, {
         // This attribute is used by the "Filter out events from legacy browsers and crawlers" features on the Sentry backend.
         // Therefore, it's set on every span.
         [USER_AGENT_ORIGINAL]: headers['User-Agent'],
 
+        // Likewise for the "Filter out localhost events" feature. Deliberately inlined rather than
+        // sharing the server-side helper, which costs bundle size for request headers and IPs that
+        // don't exist here. Mirrors Relay's localhost filter (relay-filter/src/localhost.rs).
+        'sentry.is_localhost':
+          protocol === 'file:' ||
+          hostname === 'localhost' ||
+          hostname === '127.0.0.1' ||
+          !!hostname?.endsWith('.localhost'),
+
         // These attributes, we only need on the segment span (analogous to the `request` context for events)
         ...(span.is_segment && {
           // Coerce empty string to undefined so the helper's nullish check drops it,

packages/browser/test/integrations/httpcontext.test.ts

@@ -42,6 +42,7 @@ describe('httpContextIntegration', () => {
       [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'http.client',
       'http.request.header.referer': ['https://example.com'],
       'user_agent.original': USER_AGENT,
+      'sentry.is_localhost': false,
     });
   });
 
@@ -63,6 +64,7 @@ describe('httpContextIntegration', () => {
       [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'pageload',
       'http.request.header.referer': ['https://example.com'],
       'user_agent.original': USER_AGENT,
+      'sentry.is_localhost': false,
       'url.full': 'https://example.com',
     });
   });
@@ -81,6 +83,7 @@ describe('httpContextIntegration', () => {
     expect(span.attributes).toEqual({
       [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'ui.click',
       'user_agent.original': USER_AGENT,
+      'sentry.is_localhost': false,
     });
   });
 
@@ -165,6 +168,7 @@ describe('httpContextIntegration', () => {
 
       expect(span.attributes).toEqual({
         [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'pageload',
+        'sentry.is_localhost': false,
         'url.full': 'https://example.com',
       });
     });
@@ -185,7 +189,45 @@ describe('httpContextIntegration', () => {
         'url.full': 'https://example.com',
         'http.request.header.referer': ['[Filtered]'],
         'user_agent.original': USER_AGENT,
+        'sentry.is_localhost': false,
       });
     });
   });
+
+  describe('sentry.is_localhost', () => {
+    function processSpanWithLocation(location: Partial<Location>): StreamedSpanJSON['attributes'] {
+      const original = globalThis.location;
+      globalThis.location = location as Location;
+
+      try {
+        const span: Partial<StreamedSpanJSON> = { attributes: {} };
+        httpContextIntegration().processSpan!(
+          span as StreamedSpanJSON,
+          new BrowserClient(getDefaultBrowserClientOptions()),
+        );
+        return span.attributes;
+      } finally {
+        globalThis.location = original;
+      }
+    }
+
+    it.each([
+      { protocol: 'http:', hostname: 'localhost' },
+      { protocol: 'http:', hostname: '127.0.0.1' },
+      { protocol: 'http:', hostname: 'foo.localhost' },
+      { protocol: 'http:', hostname: 'foo.bar.localhost' },
+      { protocol: 'file:', hostname: '' },
+    ])('is true for $protocol//$hostname', location => {
+      expect(processSpanWithLocation(location)).toMatchObject({ 'sentry.is_localhost': true });
+    });
+
+    it.each([
+      { protocol: 'https:', hostname: 'example.com' },
+      { protocol: 'https:', hostname: 'localhost.com' },
+      { protocol: 'https:', hostname: 'foolocalhost' },
+      { protocol: 'https:', hostname: '127.0.0.2' },
+    ])('is false for $protocol//$hostname', location => {
+      expect(processSpanWithLocation(location)).toMatchObject({ 'sentry.is_localhost': false });
+    });
+  });
 });