feat(instrumentation-memcached): support net.* and db.* semconv migra… (#3169)

Co-authored-by: Marylia Gutierrez <[email protected]>

Author: JamieDanielson

packages/instrumentation-memcached/README.md

@@ -44,23 +44,32 @@ registerInstrumentations({
 
 ### Configuration Options
 
-| Option | Type | Example | Description |
-| ------- | ---- | ------- | ----------- |
+| Option                      | Type      | Example | Description                                                                                                                  |
+| --------------------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
 | `enhancedDatabaseReporting` | `boolean` | `false` | Include full command statement in the span - **leaks potentially sensitive information to your spans**. Defaults to `false`. |
 
 ## 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.operation`  | The name of the operation being executed.                                   |
-| `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.system`     | `db.system.name`    | 'memcached'                                                                             |
+| `db.operation`  | `db.operation.name` | The name of the operation being executed.                                               |
+| `db.statement`  | `db.query.text`     | The database statement being executed (only if `enhancedDatabaseReporting` is enabled). |
+| `net.peer.name` | `server.address`    | Remote hostname or similar.                                                             |
+| `net.peer.port` | `server.port`       | Remote port number.                                                                     |
 
 ## Useful links
 

packages/instrumentation-memcached/package.json

@@ -53,7 +53,6 @@
     "@opentelemetry/contrib-test-utils": "^0.54.0",
     "@opentelemetry/sdk-trace-base": "^2.0.0",
     "@opentelemetry/sdk-trace-node": "^2.0.0",
-    "@opentelemetry/semantic-conventions": "^1.27.0",
     "@types/mocha": "10.0.10",
     "@types/node": "18.18.14",
     "cross-env": "7.0.3",
@@ -63,6 +62,7 @@
     "typescript": "5.0.4"
   },
   "dependencies": {
+    "@opentelemetry/semantic-conventions": "^1.33.0",
     "@opentelemetry/instrumentation": "^0.207.0",
     "@types/memcached": "^2.2.6"
   },

packages/instrumentation-memcached/src/instrumentation.ts

@@ -19,33 +19,55 @@ import {
   isWrapped,
   InstrumentationBase,
   InstrumentationNodeModuleDefinition,
+  SemconvStability,
+  semconvStabilityFromStr,
 } from '@opentelemetry/instrumentation';
 import type * as Memcached from 'memcached';
 import {
+  DB_SYSTEM_NAME_VALUE_MEMCACHED,
   DB_SYSTEM_VALUE_MEMCACHED,
   ATTR_DB_OPERATION,
   ATTR_DB_STATEMENT,
   ATTR_DB_SYSTEM,
 } from './semconv';
+import {
+  ATTR_DB_OPERATION_NAME,
+  ATTR_DB_QUERY_TEXT,
+  ATTR_DB_SYSTEM_NAME,
+} from '@opentelemetry/semantic-conventions';
+
 import * as utils from './utils';
 import { InstrumentationConfig } from './types';
 /** @knipignore */
 import { PACKAGE_NAME, PACKAGE_VERSION } from './version';
 
 export class MemcachedInstrumentation extends InstrumentationBase<InstrumentationConfig> {
   static readonly COMPONENT = 'memcached';
-  static readonly COMMON_ATTRIBUTES = {
-    [ATTR_DB_SYSTEM]: DB_SYSTEM_VALUE_MEMCACHED,
-  };
   static readonly DEFAULT_CONFIG: InstrumentationConfig = {
     enhancedDatabaseReporting: false,
   };
 
+  private _netSemconvStability!: SemconvStability;
+  private _dbSemconvStability!: SemconvStability;
+
   constructor(config: InstrumentationConfig = {}) {
     super(PACKAGE_NAME, PACKAGE_VERSION, {
       ...MemcachedInstrumentation.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: InstrumentationConfig = {}) {
@@ -90,15 +112,24 @@ export class MemcachedInstrumentation extends InstrumentationBase<Instrumentatio
       if (typeof queryCompiler !== 'function') {
         return original.apply(this, arguments as any);
       }
+
+      const attributes: api.Attributes = {
+        'memcached.version': moduleVersion,
+      };
+
+      if (instrumentation._dbSemconvStability & SemconvStability.OLD) {
+        attributes[ATTR_DB_SYSTEM] = DB_SYSTEM_VALUE_MEMCACHED;
+      }
+      if (instrumentation._dbSemconvStability & SemconvStability.STABLE) {
+        attributes[ATTR_DB_SYSTEM_NAME] = DB_SYSTEM_NAME_VALUE_MEMCACHED;
+      }
+
       // The name will be overwritten later
       const span = instrumentation.tracer.startSpan(
         'unknown memcached command',
         {
           kind: api.SpanKind.CLIENT,
-          attributes: {
-            'memcached.version': moduleVersion,
-            ...MemcachedInstrumentation.COMMON_ATTRIBUTES,
-          },
+          attributes,
         }
       );
       const parentContext = api.context.active();
@@ -134,16 +165,35 @@ export class MemcachedInstrumentation extends InstrumentationBase<Instrumentatio
       const callback = query.callback;
 
       span.updateName(`memcached ${query.type}`);
-      span.setAttributes({
+
+      const attributes: api.Attributes = {
         'db.memcached.key': query.key,
         'db.memcached.lifetime': query.lifetime,
-        [ATTR_DB_OPERATION]: query.type,
-        [ATTR_DB_STATEMENT]: instrumentation.getConfig()
-          .enhancedDatabaseReporting
-          ? query.command
-          : undefined,
-        ...utils.getPeerAttributes(client, server, query),
-      });
+        ...utils.getPeerAttributes(
+          client,
+          server,
+          query,
+          instrumentation._netSemconvStability
+        ),
+      };
+
+      if (instrumentation._dbSemconvStability & SemconvStability.OLD) {
+        attributes[ATTR_DB_OPERATION] = query.type;
+      }
+      if (instrumentation._dbSemconvStability & SemconvStability.STABLE) {
+        attributes[ATTR_DB_OPERATION_NAME] = query.type;
+      }
+
+      if (instrumentation.getConfig().enhancedDatabaseReporting) {
+        if (instrumentation._dbSemconvStability & SemconvStability.OLD) {
+          attributes[ATTR_DB_STATEMENT] = query.command;
+        }
+        if (instrumentation._dbSemconvStability & SemconvStability.STABLE) {
+          attributes[ATTR_DB_QUERY_TEXT] = query.command;
+        }
+      }
+
+      span.setAttributes(attributes);
 
       query.callback = api.context.bind(
         callbackContext,

packages/instrumentation-memcached/src/semconv.ts

@@ -84,3 +84,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_MEMCACHED = 'memcached' as const;
+
+/**
+ * Enum value "memcached" for attribute {@link ATTR_DB_SYSTEM_NAME}.
+ *
+ * [Memcached](https://memcached.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_MEMCACHED = 'memcached' as const;

packages/instrumentation-memcached/src/utils.ts

@@ -15,13 +15,23 @@
  */
 
 import type * as Memcached from 'memcached';
-import { ATTR_NET_PEER_NAME, ATTR_NET_PEER_PORT } from './semconv';
+import {
+  ATTR_NET_PEER_NAME,
+  ATTR_NET_PEER_PORT,
+} from './semconv';
+import {
+  ATTR_SERVER_ADDRESS,
+  ATTR_SERVER_PORT,
+} from '@opentelemetry/semantic-conventions';
+import { SemconvStability } from '@opentelemetry/instrumentation';
+import { Attributes } from '@opentelemetry/api';
 
 export const getPeerAttributes = (
   client: any /* Memcached, but the type definitions are lacking */,
   server: string | undefined,
-  query: Memcached.CommandData
-) => {
+  query: Memcached.CommandData,
+  netSemconvStability: SemconvStability
+): Attributes => {
   if (!server) {
     if (client.servers.length === 1) {
       server = client.servers[0];
@@ -47,15 +57,32 @@ export const getPeerAttributes = (
     const [host, port] = server && server.split(':');
     if (host && port) {
       const portNumber = parseInt(port, 10);
-      if (!isNaN(portNumber)) {
-        return {
-          [ATTR_NET_PEER_NAME]: host,
-          [ATTR_NET_PEER_PORT]: portNumber,
-        };
+      const attrs: Attributes = {};
+
+      if (netSemconvStability & SemconvStability.OLD) {
+        attrs[ATTR_NET_PEER_NAME] = host;
+        if (!isNaN(portNumber)) {
+          attrs[ATTR_NET_PEER_PORT] = portNumber;
+        }
+      }
+      if (netSemconvStability & SemconvStability.STABLE) {
+        attrs[ATTR_SERVER_ADDRESS] = host;
+        if (!isNaN(portNumber)) {
+          attrs[ATTR_SERVER_PORT] = portNumber;
+        }
+      }
+
+      return attrs;
+    }
+    if (host) {
+      const attrs: Attributes = {};
+      if (netSemconvStability & SemconvStability.OLD) {
+        attrs[ATTR_NET_PEER_NAME] = host;
+      }
+      if (netSemconvStability & SemconvStability.STABLE) {
+        attrs[ATTR_SERVER_ADDRESS] = host;
       }
-      return {
-        [ATTR_NET_PEER_NAME]: host,
-      };
+      return attrs;
     }
   }
   return {};