You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: GUIDELINES.md
+78
Original file line number
Diff line number
Diff line change
@@ -198,6 +198,84 @@ Instrumentation may add additional patch/unpatch messages for specific functions
198
198
199
199
The cases above are not covered by the base class and offer additional context to the user troubleshooting an issue with the instrumentation.
200
200
201
+
## Supported Versions
202
+
203
+
Supported versions can refer to 2 entities in the context of OpenTelemetry instrumentations:
204
+
205
+
- `Instrumented Package` - This is the user-facing package/s that the end user has installed in his application and is familiar with.
206
+
- `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`.
207
+
208
+
### `Instrumented Package` Documentation
209
+
210
+
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.
211
+
212
+
### `Patched Package`s Supported Versions
213
+
214
+
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:
215
+
216
+
```js
217
+
const supportedVersions = ['>=1.2.3 <3'];
218
+
219
+
protected init() {
220
+
221
+
const someModuleFile = new InstrumentationNodeModuleFile(
222
+
'foo/lib/some-file.js',
223
+
supportedVersions,
224
+
myFilePatch,
225
+
myFileUnpatch,
226
+
);
227
+
228
+
const module = new InstrumentationNodeModuleDefinition(
229
+
'foo',
230
+
supportedVersions,
231
+
myModulePatch,
232
+
myModuleUnpatch,
233
+
[someModuleFile]
234
+
);
235
+
return module
236
+
}
237
+
```
238
+
239
+
### Variations
240
+
241
+
There can be few variations between the instrumented package and the patched package:
242
+
243
+
- Single Module - instrumentation patches the same module that is instrumented.
244
+
- Different Modules - instrumentation patches internal modules with different names and version ranges as of the instrumented package.
- Multiple Modules - instrumentation may instrument a set of (potentially large number of) user-facing instrumented packages.
247
+
- 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.
248
+
249
+
### Range Specification
250
+
251
+
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.
252
+
253
+
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.
254
+
255
+
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.
256
+
257
+
New major versions should be reviewed and tested before being added to the supported versions list.
258
+
259
+
Specific guidelines for different cases:
260
+
261
+
- 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.
262
+
- 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.
263
+
- For `Multiple Modules`, the supported versions range should be specified for each module in the README file with the supported versions.
264
+
- For `Different Patch Logic`, the use of supported versions can sometimes be more flexible, and the README should specify useful versioning information.
265
+
266
+
### Add New Supported Versions
267
+
268
+
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.
269
+
270
+
Checklist for adding a new version to the supported versions list:
271
+
272
+
- [ ] Review which functions are patched by the instrumentation and if they were changed in the new version that need support in code.
273
+
- [ ] Check for breaking changes in the new version that could affect the instrumentation.
274
+
- [ ] Test the instrumentation with the new version to ensure it works as expected.
275
+
- [ ] Update the supported versions list in the instrumentation code, perhaps with different patches and additional `InstrumentationNodeModuleDefinition`s that target the new version.
276
+
- [ ] Update the README file to reflect the support for new versions.
277
+
- [ ] For instrumentations that use test-all-versions `.tav.yml`, add the new version to the list of versions to test.
Copy file name to clipboardExpand all lines: plugins/node/instrumentation-runtime-node/README.md
+6-6
Original file line number
Diff line number
Diff line change
@@ -6,6 +6,12 @@
6
6
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`).
7
7
While currently it is limited to metrics, it may be modified to produce other signals in the future.
8
8
9
+
## Supported Versions
10
+
11
+
- Node.js `>=14.10`
12
+
13
+
<!-- - 14.6.0 - this package uses _private properties_ -->
| [`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. |
60
66
61
-
## Supported Node.js versions
62
-
63
-
v14.10.0+
64
-
65
-
<!-- - 14.6.0 - this package uses _private properties_ -->
66
-
67
67
## Useful links
68
68
69
69
- For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
For further automatic instrumentation instruction see the [@opentelemetry/instrumentation](https://www.npmjs.com/package/@opentelemetry/instrumentation) package.
@@ -45,10 +49,6 @@ await client.execute('select * from foo');
45
49
|`responseHook`|`CassandraDriverResponseCustomAttributeFunction`|`undefined`| Hook for adding custom attributes before response is handled |
46
50
|`maxQueryLength`|`number`|`65536`| If `enhancedDatabaseReporting` is enabled, limits the attached query strings to this length. |
47
51
48
-
### Supported versions
49
-
50
-
`>=4.4 <5.0`
51
-
52
52
## Semantic Conventions
53
53
54
54
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)
0 commit comments