feat(node): Auto-register Koa error handler on app start (#23463)

The Koa error handler is now registered automatically when the app
starts, so `setupKoaErrorHandler` no longer needs to be called. This
mirrors the Hapi change and removes the last manual setup step for Koa
error capture.

### How it works

Koa's `Application` is an `EventEmitter` and emits `'error'` for every
request error that bubbles up unhandled — the same set of errors a
top-level try/catch middleware would see, but **order-independent**. So
instead of injecting a `try/catch` middleware (whose position in the
onion stack was load-bearing), we attach a single `app.on('error')`
listener.

Auto-registration rides a new orchestrion channel on
`Application.prototype.callback`. `app.listen()` always funnels through
`callback()`, so this also covers `http.createServer(app.callback())`.

### Decisions

- **Attach on the channel's `end`, not `start`.** Koa registers its own
default `error` listener inside `callback()` — but only if none exist
yet (`if (!this.listenerCount('error')) this.on('error',
this.onerror)`). Attaching before that runs would suppress koa's
built-in error logging. Acting on `end` (after the method body) means
koa's default listener is already in place and ours is added alongside
it.
- **`app.on('error')` over a first-position `try/catch` middleware.**
Event listeners are additive and order-independent, so there is no
ordering conflict with a user's own error handling: if a user middleware
catches and handles an error, koa never emits and we correctly don't
capture; if it's unhandled, our listener and any user `app.on('error')`
both run.
- **`setupKoaErrorHandler` stays as an idempotent delegate**
(deprecated) rather than a hard no-op, so a direct call still works
without orchestrion (e.g. error capture with tracing disabled). An
idempotency marker on the app means auto-registration plus a manual call
never stack up duplicate listeners.
- **`attachKoaErrorHandler` is also deprecated** and marked internal —
it exists only so the deprecated `setupKoaErrorHandler` can delegate to
it, and should not be called directly.
- The Koa integration files were collocated into a `koa/` folder to
match the Hapi layout.

Auto-registration is exercised end-to-end by dropping the manual call
from the koa integration-test scenario and the e2e app; a new unit suite
covers the attach behaviour (single idempotent listener, guards, and
capture mechanism).

A follow-up will do the same for Express.

Author: mydea

MIGRATION.md

@@ -287,6 +287,12 @@ Affected SDKs: `@sentry/node` and all dependents.
 
 The new channel-based instrumentations (using `orchestrion` instead of `import-in-the-middle`) are now the default. They were available opt-in in v10. This unlocks instrumenting at run and build time, which enables instrumentation at deployment targets like Vercel and Netlify, as well as using instrumentations on non-Node runtimes like Cloudflare, Bun and Deno. For most users this requires no changes.
 
+### `setupKoaErrorHandler` is deprecated (Koa errors are captured automatically)
+
+Affected SDKs: `@sentry/node` and all dependents that re-export it (e.g. `@sentry/aws-serverless`, `@sentry/google-cloud-serverless`, `@sentry/astro`, `@sentry/remix`, `@sentry/solidstart`, `@sentry/sveltekit`, `@sentry/bun`, `@sentry/elysia`).
+
+The Koa error handler is now registered automatically when your app starts, so you no longer need to call `setupKoaErrorHandler`. The function is deprecated and will be removed in a future major version; you should no longer call it.
+
 ### Initializing via `--require` is no longer supported
 
 Affected SDKs: `@sentry/node` and all dependents.

dev-packages/e2e-tests/test-applications/node-koa/index.js

@@ -22,8 +22,6 @@ const http = require('http');
 const app1 = new Koa();
 app1.use(bodyParser());
 
-Sentry.setupKoaErrorHandler(app1);
-
 const router1 = new Router();
 
 router1.get('/test-success', ctx => {

dev-packages/e2e-tests/test-applications/node-koa/tests/transactions.test.ts

@@ -66,7 +66,9 @@ test('Sends an API route transaction', async ({ baseURL }) => {
     },
   });
 
-  expect(transactionEvent.spans).toEqual([
+  const spans = transactionEvent.spans || [];
+
+  expect(spans).toEqual([
     {
       data: {
         'koa.name': 'bodyParser',
@@ -85,24 +87,6 @@ test('Sends an API route transaction', async ({ baseURL }) => {
       timestamp: expect.any(Number),
       trace_id: expect.stringMatching(/[a-f0-9]{32}/),
     },
-    {
-      data: {
-        'koa.name': 'middleware',
-        'code.function.name': 'middleware',
-        'koa.type': 'middleware',
-        'sentry.origin': 'auto.http.koa',
-        'sentry.op': 'middleware',
-      },
-      op: 'middleware',
-      origin: 'auto.http.koa',
-      description: 'middleware',
-      parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
-      span_id: expect.stringMatching(/[a-f0-9]{16}/),
-      start_timestamp: expect.any(Number),
-      status: 'ok',
-      timestamp: expect.any(Number),
-      trace_id: expect.stringMatching(/[a-f0-9]{32}/),
-    },
     {
       data: {
         'http.route': '/test-transaction',

dev-packages/node-integration-tests/suites/tracing/koa/scenario.mjs

@@ -1,14 +1,13 @@
 import Router from '@koa/router';
-import * as Sentry from '@sentry/node';
 import { sendPortToRunner } from '@sentry-internal/node-integration-tests';
 import Koa from 'koa';
 
 const port = 5698;
 
 const app = new Koa();
 
-// Registered first so it wraps every downstream middleware/route in its try/catch.
-Sentry.setupKoaErrorHandler(app);
+// The error handler is auto-registered by the koa instrumentation on app start,
+// so `setupKoaErrorHandler` is intentionally not called here.
 
 // Plain middleware -> produces a `middleware` span named after the function.
 app.use(async function simpleMiddleware(ctx, next) {

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

@@ -9,6 +9,16 @@ describe('koa auto-instrumentation', () => {
   const origin = 'auto.http.koa';
 
   const EXPECTED_ERROR_EVENT = {
+    // The error is captured within the request's koa span, so it keeps its trace
+    // linkage (a `parent_span_id`) even though koa emits `error` after the
+    // middleware chain has unwound.
+    contexts: {
+      trace: {
+        trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+        span_id: expect.stringMatching(/[a-f0-9]{16}/),
+        parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
+      },
+    },
     exception: {
       values: [
         {

packages/astro/src/index.server.ts

@@ -126,6 +126,7 @@ export {
   setAttributes,
   setupExpressErrorHandler,
   setupHapiErrorHandler,
+  // oxlint-disable-next-line typescript/no-deprecated
   setupKoaErrorHandler,
   setUser,
   spanToBaggageHeader,

packages/aws-serverless/src/index.ts

@@ -96,6 +96,7 @@ export {
   expressErrorHandler,
   setupExpressErrorHandler,
   koaIntegration,
+  // oxlint-disable-next-line typescript/no-deprecated
   setupKoaErrorHandler,
   fastifyIntegration,
   firebaseIntegration,

packages/bun/src/index.ts

@@ -120,6 +120,7 @@ export {
   setupFastifyErrorHandler,
   firebaseIntegration,
   koaIntegration,
+  // oxlint-disable-next-line typescript/no-deprecated
   setupKoaErrorHandler,
   genericPoolIntegration,
   graphqlIntegration,

packages/elysia/src/index.ts

@@ -99,6 +99,7 @@ export {
   setupFastifyErrorHandler,
   firebaseIntegration,
   koaIntegration,
+  // oxlint-disable-next-line typescript/no-deprecated
   setupKoaErrorHandler,
   genericPoolIntegration,
   graphqlIntegration,

packages/google-cloud-serverless/src/index.ts

@@ -97,6 +97,7 @@ export {
   expressErrorHandler,
   setupExpressErrorHandler,
   koaIntegration,
+  // oxlint-disable-next-line typescript/no-deprecated
   setupKoaErrorHandler,
   fastifyIntegration,
   firebaseIntegration,