From 9c92bf051a511816e68555806c3a7dd5fe556fc3 Mon Sep 17 00:00:00 2001 From: tammy-baylis-swi Date: Fri, 17 Apr 2026 15:23:09 -0500 Subject: [PATCH 1/2] Update Guideline for Instr with issues --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 29d600baca..531952a468 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -307,6 +307,8 @@ The continuous integration overrides that environment variable with as per the c Below is a checklist of things to be mindful of when implementing a new instrumentation or working on a specific instrumentation. It is one of our goals as a community to keep the implementation specific details of instrumentations as similar across the board as possible for ease of testing and feature parity. It is also good to abstract as much common functionality as possible. +- Find or Create a new [Issue](https://github.com/open-telemetry/opentelemetry-python-contrib/issues) describing the framework to instrument and its use cases to support with OpenTelemetry. + - Be familiar with the [expectations from contributors](#expectations-from-contributors) that apply. - Follow semantic conventions - The instrumentation should follow the semantic conventions defined [here](https://github.com/open-telemetry/semantic-conventions/tree/main/docs). - To ensure consistency, we encourage contributions that align with [STABLE](https://opentelemetry.io/docs/specs/otel/document-status/#lifecycle-status) semantic conventions if available. This approach helps us avoid potential confusion and reduces the need to support multiple outdated versions of semantic conventions. However, we are still open to considering exceptional cases where changes are well justified. From 9da1fe758578705de7fce14201c559aa115c9a7a Mon Sep 17 00:00:00 2001 From: tammy-baylis-swi Date: Mon, 20 Apr 2026 10:10:03 -0500 Subject: [PATCH 2/2] Add guidelines-for-native --- CONTRIBUTING.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 531952a468..d790a6cb3d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,6 +42,7 @@ Please also read the [OpenTelemetry Contributor Guide](https://github.com/open-t - [Guideline for GenAI instrumentations](#guideline-for-genai-instrumentations) - [Get Involved](#get-involved) - [Expectations from contributors](#expectations-from-contributors) + - [Guidelines for native OpenTelemetry instrumentation](#guidelines-for-native-opentelemetry-instrumentation) - [Updating supported Python versions](#updating-supported-python-versions) - [Bumping the Python baseline](#bumping-the-python-baseline) - [Adding support for a new Python release](#adding-support-for-a-new-python-release) @@ -307,8 +308,9 @@ The continuous integration overrides that environment variable with as per the c Below is a checklist of things to be mindful of when implementing a new instrumentation or working on a specific instrumentation. It is one of our goals as a community to keep the implementation specific details of instrumentations as similar across the board as possible for ease of testing and feature parity. It is also good to abstract as much common functionality as possible. -- Find or Create a new [Issue](https://github.com/open-telemetry/opentelemetry-python-contrib/issues) describing the framework to instrument and its use cases to support with OpenTelemetry. +- Find or create a new [Issue](https://github.com/open-telemetry/opentelemetry-python-contrib/issues) describing the tool or framework to instrument and its use cases to support with OpenTelemetry. - Be familiar with the [expectations from contributors](#expectations-from-contributors) that apply. + - If you're a tool or framework maintainer, please consider using the OpenTelemetry API directly to support [native instrumentation](#guidelines-for-native-opentelemetry-instrumentation) instead of adding a new community instrumentation library. - Follow semantic conventions - The instrumentation should follow the semantic conventions defined [here](https://github.com/open-telemetry/semantic-conventions/tree/main/docs). - To ensure consistency, we encourage contributions that align with [STABLE](https://opentelemetry.io/docs/specs/otel/document-status/#lifecycle-status) semantic conventions if available. This approach helps us avoid potential confusion and reduces the need to support multiple outdated versions of semantic conventions. However, we are still open to considering exceptional cases where changes are well justified. @@ -386,6 +388,16 @@ Instrumentations that relate to [Generative AI](https://opentelemetry.io/docs/sp OpenTelemetry is an open source community, and as such, greatly encourages contributions from anyone interested in the project. With that being said, there is a certain level of expectation from contributors even after a pull request is merged, specifically pertaining to instrumentations. The OpenTelemetry Python community expects contributors to maintain a level of support and interest in the instrumentations they contribute. This is to ensure that the instrumentation does not become stale and still functions the way the original contributor intended. Some instrumentations also pertain to libraries that the current members of the community are not so familiar with, so it is necessary to rely on the expertise of the original contributing parties. +### Guidelines for native OpenTelemetry instrumentation + +The preferred approach to supporting instrumentation of a tool or framework is native OpenTelemetry instrumentation. Compared to adding a new instrumentation library to this community repository, native instrumentation is better for: + +* continued support by framework experts long-term +* access to more context for critical paths and correlations +* granularity and performance + +To support native instrumentation, the tool or framework should use the [OpenTelemetry API](https://opentelemetry-python.readthedocs.io/en/latest/) directly to emit traces, metrics, and logs. + ## Updating supported Python versions ### Bumping the Python baseline