diff --git a/experimental/CHANGELOG.md b/experimental/CHANGELOG.md index b21634b9b22..9037238df14 100644 --- a/experimental/CHANGELOG.md +++ b/experimental/CHANGELOG.md @@ -31,6 +31,7 @@ All notable changes to experimental packages in this project will be documented ### :books: (Refine Doc) +* docs(instrumentation): better docs for supportedVersions option [#4693](https://github.com/open-telemetry/opentelemetry-js/pull/4693) @blumamir * docs: align all supported versions to a common format [#4696](https://github.com/open-telemetry/opentelemetry-js/pull/4696) @blumamir ### :house: (Internal) diff --git a/experimental/packages/opentelemetry-instrumentation/src/types.ts b/experimental/packages/opentelemetry-instrumentation/src/types.ts index 0445192de18..a1189eff486 100644 --- a/experimental/packages/opentelemetry-instrumentation/src/types.ts +++ b/experimental/packages/opentelemetry-instrumentation/src/types.ts @@ -88,7 +88,19 @@ export interface InstrumentationModuleFile { moduleExports?: unknown; - /** Supported version this file */ + /** Supported versions for the file. + * + * A module version is supported if one of the supportedVersions in the array satisfies the module version. + * The syntax of the version is checked with the `satisfies` function of "The semantic versioner for npm", see + * [`semver` package](https://www.npmjs.com/package/semver) + * If the version is not supported, we won't apply instrumentation patch. + * If omitted, all versions of the module will be patched. + * + * It is recommended to always specify a range that is bound to a major version, to avoid breaking changes. + * New major versions should be reviewed and tested before being added to the supportedVersions array. + * + * Example: ['>=1.2.3 <3'] + */ supportedVersions: string[]; /** Method to patch the instrumentation */ @@ -108,7 +120,19 @@ export interface InstrumentationModuleDefinition { /** Instrumented module version */ moduleVersion?: string; - /** Supported version of module */ + /** Supported version of module. + * + * A module version is supported if one of the supportedVersions in the array satisfies the module version. + * The syntax of the version is checked with the `satisfies` function of "The semantic versioner for npm", see + * [`semver` package](https://www.npmjs.com/package/semver) + * If the version is not supported, we won't apply instrumentation patch (see `enable` method). + * If omitted, all versions of the module will be patched. + * + * It is recommended to always specify a range that is bound to a major version, to avoid breaking changes. + * New major versions should be reviewed and tested before being added to the supportedVersions array. + * + * Example: ['>=1.2.3 <3'] + */ supportedVersions: string[]; /** Module internal files to be patched */