Merge branch 'main' into deprecate-my-browser-extension

GUIDELINES.md

@@ -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

metapackages/auto-instrumentations-node/README.md

@@ -77,8 +77,9 @@ For example, to enable only the `env`, `host` detectors:
 export OTEL_NODE_RESOURCE_DETECTORS="env,host"
 ```
 
-By default, all [Supported Instrumentations](#supported-instrumentations) are enabled,
-but you can use the environment variable `OTEL_NODE_ENABLED_INSTRUMENTATIONS` to enable only certain instrumentations
+By default, all [Supported Instrumentations](#supported-instrumentations) are enabled.
+You can use the environment variable `OTEL_NODE_ENABLED_INSTRUMENTATIONS` to enable only certain instrumentations,
+OR the environment variable `OTEL_NODE_DISABLED_INSTRUMENTATIONS` to disable only certain instrumentations,
 by providing a comma-separated list of the instrumentation package names without the `@opentelemetry/instrumentation-` prefix.
 
 For example, to enable only
@@ -90,6 +91,12 @@ instrumentations:
 export OTEL_NODE_ENABLED_INSTRUMENTATIONS="http,nestjs-core"
 ```
 
+To disable only [@opentelemetry/instrumentation-fs](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-fs):
+
+```shell
+export OTEL_NODE_DISABLED_INSTRUMENTATIONS="fs"
+```
+
 To enable logging for troubleshooting, set the log level by setting the `OTEL_LOG_LEVEL` environment variable to one of the following:
 
 - `none`

metapackages/auto-instrumentations-node/src/utils.ts

@@ -147,6 +147,7 @@ export function getNodeAutoInstrumentations(
 ): Instrumentation[] {
   checkManuallyProvidedInstrumentationNames(Object.keys(inputConfigs));
   const enabledInstrumentationsFromEnv = getEnabledInstrumentationsFromEnv();
+  const disabledInstrumentationsFromEnv = getDisabledInstrumentationsFromEnv();
 
   const instrumentations: Instrumentation[] = [];
 
@@ -159,7 +160,8 @@ export function getNodeAutoInstrumentations(
 
     if (
       userConfig.enabled === false ||
-      !enabledInstrumentationsFromEnv.includes(name)
+      !enabledInstrumentationsFromEnv.includes(name) ||
+      disabledInstrumentationsFromEnv.includes(name)
     ) {
       diag.debug(`Disabling instrumentation for ${name}`);
       continue;
@@ -186,6 +188,22 @@ function checkManuallyProvidedInstrumentationNames(
   }
 }
 
+function getInstrumentationsFromEnv(envVar: string): string[] {
+  const envVarValue = process.env[envVar];
+  if (envVarValue == null) {
+    return [];
+  }
+
+  const instrumentationsFromEnv = envVarValue
+    ?.split(',')
+    .map(
+      instrumentationPkgSuffix =>
+        `@opentelemetry/instrumentation-${instrumentationPkgSuffix.trim()}`
+    );
+  checkManuallyProvidedInstrumentationNames(instrumentationsFromEnv);
+  return instrumentationsFromEnv;
+}
+
 /**
  * Returns the list of instrumentations that are enabled based on the environment variable.
  */
@@ -194,12 +212,23 @@ function getEnabledInstrumentationsFromEnv() {
     return Object.keys(InstrumentationMap);
   }
 
-  const instrumentationsFromEnv =
-    process.env.OTEL_NODE_ENABLED_INSTRUMENTATIONS.split(',').map(
-      instrumentationPkgSuffix =>
-        `@opentelemetry/instrumentation-${instrumentationPkgSuffix.trim()}`
-    );
-  checkManuallyProvidedInstrumentationNames(instrumentationsFromEnv);
+  const instrumentationsFromEnv = getInstrumentationsFromEnv(
+    'OTEL_NODE_ENABLED_INSTRUMENTATIONS'
+  );
+  return instrumentationsFromEnv;
+}
+
+/**
+ * Returns the list of instrumentations that are disabled based on the environment variable.
+ */
+function getDisabledInstrumentationsFromEnv() {
+  if (!process.env.OTEL_NODE_DISABLED_INSTRUMENTATIONS) {
+    return [];
+  }
+
+  const instrumentationsFromEnv = getInstrumentationsFromEnv(
+    'OTEL_NODE_DISABLED_INSTRUMENTATIONS'
+  );
   return instrumentationsFromEnv;
 }
 

metapackages/auto-instrumentations-node/test/utils.test.ts

@@ -89,6 +89,31 @@ describe('utils', () => {
       }
     });
 
+    it('should include all instrumentations except those disabled via OTEL_NODE_DISABLED_INSTRUMENTATIONS environment variable', () => {
+      process.env.OTEL_NODE_DISABLED_INSTRUMENTATIONS =
+        'fs,aws-sdk, aws-lambda'; // separator with and without whitespaces should be allowed
+      try {
+        const instrumentations = getNodeAutoInstrumentations();
+        const disabledInstrumentations = new Set([
+          '@opentelemetry/instrumentation-fs',
+          '@opentelemetry/instrumentation-aws-sdk',
+          '@opentelemetry/instrumentation-aws-lambda',
+        ]);
+        const enabledInstrumentationNames = new Set(
+          instrumentations.map(i => i.instrumentationName)
+        );
+
+        for (const disabledInstrumentation of disabledInstrumentations) {
+          assert.strictEqual(
+            enabledInstrumentationNames.has(disabledInstrumentation),
+            false
+          );
+        }
+      } finally {
+        delete process.env.OTEL_NODE_DISABLED_INSTRUMENTATIONS;
+      }
+    });
+
     it('should show error for none existing instrumentation', () => {
       const spy = sinon.stub(diag, 'error');
       const name = '@opentelemetry/instrumentation-http2';

packages/winston-transport/README.md

@@ -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
 

plugins/node/instrumentation-amqplib/README.md

@@ -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
 

plugins/node/instrumentation-amqplib/src/amqplib.ts

@@ -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]

plugins/node/instrumentation-cucumber/README.md

@@ -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

plugins/node/instrumentation-cucumber/src/instrumentation.ts

@@ -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');

plugins/node/instrumentation-dataloader/README.md

@@ -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
 

plugins/node/instrumentation-dataloader/src/instrumentation.ts

@@ -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);

plugins/node/instrumentation-fs/README.md

@@ -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

plugins/node/instrumentation-kafkajs/README.md

@@ -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
 

plugins/node/instrumentation-kafkajs/src/instrumentation.ts

@@ -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(

plugins/node/instrumentation-lru-memoizer/README.md

@@ -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
 

plugins/node/instrumentation-mongoose/README.md

@@ -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