OpenTelemetry Semantic Conventions

0.61b0 verified Tue May 12 auth: no python install: stale quickstart: verified

OpenTelemetry Semantic Conventions library for OpenTelemetry projects, providing standard definitions and formats for telemetry data. Currently at version 0.61b0, it follows a semi-regular release cadence with breaking changes announced in advance.

pip install opentelemetry-semantic-conventions

Common errors

error ModuleNotFoundError: No module named 'opentelemetry.semconv' ↓

cause This error typically occurs when the `opentelemetry-semantic-conventions` package is not installed, or when there's a version mismatch between `opentelemetry-sdk` and `opentelemetry-semantic-conventions` where the `semconv` module's expected location or existence has changed.

fix

Ensure opentelemetry-semantic-conventions is installed (pip install opentelemetry-semantic-conventions) and that all OpenTelemetry packages (API, SDK, instrumentation, and semantic conventions) are pinned to compatible versions from the same release train to avoid module location changes.

error ImportError: cannot import name 'SpanAttributes' from 'opentelemetry.semconv.trace' ↓

cause The `SpanAttributes` constant was removed or renamed in newer versions of `opentelemetry-semantic-conventions`, causing existing code that tries to import it to fail. This is often due to breaking changes in semantic convention definitions across versions.

fix

Update your code to use the new attribute naming conventions. For example, attributes are now typically accessed directly via from opentelemetry.semconv.trace import SpanAttributes is replaced by importing specific attributes, or the attributes themselves have been renamed (e.g., SpanAttributes might be replaced by directly using constants from opentelemetry.semconv.attributes). Review the latest opentelemetry-semantic-conventions documentation for the correct attribute names and import paths for your installed version.

error ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. Required by opentelemetry-instrumentation-flask==0.44b0: opentelemetry-semantic-conventions==0.44b0 But opentelemetry-sdk==1.22.0 requires: opentelemetry-semantic-conventions==0.43b0. ↓

cause OpenTelemetry Python packages, including `opentelemetry-semantic-conventions`, are released in lockstep, meaning the SDK, API, and instrumentation libraries expect specific, matching versions of the semantic conventions. This error occurs when installing different OpenTelemetry components with incompatible version requirements for `opentelemetry-semantic-conventions`.

fix

Pin all OpenTelemetry Python packages (e.g., opentelemetry-api, opentelemetry-sdk, opentelemetry-instrumentation-*, and opentelemetry-semantic-conventions) to compatible versions from the same release. For example, if using opentelemetry-sdk==1.23.0, ensure opentelemetry-semantic-conventions==0.44b0 and any instrumentation libraries are also compatible with that release.

error AttributeError: 'module' object has no attribute 'SEMATTRS_HTTP_METHOD' ↓

cause This error indicates that an attribute constant, specifically one prefixed with `SEMATTRS_` (or `SEMRESATTRS_`), is no longer available in the `opentelemetry-semantic-conventions` module. This is a common breaking change where attribute naming conventions were standardized to use an `ATTR_` prefix instead.

fix

Migrate your code to use the updated attribute naming convention, typically by replacing SEMATTRS_ or SEMRESATTRS_ prefixed attributes with their ATTR_ counterparts. For example, SEMATTRS_HTTP_METHOD should be updated to ATTR_HTTP_REQUEST_METHOD. You might also need to import these new constants from a different module path if the structure has changed.

Warnings

breaking The behavior of `start_span` and `start_as_current_span` was updated to propagate span contexts differently. ↓

fix Update your usage of these methods according to the new behavior.

deprecated The `LoggingHandler` from opentelemetry-sdk is deprecated. ↓

fix Use `opentelemetry-instrumentation-logging` instead.

gotcha The application failed because the 'OTEL_KEY' environment variable was not found. This key is typically required for authentication or configuration of the OpenTelemetry collector/exporter. ↓

fix Ensure the 'OTEL_KEY' environment variable is correctly set in the deployment environment.

gotcha A required environment variable or configuration key named `OTEL_KEY` was not found. This key is often used for API authentication or exporter configuration. ↓

fix Ensure the `OTEL_KEY` environment variable is set in your environment or that the equivalent configuration (e.g., an API key within your application's OpenTelemetry setup) is properly provided.

Install compatibility stale last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - - -

3.10 slim (glibc) - - - -

3.11 alpine (musl) - - - -

3.11 slim (glibc) - - - -

3.12 alpine (musl) - - - -

3.12 slim (glibc) - - - -

3.13 alpine (musl) - - - -

3.13 slim (glibc) - - - -

3.9 alpine (musl) - - - -

3.9 slim (glibc) - - - -

Imports

SemanticAttributes
```
from opentelemetry.semconv import SemanticAttributes
```
Ensure to use the correct import path from the semantic conventions module.

Quickstart verified last tested: 2026-04-23

This quickstart demonstrates how to utilize SemanticAttributes for telemetry data.

import os

# Example usage of SemanticAttributes
attribute_key = 'http.method'
attribute_value = 'GET'

if os.environ.get('OTEL_KEY', ''):
    print(f'Setting attribute: {attribute_key} = {attribute_value}')
else:
    print('OTEL_KEY not found!')