OpenTelemetry semantic conventions: names, types, and migrations

OpenTelemetry semantic conventions define what telemetry names and values mean: attributes, resource identity, span names, metric instruments and units, and event structure. They let different instrumentation libraries describe the same kind of operation consistently enough for shared queries and analysis.

That consistency is valuable, but it is not automatic. A Java and a Go library may implement different convention versions, and a backend may map incoming fields into its own schema. Treat the convention version and the receiving data model as part of the integration contract.

Why naming is only part of the contract

A dashboard cannot safely combine two fields merely because both describe an HTTP method in prose. Names, types, allowed values, placement, and requirement levels need to agree. http.request.method is more useful as a shared contract than a mixture of application-specific httpMethod and http_method keys.

The same principle applies to metric units, span kind, error status, and resource identity. Consistent data helps dashboards, alerts, automated analysis, and migration. It does not guarantee that a backend supports every convention or that every automatically generated view will work without configuration.

Describe the producer with Resource conventions

A Resource describes where telemetry came from. Common attributes include:

Set service identity deliberately and verify how detectors populate infrastructure attributes. The Resource is different from an individual span's attributes. If an environment value describes the deployment, placing it only on one span does not make it a Resource attribute for the other signals.

Do not label every Resource convention “stable” as a group. Inspect the stability and requirement level of the specific attribute or convention you use. See the semantic convention registry.

Describe operations with trace conventions

Trace conventions specify operation names, span kinds, attributes, and error handling for domains such as HTTP, databases, messaging, and RPC.

For HTTP, examples include http.request.method, http.response.status_code, and URL attributes such as url.path where required by the relevant span convention. A route template and a raw path have different cardinality and privacy properties; use the field required for that purpose rather than treating them as interchangeable.

For current stable database client conventions, use names such as db.system.name and, where appropriate and safe, db.query.text. Older instrumentation may emit db.system or db.statement. Query text can contain sensitive values, so review sanitization and collection rules before recording it. See the database span conventions.

Messaging conventions include messaging.system and messaging.destination.name, with additional rules for the operation and context. A topic name alone does not establish a parent-child relationship: propagation and span construction still need to match the messaging model.

Consult the particular operation's table rather than copying attributes from another protocol. A plausible-looking name is not evidence of a valid semantic mapping.

Keep metric names, units, and aggregation separate

Metric conventions specify more than a dotted name. For example, http.server.request.duration is a duration histogram whose unit is seconds (s). The unit is separate metadata; do not append a plural unit suffix to every metric name by default.

Names generally use lowercase dotted namespaces, but pluralization rules depend on what the metric measures. Time and byte units should follow the applicable convention and UCUM guidance. A request count, current connection count, and duration distribution require different instrument semantics even if all values are numeric.

The convention also describes required, conditionally required, recommended, or opt-in attributes as applicable. An attribute's usefulness for a trace does not make it safe as a metric dimension: unique user, request, or order IDs can create an excessive number of time series.

See the metric naming rules and metric conventions, alongside the metrics guide.

Distinguish log fields from exception attributes

The OpenTelemetry log data model includes fields such as SeverityText, SeverityNumber, timestamps, body, and trace context. Wire encodings and language APIs may spell these fields differently. They are not all ordinary attributes that should be added to an attribute map under lowercase names.

Exception conventions define attributes including exception.type, exception.message, and exception.stacktrace. Older instrumentation records an exception as a span event named exception. The current specification deprecates that convention in favor of exceptions in logs, while defining a migration path that lets existing instrumentation retain span events during rollout; check the library’s implemented version and opt-ins. Event identity, body, and attributes have separate roles.

A structured exception can still expose query parameters, credentials, or personal information in its message and stack. Apply the data-handling policy to actual values, not just to the chosen keys. See the logs data model and exception conventions.

Name custom attributes without colliding with standards

When a business concept has no standard convention, choose a company or project namespace. A reverse-domain prefix such as com.example.order.id or com.acme.user.tier is a useful way to avoid collisions; it is not a requirement that every custom attribute must follow that exact style.

Document the type, meaning, allowable values, privacy treatment, and intended signal. An order ID can help locate an individual trace but is usually unsuitable as a metric label. A bounded user tier may be appropriate for a metric if the analysis needs it. Avoid using an existing OpenTelemetry namespace for a different meaning.

The attribute naming guidance recommends namespacing extensions and avoiding conflicts. The high-cardinality guide, currently in Chinese, explains the operational consequences of unbounded dimensions.

Validate the receiving schema in Guance

Send a controlled span through the DataKit OpenTelemetry input with a known service name, environment, and custom attribute. Inspect the service assignment and the fields available for queries after processing.

Repeat the check for a metric and a log if those signals are in scope. Confirm numeric types, units, resource placement, and any field mapping. A matching attribute name across two records does not itself establish trace correlation; a log must retain the appropriate trace identity and the matching trace must be available.

Common questions

Will the conventions change after instrumentation ships?

Each convention or attribute has a lifecycle and stability status. Stable definitions have compatibility commitments, while development conventions can change more substantially; deprecated definitions also need migration planning. Review instrumentation-library releases and emitted schema versions as well as SDK releases. Upgrading the SDK alone may not change the instrumentation's convention version.

Can old instrumentation be normalized without changing application code?

Sometimes. Collector OTTL transformations or a compatible Guance Pipeline mapping can rename or derive fields where the semantics are known. They cannot recover missing context or turn an incompatible unit or meaning into the right value just by renaming a key. Check resource versus span placement, collisions, types, and units, and stage dashboard and alert migrations alongside the data change.

Why have HTTP attribute names changed?

HTTP conventions went through a stabilization migration, including http.method to http.request.method. Stable does not mean the entire surrounding ecosystem stops evolving. Libraries can retain legacy output or provide migration opt-ins, and old and new records may coexist during rollout. Follow the HTTP migration guidance for the instrumentation in use.

Do engineers need to memorize the registry?

No. Start with supported automatic instrumentation, inspect what it emits, and use the official table for manual work. Automatic instrumentation follows the conventions implemented by that particular library and version, which may differ from the latest specification.

Continue with the SDK guide. The OpenTelemetry introduction, OTLP guide, and sensitive-data guide are currently in Chinese.