refactor(instr-mongoose): use exported strings for attributes (#2103)

david-luna · pichlermarc · web-flow · commit 5f42c51a9902 · 2024-04-17T17:25:53.000+02:00
Co-authored-by: Marc Pichler &lt;marc.pichler@dynatrace.com&gt;
diff --git a/package-lock.json b/package-lock.json
diff --git a/plugins/node/instrumentation-mongoose/README.md b/plugins/node/instrumentation-mongoose/README.md
@@ -52,6 +52,23 @@ The instrumentation's config `responseHook` functions signature changed, so the
 
 The `moduleVersionAttributeName` config option is removed. To add the mongoose package version to spans, use the `moduleVersion` attribute in hook info for `responseHook` 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)
+
+Attributes collected:
+
+| Attribute               | Short Description                                                           |
+| ----------------------- | --------------------------------------------------------------------------- |
+| `db.mongodb.collection` | The collection being accessed within the database stated in `db.name`.      |
+| `db.name`               | This attribute is used to report the name of the database being accessed.   |
+| `db.operation`          | The name of the operation being executed, or the SQL keyword.               |
+| `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.                                                         |
+
 ## Useful links
 
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
diff --git a/plugins/node/instrumentation-mongoose/package.json b/plugins/node/instrumentation-mongoose/package.json
@@ -62,7 +62,7 @@
   "dependencies": {
     "@opentelemetry/core": "^1.8.0",
     "@opentelemetry/instrumentation": "^0.50.0",
-    "@opentelemetry/semantic-conventions": "^1.0.0"
+    "@opentelemetry/semantic-conventions": "^1.22.0"
   },
   "homepage": "https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-mongoose#readme"
 }
diff --git a/plugins/node/instrumentation-mongoose/src/mongoose.ts b/plugins/node/instrumentation-mongoose/src/mongoose.ts
@@ -13,13 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import {
-  context,
-  Span,
-  trace,
-  SpanAttributes,
-  SpanKind,
-} from '@opentelemetry/api';
+import { context, Span, trace, Attributes, SpanKind } from '@opentelemetry/api';
 import { suppressTracing } from '@opentelemetry/core';
 import type * as mongoose from 'mongoose';
 import { MongooseInstrumentationConfig, SerializerPayload } from './types';
@@ -34,7 +28,11 @@ import {
   InstrumentationNodeModuleDefinition,
 } from '@opentelemetry/instrumentation';
 import { VERSION } from './version';
-import { SemanticAttributes } from '@opentelemetry/semantic-conventions';
+import {
+  SEMATTRS_DB_OPERATION,
+  SEMATTRS_DB_STATEMENT,
+  SEMATTRS_DB_SYSTEM,
+} from '@opentelemetry/semantic-conventions';
 
 const contextCaptureFunctions = [
   'remove',
@@ -155,9 +153,9 @@ export class MongooseInstrumentation extends InstrumentationBase<any> {
         }
 
         const parentSpan = this[_STORED_PARENT_SPAN];
-        const attributes: SpanAttributes = {};
+        const attributes: Attributes = {};
         if (self._config.dbStatementSerializer) {
-          attributes[SemanticAttributes.DB_STATEMENT] =
+          attributes[SEMATTRS_DB_STATEMENT] =
             self._config.dbStatementSerializer('aggregate', {
               options: this.options,
               aggregatePipeline: this._pipeline,
@@ -197,9 +195,9 @@ export class MongooseInstrumentation extends InstrumentationBase<any> {
         }
 
         const parentSpan = this[_STORED_PARENT_SPAN];
-        const attributes: SpanAttributes = {};
+        const attributes: Attributes = {};
         if (self._config.dbStatementSerializer) {
-          attributes[SemanticAttributes.DB_STATEMENT] =
+          attributes[SEMATTRS_DB_STATEMENT] =
             self._config.dbStatementSerializer(this.op, {
               condition: this._conditions,
               updates: this._update,
@@ -243,9 +241,9 @@ export class MongooseInstrumentation extends InstrumentationBase<any> {
         if (options && !(options instanceof Function)) {
           serializePayload.options = options;
         }
-        const attributes: SpanAttributes = {};
+        const attributes: Attributes = {};
         if (self._config.dbStatementSerializer) {
-          attributes[SemanticAttributes.DB_STATEMENT] =
+          attributes[SEMATTRS_DB_STATEMENT] =
             self._config.dbStatementSerializer(op, serializePayload);
         }
         const span = self._startSpan(
@@ -308,7 +306,7 @@ export class MongooseInstrumentation extends InstrumentationBase<any> {
     collection: mongoose.Collection,
     modelName: string,
     operation: string,
-    attributes: SpanAttributes,
+    attributes: Attributes,
     parentSpan?: Span
   ): Span {
     return this.tracer.startSpan(
@@ -318,8 +316,8 @@ export class MongooseInstrumentation extends InstrumentationBase<any> {
         attributes: {
           ...attributes,
           ...getAttributesFromCollection(collection),
-          [SemanticAttributes.DB_OPERATION]: operation,
-          [SemanticAttributes.DB_SYSTEM]: 'mongoose',
+          [SEMATTRS_DB_OPERATION]: operation,
+          [SEMATTRS_DB_SYSTEM]: 'mongoose',
         },
       },
       parentSpan ? trace.setSpan(context.active(), parentSpan) : undefined
diff --git a/plugins/node/instrumentation-mongoose/src/utils.ts b/plugins/node/instrumentation-mongoose/src/utils.ts
@@ -13,21 +13,27 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { SpanAttributes, SpanStatusCode, diag, Span } from '@opentelemetry/api';
+import { Attributes, SpanStatusCode, diag, Span } from '@opentelemetry/api';
 import type { Collection } from 'mongoose';
 import { MongooseResponseCustomAttributesFunction } from './types';
 import { safeExecuteInTheMiddle } from '@opentelemetry/instrumentation';
-import { SemanticAttributes } from '@opentelemetry/semantic-conventions';
+import {
+  SEMATTRS_DB_MONGODB_COLLECTION,
+  SEMATTRS_DB_NAME,
+  SEMATTRS_DB_USER,
+  SEMATTRS_NET_PEER_NAME,
+  SEMATTRS_NET_PEER_PORT,
+} from '@opentelemetry/semantic-conventions';
 
 export function getAttributesFromCollection(
   collection: Collection
-): SpanAttributes {
+): Attributes {
   return {
-    [SemanticAttributes.DB_MONGODB_COLLECTION]: collection.name,
-    [SemanticAttributes.DB_NAME]: collection.conn.name,
-    [SemanticAttributes.DB_USER]: collection.conn.user,
-    [SemanticAttributes.NET_PEER_NAME]: collection.conn.host,
-    [SemanticAttributes.NET_PEER_PORT]: collection.conn.port,
+    [SEMATTRS_DB_MONGODB_COLLECTION]: collection.name,
+    [SEMATTRS_DB_NAME]: collection.conn.name,
+    [SEMATTRS_DB_USER]: collection.conn.user,
+    [SEMATTRS_NET_PEER_NAME]: collection.conn.host,
+    [SEMATTRS_NET_PEER_PORT]: collection.conn.port,
   };
 }
 
diff --git a/plugins/node/instrumentation-mongoose/test/asserts.ts b/plugins/node/instrumentation-mongoose/test/asserts.ts
@@ -15,21 +15,26 @@
  */
 import { expect } from 'expect';
 import { ReadableSpan } from '@opentelemetry/sdk-trace-base';
-import { SemanticAttributes } from '@opentelemetry/semantic-conventions';
+import {
+  SEMATTRS_DB_MONGODB_COLLECTION,
+  SEMATTRS_DB_NAME,
+  SEMATTRS_DB_STATEMENT,
+  SEMATTRS_DB_SYSTEM,
+  SEMATTRS_NET_PEER_NAME,
+  SEMATTRS_NET_PEER_PORT,
+} from '@opentelemetry/semantic-conventions';
 import { SpanStatusCode } from '@opentelemetry/api';
 import { SerializerPayload } from '../src';
 import { DB_NAME, MONGO_HOST, MONGO_PORT } from './config';
 
 export const assertSpan = (span: ReadableSpan) => {
   expect(span.status.code).toBe(SpanStatusCode.UNSET);
-  expect(span.attributes[SemanticAttributes.DB_SYSTEM]).toEqual('mongoose');
-  expect(span.attributes[SemanticAttributes.DB_MONGODB_COLLECTION]).toEqual(
-    'users'
-  );
-  expect(span.attributes[SemanticAttributes.DB_NAME]).toEqual(DB_NAME);
-  expect(span.attributes[SemanticAttributes.NET_PEER_NAME]).toEqual(MONGO_HOST);
-  expect(span.attributes[SemanticAttributes.NET_PEER_PORT]).toEqual(MONGO_PORT);
+  expect(span.attributes[SEMATTRS_DB_SYSTEM]).toEqual('mongoose');
+  expect(span.attributes[SEMATTRS_DB_MONGODB_COLLECTION]).toEqual('users');
+  expect(span.attributes[SEMATTRS_DB_NAME]).toEqual(DB_NAME);
+  expect(span.attributes[SEMATTRS_NET_PEER_NAME]).toEqual(MONGO_HOST);
+  expect(span.attributes[SEMATTRS_NET_PEER_PORT]).toEqual(MONGO_PORT);
 };
 
 export const getStatement = (span: ReadableSpan): SerializerPayload =>
-  JSON.parse(span.attributes[SemanticAttributes.DB_STATEMENT] as string);
+  JSON.parse(span.attributes[SEMATTRS_DB_STATEMENT] as string);
diff --git a/plugins/node/instrumentation-mongoose/test/mongoose.test.ts b/plugins/node/instrumentation-mongoose/test/mongoose.test.ts

Original file line number	Diff line number	Diff line change
`@@ -62,7 +62,7 @@`
`62`	`62`	`"dependencies": {`
`63`	`63`	`"@opentelemetry/core": "^1.8.0",`
`64`	`64`	`"@opentelemetry/instrumentation": "^0.50.0",`
`65`		`- "@opentelemetry/semantic-conventions": "^1.0.0"`
	`65`	`+ "@opentelemetry/semantic-conventions": "^1.22.0"`
`66`	`66`	`},`
`67`	`67`	`"homepage": "https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-mongoose#readme"`
`68`	`68`	`}`