Skip to content

Commit cb8e044

Browse files
lmolkovaarminru
andauthored
Update instrumentation library naming guidance to avoid conflicts between external and otel instrumentations (open-telemetry#4187)
Some package managers (PyPi) don't provide means to reserve namespaces for projects. We also have a number of **external** instrumentation libraries in python that follow current guidance and use `opentelemetry-instrumentation-{component}` naming pattern. These libraries are hard to distinguish from otel-authored ones. Also, when someone (legitimately following existing guidance) creates an external instrumentation package like this, it blocks our ability to have OTel-authored instrumentation with this 'good' name. See open-telemetry/opentelemetry-python-contrib#2759 (comment) for real-life example. ## Changes This PR changes the recommendation to: - otel authored instrumentation should use `opentelemetry-instrumentation-*` pattern - external instrumentation should not use this pattern and should prefix lib name with their company/project/etc name * ~~[ ] Related issues #~~ * ~~[ ] Related [OTEP(s)](https://github.com/open-telemetry/oteps) #~~ * ~~[ ] Links to the prototypes (when adding or changing features)~~ * [x] [`CHANGELOG.md`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/CHANGELOG.md) file updated for non-trivial changes * ~~[ ] [`spec-compliance-matrix.md`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md) updated if necessary~~ --------- Co-authored-by: Armin Ruech <[email protected]>
1 parent eaacf07 commit cb8e044

File tree

2 files changed

+14
-3
lines changed

2 files changed

+14
-3
lines changed

Diff for: CHANGELOG.md

+3
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,9 @@ release.
3232

3333
### Common
3434

35+
- Update instrumentation library guidance to avoid naming collisions between external and OTel instrumentations.
36+
([#4187](https://github.com/open-telemetry/opentelemetry-specification/pull/4187))
37+
3538
### Supplementary Guidelines
3639

3740
## v1.36.0 (2024-08-12)

Diff for: specification/overview.md

+11-3
Original file line numberDiff line numberDiff line change
@@ -384,9 +384,17 @@ an [Instrumentation Library](glossary.md#instrumentation-library).
384384
An instrumentation library should be named to follow any naming conventions of
385385
the instrumented library (e.g. 'middleware' for a web framework).
386386

387-
If there is no established name, the recommendation is to prefix packages
388-
with "opentelemetry-instrumentation", followed by the instrumented library
389-
name itself. Examples include:
387+
For instrumentation hosted in OpenTelemetry repositories, the recommendation is
388+
to prefix packages with "opentelemetry-instrumentation", followed by the
389+
instrumented library name itself. Examples include:
390390

391391
* opentelemetry-instrumentation-flask (Python)
392392
* @opentelemetry/instrumentation-grpc (Javascript)
393+
394+
Instrumentations libraries not hosted by OpenTelemetry should avoid
395+
potential naming collisions with OpenTelemetry-hosted packages.
396+
For example, they may prefix instrumentation package name with their company or
397+
project name:
398+
399+
* {company}-opentelemetry-instrumentation-{component} (Python)
400+
* @{company}/opentelemetry-instrumentation-{component} (Javascript)

0 commit comments

Comments
 (0)