feat(instrumentation-nestjs-core): support migration to stable HTTP semconv (#3080)

Author: trentm

packages/instrumentation-nestjs-core/README.md

@@ -62,12 +62,37 @@ Attributes collected:
 | `nestjs.module`     | Nest module class name                             |
 | `nestjs.controller` | Nest controller class name                         |
 | `nestjs.callback`   | The function name of the member in the controller  |
-| `http.method`       | HTTP method                                        |
-| `http.url`          | Full request URL                                   |
 | `http.route`        | Route assigned to handler. Ex: `/users/:id`        |
+| `http.method` / `http.request.method` | HTTP method. See "HTTP Semantic Convention migration" note below. |
+| `http.url` / `url.full` | Full request URL. See "HTTP Semantic Convention migration" note below. |
 
 \* included in all of the spans.
 
+### HTTP Semantic Convention migration
+
+HTTP semantic conventions (semconv) were stabilized in v1.23.0, and a [migration process](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/non-normative/http-migration.md#http-semantic-convention-stability-migration)
+was defined.  This instrumentations adds some minimal HTTP-related
+attributes on created spans. Starting with `instrumentation-nestjs-core` version
+0.52.0, the `OTEL_SEMCONV_STABILITY_OPT_IN` environment variable can be used to
+customize which HTTP semantic conventions are used for those HTTP-related
+attributes.
+
+To select which semconv version(s) is emitted from this instrumentation, use the
+`OTEL_SEMCONV_STABILITY_OPT_IN` environment variable.
+
+- `http`: emit the new (stable) v1.23.0+ semantics
+- `http/dup`: emit **both** the old v1.7.0 and the new (stable) v1.23.0+ semantics
+- By default, if `OTEL_SEMCONV_STABILITY_OPT_IN` includes neither of the above tokens, the old v1.7.0 semconv is used.
+
+For this instrumentation, the only impacted attributes are as follows:
+
+| v1.7.0 semconv | v1.23.0 semconv       |
+| -------------- | --------------------- |
+| `http.method`  | `http.request.method` |
+| `http.url`     | `url.full`            |
+
+See the [HTTP semconv migration plan for OpenTelemetry JS instrumentations](https://github.com/open-telemetry/opentelemetry-js/issues/5646) for more details.
+
 ## Useful links
 
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>

packages/instrumentation-nestjs-core/src/instrumentation.ts

@@ -21,8 +21,14 @@ import {
   InstrumentationNodeModuleDefinition,
   InstrumentationNodeModuleFile,
   isWrapped,
+  SemconvStability,
+  semconvStabilityFromStr,
 } from '@opentelemetry/instrumentation';
-import { ATTR_HTTP_ROUTE } from '@opentelemetry/semantic-conventions';
+import {
+  ATTR_HTTP_REQUEST_METHOD,
+  ATTR_HTTP_ROUTE,
+  ATTR_URL_FULL,
+} from '@opentelemetry/semantic-conventions';
 import type { NestFactory } from '@nestjs/core/nest-factory.js';
 import type { RouterExecutionContext } from '@nestjs/core/router/router-execution-context.js';
 import type { Controller } from '@nestjs/common/interfaces';
@@ -39,8 +45,14 @@ export class NestInstrumentation extends InstrumentationBase {
     component: NestInstrumentation.COMPONENT,
   };
 
+  private _semconvStability: SemconvStability;
+
   constructor(config: InstrumentationConfig = {}) {
     super(PACKAGE_NAME, PACKAGE_VERSION, config);
+    this._semconvStability = semconvStabilityFromStr(
+      'http',
+      process.env.OTEL_SEMCONV_STABILITY_OPT_IN
+    );
   }
 
   init() {
@@ -83,7 +95,11 @@ export class NestInstrumentation extends InstrumentationBase {
         this.ensureWrapped(
           RouterExecutionContext.RouterExecutionContext.prototype,
           'create',
-          createWrapCreateHandler(this.tracer, moduleVersion)
+          createWrapCreateHandler(
+            this.tracer,
+            moduleVersion,
+            this._semconvStability
+          )
         );
         return RouterExecutionContext;
       },
@@ -141,7 +157,11 @@ function createWrapNestFactoryCreate(
   };
 }
 
-function createWrapCreateHandler(tracer: api.Tracer, moduleVersion?: string) {
+function createWrapCreateHandler(
+  tracer: api.Tracer,
+  moduleVersion: string | undefined,
+  semconvStability: SemconvStability
+) {
   return function wrapCreateHandler(
     original: RouterExecutionContext['create']
   ) {
@@ -167,19 +187,24 @@ function createWrapCreateHandler(tracer: api.Tracer, moduleVersion?: string) {
         res: any,
         next: (...args: any[]) => unknown
       ) {
-        const span = tracer.startSpan(spanName, {
-          attributes: {
-            ...NestInstrumentation.COMMON_ATTRIBUTES,
-            [AttributeNames.VERSION]: moduleVersion,
-            [AttributeNames.TYPE]: NestType.REQUEST_CONTEXT,
-            [ATTR_HTTP_METHOD]: req.method,
-            [ATTR_HTTP_URL]: req.originalUrl || req.url,
-            [ATTR_HTTP_ROUTE]:
-              req.route?.path || req.routeOptions?.url || req.routerPath,
-            [AttributeNames.CONTROLLER]: instanceName,
-            [AttributeNames.CALLBACK]: callbackName,
-          },
-        });
+        const attributes: api.Attributes = {
+          ...NestInstrumentation.COMMON_ATTRIBUTES,
+          [AttributeNames.VERSION]: moduleVersion,
+          [AttributeNames.TYPE]: NestType.REQUEST_CONTEXT,
+          [ATTR_HTTP_ROUTE]:
+            req.route?.path || req.routeOptions?.url || req.routerPath,
+          [AttributeNames.CONTROLLER]: instanceName,
+          [AttributeNames.CALLBACK]: callbackName,
+        };
+        if (semconvStability & SemconvStability.OLD) {
+          attributes[ATTR_HTTP_METHOD] = req.method;
+          attributes[ATTR_HTTP_URL] = req.originalUrl || req.url;
+        }
+        if (semconvStability & SemconvStability.STABLE) {
+          attributes[ATTR_HTTP_REQUEST_METHOD] = req.method;
+          attributes[ATTR_URL_FULL] = req.originalUrl || req.url;
+        }
+        const span = tracer.startSpan(spanName, { attributes });
         const spanContext = api.trace.setSpan(api.context.active(), span);
 
         return api.context.with(spanContext, async () => {

packages/instrumentation-nestjs-core/test/index.test.ts

@@ -31,6 +31,12 @@ import * as util from 'util';
 
 const LIB_VERSION = require('@nestjs/core/package.json').version;
 
+// This is a meagre testing of just a single value of
+// OTEL_SEMCONV_STABILITY_OPT_IN, because testing multiple configurations of
+// `NestInstrumentation` in this all-in-one-process is more trouble than it
+// it is worth for the ~6mo migration process.
+process.env.OTEL_SEMCONV_STABILITY_OPT_IN = 'http/dup';
+
 const instrumentation = new NestInstrumentation();
 const memoryExporter = new InMemorySpanExporter();
 
@@ -215,8 +221,17 @@ const assertSpans = (actualSpans: any[], expectedSpans: any[]) => {
 
       assert.strictEqual(span.name, expected.name);
 
+      // Because OTEL_SEMCONV_STABILITY_OPT_IN=http/dup is being set for testing
+      // we expect both the deprecated:
       assert.strictEqual(span.attributes['http.method'], expected.method);
       assert.strictEqual(span.attributes['http.url'], expected.url);
+      // ... and stable HTTP semconv attributes:
+      assert.strictEqual(
+        span.attributes['http.request.method'],
+        expected.method
+      );
+      assert.strictEqual(span.attributes['url.full'], expected.url);
+
       assert.strictEqual(span.attributes['http.route'], expected.path);
       assert.strictEqual(span.attributes['nestjs.type'], expected.type);
       assert.strictEqual(span.attributes['nestjs.callback'], expected.callback);