feat(server-utils): Add @opentelemetry/instrumentation-koa orchestrion integration (#22146)

Adds `koaChannelIntegration` in `@sentry/server-utils` for injecting
orchestrion channels into `koa`.

A subscriber wraps each registered layer in a span-creating proxy.
Span-helpers are ported from the vendored instrumentation, preserving
span names (but adapting to [new
conventions](getsentry/sentry-conventions#472)).

Also upgraded `@apm-js-collab/tracing-hooks` to get this:
apm-js-collab/tracing-hooks#45 to be released
(lets us actually patch `koa` - see 1. iteration below).



<details>
<summary>1. iteration</summary>

One thing to know for review: **we instrument `koa-compose`, not `use`
from koa.** koa's `use` lives in koa's main entry
(`lib/application.js`), and transforming a package's main entry forces
its top-level `require` chain through Node's `require(esm)` bridge,
which throws on Node < 24.13.

1. Orchestrion instruments by rewriting a module's source at load time
(via the ESM load hook).
2. `use` lives in koa's main entry (`lib/application.js`), so to
instrument it we transform that file. But transforming a main entry
pulls its whole top-level `require` chain into the loader's handling -->
and that changes how those `require`s are loaded (through the
ESM→CommonJS translator, not the normal sync require path).
3. `koa` is CJS (but support ESM). When `import`ing koa, it loads a shim
that loads the CJS code: `import 'koa'` → `dist/koa.mjs` (a ESM shim) →
`import '../lib/application.js'` (CJS). That CJS entry has a top-level
`require('is-generator-function')`.
4. `is-generator-function` → `require('generator-function')`, and
`generator-function` points at an `.mjs` file, which in turn imports
`./index.js`.
--> So the top-level `require` in koa's `application.js` (CJS) becomes
`require(esm)` of an ESM file importing a CJS file.
5. On Node < 24.13 (we pin 20.19.5), the loader can't pre-link this
dual-package shape into the `require(esm)` cache, so it throws `request
for './index.js' is not in cache`.

The failing chain:
```
koa/lib/application.js (CJS)
  └─ require('is-generator-function')        (CJS)
       └─ require('generator-function')      → require(esm) → require.mjs (ESM)
            └─ import './index.js'            (ESM importing CJS)
```

`koa-compose` is koa's zero-dependency dispatch engine, so it's safe to
transform, and `compose(app.middleware)` sees the same layers `use`
would. Since `@koa/router` also calls `compose` per request, the
subscriber uses `getActiveSpan()` to only wrap at app startup (no active
span) and skip the per-request router composition.</details>





Closes #20758

Linear:
https://linear.app/getsentry/issue/JS-2409/rewrite-opentelemetryinstrumentation-koa-to-orchestrion

Author: s1gr1d

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

@@ -65,6 +65,7 @@ test('Sends an API route transaction', async ({ baseURL }) => {
     {
       data: {
         'koa.name': 'bodyParser',
+        'code.function.name': 'bodyParser',
         'koa.type': 'middleware',
         'sentry.op': 'middleware.koa',
         'sentry.origin': 'auto.http.otel.koa',
@@ -82,6 +83,7 @@ test('Sends an API route transaction', async ({ baseURL }) => {
     {
       data: {
         'koa.name': '',
+        'code.function.name': '',
         'koa.type': 'middleware',
         'sentry.origin': 'auto.http.otel.koa',
         'sentry.op': 'middleware.koa',

dev-packages/node-integration-tests/package.json

@@ -40,6 +40,7 @@
     "@growthbook/growthbook": "^1.6.5",
     "@hapi/hapi": "^21.3.10",
     "@hono/node-server": "^1.19.13",
+    "@koa/router": "^12.0.1",
     "@langchain/anthropic": "^0.3.10",
     "@langchain/core": "^0.3.80",
     "@langchain/openai": "^0.5.0",
@@ -76,6 +77,7 @@
     "ioredis-5": "npm:ioredis@^5.11.0",
     "kafkajs": "2.2.4",
     "knex": "^2.5.1",
+    "koa": "^2.15.2",
     "lru-memoizer": "2.3.0",
     "mongodb": "^3.7.3",
     "mongodb-memory-server-global": "^11.0.1",

dev-packages/node-integration-tests/suites/tracing/koa/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/koa/scenario.mjs

@@ -0,0 +1,36 @@
+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);
+
+// Plain middleware -> produces a `middleware.koa` span named after the function.
+app.use(async function simpleMiddleware(ctx, next) {
+  await next();
+});
+
+const router = new Router();
+
+router.get('/', ctx => {
+  ctx.body = 'Hello World!';
+});
+
+router.get('/test-param/:id', ctx => {
+  ctx.body = { id: ctx.params.id };
+});
+
+router.get('/error', () => {
+  throw new Error('Sentry Test Error');
+});
+
+app.use(router.routes()).use(router.allowedMethods());
+
+app.listen(port, () => {
+  sendPortToRunner(port);
+});

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

@@ -0,0 +1,104 @@
+import { afterAll, describe, expect } from 'vitest';
+import { isOrchestrionEnabled } from '../../../utils';
+import { cleanupChildProcesses, createEsmAndCjsTests } from '../../../utils/runner';
+
+describe('koa auto-instrumentation', () => {
+  afterAll(async () => {
+    cleanupChildProcesses();
+  });
+
+  // `createEsmAndCjsTests` auto-runs this suite with orchestrion on CI. The
+  // orchestrion path keeps span ops/attributes identical to the OTel path; only
+  // the origin differs to signal the injection mechanism, so we branch on
+  // `isOrchestrionEnabled()`.
+  const origin = isOrchestrionEnabled() ? 'auto.http.orchestrion.koa' : 'auto.http.otel.koa';
+
+  const EXPECTED_ERROR_EVENT = {
+    exception: {
+      values: [
+        {
+          type: 'Error',
+          value: 'Sentry Test Error',
+        },
+      ],
+    },
+  };
+
+  createEsmAndCjsTests(__dirname, 'scenario.mjs', 'instrument.mjs', (createRunner, test) => {
+    test('should auto-instrument `koa` router and middleware layers.', async () => {
+      const runner = createRunner()
+        .expect({
+          transaction: {
+            transaction: 'GET /',
+            spans: expect.arrayContaining([
+              // Router layer span (from `@koa/router`), carrying the matched route.
+              expect.objectContaining({
+                description: '/',
+                op: 'router.koa',
+                origin,
+                data: expect.objectContaining({
+                  'http.route': '/',
+                  'koa.type': 'router',
+                  'koa.name': '/',
+                  'sentry.op': 'router.koa',
+                  'sentry.origin': origin,
+                }),
+              }),
+              // Plain middleware span.
+              expect.objectContaining({
+                description: 'simpleMiddleware',
+                op: 'middleware.koa',
+                origin,
+                data: expect.objectContaining({
+                  'koa.type': 'middleware',
+                  'koa.name': 'simpleMiddleware',
+                  'code.function.name': 'simpleMiddleware',
+                  'sentry.op': 'middleware.koa',
+                  'sentry.origin': origin,
+                }),
+              }),
+            ]),
+          },
+        })
+        .start();
+      runner.makeRequest('get', '/');
+      await runner.completed();
+    });
+
+    test('should assign a parameterized transaction name.', async () => {
+      const runner = createRunner()
+        .expect({
+          transaction: {
+            transaction: 'GET /test-param/:id',
+            spans: expect.arrayContaining([
+              expect.objectContaining({
+                description: '/test-param/:id',
+                op: 'router.koa',
+                origin,
+                data: expect.objectContaining({
+                  'http.route': '/test-param/:id',
+                  'koa.type': 'router',
+                  'koa.name': '/test-param/:id',
+                  'sentry.op': 'router.koa',
+                  'sentry.origin': origin,
+                }),
+              }),
+            ]),
+          },
+        })
+        .start();
+      runner.makeRequest('get', '/test-param/123');
+      await runner.completed();
+    });
+
+    test('should capture errors thrown in routes via the koa error handler.', async () => {
+      const runner = createRunner()
+        .unordered()
+        .expect({ transaction: { transaction: 'GET /error' } })
+        .expect({ event: EXPECTED_ERROR_EVENT })
+        .start();
+      runner.makeRequest('get', '/error', { expectError: true });
+      await runner.completed();
+    });
+  });
+});

packages/deno/src/index.ts

@@ -116,6 +116,7 @@ export { denoPostgresIntegration } from './integrations/postgres';
 export { denoAmqplibIntegration } from './integrations/amqplib';
 export { denoDataloaderIntegration } from './integrations/dataloader';
 export { denoKnexIntegration } from './integrations/knex';
+export { denoKoaIntegration } from './integrations/koa';
 export { denoContextIntegration } from './integrations/context';
 export { globalHandlersIntegration } from './integrations/globalhandlers';
 export { normalizePathsIntegration } from './integrations/normalizepaths';

packages/deno/src/integrations/koa.ts

@@ -0,0 +1,31 @@
+import { koaChannelIntegration } from '@sentry/server-utils/orchestrion';
+import type { KoaChannelIntegrationOptions } from '@sentry/server-utils/orchestrion';
+import type { Integration, IntegrationFn } from '@sentry/core';
+import { defineIntegration, extendIntegration } from '@sentry/core';
+import { setAsyncLocalStorageAsyncContextStrategy } from '../async';
+
+const INTEGRATION_NAME = 'DenoKoa' as const;
+
+/**
+ * Create spans for `koa` middleware/router layers under Deno. Requires the
+ * `@sentry/deno/import` loader. Delegates to the shared subscriber in
+ * `@sentry/server-utils`, adding Deno's `AsyncLocalStorage` context strategy so
+ * spans nest under the active HTTP server span.
+ */
+const _denoKoaIntegration = ((options: KoaChannelIntegrationOptions = {}) => {
+  const inner = koaChannelIntegration(options);
+
+  return extendIntegration(inner, {
+    name: INTEGRATION_NAME,
+    setupOnce() {
+      setAsyncLocalStorageAsyncContextStrategy();
+    },
+  });
+}) satisfies IntegrationFn;
+
+export const denoKoaIntegration = defineIntegration(_denoKoaIntegration) as (
+  options?: KoaChannelIntegrationOptions,
+) => Integration & {
+  name: 'DenoKoa';
+  setupOnce: () => void;
+};

packages/deno/src/sdk.ts

@@ -24,6 +24,7 @@ import {
 import { denoServeIntegration } from './integrations/deno-serve';
 import { denoHttpIntegration } from './integrations/http';
 import { denoAmqplibIntegration } from './integrations/amqplib';
+import { denoKoaIntegration } from './integrations/koa';
 import { denoMysqlIntegration } from './integrations/mysql';
 import { denoPostgresIntegration } from './integrations/postgres';
 import { denoRedisIntegration } from './integrations/redis';
@@ -62,7 +63,7 @@ export function getDefaultIntegrations(_options: Options): Integration[] {
     // (or in parallel to) loading the SDK, so we only gate on whether the
     // feature is possible. If they're never loaded, it'll just be a no-op.
     ...(MODULE_REGISTER_HOOKS_SUPPORTED
-      ? [denoMysqlIntegration(), denoPostgresIntegration(), denoAmqplibIntegration()]
+      ? [denoMysqlIntegration(), denoPostgresIntegration(), denoAmqplibIntegration(), denoKoaIntegration()]
       : []),
     contextLinesIntegration(),
     normalizePathsIntegration(),

packages/deno/test/__snapshots__/mod.test.ts.snap

@@ -118,6 +118,7 @@ snapshot[`captureException 1`] = `
       "DenoMysql",
       "DenoPostgres",
       "DenoAmqplib",
+      "DenoKoa",
       "ContextLines",
       "NormalizePaths",
       "GlobalHandlers",
@@ -196,6 +197,7 @@ snapshot[`captureMessage 1`] = `
       "DenoMysql",
       "DenoPostgres",
       "DenoAmqplib",
+      "DenoKoa",
       "ContextLines",
       "NormalizePaths",
       "GlobalHandlers",
@@ -281,6 +283,7 @@ snapshot[`captureMessage twice 1`] = `
       "DenoMysql",
       "DenoPostgres",
       "DenoAmqplib",
+      "DenoKoa",
       "ContextLines",
       "NormalizePaths",
       "GlobalHandlers",
@@ -373,6 +376,7 @@ snapshot[`captureMessage twice 2`] = `
       "DenoMysql",
       "DenoPostgres",
       "DenoAmqplib",
+      "DenoKoa",
       "ContextLines",
       "NormalizePaths",
       "GlobalHandlers",

packages/node/src/integrations/tracing/koa/vendored/utils.ts

@@ -11,7 +11,7 @@ import { KoaLayerType, type KoaInstrumentationConfig } from './types';
 import type { KoaContext, KoaMiddleware } from './internal-types';
 import { AttributeNames } from './enums/AttributeNames';
 import type { Attributes } from '@opentelemetry/api';
-import { HTTP_ROUTE } from '@sentry/conventions/attributes';
+import { CODE_FUNCTION_NAME, HTTP_ROUTE } from '@sentry/conventions/attributes';
 
 export const getMiddlewareMetadata = (
   context: KoaContext,
@@ -25,7 +25,7 @@ export const getMiddlewareMetadata = (
   if (isRouter) {
     return {
       attributes: {
-        [AttributeNames.KOA_NAME]: layerPath?.toString(),
+        [AttributeNames.KOA_NAME]: layerPath?.toString(), // TODO(v11): remove, replaced by http.route
         [AttributeNames.KOA_TYPE]: KoaLayerType.ROUTER,
         [HTTP_ROUTE]: layerPath?.toString(),
       },
@@ -34,8 +34,9 @@ export const getMiddlewareMetadata = (
   } else {
     return {
       attributes: {
-        [AttributeNames.KOA_NAME]: layer.name ?? 'middleware',
+        [AttributeNames.KOA_NAME]: layer.name ?? 'middleware', // TODO(v11): remove, replaced by code.function.name
         [AttributeNames.KOA_TYPE]: KoaLayerType.MIDDLEWARE,
+        [CODE_FUNCTION_NAME]: layer.name ?? 'middleware',
       },
       name: `middleware - ${layer.name}`,
     };