From 6672dbc97ddeb34f36c020a0f0a30323c8bc4d95 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 28 Aug 2024 11:31:01 -0700 Subject: [PATCH] Update instrumentation library naming guidance to avoid conflicts between external and otel instrumentations (#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 https://github.com/open-telemetry/opentelemetry-python-contrib/pull/2759#discussion_r1698096166 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 <7052238+arminru@users.noreply.github.com> --- CHANGELOG.md | 3 +++ specification/overview.md | 14 +++++++++++--- 2 files changed, 14 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2ef43e77f07..bf48c6354c6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -32,6 +32,9 @@ release. ### Common +- Update instrumentation library guidance to avoid naming collisions between external and OTel instrumentations. + ([#4187](https://github.com/open-telemetry/opentelemetry-specification/pull/4187)) + ### Supplementary Guidelines ## v1.36.0 (2024-08-12) diff --git a/specification/overview.md b/specification/overview.md index 5eb7b3d410c..1138fdd30fe 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -384,9 +384,17 @@ an [Instrumentation Library](glossary.md#instrumentation-library). An instrumentation library should be named to follow any naming conventions of the instrumented library (e.g. 'middleware' for a web framework). -If there is no established name, the recommendation is to prefix packages -with "opentelemetry-instrumentation", followed by the instrumented library -name itself. Examples include: +For instrumentation hosted in OpenTelemetry repositories, the recommendation is +to prefix packages with "opentelemetry-instrumentation", followed by the +instrumented library name itself. Examples include: * opentelemetry-instrumentation-flask (Python) * @opentelemetry/instrumentation-grpc (Javascript) + +Instrumentations libraries not hosted by OpenTelemetry should avoid +potential naming collisions with OpenTelemetry-hosted packages. +For example, they may prefix instrumentation package name with their company or +project name: + +* {company}-opentelemetry-instrumentation-{component} (Python) +* @{company}/opentelemetry-instrumentation-{component} (Javascript)