diff --git a/package-lock.json b/package-lock.json index 4dd4b0bc05..4979d0f992 100644 --- a/package-lock.json +++ b/package-lock.json @@ -8959,9 +8959,9 @@ } }, "node_modules/@opentelemetry/semantic-conventions": { - "version": "1.33.0", - "resolved": "https://registry.npmjs.org/@opentelemetry/semantic-conventions/-/semantic-conventions-1.33.0.tgz", - "integrity": "sha512-TIpZvE8fiEILFfTlfPnltpBaD3d9/+uQHVCyC3vfdh6WfCXKhNFzoP5RyDDIndfvZC5GrA4pyEDNyjPloJud+w==", + "version": "1.33.1", + "resolved": "https://registry.npmjs.org/@opentelemetry/semantic-conventions/-/semantic-conventions-1.33.1.tgz", + "integrity": "sha512-tBco+nVMoGqJ0LHPKOWlN9o1PX2AA9zxDMgvL210YYXlG9UkMXpiXhsWvvQriZrjOzTXXEpH6jleCgAuVGg3EQ==", "engines": { "node": ">=14" } @@ -36338,8 +36338,8 @@ "version": "0.46.0", "license": "Apache-2.0", "dependencies": { - "@opentelemetry/instrumentation": "^0.201.0", - "@opentelemetry/semantic-conventions": "^1.27.0" + "@opentelemetry/instrumentation": "^0.201.1", + "@opentelemetry/semantic-conventions": "^1.33.1" }, "devDependencies": { "@opentelemetry/api": "^1.3.0", @@ -36362,6 +36362,37 @@ "@opentelemetry/api": "^1.3.0" } }, + "plugins/node/opentelemetry-instrumentation-knex/node_modules/@opentelemetry/api-logs": { + "version": "0.201.1", + "resolved": "https://registry.npmjs.org/@opentelemetry/api-logs/-/api-logs-0.201.1.tgz", + "integrity": "sha512-IxcFDP1IGMDemVFG2by/AMK+/o6EuBQ8idUq3xZ6MxgQGeumYZuX5OwR0h9HuvcUc/JPjQGfU5OHKIKYDJcXeA==", + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/api": "^1.3.0" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "plugins/node/opentelemetry-instrumentation-knex/node_modules/@opentelemetry/instrumentation": { + "version": "0.201.1", + "resolved": "https://registry.npmjs.org/@opentelemetry/instrumentation/-/instrumentation-0.201.1.tgz", + "integrity": "sha512-6EOSoT2zcyBM3VryAzn35ytjRrOMeaWZyzQ/PHVfxoXp5rMf7UUgVToqxOhQffKOHtC7Dma4bHt+DuwIBBZyZA==", + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/api-logs": "0.201.1", + "@types/shimmer": "^1.2.0", + "import-in-the-middle": "^1.8.1", + "require-in-the-middle": "^7.1.1", + "shimmer": "^1.2.1" + }, + "engines": { + "node": "^18.19.0 || >=20.6.0" + }, + "peerDependencies": { + "@opentelemetry/api": "^1.3.0" + } + }, "plugins/node/opentelemetry-instrumentation-knex/node_modules/@types/node": { "version": "18.18.14", "resolved": "https://registry.npmjs.org/@types/node/-/node-18.18.14.tgz", @@ -36371,6 +36402,12 @@ "undici-types": "~5.26.4" } }, + "plugins/node/opentelemetry-instrumentation-knex/node_modules/@types/shimmer": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/@types/shimmer/-/shimmer-1.2.0.tgz", + "integrity": "sha512-UE7oxhQLLd9gub6JKIAhDq06T0F6FnztwMNRvYgjeQSBeMc1ZG/tA47EwfduvkuQS8apbkM/lpLpWsaCeYsXVg==", + "license": "MIT" + }, "plugins/node/opentelemetry-instrumentation-knex/node_modules/typescript": { "version": "5.0.4", "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.0.4.tgz", @@ -45218,10 +45255,10 @@ "requires": { "@opentelemetry/api": "^1.3.0", "@opentelemetry/context-async-hooks": "^2.0.0", - "@opentelemetry/instrumentation": "^0.201.0", + "@opentelemetry/instrumentation": "^0.201.1", "@opentelemetry/sdk-trace-base": "^2.0.0", "@opentelemetry/sdk-trace-node": "^2.0.0", - "@opentelemetry/semantic-conventions": "^1.27.0", + "@opentelemetry/semantic-conventions": "^1.33.1", "@types/mocha": "10.0.10", "@types/node": "18.18.14", "better-sqlite3": "11.0.0", @@ -45232,6 +45269,26 @@ "typescript": "5.0.4" }, "dependencies": { + "@opentelemetry/api-logs": { + "version": "0.201.1", + "resolved": "https://registry.npmjs.org/@opentelemetry/api-logs/-/api-logs-0.201.1.tgz", + "integrity": "sha512-IxcFDP1IGMDemVFG2by/AMK+/o6EuBQ8idUq3xZ6MxgQGeumYZuX5OwR0h9HuvcUc/JPjQGfU5OHKIKYDJcXeA==", + "requires": { + "@opentelemetry/api": "^1.3.0" + } + }, + "@opentelemetry/instrumentation": { + "version": "0.201.1", + "resolved": "https://registry.npmjs.org/@opentelemetry/instrumentation/-/instrumentation-0.201.1.tgz", + "integrity": "sha512-6EOSoT2zcyBM3VryAzn35ytjRrOMeaWZyzQ/PHVfxoXp5rMf7UUgVToqxOhQffKOHtC7Dma4bHt+DuwIBBZyZA==", + "requires": { + "@opentelemetry/api-logs": "0.201.1", + "@types/shimmer": "^1.2.0", + "import-in-the-middle": "^1.8.1", + "require-in-the-middle": "^7.1.1", + "shimmer": "^1.2.1" + } + }, "@types/node": { "version": "18.18.14", "resolved": "https://registry.npmjs.org/@types/node/-/node-18.18.14.tgz", @@ -45241,6 +45298,11 @@ "undici-types": "~5.26.4" } }, + "@types/shimmer": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/@types/shimmer/-/shimmer-1.2.0.tgz", + "integrity": "sha512-UE7oxhQLLd9gub6JKIAhDq06T0F6FnztwMNRvYgjeQSBeMc1ZG/tA47EwfduvkuQS8apbkM/lpLpWsaCeYsXVg==" + }, "typescript": { "version": "5.0.4", "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.0.4.tgz", @@ -47558,9 +47620,9 @@ } }, "@opentelemetry/semantic-conventions": { - "version": "1.33.0", - "resolved": "https://registry.npmjs.org/@opentelemetry/semantic-conventions/-/semantic-conventions-1.33.0.tgz", - "integrity": "sha512-TIpZvE8fiEILFfTlfPnltpBaD3d9/+uQHVCyC3vfdh6WfCXKhNFzoP5RyDDIndfvZC5GrA4pyEDNyjPloJud+w==" + "version": "1.33.1", + "resolved": "https://registry.npmjs.org/@opentelemetry/semantic-conventions/-/semantic-conventions-1.33.1.tgz", + "integrity": "sha512-tBco+nVMoGqJ0LHPKOWlN9o1PX2AA9zxDMgvL210YYXlG9UkMXpiXhsWvvQriZrjOzTXXEpH6jleCgAuVGg3EQ==" }, "@opentelemetry/sql-common": { "version": "file:packages/opentelemetry-sql-common", diff --git a/plugins/node/opentelemetry-instrumentation-knex/README.md b/plugins/node/opentelemetry-instrumentation-knex/README.md index 596fdcc619..be61ddce58 100644 --- a/plugins/node/opentelemetry-instrumentation-knex/README.md +++ b/plugins/node/opentelemetry-instrumentation-knex/README.md @@ -54,21 +54,38 @@ registerInstrumentations({ ## 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 package uses `@opentelemetry/semantic-conventions` version `1.33+`, which implements Semantic Convention [Version 1.7.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.7.0/semantic_conventions/README.md) + +This package is capable of emitting both Semantic Convention [Version 1.7.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.7.0/semantic_conventions/README.md) and [Version 1.33.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.33.0/docs/database/database-spans.md) +It is controlled using the environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`, which is a comma separated list of values. +The values `database` and `database/dup` control this instrumentation. +See details for the behavior of each of these values below. +If neither `database` or `database/dup` is included in `OTEL_SEMCONV_STABILITY_OPT_IN`, the old experimental semantic conventions will be used by default. + +### Upgrading Semantic Conventions + +When upgrading to the new semantic conventions, it is recommended to do so in the following order: + +1. Upgrade `@opentelemetry/instrumentation-knex` to the latest version +2. Set `OTEL_SEMCONV_STABILITY_OPT_IN=database/dup` to emit both old and new semantic conventions +3. Modify alerts, dashboards, metrics, and other processes to expect the new semantic conventions +4. Set `OTEL_SEMCONV_STABILITY_OPT_IN=database` to emit only the new semantic conventions + +This will cause both the old and new semantic conventions to be emitted during the transition period. Attributes collected: -| Attribute | Short Description | -| ----------------------- | ------------------------------------------------------------------------------ | -| `db.name` | This attribute is used to report the name of the database being accessed. | -| `db.operation` | The name of the operation being executed. | -| `db.sql.table` | The name of the primary table that the operation is acting upon. | -| `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. | -| `net.transport` | Transport protocol used. | +| v1.7.0 semconv | v1.23.0 semconv | Short Description | +|-----------------|----------------------|-----------------------------------------------------------------------------| +| `db.name` | `db.namespace` | This attribute is used to report the name of the database being accessed. | +| `db.operation` | `db.operation.name` | The name of the operation being executed. | +| `db.sql.table` | `db.collection.name` | The name of the primary table that the operation is acting upon. | +| `db.statement` | `db.query.text` | The database statement being executed. | +| `db.system` | `db.system.name` | An identifier for the database management system (DBMS) product being used. | +| `db.user` | (not included) | Username for accessing the database. | +| `net.peer.name` | `server.address` | Remote hostname or similar. | +| `net.peer.port` | `server.port` | Remote port number. | +| `net.transport` | (not included) | Transport protocol used. | ## Useful links diff --git a/plugins/node/opentelemetry-instrumentation-knex/package.json b/plugins/node/opentelemetry-instrumentation-knex/package.json index 3d8a5dab39..47710a914e 100644 --- a/plugins/node/opentelemetry-instrumentation-knex/package.json +++ b/plugins/node/opentelemetry-instrumentation-knex/package.json @@ -56,8 +56,8 @@ "typescript": "5.0.4" }, "dependencies": { - "@opentelemetry/instrumentation": "^0.201.0", - "@opentelemetry/semantic-conventions": "^1.27.0" + "@opentelemetry/instrumentation": "^0.201.1", + "@opentelemetry/semantic-conventions": "^1.33.1" }, "homepage": "https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-knex#readme" } diff --git a/plugins/node/opentelemetry-instrumentation-knex/src/instrumentation.ts b/plugins/node/opentelemetry-instrumentation-knex/src/instrumentation.ts index 5b7086895d..bc13842a77 100644 --- a/plugins/node/opentelemetry-instrumentation-knex/src/instrumentation.ts +++ b/plugins/node/opentelemetry-instrumentation-knex/src/instrumentation.ts @@ -23,8 +23,19 @@ import { InstrumentationNodeModuleDefinition, InstrumentationNodeModuleFile, isWrapped, + SemconvStability, + semconvStabilityFromStr, } from '@opentelemetry/instrumentation'; +import * as utils from './utils'; +import { KnexInstrumentationConfig } from './types'; import { + ATTR_DB_COLLECTION_NAME, + ATTR_DB_NAMESPACE, + ATTR_DB_OPERATION_NAME, + ATTR_DB_QUERY_TEXT, + ATTR_DB_SYSTEM_NAME, + ATTR_SERVER_ADDRESS, + ATTR_SERVER_PORT, SEMATTRS_DB_NAME, SEMATTRS_DB_OPERATION, SEMATTRS_DB_SQL_TABLE, @@ -35,8 +46,6 @@ import { SEMATTRS_NET_PEER_PORT, SEMATTRS_NET_TRANSPORT, } from '@opentelemetry/semantic-conventions'; -import * as utils from './utils'; -import { KnexInstrumentationConfig } from './types'; const contextSymbol = Symbol('opentelemetry.instrumentation-knex.context'); const DEFAULT_CONFIG: KnexInstrumentationConfig = { @@ -45,8 +54,15 @@ const DEFAULT_CONFIG: KnexInstrumentationConfig = { }; export class KnexInstrumentation extends InstrumentationBase { + private _semconvStability: SemconvStability; + constructor(config: KnexInstrumentationConfig = {}) { super(PACKAGE_NAME, PACKAGE_VERSION, { ...DEFAULT_CONFIG, ...config }); + + this._semconvStability = semconvStabilityFromStr( + 'database', + process.env.OTEL_SEMCONV_STABILITY_OPT_IN + ); } override setConfig(config: KnexInstrumentationConfig = {}) { @@ -122,6 +138,7 @@ export class KnexInstrumentation extends InstrumentationBase any) { return function wrapped_logging_method(this: any, query: any) { const config = this.client.config; @@ -134,24 +151,43 @@ export class KnexInstrumentation extends InstrumentationBase {