feat(instr-cassandra-driver): support net.* and db semconv migration (#3302)

Author: JamieDanielson

package-lock.json

@@ -51,18 +51,27 @@ await client.execute('select * from foo');
 
 ## 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)
-
-Attributes collected:
-
-| Attribute               | Short Description                                                              |
-| ----------------------- | ------------------------------------------------------------------------------ |
-| `db.name`               | This attribute is used to report the name of the database being accessed.      |
-| `db.statement`          | The database statement being executed.                                         |
-| `db.system`             | An identifier for the database management system (DBMS) product being used.    |
-| `db.user`               | Username for accessing the database.                                           |
-| `net.peer.name`         | Remote hostname or similar.                                                    |
-| `net.peer.port`         | Remote port number.                                                            |
+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 the `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
+
+| Old semconv     | Stable semconv   | Description                             |
+| --------------- | ---------------- | --------------------------------------- |
+| `db.system`     | `db.system.name` | Database system identifier (cassandra). |
+| `db.statement`  | `db.query.text`  | The database query being executed.      |
+| `db.name`       | `db.namespace`   | The keyspace being accessed.            |
+| `db.user`       | _(removed)_      | Username for accessing the database.    |
+| `net.peer.name` | `server.address` | Remote hostname or similar.             |
+| `net.peer.port` | `server.port`    | Remote port number.                     |
 
 ## Useful links
 

packages/instrumentation-cassandra-driver/README.md

@@ -55,11 +55,11 @@
     "@opentelemetry/contrib-test-utils": "^0.56.0",
     "@opentelemetry/sdk-trace-base": "^2.0.0",
     "@opentelemetry/sdk-trace-node": "^2.0.0",
-    "@opentelemetry/semantic-conventions": "^1.37.0",
     "cassandra-driver": "4.6.4"
   },
   "dependencies": {
-    "@opentelemetry/instrumentation": "^0.208.0"
+    "@opentelemetry/instrumentation": "^0.208.0",
+    "@opentelemetry/semantic-conventions": "^1.37.0"
   },
   "homepage": "https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/packages/instrumentation-cassandra-driver#readme"
 }

packages/instrumentation-cassandra-driver/package.json

@@ -28,6 +28,8 @@ import {
   InstrumentationNodeModuleFile,
   isWrapped,
   safeExecuteInTheMiddle,
+  SemconvStability,
+  semconvStabilityFromStr,
 } from '@opentelemetry/instrumentation';
 import { CassandraDriverInstrumentationConfig, ResultSet } from './types';
 import {
@@ -38,7 +40,15 @@ import {
   ATTR_DB_USER,
   ATTR_NET_PEER_NAME,
   ATTR_NET_PEER_PORT,
+  DB_SYSTEM_NAME_VALUE_CASSANDRA,
 } from './semconv';
+import {
+  ATTR_DB_NAMESPACE,
+  ATTR_DB_QUERY_TEXT,
+  ATTR_DB_SYSTEM_NAME,
+  ATTR_SERVER_ADDRESS,
+  ATTR_SERVER_PORT,
+} from '@opentelemetry/semantic-conventions';
 /** @knipignore */
 import { PACKAGE_NAME, PACKAGE_VERSION } from './version';
 import { EventEmitter } from 'events';
@@ -47,8 +57,23 @@ import type * as CassandraDriver from 'cassandra-driver';
 const supportedVersions = ['>=4.4.0 <5'];
 
 export class CassandraDriverInstrumentation extends InstrumentationBase<CassandraDriverInstrumentationConfig> {
+  private _netSemconvStability!: SemconvStability;
+  private _dbSemconvStability!: SemconvStability;
+
   constructor(config: CassandraDriverInstrumentationConfig = {}) {
     super(PACKAGE_NAME, PACKAGE_VERSION, config);
+    this._setSemconvStabilityFromEnv();
+  }
+
+  private _setSemconvStabilityFromEnv() {
+    this._netSemconvStability = semconvStabilityFromStr(
+      'http',
+      process.env.OTEL_SEMCONV_STABILITY_OPT_IN
+    );
+    this._dbSemconvStability = semconvStabilityFromStr(
+      'database',
+      process.env.OTEL_SEMCONV_STABILITY_OPT_IN
+    );
   }
 
   protected init() {
@@ -166,6 +191,7 @@ export class CassandraDriverInstrumentation extends InstrumentationBase<Cassandr
 
   private _getPatchedSendOnConnection() {
     return (original: (...args: unknown[]) => unknown) => {
+      const plugin = this;
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       return function patchedSendOnConnection(this: any, ...args: unknown[]) {
         const span = trace.getSpan(context.active());
@@ -174,10 +200,17 @@ export class CassandraDriverInstrumentation extends InstrumentationBase<Cassandr
         if (span !== undefined && conn !== undefined) {
           const port = parseInt(conn.port, 10);
 
-          span.setAttribute(ATTR_NET_PEER_NAME, conn.address);
-
-          if (!isNaN(port)) {
-            span.setAttribute(ATTR_NET_PEER_PORT, port);
+          if (plugin._netSemconvStability & SemconvStability.OLD) {
+            span.setAttribute(ATTR_NET_PEER_NAME, conn.address);
+            if (!isNaN(port)) {
+              span.setAttribute(ATTR_NET_PEER_PORT, port);
+            }
+          }
+          if (plugin._netSemconvStability & SemconvStability.STABLE) {
+            span.setAttribute(ATTR_SERVER_ADDRESS, conn.address);
+            if (!isNaN(port)) {
+              span.setAttribute(ATTR_SERVER_PORT, port);
+            }
           }
         }
 
@@ -234,10 +267,12 @@ export class CassandraDriverInstrumentation extends InstrumentationBase<Cassandr
 
         const batchPromise = safeExecuteInTheMiddle(
           () => {
-            return original.apply(
-              this,
-              args
-            ) as Promise<CassandraDriver.types.ResultSet>;
+            return context.with(batchContext, () => {
+              return original.apply(
+                this,
+                args
+              ) as Promise<CassandraDriver.types.ResultSet>;
+            });
           },
           error => {
             if (error) {
@@ -285,10 +320,12 @@ export class CassandraDriverInstrumentation extends InstrumentationBase<Cassandr
           };
           args[3] = wrappedCallback;
         }
-
+        const streamContext = trace.setSpan(context.active(), span);
         return safeExecuteInTheMiddle(
           () => {
-            return original.apply(this, args);
+            return context.with(streamContext, () => {
+              return original.apply(this, args);
+            });
           },
           error => {
             if (error) {
@@ -304,24 +341,39 @@ export class CassandraDriverInstrumentation extends InstrumentationBase<Cassandr
     { op, query }: { op: string; query?: unknown },
     client: CassandraDriver.Client
   ): Span {
-    const attributes: Attributes = {
-      [ATTR_DB_SYSTEM]: DB_SYSTEM_VALUE_CASSANDRA,
-    };
+    const attributes: Attributes = {};
+
+    if (this._dbSemconvStability & SemconvStability.OLD) {
+      attributes[ATTR_DB_SYSTEM] = DB_SYSTEM_VALUE_CASSANDRA;
+    }
+    if (this._dbSemconvStability & SemconvStability.STABLE) {
+      attributes[ATTR_DB_SYSTEM_NAME] = DB_SYSTEM_NAME_VALUE_CASSANDRA;
+    }
 
     if (this._shouldIncludeDbStatement() && query !== undefined) {
       const statement = truncateQuery(query, this._getMaxQueryLength());
-      attributes[ATTR_DB_STATEMENT] = statement;
+      if (this._dbSemconvStability & SemconvStability.OLD) {
+        attributes[ATTR_DB_STATEMENT] = statement;
+      }
+      if (this._dbSemconvStability & SemconvStability.STABLE) {
+        attributes[ATTR_DB_QUERY_TEXT] = statement;
+      }
     }
 
+    // db.user (deprecated, no stable replacement - only emit with OLD)
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const user = (client as any).options?.credentials?.username;
-
-    if (user) {
+    if (user && this._dbSemconvStability & SemconvStability.OLD) {
       attributes[ATTR_DB_USER] = user;
     }
 
     if (client.keyspace) {
-      attributes[ATTR_DB_NAME] = client.keyspace;
+      if (this._dbSemconvStability & SemconvStability.OLD) {
+        attributes[ATTR_DB_NAME] = client.keyspace;
+      }
+      if (this._dbSemconvStability & SemconvStability.STABLE) {
+        attributes[ATTR_DB_NAMESPACE] = client.keyspace;
+      }
     }
 
     return this.tracer.startSpan(`cassandra-driver.${op}`, {

packages/instrumentation-cassandra-driver/src/instrumentation.ts

@@ -95,3 +95,12 @@ export const ATTR_NET_PEER_PORT = 'net.peer.port' as const;
  * @experimental This enum value is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`.
  */
 export const DB_SYSTEM_VALUE_CASSANDRA = 'cassandra' as const;
+
+/**
+ * Enum value "cassandra" for attribute {@link ATTR_DB_SYSTEM_NAME}.
+ *
+ * [Apache Cassandra](https://cassandra.apache.org/)
+ *
+ * @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_CASSANDRA = 'cassandra' as const;