ref(node): Streamline koa

Migrate koa span creation to the @sentry/core API, fold the op/origin/name/transaction-name requestHook into span creation, and remove the vendored files' eslint-disable + no-explicit-any exemption. Extend the node-koa e2e for RegExp/nested routers, middleware dedup, and errored-span status, and port the isLayerIgnored unit test.

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

Author: nicohrubec

.oxlintrc.base.json

@@ -145,7 +145,6 @@
         "**/integrations/fs/vendored/**/*.ts",
         "**/integrations/tracing/knex/vendored/**/*.ts",
         "**/integrations/tracing/mongo/vendored/**/*.ts",
-        "**/integrations/tracing/koa/vendored/**/*.ts",
         "**/integrations/tracing/mysql2/vendored/**/*.ts",
         "**/integration/aws/vendored/**/*.ts",
         "**/integrations/tracing/kafka/vendored/**/*.ts",

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

@@ -115,8 +115,30 @@ router1.post('/test-post', async ctx => {
   ctx.body = { status: 'ok', body: ctx.request.body };
 });
 
+// RegExp route - exercises the @koa/router dispatch patch with a non-string layer path.
+router1.get(/^\/test-regexp/, ctx => {
+  ctx.body = { matched: 'regexp' };
+});
+
+// Same middleware instance passed twice - the second occurrence must be skipped (kLayerPatched dedup).
+const sharedRouteMiddleware = async (ctx, next) => {
+  await next();
+};
+router1.get('/test-dedup', sharedRouteMiddleware, sharedRouteMiddleware, ctx => {
+  ctx.body = { ok: true };
+});
+
 app1.use(router1.routes()).use(router1.allowedMethods());
 
+// Nested router - the routed span's http.route is the composed parent + child path.
+const nestedRouter = new Router();
+nestedRouter.get('/details/:id', ctx => {
+  ctx.body = { id: ctx.params.id };
+});
+const outerRouter = new Router();
+outerRouter.use('/:first', nestedRouter.routes());
+app1.use(outerRouter.routes()).use(outerRouter.allowedMethods());
+
 app1.listen(port1);
 
 const app2 = new Koa();

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

@@ -0,0 +1,99 @@
+import { expect, test } from '@playwright/test';
+import { waitForTransaction } from '@sentry-internal/test-utils';
+
+test('instruments RegExp router routes', async ({ baseURL }) => {
+  const transactionPromise = waitForTransaction('node-koa', transactionEvent => {
+    return (
+      transactionEvent?.contexts?.trace?.op === 'http.server' && !!transactionEvent.transaction?.includes('test-regexp')
+    );
+  });
+
+  await fetch(`${baseURL}/test-regexp`);
+
+  const transactionEvent = await transactionPromise;
+
+  expect(transactionEvent.spans).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        op: 'router.koa',
+        origin: 'auto.http.otel.koa',
+        data: expect.objectContaining({
+          'koa.type': 'router',
+          'sentry.op': 'router.koa',
+          'sentry.origin': 'auto.http.otel.koa',
+          'http.route': '/^\\/test-regexp/',
+        }),
+      }),
+    ]),
+  );
+});
+
+test('instruments nested routers with the composed http.route', async ({ baseURL }) => {
+  const transactionPromise = waitForTransaction('node-koa', transactionEvent => {
+    return (
+      transactionEvent?.contexts?.trace?.op === 'http.server' &&
+      transactionEvent.transaction === 'GET /:first/details/:id'
+    );
+  });
+
+  await fetch(`${baseURL}/shop/details/1`);
+
+  const transactionEvent = await transactionPromise;
+
+  expect(transactionEvent.spans).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        op: 'router.koa',
+        description: '/:first/details/:id',
+        data: expect.objectContaining({
+          'koa.type': 'router',
+          'http.route': '/:first/details/:id',
+          'sentry.op': 'router.koa',
+          'sentry.origin': 'auto.http.otel.koa',
+        }),
+      }),
+    ]),
+  );
+});
+
+test('does not instrument the same middleware twice', async ({ baseURL }) => {
+  const transactionPromise = waitForTransaction('node-koa', transactionEvent => {
+    return (
+      transactionEvent?.contexts?.trace?.op === 'http.server' && transactionEvent.transaction === 'GET /test-dedup'
+    );
+  });
+
+  await fetch(`${baseURL}/test-dedup`);
+
+  const transactionEvent = await transactionPromise;
+
+  // The route stack is [sharedRouteMiddleware, sharedRouteMiddleware, handler]; the repeated
+  // middleware instance is skipped, leaving one span for it plus the handler span.
+  const dedupSpans = transactionEvent.spans?.filter(
+    span => span.op === 'router.koa' && span.description === '/test-dedup',
+  );
+  expect(dedupSpans).toHaveLength(2);
+});
+
+test('marks the layer span as errored when a handler throws', async ({ baseURL }) => {
+  const transactionPromise = waitForTransaction('node-koa', transactionEvent => {
+    return (
+      transactionEvent?.contexts?.trace?.op === 'http.server' &&
+      transactionEvent.transaction === 'GET /test-exception/:id'
+    );
+  });
+
+  await fetch(`${baseURL}/test-exception/123`);
+
+  const transactionEvent = await transactionPromise;
+
+  expect(transactionEvent.spans).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        op: 'router.koa',
+        origin: 'auto.http.otel.koa',
+        status: 'internal_error',
+      }),
+    ]),
+  );
+});

packages/node/src/integrations/tracing/koa/index.ts

@@ -1,18 +1,8 @@
 import type { KoaInstrumentationConfig, KoaLayerType } from './vendored/types';
 import { KoaInstrumentation } from './vendored/instrumentation';
-import { ATTR_HTTP_ROUTE } from '@opentelemetry/semantic-conventions';
 import type { IntegrationFn } from '@sentry/core';
-import {
-  captureException,
-  debug,
-  defineIntegration,
-  getDefaultIsolationScope,
-  getIsolationScope,
-  SEMANTIC_ATTRIBUTE_SENTRY_OP,
-  spanToJSON,
-} from '@sentry/core';
-import { addOriginToSpan, ensureIsWrapped, generateInstrumentOnce } from '@sentry/node-core';
-import { DEBUG_BUILD } from '../../../debug-build';
+import { captureException, defineIntegration } from '@sentry/core';
+import { ensureIsWrapped, generateInstrumentOnce } from '@sentry/node-core';
 
 interface KoaOptions {
   /**
@@ -29,36 +19,6 @@ export const instrumentKoa = generateInstrumentOnce(
   (options: KoaOptions = {}) => {
     return {
       ignoreLayersType: options.ignoreLayersType as KoaLayerType[],
-      requestHook(span, info) {
-        addOriginToSpan(span, 'auto.http.otel.koa');
-
-        const attributes = spanToJSON(span).data;
-
-        // this is one of: middleware, router
-        const type = attributes['koa.type'];
-        if (type) {
-          span.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_OP, `${type}.koa`);
-        }
-
-        // Also update the name
-        const name = attributes['koa.name'];
-        if (typeof name === 'string') {
-          // Somehow, name is sometimes `''` for middleware spans
-          // See: https://github.com/open-telemetry/opentelemetry-js-contrib/issues/2220
-          span.updateName(name || '< unknown >');
-        }
-
-        if (getIsolationScope() === getDefaultIsolationScope()) {
-          DEBUG_BUILD && debug.warn('Isolation scope is default isolation scope - skipping setting transactionName');
-          return;
-        }
-        const route = attributes[ATTR_HTTP_ROUTE];
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
-        const method = info.context?.request?.method?.toUpperCase() || 'GET';
-        if (route) {
-          getIsolationScope().setTransactionName(`${method} ${route}`);
-        }
-      },
     } satisfies KoaInstrumentationConfig;
   },
 );

packages/node/src/integrations/tracing/koa/vendored/enums/AttributeNames.ts

@@ -17,7 +17,6 @@
  * - Vendored from: https://github.com/open-telemetry/opentelemetry-js-contrib/tree/15ef7506553f631ea4181391e0c5725a56f0d082/packages/instrumentation-koa
  * - Upstream version: @opentelemetry/instrumentation-koa@0.66.0
  */
-/* eslint-disable */
 
 export enum AttributeNames {
   KOA_TYPE = 'koa.type',

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

@@ -17,25 +17,43 @@
  * - Vendored from: https://github.com/open-telemetry/opentelemetry-js-contrib/tree/15ef7506553f631ea4181391e0c5725a56f0d082/packages/instrumentation-koa
  * - Upstream version: @opentelemetry/instrumentation-koa@0.66.0
  * - Minor TypeScript strictness adjustments for this repository's compiler settings
+ * - Span creation migrated to the @sentry/core API; op/origin/name and transaction name folded into
+ *   span creation (previously set via a Sentry requestHook)
  */
-/* eslint-disable */
 
 import * as api from '@opentelemetry/api';
+import { isWrapped, InstrumentationBase, InstrumentationNodeModuleDefinition } from '@opentelemetry/instrumentation';
+
+import { KoaLayerType, type KoaInstrumentationConfig } from './types';
 import {
-  isWrapped,
-  InstrumentationBase,
-  InstrumentationNodeModuleDefinition,
-  safeExecuteInTheMiddle,
-} from '@opentelemetry/instrumentation';
-
-import { KoaLayerType, KoaInstrumentationConfig } from './types';
-import { SDK_VERSION } from '@sentry/core';
+  debug,
+  getDefaultIsolationScope,
+  getIsolationScope,
+  SDK_VERSION,
+  SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
+  startSpan,
+} from '@sentry/core';
+import { ATTR_HTTP_ROUTE } from '@opentelemetry/semantic-conventions';
 import { getMiddlewareMetadata, isLayerIgnored } from './utils';
 import { setHttpServerSpanRouteAttribute } from '../../../../utils/setHttpServerSpanRouteAttribute';
-import { Next, kLayerPatched, KoaContext, KoaMiddleware, KoaPatchedMiddleware } from './internal-types';
+import { DEBUG_BUILD } from '../../../../debug-build';
+import { AttributeNames } from './enums/AttributeNames';
+import {
+  kLayerPatched,
+  type Next,
+  type KoaContext,
+  type KoaMiddleware,
+  type KoaPatchedMiddleware,
+} from './internal-types';
 
 const PACKAGE_NAME = '@sentry/instrumentation-koa';
 
+interface KoaModuleExports {
+  prototype: { use: KoaMiddleware };
+}
+
+type KoaModule = KoaModuleExports & { [Symbol.toStringTag]?: string; default?: KoaModuleExports };
+
 /** Koa instrumentation for OpenTelemetry */
 export class KoaInstrumentation extends InstrumentationBase<KoaInstrumentationConfig> {
   constructor(config: KoaInstrumentationConfig = {}) {
@@ -46,11 +64,8 @@ export class KoaInstrumentation extends InstrumentationBase<KoaInstrumentationCo
     return new InstrumentationNodeModuleDefinition(
       'koa',
       ['>=2.0.0 <4'],
-      (module: any) => {
-        const moduleExports: any =
-          module[Symbol.toStringTag] === 'Module'
-            ? module.default // ESM
-            : module; // CommonJS
+      (module: KoaModule) => {
+        const moduleExports = module[Symbol.toStringTag] === 'Module' ? module.default : module;
         if (moduleExports == null) {
           return moduleExports;
         }
@@ -60,12 +75,9 @@ export class KoaInstrumentation extends InstrumentationBase<KoaInstrumentationCo
         this._wrap(moduleExports.prototype, 'use', this._getKoaUsePatch.bind(this));
         return module;
       },
-      (module: any) => {
-        const moduleExports: any =
-          module[Symbol.toStringTag] === 'Module'
-            ? module.default // ESM
-            : module; // CommonJS
-        if (isWrapped(moduleExports.prototype.use)) {
+      (module: KoaModule) => {
+        const moduleExports = module[Symbol.toStringTag] === 'Module' ? module.default : module;
+        if (moduleExports && isWrapped(moduleExports.prototype.use)) {
           this._unwrap(moduleExports.prototype, 'use');
         }
       },
@@ -77,15 +89,13 @@ export class KoaInstrumentation extends InstrumentationBase<KoaInstrumentationCo
    * middleware layer which is introduced
    * @param {KoaMiddleware} middleware - the original middleware function
    */
-  private _getKoaUsePatch(original: (middleware: KoaMiddleware) => any) {
-    const plugin = this;
-    return function use(this: any, middlewareFunction: KoaMiddleware) {
-      let patchedFunction: KoaMiddleware;
-      if (middlewareFunction.router) {
-        patchedFunction = plugin._patchRouterDispatch(middlewareFunction);
-      } else {
-        patchedFunction = plugin._patchLayer(middlewareFunction, false);
-      }
+  private _getKoaUsePatch(original: (middleware: KoaMiddleware) => unknown) {
+    const patchRouterDispatch = this._patchRouterDispatch.bind(this);
+    const patchLayer = this._patchLayer.bind(this);
+    return function use(this: unknown, middlewareFunction: KoaMiddleware) {
+      const patchedFunction = middlewareFunction.router
+        ? patchRouterDispatch(middlewareFunction)
+        : patchLayer(middlewareFunction, false);
       return original.apply(this, [patchedFunction]);
     };
   }
@@ -107,9 +117,9 @@ export class KoaInstrumentation extends InstrumentationBase<KoaInstrumentationCo
       const path = pathLayer.path;
       // Type cast needed: router.stack comes from @types/koa@2.x but we use @types/koa@3.x
       // See internal-types.ts for full explanation
-      const pathStack = pathLayer.stack as any;
+      const pathStack = pathLayer.stack as KoaMiddleware[];
       for (let j = 0; j < pathStack.length; j++) {
-        const routedMiddleware: KoaMiddleware = pathStack[j];
+        const routedMiddleware = pathStack[j] as KoaMiddleware;
         pathStack[j] = this._patchLayer(routedMiddleware, true, path);
       }
     }
@@ -146,49 +156,40 @@ export class KoaInstrumentation extends InstrumentationBase<KoaInstrumentationCo
     middlewareLayer[kLayerPatched] = true;
 
     api.diag.debug('patching Koa middleware layer');
-    return async (context: KoaContext, next: Next) => {
+    return (context: KoaContext, next: Next) => {
       const parent = api.trace.getSpan(api.context.active());
       if (parent === undefined) {
         return middlewareLayer(context, next);
       }
       const metadata = getMiddlewareMetadata(context, middlewareLayer, isRouter, layerPath);
-      const span = this.tracer.startSpan(metadata.name, {
-        attributes: metadata.attributes,
-      });
 
       if (context._matchedRoute) {
         setHttpServerSpanRouteAttribute(context._matchedRoute.toString());
       }
 
-      const { requestHook } = this.getConfig();
-      if (requestHook) {
-        safeExecuteInTheMiddle(
-          () =>
-            requestHook(span, {
-              context,
-              middlewareLayer,
-              layerType,
-            }),
-          e => {
-            if (e) {
-              api.diag.error('koa instrumentation: request hook failed', e);
-            }
-          },
-          true,
-        );
-      }
+      const koaName = metadata.attributes[AttributeNames.KOA_NAME];
+      const name = typeof koaName === 'string' ? koaName || '< unknown >' : metadata.name;
 
-      const newContext = api.trace.setSpan(api.context.active(), span);
-      return api.context.with(newContext, async () => {
-        try {
-          return await middlewareLayer(context, next);
-        } catch (err: any) {
-          span.recordException(err);
-          throw err;
-        } finally {
-          span.end();
-        }
-      });
+      return startSpan(
+        {
+          name,
+          op: `${layerType}.koa`,
+          attributes: {
+            ...metadata.attributes,
+            [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.http.otel.koa',
+          },
+        },
+        () => {
+          const route = metadata.attributes[ATTR_HTTP_ROUTE];
+          if (getIsolationScope() === getDefaultIsolationScope()) {
+            DEBUG_BUILD && debug.warn('Isolation scope is default isolation scope - skipping setting transactionName');
+          } else if (route) {
+            const method = (context.request as { method?: string } | undefined)?.method?.toUpperCase() || 'GET';
+            getIsolationScope().setTransactionName(`${method} ${route}`);
+          }
+          return middlewareLayer(context, next);
+        },
+      );
     };
   }
 }