feat(instrumentations-ioredis): support net.* and database semconv migration (#3266)

Author: trentm

package-lock.json

@@ -100,17 +100,27 @@ requestHook: function (
 
 ## Semantic Conventions
 
-This package uses `@opentelemetry/semantic-conventions` version `1.22+`, which implements Semantic Convention [Version 1.7.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.7.0/semantic_conventions/README.md)
+This instrumentation implements Semantic Conventions (semconv) v1.7.0. Since then, networking (in semconv v1.23.1) and database (in semconv v1.33.0) semantic conventions were stabilized. As of `@opentelemetry/[email protected]` support has been added for migrating to the stable semantic conventions using the `OTEL_SEMCONV_STABILITY_OPT_IN` environment variable as follows:
+
+1. Upgrade to the latest version of this instrumentation package.
+2. Set `OTEL_SEMCONV_STABILITY_OPT_IN=http/dup,database/dup` to emit both old and stable semantic conventions. (The `http` token is used to control the `net.*` attributes, the `database` token to control to `db.*` attributes.)
+3. Modify alerts, dashboards, metrics, and other processes in your Observability system to use the stable semantic conventions.
+4. Set `OTEL_SEMCONV_STABILITY_OPT_IN=http,database` to emit only the stable semantic conventions.
+
+By default, if `OTEL_SEMCONV_STABILITY_OPT_IN` includes neither of the above tokens, the old v1.7.0 semconv is used.
+The intent is to provide an approximate 6 month time window for users of this instrumentation to migrate to the new database and networking semconv, after which a new minor version will use the new semconv by default and drop support for the old semconv.
+See [the HTTP migration guide](https://opentelemetry.io/docs/specs/semconv/non-normative/http-migration/) and the [database migration guide](https://opentelemetry.io/docs/specs/semconv/non-normative/db-migration/) for details.
 
 Attributes collected:
 
-| Attribute              | Short Description                                                           |
-| ---------------------- | --------------------------------------------------------------------------- |
-| `db.connection_string` | The connection string used to connect to the database.                      |
-| `db.statement`         | The database statement being executed.                                      |
-| `db.system`            | An identifier for the database management system (DBMS) product being used. |
-| `net.peer.name`        | Remote hostname or similar.                                                 |
-| `net.peer.port`        | Remote port number.                                                         |
+| Old semconv            | Stable semconv   | Description                        |
+| ---------------------- | ---------------- | ---------------------------------- |
+| `db.connection_string` | Removed          |                                    |
+| `db.system`            | `db.system.name` | 'redis'                            |
+| `db.statement`         | `db.query.text`  | The database query being executed. |
+| `net.peer.port`        | `server.port`    | Remote port number.                |
+| `net.peer.name`        | `server.address` | Remote hostname or similar.        |
+
 
 ## Useful links
 

packages/instrumentation-ioredis/README.md

@@ -56,13 +56,13 @@
     "@opentelemetry/contrib-test-utils": "^0.55.0",
     "@opentelemetry/sdk-trace-base": "^2.0.0",
     "@opentelemetry/sdk-trace-node": "^2.0.0",
-    "@opentelemetry/semantic-conventions": "^1.27.0",
     "@types/ioredis4": "npm:@types/[email protected]",
     "ioredis": "5.8.2"
   },
   "dependencies": {
     "@opentelemetry/instrumentation": "^0.208.0",
-    "@opentelemetry/redis-common": "^0.38.2"
+    "@opentelemetry/redis-common": "^0.38.2",
+    "@opentelemetry/semantic-conventions": "^1.33.0"
   },
   "homepage": "https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/packages/instrumentation-ioredis#readme"
 }

packages/instrumentation-ioredis/package.json

@@ -14,16 +14,25 @@
  * limitations under the License.
  */
 
-import { diag, trace, context, SpanKind } from '@opentelemetry/api';
+import { diag, trace, context, SpanKind, type Attributes } from '@opentelemetry/api';
 import {
   InstrumentationBase,
   InstrumentationNodeModuleDefinition,
   isWrapped,
+  SemconvStability,
+  semconvStabilityFromStr,
 } from '@opentelemetry/instrumentation';
 import { IORedisInstrumentationConfig } from './types';
 import { IORedisCommand, RedisInterface } from './internal-types';
+import {
+  ATTR_DB_QUERY_TEXT,
+  ATTR_DB_SYSTEM_NAME,
+  ATTR_SERVER_ADDRESS,
+  ATTR_SERVER_PORT,
+} from '@opentelemetry/semantic-conventions';
 import {
   DB_SYSTEM_VALUE_REDIS,
+  DB_SYSTEM_NAME_VALUE_REDIS,
   ATTR_DB_CONNECTION_STRING,
   ATTR_DB_STATEMENT,
   ATTR_DB_SYSTEM,
@@ -41,8 +50,24 @@ const DEFAULT_CONFIG: IORedisInstrumentationConfig = {
 };
 
 export class IORedisInstrumentation extends InstrumentationBase<IORedisInstrumentationConfig> {
+  private _netSemconvStability!: SemconvStability;
+  private _dbSemconvStability!: SemconvStability;
+
   constructor(config: IORedisInstrumentationConfig = {}) {
     super(PACKAGE_NAME, PACKAGE_VERSION, { ...DEFAULT_CONFIG, ...config });
+    this._setSemconvStabilityFromEnv();
+  }
+
+  // Used for testing.
+  private _setSemconvStabilityFromEnv() {
+    this._netSemconvStability = semconvStabilityFromStr(
+      'http',
+      process.env.OTEL_SEMCONV_STABILITY_OPT_IN
+    );
+    this._dbSemconvStability = semconvStabilityFromStr(
+      'database',
+      process.env.OTEL_SEMCONV_STABILITY_OPT_IN
+    );
   }
 
   override setConfig(config: IORedisInstrumentationConfig = {}) {
@@ -120,12 +145,29 @@ export class IORedisInstrumentation extends InstrumentationBase<IORedisInstrumen
         return original.apply(this, arguments);
       }
 
+      const attributes: Attributes = {};
+      const { host, port } = this.options;
+      const dbQueryText = dbStatementSerializer(cmd.name, cmd.args);
+      if (instrumentation._dbSemconvStability & SemconvStability.OLD) {
+        attributes[ATTR_DB_SYSTEM] = DB_SYSTEM_VALUE_REDIS;
+        attributes[ATTR_DB_STATEMENT] = dbQueryText;
+        attributes[ATTR_DB_CONNECTION_STRING] = `redis://${host}:${port}`;
+      }
+      if (instrumentation._dbSemconvStability & SemconvStability.STABLE) {
+        attributes[ATTR_DB_SYSTEM_NAME] = DB_SYSTEM_NAME_VALUE_REDIS;
+        attributes[ATTR_DB_QUERY_TEXT] = dbQueryText;
+      }
+      if (instrumentation._netSemconvStability & SemconvStability.OLD) {
+        attributes[ATTR_NET_PEER_NAME] = host;
+        attributes[ATTR_NET_PEER_PORT] = port;
+      }
+      if (instrumentation._netSemconvStability & SemconvStability.STABLE) {
+        attributes[ATTR_SERVER_ADDRESS] = host;
+        attributes[ATTR_SERVER_PORT] = port;
+      }
       const span = instrumentation.tracer.startSpan(cmd.name, {
         kind: SpanKind.CLIENT,
-        attributes: {
-          [ATTR_DB_SYSTEM]: DB_SYSTEM_VALUE_REDIS,
-          [ATTR_DB_STATEMENT]: dbStatementSerializer(cmd.name, cmd.args),
-        },
+        attributes,
       });
 
       const { requestHook } = config;
@@ -146,13 +188,6 @@ export class IORedisInstrumentation extends InstrumentationBase<IORedisInstrumen
         );
       }
 
-      const { host, port } = this.options;
-
-      span.setAttributes({
-        [ATTR_NET_PEER_NAME]: host,
-        [ATTR_NET_PEER_PORT]: port,
-        [ATTR_DB_CONNECTION_STRING]: `redis://${host}:${port}`,
-      });
 
       try {
         const result = original.apply(this, arguments);
@@ -199,20 +234,30 @@ export class IORedisInstrumentation extends InstrumentationBase<IORedisInstrumen
         return original.apply(this, arguments);
       }
 
+      const attributes: Attributes = {};
+      const { host, port } = this.options;
+      if (instrumentation._dbSemconvStability & SemconvStability.OLD) {
+        attributes[ATTR_DB_SYSTEM] = DB_SYSTEM_VALUE_REDIS;
+        attributes[ATTR_DB_STATEMENT] = 'connect';
+        attributes[ATTR_DB_CONNECTION_STRING] = `redis://${host}:${port}`;
+      }
+      if (instrumentation._dbSemconvStability & SemconvStability.STABLE) {
+        attributes[ATTR_DB_SYSTEM_NAME] = DB_SYSTEM_NAME_VALUE_REDIS;
+        attributes[ATTR_DB_QUERY_TEXT] = 'connect';
+      }
+      if (instrumentation._netSemconvStability & SemconvStability.OLD) {
+        attributes[ATTR_NET_PEER_NAME] = host;
+        attributes[ATTR_NET_PEER_PORT] = port;
+      }
+      if (instrumentation._netSemconvStability & SemconvStability.STABLE) {
+        attributes[ATTR_SERVER_ADDRESS] = host;
+        attributes[ATTR_SERVER_PORT] = port;
+      }
       const span = instrumentation.tracer.startSpan('connect', {
         kind: SpanKind.CLIENT,
-        attributes: {
-          [ATTR_DB_SYSTEM]: DB_SYSTEM_VALUE_REDIS,
-          [ATTR_DB_STATEMENT]: 'connect',
-        },
+        attributes,
       });
-      const { host, port } = this.options;
 
-      span.setAttributes({
-        [ATTR_NET_PEER_NAME]: host,
-        [ATTR_NET_PEER_PORT]: port,
-        [ATTR_DB_CONNECTION_STRING]: `redis://${host}:${port}`,
-      });
       try {
         const client = original.apply(this, arguments);
         endSpan(span, null);

packages/instrumentation-ioredis/src/instrumentation.ts

@@ -74,6 +74,15 @@ export const ATTR_NET_PEER_NAME = 'net.peer.name' as const;
  */
 export const ATTR_NET_PEER_PORT = 'net.peer.port' as const;
 
+/**
+ * Enum value "redis" for attribute {@link ATTR_DB_SYSTEM_NAME}.
+ *
+ * [Redis](https://redis.io/)
+ *
+ * @experimental This enum value is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`.
+ */
+export const DB_SYSTEM_NAME_VALUE_REDIS = 'redis' as const;
+
 /**
  * Enum value "redis" for attribute {@link ATTR_DB_SYSTEM}.
  *