From b3531d333949c396afa65e5b41725f05d826d21a Mon Sep 17 00:00:00 2001 From: Lukas Hering Date: Sat, 26 Sep 2026 15:01:59 -0400 Subject: [PATCH 1/3] feat: stabilize semantic conventions package --- eachdist.ini | 2 +- opentelemetry-sdk/pyproject.toml | 2 +- .../DEVELOPMENT.md | 26 +++++ opentelemetry-semantic-conventions/README.rst | 98 ++++++++++++++++--- .../opentelemetry/semconv/version/__init__.py | 2 +- 5 files changed, 115 insertions(+), 15 deletions(-) create mode 100644 opentelemetry-semantic-conventions/DEVELOPMENT.md diff --git a/eachdist.ini b/eachdist.ini index 3bee29f59df..338bad317a4 100644 --- a/eachdist.ini +++ b/eachdist.ini @@ -26,6 +26,7 @@ packages= opentelemetry-exporter-otlp-proto-http opentelemetry-exporter-otlp opentelemetry-api + opentelemetry-semantic-conventions [prerelease] version=0.67b0.dev @@ -42,7 +43,6 @@ packages= opentelemetry-exporter-otlp-common opentelemetry-configuration opentelemetry-proto-json - opentelemetry-semantic-conventions opentelemetry-test-utils [lintroots] diff --git a/opentelemetry-sdk/pyproject.toml b/opentelemetry-sdk/pyproject.toml index 0a71623735c..b8db875d527 100644 --- a/opentelemetry-sdk/pyproject.toml +++ b/opentelemetry-sdk/pyproject.toml @@ -27,7 +27,7 @@ classifiers = [ ] dependencies = [ "opentelemetry-api == 1.46.0.dev", - "opentelemetry-semantic-conventions == 0.67b0.dev", + "opentelemetry-semantic-conventions == 1.46.0.dev", "typing-extensions >= 4.5.0", ] diff --git a/opentelemetry-semantic-conventions/DEVELOPMENT.md b/opentelemetry-semantic-conventions/DEVELOPMENT.md new file mode 100644 index 00000000000..3aded70efb8 --- /dev/null +++ b/opentelemetry-semantic-conventions/DEVELOPMENT.md @@ -0,0 +1,26 @@ +# OpenTelemetry Semantic Conventions + +The modules in this package are generated from the +[OpenTelemetry Semantic Conventions](https://github.com/open-telemetry/semantic-conventions) +registry using [weaver](https://github.com/open-telemetry/weaver). Do **NOT** modify the +generated files by hand. + +## Updating to a new semantic conventions release + +1. In `scripts/semconv/generate.sh`, set `SEMCONV_VERSION` to the new release + (and bump `OTEL_WEAVER_IMG_VERSION` if needed). +2. Add the new schema URL to `Schemas` in + `src/opentelemetry/semconv/schemas.py`. The script fails if it is missing. +3. Run `scripts/semconv/generate.sh` (requires Docker). +4. **Update the "Supported Semantic Conventions Version" section of + [`README.rst`](README.rst) to the new `SEMCONV_VERSION`**, including the + link to the upstream tag. The README must always state the semantic + conventions version this package is generated from. +5. Review the diff against the compatibility rules below, then commit. + +## Compatibility rules + +This package is on the stable 1.x release line. The stable modules +(`opentelemetry.semconv.attributes`, `opentelemetry.semconv.metrics` and +`opentelemetry.semconv.schemas`) are public API and **MUST** stay backwards +compatible. diff --git a/opentelemetry-semantic-conventions/README.rst b/opentelemetry-semantic-conventions/README.rst index e5a40e739c8..8a9b168efb0 100644 --- a/opentelemetry-semantic-conventions/README.rst +++ b/opentelemetry-semantic-conventions/README.rst @@ -6,7 +6,7 @@ OpenTelemetry Semantic Conventions .. |pypi| image:: https://badge.fury.io/py/opentelemetry-semantic-conventions.svg :target: https://pypi.org/project/opentelemetry-semantic-conventions/ -This library contains generated code for the semantic conventions defined by the OpenTelemetry specification. +This library contains generated code for the `OpenTelemetry Semantic Conventions`_. Installation ------------ @@ -15,23 +15,97 @@ Installation pip install opentelemetry-semantic-conventions -Code Generation ---------------- +Supported Semantic Conventions Version +-------------------------------------- -These files were generated automatically from code in semconv_. -To regenerate the code, run ``../scripts/semconv/generate.sh``. +This release of the package is generated from +`OpenTelemetry Semantic Conventions v1.44.0 `_. -To build against a new release or specific commit of opentelemetry-specification_, -update the ``SPEC_VERSION`` variable in -``../scripts/semconv/generate.sh``. Then run the script and commit the changes. +The version of this package is independent of the semantic conventions version it +is generated from. Check this section, or ``opentelemetry.semconv.schemas.Schemas``, +to find out which semantic conventions version a given release supports. -.. _opentelemetry-specification: https://github.com/open-telemetry/opentelemetry-specification -.. _semconv: https://github.com/open-telemetry/opentelemetry-python/tree/main/scripts/semconv +Stability +--------- +This package follows `Semantic Versioning `_ for its +**public** modules only (i.e. portions of the Semantic Conventions which have +been marked as **stable**). + +Stable modules +~~~~~~~~~~~~~~ + +The following modules contain only conventions marked **stable** upstream: + +* ``opentelemetry.semconv.attributes.*`` +* ``opentelemetry.semconv.metrics.*`` +* ``opentelemetry.semconv.schemas`` + +Within the 1.x release line, these modules will not remove or rename any symbol. +Upgrading can still change them in the following ways: + +* New attributes, metrics, enum members and schema URLs may be added in minor releases. +* An attribute or metric may be **deprecated** when the semantic conventions deprecate it. + Deprecated symbols are documented as deprecated (enum classes are also marked with + ``@deprecated``), but remain available. +* Documentation (docstrings) may change. + +Incubating modules +~~~~~~~~~~~~~~~~~~ + +.. warning:: + + Anything under ``opentelemetry.semconv._incubating`` is **not** covered by + Semantic Versioning and is subject to breaking changes across **minor** (and patch) + versions of this package. + +``opentelemetry.semconv._incubating.attributes.*`` and +``opentelemetry.semconv._incubating.metrics.*`` contain every convention in the +semantic conventions registry, including those in development or experimental/deprecated +ones. These can be renamed, changed or removed upstream at any time +and this package will follow those changes without a major version bump. + +.. important:: + + Libraries that depend on anything under ``opentelemetry.semconv._incubating`` + **SHOULD** pin an exact version of this package, for example:: + + dependencies = [ + "opentelemetry-semantic-conventions == 1.46.0", + ] + + A version range such as ``~= 1.46`` or ``>= 1.46`` can break your library when a + new minor version of this package is released. + +The ``_incubating`` modules also contain copies of the stable conventions, marked as +deprecated in favor of the stable module. When a convention is available in a stable +module, import it from there. + +Other caveats +~~~~~~~~~~~~~ + +* Not every semantic conventions namespace is generated. Namespaces specific to other + languages or runtimes (e.g. ``jvm``, ``dotnet``, ``go`` and ``nodejs``) are + excluded. See ``excluded_namespaces`` in the + `weaver configuration `_. + Excluded namespaces may be added in a future minor release. +* ``opentelemetry.semconv.trace`` and ``opentelemetry.semconv.resource`` are legacy + modules and are deprecated. Use ``opentelemetry.semconv.attributes`` or + ``opentelemetry.semconv._incubating.attributes`` instead. + +Contributing +------------ + +This package is generated. See `DEVELOPMENT.md`_ for how to regenerate it and +the compatibility rules maintainers must follow. References ---------- * `OpenTelemetry Project `_ -* `OpenTelemetry Semantic Conventions Definitions `_ -* `generate.sh script `_ +* `OpenTelemetry Semantic Conventions`_ +* `Semantic Conventions repository `_ +* `Semantic Conventions stability guarantees `_ + +.. _OpenTelemetry Semantic Conventions: https://opentelemetry.io/docs/specs/semconv/ +.. _DEVELOPMENT.md: https://github.com/open-telemetry/opentelemetry-python/blob/main/opentelemetry-semantic-conventions/DEVELOPMENT.md diff --git a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/version/__init__.py b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/version/__init__.py index b83363231d3..6e653a1c7ce 100644 --- a/opentelemetry-semantic-conventions/src/opentelemetry/semconv/version/__init__.py +++ b/opentelemetry-semantic-conventions/src/opentelemetry/semconv/version/__init__.py @@ -1,4 +1,4 @@ # Copyright The OpenTelemetry Authors # SPDX-License-Identifier: Apache-2.0 -__version__ = "0.67b0.dev" +__version__ = "1.46.0.dev" From 20623bd3878cb22e2f6c1dc873eb1e63fa99fc75 Mon Sep 17 00:00:00 2001 From: Lukas Hering Date: Sat, 26 Sep 2026 15:10:00 -0400 Subject: [PATCH 2/3] add section on vendoring incubating conventions --- opentelemetry-semantic-conventions/README.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/opentelemetry-semantic-conventions/README.rst b/opentelemetry-semantic-conventions/README.rst index 8a9b168efb0..6e11a917b0a 100644 --- a/opentelemetry-semantic-conventions/README.rst +++ b/opentelemetry-semantic-conventions/README.rst @@ -29,7 +29,7 @@ Stability --------- This package follows `Semantic Versioning `_ for its -**public** modules only (i.e. portions of the Semantic Conventions which have +**public** modules only (i.e. portions of the semantic conventions which have been marked as **stable**). Stable modules @@ -81,6 +81,10 @@ The ``_incubating`` modules also contain copies of the stable conventions, marke deprecated in favor of the stable module. When a convention is available in a stable module, import it from there. +Library authors that wish to depend on incubating semantic conventions without having +to pin `opentelemetry-semantic-conventions` can consider vendoring incubating conventions +directly into their package. + Other caveats ~~~~~~~~~~~~~ From b565ec0d904a1e22ddae3f6d7edcda6ccad4d782 Mon Sep 17 00:00:00 2001 From: Lukas Hering Date: Sat, 26 Sep 2026 15:17:04 -0400 Subject: [PATCH 3/3] add changelog fragment --- .changelog/5698.added | 1 + 1 file changed, 1 insertion(+) create mode 100644 .changelog/5698.added diff --git a/.changelog/5698.added b/.changelog/5698.added new file mode 100644 index 00000000000..6a1b83d51be --- /dev/null +++ b/.changelog/5698.added @@ -0,0 +1 @@ +`opentelemetry-semantic-conventions`: stabilize semantic conventions package