Merge branch 'main' into tm-pino-logs-bridge

.github/ISSUE_TEMPLATE/plugin_request.md → .github/ISSUE_TEMPLATE/instrumentation_request.md

@@ -5,9 +5,7 @@ labels: instrumentation-request
 ---
 
 <!--
-**NB:** Before opening an instrumentation request against this repo, consider whether the instrumentation should/could be implemented in the [other OpenTelemetry client libraries](https://github.com/open-telemetry/). If so, please [open an issue on opentelemetry-specification](https://github.com/open-telemetry/opentelemetry-specification/issues/new) first.
-
-You are welcome to try to build your own instrumentation. If you do, please let us know if you have any questions/feedback.
+**NB:** Before opening an instrumentation request against this repo, please read [the contributing guidelines for new instrumentation](../../CONTRIBUTING.md#new-instrumentation).
 -->
 
 ### Is your instrumentation request related to a problem? Please describe
@@ -27,6 +25,15 @@ Weekly Downloads:
 
 Versions:
 
+### Code Owners
+
+<!--
+New Instrumentation requests need at least 2 code-owners that will maintain the instrumentation long-term.
+-->
+
+- Owner 1
+- Owner 2
+
 ### Additional context
 <!--
 Add any other context or screenshots about the instrumentation request here. Is there a reference you could point for the well-defined lifecycle methods?

.github/ISSUE_TEMPLATE/ownership_request.md

@@ -0,0 +1,39 @@
+---
+name: Component Ownership Request
+about: Request yourself being added as a component owner for a component in this repository
+labels: type:ownership-request
+---
+
+<!--
+**NB:** Before opening a component ownership request against this repo, please read [CONTRIBUTING.md](../../CONTRIBUTING.md#component-ownership) and its subsections first.
+-->
+
+### Which component are you requesting ownership of?
+
+<!--
+Put a link to the component here.
+-->
+
+### Related Work and Qualifications
+
+<!--
+List here why you're qualified to take ownership of the component, see [CONTRIBUTING.md](../../CONTRIBUTING.md#becoming-a-component-owner) for details.
+
+Examples:
+- I am working on <related open-source-project> and have deep knowledge of the instrumented package.
+- I am using the instrumented package on a regular basis and have deep knowledge of the instrumented package.
+- I am working on <similar package or system> and have deep knowledge of the concepts of the instrumented package.
+- I am an engineer at an observability vendor we would like to sponsor this component.
+-->
+
+### Checklist
+
+- [ ] I have read [CONTRIBUTING.md](../../CONTRIBUTING.md) and understand the responsibilities of a component owner.
+- [ ] I agree to follow and uphold the [mission, vision and values](https://github.com/open-telemetry/community/blob/main/mission-vision-values.md) of the OpenTelemetry project
+- [ ] I understand that the component I'm requesting ownership of may be subject to the [OpenTelemetry Semantic Conventions](https://github.com/open-telemetry/semantic-conventions) and agree to follow the rules set out therein.
+
+### Additional context
+
+<!--
+Add any other context that does not fit any of the above sections
+-->

.github/workflows/lint.yml

@@ -20,3 +20,4 @@ jobs:
         run: |
           npm run lint
           npm run lint:markdown
+          npm run lint:readme

CONTRIBUTING.md

@@ -14,6 +14,7 @@ We'd love your help!
   - [CHANGELOG](#changelog)
   - [Benchmarks](#benchmarks)
 - [Component Ownership](#component-ownership)
+  - [Becoming a Component Owner](#becoming-a-component-owner)
 - [Component Lifecycle](#component-lifecycle)
   - [Unreleased](#unreleased)
   - [Experimental](#experimental)
@@ -26,6 +27,7 @@ We'd love your help!
 - [Contributing Vendor Components](#contributing-vendor-components)
   - [Adding a New Vendor Component](#adding-a-new-vendor-component)
   - [Removing Vendor Components](#removing-vendor-components)
+- [New Instrumentation](#new-instrumentation)
 
 ## Development Quick Start
 
@@ -138,10 +140,44 @@ When two or more approaches must be compared, please write a benchmark in the be
 This repository contains many components which are maintained by more than the typical set of JS maintainers and approvers.
 Each component in this repository SHOULD have a component owner who is responsible for maintaining it.
 The README.md for each component SHOULD contain its owner, but the source of truth for component ownership is in [.github/component_owners.yml](.github/component_owners.yml).
-Component owners are generally given authority to make decisions relating to implementation and feature requests for their components, provided they follow the best practices set out by the maintainers.
+Component owners are generally given authority to make decisions relating to implementation and feature requests for their components,
+provided they follow the best practices set out by the maintainers and the [mission, vision and values](https://github.com/open-telemetry/community/blob/main/mission-vision-values.md)
+of the OpenTelemetry Project.
+
 Component owners MUST do their best to maintain a high level of quality, security, performance, and specification compliance within their components.
 Maintainers may override the decisions of component owners, but should only do so when they feel one or more of these traits is compromised.
 
+### Becoming a Component Owner
+
+To become a component owner, contributors SHOULD demonstrate prior knowledge of the instrumented package or the concepts therein.
+
+Ways do to so may be by providing proof of:
+
+- current or prior involvement with the community that develops the upstream package
+  - **Example:** A person working on MongoDB requesting ownership over a MongoDB instrumentation
+- current or prior involvement with a community that develops systems with similar concepts
+  - **Example:** A person previously working on a MySQL requesting ownership of a instrumentation package that instruments another database client library instrumentation.
+- current or prior extensive use of the instrumented package in other project they are involved in
+  - **Example:** A person working at a company that makes extensive use of the `fastify` library requesting ownership of the `@opentelemetry/instrumentation-fastify` package.
+- a vested interest in the telemetry being emitted from that instrumentation
+  - **Example:** A person employed at an observability vendor that relies on the continued maintenance of the instrumentation
+
+**Examples of proof may include but are not limited to:**
+
+- Links to issues/PRs they worked on
+- Links to blog posts authored by them on behalf of the organization developing that system
+- Membership in GitHub teams/organizations that are associated with the development of the upstream package
+
+Aspiring Component Owners MUST agree to uphold the [mission, vision and values](https://github.com/open-telemetry/community/blob/main/mission-vision-values.md) of the OpenTelemetry project.
+Further, aspiring component owners are expected to have knowledge of the [OpenTelemetry Semantic Conventions](https://github.com/open-telemetry/semantic-conventions)
+and MUST agree to adhere to the rules set out therein.
+
+If all these conditions are met, aspiring component owners are encouraged to self-nominate by opening an issue.
+@open-telemetry/javascript-maintainers will then engage on the issue, may ask questions, and will then - based on the
+information provided on the issue - either approve or deny the ownership request. If the ownership request has been
+approved, the new component owner opens a PR to add themselves to the list of owners ([.github/component_owners.yml](.github/component_owners.yml))
+for that package.
+
 ## Component Lifecycle
 
 This repository contains many components in various stages of the component lifecycle.
@@ -232,6 +268,38 @@ please ping ([@open-telemetry/javascript-approvers](https://github.com/orgs/open
 - New or changed functionality is documented if appropriate
 - Substantial changes should not be merged within 24 hours of opening in order to allow reviewers from all time zones to have a chance to review
 
+## New Instrumentation
+
+**Do not submit pull requests for new instrumentation without reading the following.**
+
+This project is dedicated to promoting the development of quality instrumentation using OpenTelemetry.
+To achieve this goal, we recognize that the instrumentation needs to be written using the best practices of OpenTelemetry, but also by developers that understand the package they are instrumenting.
+Additionally, the produced instrumentation needs to be maintained and evolved.
+
+The size of the OpenTelemetry JavaScript developer community is not large enough to support an ever-growing amount of instrumentation.
+Therefore, to reach our goal, we have the following recommendations for where instrumentation packages should live.
+
+1. Native to the instrumented package
+2. A dedicated public repository
+3. Here in the opentelemetry-js-contrib repository
+
+If possible, OpenTelemetry instrumentation should be included in the instrumented package.
+This will ensure the instrumentation reaches all package users, and is continuously maintained by developers that understand the package.
+
+If instrumentation cannot be directly included in the package it is instrumenting, it should be hosted in a dedicated public repository owned by its maintainer(s).
+This will appropriately assign maintenance responsibilities for the instrumentation and ensure these maintainers have the needed privilege to maintain the code.
+
+The last place instrumentation should be hosted is here in this repository.
+Maintaining instrumentation here hampers the development of OpenTelemetry for JavaScript and therefore should be avoided.
+When instrumentation cannot be included in a target package and there is good reason to not host it in a separate and dedicated repository an [instrumentation request](https://github.com/open-telemetry/opentelemetry-js-contrib/issues/new/choose) should be filed.
+Note that new instrumentation needs at least two contributors assigned to it as code-owners.  It is the responsibility
+of the requesting party to reach out and find code-owners for the proposed instrumentation. The instrumentation request
+needs to be accepted before any pull requests for the instrumentation can be considered for merging.
+
+Regardless of where instrumentation is hosted, it needs to be discoverable.
+The [OpenTelemetry registry](https://opentelemetry.io/registry/) exists to ensure that instrumentation is discoverable.
+You can find out how to add instrumentation to the registry [here](https://github.com/open-telemetry/opentelemetry.io#adding-a-project-to-the-opentelemetry-registry).
+
 ## Contributing Vendor Components
 
 This repo is generally meant for hosting components that work with popular open-source frameworks and tools. However, it is also possible to contribute components specific to a 3rd party vendor in this repo.

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

README.md

@@ -48,6 +48,7 @@ This project includes:
 - [Resource Detectors](./detectors).
 
 **Instrumentations**: OpenTelemetry can collect tracing data automatically using instrumentations. Vendors/Users can also create and use their own.
+Please read the [contributing guidelines on adding new instrumentation](CONTRIBUTING.md#new-instrumentation) before opening any PRs.
 
 **Resource Detectors**: OpenTelemetry can collect resource attributes of the entity that producing telemetry. For example, a process producing telemetry that is running in a container on Kubernetes has a Pod name, it is in a namespace and possibly is part of a Deployment which also has a name. All three of these attributes can be included in the `Resource`.