open-telemetry · blumamir · Jun 20, 2024 · May 10, 2024 · May 10, 2024 · May 11, 2024
@@ -198,6 +198,84 @@ Instrumentation may add additional patch/unpatch messages for specific functions
 
 The cases above are not covered by the base class and offer additional context to the user troubleshooting an issue with the instrumentation.
 
+## Supported Versions
+
+Supported versions can refer to 2 entities in the context of OpenTelemetry instrumentations:
+
+- `Instrumented Package` - This is the user-facing package/s that the end user has installed in his application and is familiar with.
+- `Patched Package` - These are the packages that are being patched in practice to achieve the instrumentation goals. It may be `Instrumented Package` itself or transitive internal dependencies of the `Instrumented Package`.
+
+### `Instrumented Package` Documentation
+
+Instrumentation should have a "## Supported Versions" section in the README file that lists the supported versions range of the instrumented package. This range should hide and consolidate any internal implementation details like the use of internal modules, different patch logic for different versions, etc. It should focus on the relevance to the human consumer.
+
+### `Patched Package`s Supported Versions
+
+The packages to patch are specified in the `InstrumentationNodeModuleDefinition` and `InstrumentationNodeModuleFile` classes. Instrumentation can specify arrays with different package names and version ranges to use to implement the instrumentation logic. example use:
+
+```js
+const supportedVersions = ['>=1.2.3 <3'];
+
+  protected init() {
+
+    const someModuleFile = new InstrumentationNodeModuleFile(
+      'foo/lib/some-file.js',
+      supportedVersions,
+      myFilePatch,
+      myFileUnpatch,
+    );
+
+    const module = new InstrumentationNodeModuleDefinition(
+      'foo',
+      supportedVersions,
+      myModulePatch,
+      myModuleUnpatch,
+      [someModuleFile]
+    );
+    return module
+  }
+```
+
+### Variations
+
+There can be few variations between the instrumented package and the patched package:
+
+- Single Module - instrumentation patches the same module that is instrumented.
+- Different Modules - instrumentation patches internal modules with different names and version ranges as of the instrumented package.
+- Node.js Core Modules - instrumentation patches a Node.js internal module.
+- Multiple Modules - instrumentation may instrument a set of (potentially large number of) user-facing instrumented packages.
+- Patch Logic - instrumentation may use the `moduleExports` to patch, or hooks up to other mechanisms for recording signals. examples are: Node.js diagnostics channel, patching globals (like `window` being patched in browser instrumentations, or patches arbitrary lambda function handlers, etc.
+
+### Range Specification
+
+For versions that are a closed range, instrumentations should prefer to specify the supported versions of the instrumented package as `>=x.y.z <w` to promote consistency and readability across the code-base.
+
+If an instrumentation supports just one major version of the instrumented package, it can specify the version range as `^x.y.z` or `^x`, which are equivalent but more readable.
+
+Instrumentation should use an upper and lower bounds for the version ranges it uses for patches. This is to ensure that any new major versions of the instrumented package are not automatically patched by the instrumentation, which could lead to unexpected behavior.
+
+New major versions should be reviewed and tested before being added to the supported versions list.
+
+Specific guidelines for different cases:
+
+- For `Different Modules`, instrumentations can use an upper limit on patched packages but it is unknown which future versions of the instrumented package will continue to use it. Thus it is ok to use an open upper limit, for example `>=1.2.3`, for the instrumented package.
+- For `Node.js Core Modules`, the supported versions range is set to `['*']` to advertise that the instrumentation is compatible with all versions of Node.js that OpenTelemetry supports.
+- For `Multiple Modules`, the supported versions range should be specified for each module in the README file with the supported versions.
+- For `Different Patch Logic`, the use of supported versions can sometimes be more flexible, and the README should specify useful versioning information.
+
+### Add New Supported Versions
+
+When a new major version of the instrumented package is released, renovate bot will open a PR in contrib which helps maintainers to become aware of it. The instrumentation maintainer should review the new version and check compatibility with existing code. It can then be added to the supported versions list to be released in the next version of the instrumentation.
+
+Checklist for adding a new version to the supported versions list:
+
+- [ ] Review which functions are patched by the instrumentation and if they were changed in the new version that need support in code.
+- [ ] Check for breaking changes in the new version that could affect the instrumentation.
+- [ ] Test the instrumentation with the new version to ensure it works as expected.
+- [ ] Update the supported versions list in the instrumentation code, perhaps with different patches and additional `InstrumentationNodeModuleDefinition`s that target the new version.
+- [ ] Update the README file to reflect the support for new versions.
+- [ ] For instrumentations that use test-all-versions `.tav.yml`, add the new version to the list of versions to test.
+
 ## package.json
 
 ### Description

@@ -51,7 +51,7 @@ const logger = winston.createLogger({
 
 ### Supported versions
 
-Winston `3.x`
+- [`winston`](https://www.npmjs.com/package/winston) versions `>=3.0.0 <4`
 
 ## Useful links
 

@@ -17,7 +17,7 @@ npm install --save @opentelemetry/instrumentation-amqplib
 
 ## Supported Versions
 
-- `>=0.5.5`
+- [`amqplib`](https://www.npmjs.com/package/amqplib) versions `>=0.5.5 <1`
 
 ## Usage
 

@@ -74,6 +74,8 @@ import {
 } from './utils';
 import { PACKAGE_NAME, PACKAGE_VERSION } from './version';
 
+const supportedVersions = ['>=0.5.5 <1'];
+
 export class AmqplibInstrumentation extends InstrumentationBase {
   protected override _config!: AmqplibInstrumentationConfig;
 
@@ -92,28 +94,28 @@ export class AmqplibInstrumentation extends InstrumentationBase {
   protected init() {
     const channelModelModuleFile = new InstrumentationNodeModuleFile(
       'amqplib/lib/channel_model.js',
-      ['>=0.5.5'],
+      supportedVersions,
       this.patchChannelModel.bind(this),
       this.unpatchChannelModel.bind(this)
     );
 
     const callbackModelModuleFile = new InstrumentationNodeModuleFile(
       'amqplib/lib/callback_model.js',
-      ['>=0.5.5'],
+      supportedVersions,
       this.patchChannelModel.bind(this),
       this.unpatchChannelModel.bind(this)
     );
 
     const connectModuleFile = new InstrumentationNodeModuleFile(
       'amqplib/lib/connect.js',
-      ['>=0.5.5'],
+      supportedVersions,
       this.patchConnect.bind(this),
       this.unpatchConnect.bind(this)
     );
 
     const module = new InstrumentationNodeModuleDefinition(
       'amqplib',
-      ['>=0.5.5'],
+      supportedVersions,
       undefined,
       undefined,
       [channelModelModuleFile, connectModuleFile, callbackModelModuleFile]

@@ -15,6 +15,10 @@ Compatible with OpenTelemetry JS API and SDK `1.0+`.
 npm install --save @opentelemetry/instrumentation-cucumber
 ```
 
+## Supported Versions
+
+- [`@cucumber/cucumber`](https://www.npmjs.com/package/@cucumber/cucumber) versions `>=8.0.0 <11`
+
 ## Usage
 
 ```js

@@ -46,6 +46,8 @@ type Cucumber = typeof cucumber;
 type Hook = (typeof hooks)[number];
 type Step = (typeof steps)[number];
 
+const supportedVersions = ['>=8.0.0 <11'];
+
 export class CucumberInstrumentation extends InstrumentationBase {
   private module: Cucumber | undefined;
 
@@ -57,7 +59,7 @@ export class CucumberInstrumentation extends InstrumentationBase {
     return [
       new InstrumentationNodeModuleDefinition(
         '@cucumber/cucumber',
-        ['^8.0.0', '^9.0.0', '^10.0.0'],
+        supportedVersions,
         (moduleExports: Cucumber) => {
           this.module = moduleExports;
           steps.forEach(step => {
@@ -83,7 +85,7 @@ export class CucumberInstrumentation extends InstrumentationBase {
         [
           new InstrumentationNodeModuleFile(
             '@cucumber/cucumber/lib/runtime/test_case_runner.js',
-            ['^8.0.0', '^9.0.0', '^10.0.0'],
+            supportedVersions,
             moduleExports => {
               if (isWrapped(moduleExports.default.prototype.run)) {
                 this._unwrap(moduleExports.default.prototype, 'run');

@@ -15,9 +15,9 @@ Compatible with OpenTelemetry JS API and SDK `1.0+`.
 npm install --save @opentelemetry/instrumentation-dataloader
 ```
 
-### Supported Versions
+## Supported Versions
 
-- `^2.0.0`
+- [`dataloader`](https://www.npmjs.com/package/dataloader) versions `>=2.0.0 <3`
 
 ## Usage
 

@@ -52,7 +52,7 @@ export class DataloaderInstrumentation extends InstrumentationBase {
     return [
       new InstrumentationNodeModuleDefinition(
         MODULE_NAME,
-        ['^2.0.0'],
+        ['>=2.0.0 <3'],
         dataloader => {
           this._patchLoad(dataloader.prototype);
           this._patchLoadMany(dataloader.prototype);

@@ -17,6 +17,10 @@ See the full list of instrumented functions in [constants.ts](src/constants.ts);
 npm install --save @opentelemetry/instrumentation-fs
 ```
 
+## Supported Versions
+
+- Node.js `>=14`
+
 ## Usage
 
 ```js

@@ -17,7 +17,7 @@ npm install --save @opentelemetry/instrumentation-kafkajs
 
 ### Supported versions
 
-- `<3.0.0`
+- [`kafkajs`](https://www.npmjs.com/package/kafkajs) versions `>=0.1.0 <3`
 
 ## Usage
 

@@ -72,7 +72,7 @@ export class KafkaJsInstrumentation extends InstrumentationBase {
 
     const module = new InstrumentationNodeModuleDefinition(
       'kafkajs',
-      ['< 3'],
+      ['>=0.1.0 <3'],
       (moduleExports: typeof kafkaJs) => {
         unpatch(moduleExports);
         this._wrap(

@@ -17,7 +17,7 @@ npm install --save @opentelemetry/instrumentation-lru-memoizer
 
 ## Supported Versions
 
-- `>=1.3 <3`
+- [`lru-memorizer`](https://www.npmjs.com/package/lru-memoizer) versions `>=1.3.0 <3`
 
 ## Usage
 

@@ -17,7 +17,7 @@ npm install --save @opentelemetry/instrumentation-mongoose
 
 ## Supported Versions
 
-- `>=5.9.7 <7`
+- [`mongoose`](https://www.npmjs.com/package/mongoose) versions `>=5.9.7 <7`
 
 ## Usage
 

@@ -6,6 +6,12 @@
 This module provides automatic metric instrumentation that exposes measurements from the [Performance measurement APIs](https://nodejs.org/api/perf_hooks.html) (i.e. `perf_hooks`).
 While currently it is limited to metrics, it may be modified to produce other signals in the future.
 
+## Supported Versions
+
+- Node.js `>=14.10`
+
+<!-- - 14.6.0 - this package uses _private properties_ -->
+
 ## Example
 
 ```bash
@@ -58,12 +64,6 @@ nodejs_performance_event_loop_utilization 0.010140079547955264
 |---|---|---|---|---|
 | [`eventLoopUtilizationMeasurementInterval`](./src/types.ts#L25) | `int` | millisecond | `5000` | The approximate number of milliseconds for which to calculate event loop utilization averages. A larger value will result in more accurate averages at the expense of less granular data. Should be set to below the scrape interval of your metrics collector to avoid duplicated data points. |
 
-## Supported Node.js versions
-
-v14.10.0+
-
-<!-- - 14.6.0 - this package uses _private properties_ -->
-
 ## Useful links
 
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>

@@ -17,7 +17,7 @@ npm install --save @opentelemetry/instrumentation-socket.io
 
 ## Supported Versions
 
-- `>=2 <5`
+- [socket.io](https://www.npmjs.com/package/socket.io) versions `>=2.0.0 <5`
 
 ## Usage
 

@@ -17,7 +17,7 @@ npm install --save @opentelemetry/instrumentation-tedious
 
 ## Supported Versions
 
-- `>=1.11.0 <=17`
+- [tedious](https://www.npmjs.com/package/tedious) `>=1.11.0 <18`
 
 ## Usage
 

@@ -16,7 +16,7 @@ npm install --save @opentelemetry/instrumentation-undici
 
 ## Supported Versions
 
-- `undici@>=5.12.0`
+- [`undici`](https://www.npmjs.com/package/undici) version `>=5.12.0`
 
 ## Usage
 

@@ -19,6 +19,10 @@ Compatible with OpenTelemetry JS API and SDK `1.0+`.
 npm install --save @opentelemetry/instrumentation-aws-lambda
 ```
 
+## Supported Versions
+
+- This package will instrument the lambda execution regardless of versions.
+
 ## Usage
 
 Create a file to initialize the instrumentation, such as `lambda-wrapper.js`.

@@ -15,6 +15,11 @@ If total installation size is not constrained, it is recommended to use the [`@o
 npm install --save @opentelemetry/instrumentation-aws-sdk
 ```
 
+## Supported Versions
+
+- [`aws-sdk`](https://www.npmjs.com/package/aws-sdk) versions `>=2.308.0 <3`
+- `@aws-sdk/client-*` versions `>=3.0.0 <4`
+
 ## Usage
 
 For further automatic instrumentation instruction see the [@opentelemetry/instrumentation](https://www.npmjs.com/package/@opentelemetry/instrumentation) package.

@@ -17,7 +17,7 @@ npm install --save @opentelemetry/instrumentation-bunyan
 
 ## Supported Versions
 
-- `bunyan@^1.0.0`
+- [`bunyan`](https://www.npmjs.com/package/bunyan) versions `>=1.0.0 <2`
 
 ## Usage
 

@@ -45,7 +45,7 @@ export class BunyanInstrumentation extends InstrumentationBase {
     return [
       new InstrumentationNodeModuleDefinition(
         'bunyan',
-        ['<2.0'],
+        ['>=1.0.0 <2'],
         (module: any) => {
           const instrumentation = this;
           const Logger =

@@ -15,6 +15,10 @@ Compatible with OpenTelemetry JS API and SDK `1.0+`.
 npm install --save @opentelemetry/instrumentation-cassandra-driver
 ```
 
+### Supported Versions
+
+- [`cassandra-driver`](https://www.npmjs.com/package/cassandra-driver) versions `>=4.4.0 <5`
+
 ## Usage
 
 ```js
@@ -45,10 +49,6 @@ await client.execute('select * from foo');
 | `responseHook`              | `CassandraDriverResponseCustomAttributeFunction` | `undefined` | Hook for adding custom attributes before response is handled                                                                                                                                                                   |
 | `maxQueryLength`            | `number`                                         | `65536`     | If `enhancedDatabaseReporting` is enabled, limits the attached query strings to this length.                                                                                                                                   |
 
-### Supported versions
-
-`>=4.4 <5.0`
-
 ## 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)

@@ -43,7 +43,7 @@ import { PACKAGE_NAME, PACKAGE_VERSION } from './version';
 import { EventEmitter } from 'events';
 import type * as CassandraDriver from 'cassandra-driver';
 
-const supportedVersions = ['>=4.4 <5.0'];
+const supportedVersions = ['>=4.4.0 <5'];
 
 export class CassandraDriverInstrumentation extends InstrumentationBase {
   protected override _config!: CassandraDriverInstrumentationConfig;

@@ -23,7 +23,7 @@ npm install --save @opentelemetry/instrumentation-http @opentelemetry/instrument
 
 ### Supported Versions
 
-- `^3.0.0`
+- [`connect`](https://www.npmjs.com/package/connect) versions `>=3.0.0 <4`
 
 ## Usage
 

@@ -50,7 +50,7 @@ export class ConnectInstrumentation extends InstrumentationBase {
     return [
       new InstrumentationNodeModuleDefinition(
         'connect',
-        ['^3.0.0'],
+        ['>=3.0.0 <4'],
         moduleExports => {
           return this._patchConstructor(moduleExports);
         }