feat(node): Add onSpanEnd to httpIntegration

`httpIntegration` takes `onSpanCreated` for incoming requests, but not
`onSpanEnd`. A user could not change the server span based on the
response, for example to rename it from data that is only known when
the response finishes. Core's `node:http` server code already supports
`onSpanEnd`, and `denoHttpIntegration` and `bunHttpServerIntegration`
pass it through.

`httpServerSpansIntegration` now accepts `onSpanEnd` and calls it as
core does: when the response finishes, after the SDK sets the response
attributes and the span status, before the span ends. `httpIntegration`
passes it through. The shared `ServerRequestOptions` check for Node now
lists no unsupported options.

Fixes #25572
Fixes JS-3970

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: isaacs

CHANGELOG.md

@@ -59,6 +59,10 @@ Work in this release was contributed by @adityareddy-dev, @jpdefo, @Jxxunnn, @ph
 
   `ignoreStaticAssets` defaults to `true`, so `Bun.serve` no longer creates spans for `GET` requests to common static assets such as `favicon.ico`, `robots.txt` or `*.js` files. To keep these spans, set `bunServerIntegration({ ignoreStaticAssets: false })`. `Bun.serve` spans also follow the client's tracing configuration by default, so the integration does not start spans when tracing is disabled. Errors thrown for `OPTIONS` and `HEAD` requests are now captured.
 
+- **feat(node): Add `onSpanEnd` to `httpIntegration`**
+
+  `httpIntegration` and `httpServerSpansIntegration` now accept `onSpanEnd`, a hook that runs when the response for an incoming request finishes, before its span ends. Use it to change the span based on the response. Deno and Bun already have this option.
+
 ## 11.8.0
 
 ### Important Changes

dev-packages/node-integration-tests/suites/tracing/httpIntegration/instrument-onSpanEnd-throws.mjs

@@ -0,0 +1,17 @@
+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,
+
+  integrations: [
+    Sentry.httpIntegration({
+      onSpanEnd: () => {
+        throw new Error('onSpanEnd failed');
+      },
+    }),
+  ],
+});

dev-packages/node-integration-tests/suites/tracing/httpIntegration/instrument-options.mjs

@@ -18,6 +18,12 @@ Sentry.init({
           'onSpanCreated.resMethod': res.req.method,
         });
       },
+      onSpanEnd: (span, req, res) => {
+        span.setAttributes({
+          'onSpanEnd.reqUrl': req.url,
+          'onSpanEnd.resStatusCode': res.statusCode,
+        });
+      },
     }),
   ],
 });

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

@@ -22,9 +22,9 @@ describe('httpIntegration', () => {
     cleanupChildProcesses();
   });
 
-  describe('onSpanCreated option', () => {
+  describe('onSpanCreated and onSpanEnd options', () => {
     createEsmAndCjsTests(__dirname, 'server.mjs', 'instrument-options.mjs', (createRunner, test) => {
-      test('allows to configure onSpanCreated', async () => {
+      test('allows to configure onSpanCreated and onSpanEnd', async () => {
         const runner = createRunner()
           .expect({
             span: {
@@ -43,6 +43,8 @@ describe('httpIntegration', () => {
                     'onSpanCreated.reqMethod': { type: 'string', value: 'GET' },
                     'onSpanCreated.resUrl': { type: 'string', value: expect.stringMatching(/\/test$/) },
                     'onSpanCreated.resMethod': { type: 'string', value: 'GET' },
+                    'onSpanEnd.reqUrl': { type: 'string', value: expect.stringMatching(/\/test$/) },
+                    'onSpanEnd.resStatusCode': { type: 'integer', value: 200 },
                   }),
                 }),
               ]),
@@ -55,6 +57,43 @@ describe('httpIntegration', () => {
     });
   });
 
+  describe('onSpanEnd that throws', () => {
+    createEsmAndCjsTests(__dirname, 'server.mjs', 'instrument-onSpanEnd-throws.mjs', (createRunner, test) => {
+      test('still ends and sends the span, and keeps the server running', async () => {
+        const runner = createRunner()
+          .expect({
+            span: {
+              items: expect.arrayContaining([
+                expect.objectContaining({
+                  is_segment: true,
+                  attributes: expect.objectContaining({
+                    [URL_FULL]: { type: 'string', value: expect.stringMatching(/\/test$/) },
+                    [HTTP_RESPONSE_STATUS_CODE]: { type: 'integer', value: 200 },
+                  }),
+                }),
+              ]),
+            },
+          })
+          .expect({
+            span: {
+              items: expect.arrayContaining([
+                expect.objectContaining({
+                  is_segment: true,
+                  attributes: expect.objectContaining({
+                    [URL_FULL]: { type: 'string', value: expect.stringMatching(/\/test$/) },
+                  }),
+                }),
+              ]),
+            },
+          })
+          .start();
+        await runner.makeRequest('get', '/test');
+        await runner.makeRequest('get', '/test');
+        await runner.completed();
+      });
+    });
+  });
+
   describe('outgoing request span hooks', () => {
     test('runs outgoingRequestHook, outgoingResponseHook and outgoingRequestApplyCustomAttributes', async () => {
       const [SERVER_URL, closeTestServer] = await createTestServer()

packages/node/src/integrations/http/httpServerSpansIntegration.ts

@@ -36,6 +36,7 @@ import {
 } from '@sentry/core/server';
 import {
   debug,
+  safeCallback,
   getSpanStatusFromHttpCode,
   httpHeadersToSpanAttributes,
   getContentLengthFromHeaders,
@@ -104,6 +105,12 @@ export interface HttpServerSpansIntegrationOptions {
    * This is triggered after the span is created, but before it is recorded.
    */
   onSpanCreated?: (span: Span, request: HttpIncomingMessage, response: HttpServerResponse) => void;
+
+  /**
+   * A hook that can be used to mutate the span one last time when the response is finished.
+   * This is triggered after the response status is set on the span, before the span ends.
+   */
+  onSpanEnd?: (span: Span, request: HttpIncomingMessage, response: HttpServerResponse) => void;
 }
 
 const _httpServerSpansIntegration = ((options: HttpServerSpansIntegrationOptions = {}) => {
@@ -112,7 +119,7 @@ const _httpServerSpansIntegration = ((options: HttpServerSpansIntegrationOptions
   // oxlint-disable-next-line typescript/no-deprecated
   const ignoreStatusCodes = options.ignoreStatusCodes ?? DEFAULT_IGNORE_STATUS_CODES;
 
-  const { onSpanCreated } = options;
+  const { onSpanCreated, onSpanEnd } = options;
 
   return {
     name: INTEGRATION_NAME,
@@ -209,6 +216,15 @@ const _httpServerSpansIntegration = ((options: HttpServerSpansIntegrationOptions
               );
               span.setAttributes(newAttributes);
               span.setStatus(status);
+              if (onSpanEnd) {
+                // A hook that throws must not skip `span.end()` or crash the process from the
+                // response's event listener.
+                safeCallback(
+                  DEBUG_BUILD ? 'Error in `onSpanEnd`:' : '',
+                  () => onSpanEnd(span, request, response),
+                  () => undefined,
+                );
+              }
               span.end();
             }
 

packages/node/src/integrations/http/index.ts

@@ -93,13 +93,7 @@ interface HttpOptions extends HttpServerIntegrationOptions, HttpServerSpansInteg
 // shared field fails to compile here, until this integration supports
 // it or lists it as unsupported.
 type _ServerRequestOptionsCheck = AssertTrue<
-  CheckServerRequestOptions<
-    HttpOptions,
-    HttpIncomingMessage,
-    HttpServerResponse,
-    // Not supported yet.
-    'onSpanEnd'
-  >
+  CheckServerRequestOptions<HttpOptions, HttpIncomingMessage, HttpServerResponse>
 >;
 
 /**