OpenTelemetry semantic attributes convention

What are semantic attributes?

OpenTelemetry semantic attribute conventions are standardized naming and value specifications for telemetry data attributes across traces, metrics, and logs. These conventions ensure consistency and interoperability when instrumenting applications and services.

Attributes use dot-notation namespacing (e.g., http.method, db.connection_string) and follow consistent naming patterns. The conventions specify not only attribute names but also their expected values, data types, and appropriate usage contexts.

To maintain compatibility with other tools like Prometheus and Tempo, Uptrace replaces dots with underscores in attribute names. For example, service.name becomes service_name.

Evolution

The semantic conventions are actively maintained and versioned separately from the OpenTelemetry specification. They continue to expand to cover new technologies, protocols, and use cases while maintaining backward compatibility where possible.

To simplify migration between different versions, Uptrace allows you to select your desired semantic convention version on the Project Settings page. Once selected, Uptrace automatically renames certain attributes to follow the chosen convention. For example, it will rename deployment_environment to deployment_environment_name.

Uptrace does not modify existing rules to avoid breaking current queries, but we welcome suggestions for changes to include in the next supported version.

v1.33.0

v1.25.0

Indexed attributes

To store data, Uptrace uses ClickHouse, a columnar database that stores data in columns rather than rows. This means that instead of storing all data for a single record together, each column is stored separately.

To improve query performance, Uptrace places some attributes into separate columns. However, Uptrace cannot place all attributes into separate columns because it doesn't know the complete list of attributes in advance, and this list can become very large with thousands of attributes.