feat(express): allow rewriting span names (open-telemetry#463)

plugins/node/opentelemetry-instrumentation-express/README.md

@@ -62,6 +62,7 @@ Express instrumentation has few options available to choose from. You can set th
 | ------- | ---- | ------- | ----------- |
 | `ignoreLayers` | `IgnoreMatcher[]` | `[/^\/_internal\//]` | Ignore layers that by match. |
 | `ignoreLayersType`| `ExpressLayerType[]` | `['request_handler']` | Ignore layers of specified type. |
+| `spanNameHook` | `SpanNameHook` | `() => 'my-span-name'` | Can be used to customize span names by returning a new name from the hook. |
 
 `ignoreLayers` accepts an array of elements of types:
 
@@ -75,6 +76,11 @@ Express instrumentation has few options available to choose from. You can set th
 - `middleware`,
 - `request_handler` is the name for anything that's not a router or a middleware.
 
+`spanNameHook` is invoked with 2 arguments:
+
+- `info: ExpressRequestInfo` containing the incoming Express.js request, the current route handler creating a span and `ExpressLayerType` - the type of the handling layer or undefined when renaming the root HTTP instrumentation span.
+- `defaultName: string` - original name proposed by the instrumentation.
+
 ## Useful links
 
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>

plugins/node/opentelemetry-instrumentation-express/package.json

@@ -6,7 +6,7 @@
   "types": "build/src/index.d.ts",
   "repository": "open-telemetry/opentelemetry-js-contrib",
   "scripts": {
-    "test": "nyc ts-mocha -p tsconfig.json 'test/**/*.ts'",
+    "test": "nyc ts-mocha -p tsconfig.json 'test/**/*.test.ts'",
     "codecov": "nyc report --reporter=json && codecov -f coverage/*.json -p ../../",
     "tdd": "yarn test -- --watch-extensions ts --watch",
     "clean": "rimraf build/*",

plugins/node/opentelemetry-instrumentation-express/src/instrumentation.ts

@@ -21,13 +21,14 @@ import {
   RPCType,
 } from '@opentelemetry/core';
 import { trace, context, diag, SpanAttributes } from '@opentelemetry/api';
-import * as express from 'express';
+import type * as express from 'express';
 import {
   ExpressLayer,
   ExpressRouter,
   PatchedRequest,
   _LAYERS_STORE_PROPERTY,
   ExpressInstrumentationConfig,
+  ExpressRequestInfo,
 } from './types';
 import { ExpressLayerType } from './enums/ExpressLayerType';
 import { AttributeNames } from './enums/AttributeNames';
@@ -58,6 +59,14 @@ export class ExpressInstrumentation extends InstrumentationBase<
     );
   }
 
+  override setConfig(config: ExpressInstrumentationConfig = {}) {
+    this._config = Object.assign({}, config);
+  }
+
+  override getConfig(): ExpressInstrumentationConfig {
+    return this._config as ExpressInstrumentationConfig;
+  }
+
   init() {
     return [
       new InstrumentationNodeModuleDefinition<typeof express>(
@@ -202,9 +211,14 @@ export class ExpressInstrumentation extends InstrumentationBase<
             ExpressLayerType.REQUEST_HANDLER &&
           rpcMetadata?.type === RPCType.HTTP
         ) {
-          rpcMetadata.span.updateName(
+          const name = instrumentation._getSpanName(
+            {
+              request: req,
+              route,
+            },
             `${req.method} ${route.length > 0 ? route : '/'}`
           );
+          rpcMetadata.span.updateName(name);
         }
 
         // verify against the config if the layer should be ignored
@@ -218,7 +232,15 @@ export class ExpressInstrumentation extends InstrumentationBase<
           return original.apply(this, arguments);
         }
 
-        const span = instrumentation.tracer.startSpan(metadata.name, {
+        const spanName = instrumentation._getSpanName(
+          {
+            request: req,
+            layerType: type,
+            route,
+          },
+          metadata.name
+        );
+        const span = instrumentation.tracer.startSpan(spanName, {
           attributes: Object.assign(attributes, metadata.attributes),
         });
         const startTime = hrTime();
@@ -277,4 +299,22 @@ export class ExpressInstrumentation extends InstrumentationBase<
       };
     });
   }
+
+  _getSpanName(info: ExpressRequestInfo, defaultName: string) {
+    const hook = this.getConfig().spanNameHook;
+
+    if (!(hook instanceof Function)) {
+      return defaultName;
+    }
+
+    try {
+      return hook(info, defaultName) ?? defaultName;
+    } catch (err) {
+      diag.error(
+        'express instrumentation: error calling span name rewrite hook',
+        err
+      );
+      return defaultName;
+    }
+  }
 }

plugins/node/opentelemetry-instrumentation-express/src/types.ts

@@ -70,6 +70,24 @@ export type LayerMetadata = {
 
 export type IgnoreMatcher = string | RegExp | ((name: string) => boolean);
 
+export type ExpressRequestInfo = {
+  request: Request;
+  route: string;
+  /**
+   * If layerType is undefined, SpanNameHook is being invoked to rename the original root HTTP span.
+   */
+  layerType?: ExpressLayerType;
+};
+
+export type SpanNameHook = (
+  info: ExpressRequestInfo,
+  /**
+   * If no decision is taken based on RequestInfo, the default name
+   * supplied by the instrumentation can be used instead.
+   */
+  defaultName: string
+) => string;
+
 /**
  * Options available for the Express Instrumentation (see [documentation](https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-Instrumentation-express#express-Instrumentation-options))
  */
@@ -78,4 +96,5 @@ export interface ExpressInstrumentationConfig extends InstrumentationConfig {
   ignoreLayers?: IgnoreMatcher[];
   /** Ignore specific layers based on their type */
   ignoreLayersType?: ExpressLayerType[];
+  spanNameHook?: SpanNameHook;
 }

plugins/node/opentelemetry-instrumentation-express/test/custom-config.test.ts

@@ -27,6 +27,7 @@ import { RPCType, setRPCMetadata } from '@opentelemetry/core';
 import { ExpressLayerType } from '../src/enums/ExpressLayerType';
 import { AttributeNames } from '../src/enums/AttributeNames';
 import { ExpressInstrumentation, ExpressInstrumentationConfig } from '../src';
+import { createServer, httpRequest } from './utils';
 
 const instrumentation = new ExpressInstrumentation({
   ignoreLayersType: [ExpressLayerType.MIDDLEWARE],
@@ -36,26 +37,6 @@ instrumentation.disable();
 
 import * as express from 'express';
 import * as http from 'http';
-import { AddressInfo } from 'net';
-
-const httpRequest = {
-  get: (options: http.ClientRequestArgs | string) => {
-    return new Promise((resolve, reject) => {
-      return http.get(options, resp => {
-        let data = '';
-        resp.on('data', chunk => {
-          data += chunk;
-        });
-        resp.on('end', () => {
-          resolve(data);
-        });
-        resp.on('error', err => {
-          reject(err);
-        });
-      });
-    });
-  },
-};
 
 describe('ExpressInstrumentation', () => {
   const provider = new NodeTracerProvider();
@@ -84,9 +65,9 @@ describe('ExpressInstrumentation', () => {
 
     beforeEach(async () => {
       app = express();
-      server = http.createServer(app);
-      await new Promise<void>(resolve => server.listen(0, resolve));
-      port = (server.address() as AddressInfo).port;
+      const httpServer = await createServer(app);
+      server = httpServer.server;
+      port = httpServer.port;
     });
 
     afterEach(() => {