OpenTelemetry Semantic Conventions Explained (with Examples)

Collecting logs, metrics, and traces gives you visibility into your systems, but interpreting that data consistently across services isn't always straightforward.

One service might record an HTTP status code as status_code, while another uses http_status_code. Even when services agree on attribute names, they might measure the same operation differently. For example, two services could report HTTP request durations in different units or measure different parts of the request lifecycle, making their metrics difficult to compare.

OpenTelemetry Semantic Conventions address these inconsistencies by defining standard names, meanings, units, and instrumentation rules for common operations and resources. They help ensure that telemetry produced by different languages, frameworks, and services can be interpreted consistently, whether you're building dashboards, investigating incidents, or using AI-powered tools to analyze your systems.

In this guide, you'll learn how semantic conventions apply to OpenTelemetry signals, how their stability levels affect instrumentation, and how to adopt new conventions without breaking existing queries, dashboards, and alerts.

What semantic conventions actually define

OpenTelemetry Semantic Conventions define how common operations, resources, and events should be represented in telemetry so that different instrumentation libraries describe the same activity consistently.

Depending on the convention, this includes:

• Attribute names and meanings: What an attribute represents, its expected data type, and any restrictions on its values.
• Metric definitions: Standard metric names, units, instrument types, and attributes, including what is actually being measured.
• Span conventions: How operations should be named, which span kind to use, and what attributes describe the operation.
• Instrumentation requirements: Which attributes must be recorded, which are recommended, and how instrumentation should behave in specific circumstances.

Consider a POST /payments request handled by a payment-service. The conventions define the server span's name, POST /payments, and the attributes that describe the request, such as http.request.method, http.route, and http.response.status_code.

The same request is also recorded in the http.server.request.duration histogram, which measures its duration in seconds according to a defined measurement boundary. If the service logs an error while handling the request, a properly configured logging integration can include the same resource context and trace identifiers, allowing the log to be correlated with the request's span.

These shared definitions make telemetry easier to compare and correlate across services, even when different languages and instrumentation libraries are involved in producing the pieces.

Resource semantic conventions: describing services and infrastructure

In OpenTelemetry, every piece of telemetry, whether a log, metric, or span, originates from a Resource. This is the entity producing the data, such as a microservice, a serverless function, a Kubernetes pod, or a physical host.

The semantic conventions for resources standardize the attributes that describe this entity. The most important one is service.name, which gives your application a logical identity in your observability platform. It's commonly set through an environment variable:

export OTEL_SERVICE_NAME="payment-service"

While service.name is the most crucial identifier, a complete resource description answers several key questions: what is this service?, where is it running?, and how is it instrumented?

Let's look at a few of the attributes that you can use to answer these questions.

Logical and deployment context

These attributes describe the service's identity and its role in the software development lifecycle:

• service.version: The version of the service (e.g. v1.2.3 or a git commit hash).
• service.instance.id: A unique identifier for a specific instance.
• service.namespace: A name that groups related services.
• deployment.environment.name: The environment the service is deployed in (such as production or staging).

Execution environment context

This group of attributes pinpoints the physical or virtual infrastructure where your code is running:

• cloud.*: Describes the cloud provider, region, and platform.
• aws.*, gcp.*, and similar namespaces: Describes resources that are only applicable to a specific cloud provider.
• k8s.*: For Kubernetes, these attributes describe the namespace, node, pod, cluster, containers, and more. The best practices for Kubernetes attributes cover which ones to set and how.
• host.*, os.*, process.*: Describes the host machine, operating system, and the underlying OS processes.

Telemetry origin context

The telemetry.sdk.* attributes describe the underlying technology that captured the telemetry, helping you understand how the data was generated.

How resource semantic conventions are applied

Resource semantic conventions define how services and their execution environments should be described, but you generally don't need to populate these attributes manually.

Most OpenTelemetry SDKs automatically populate attributes such as telemetry.sdk.*, and their built-in resource detectors can discover and include details about the host, process, operating system, and more using the standard attribute names defined by the conventions.

You generally only need to supply application-specific information, such as service.version or deployment.environment.name, that the SDK can't reliably discover on its own. This can be done through the OTEL_RESOURCE_ATTRIBUTES environment variable:

export OTEL_RESOURCE_ATTRIBUTES="service.version=1.2.3,deployment.environment.name=production"

The OpenTelemetry Collector can also enrich resource attributes based on where your applications run. For example, the Kubernetes attributes processor adds Kubernetes metadata, while the resourcedetection processor discovers host and cloud infrastructure details. You can also use the resource processor to add or modify attributes that require explicit configuration.

Together, these mechanisms allow you to describe services consistently using the standard resource conventions without writing custom instrumentation code for each attribute.

Span semantic conventions: describing operations consistently

Span semantic conventions standardize how operations are described through span names, kinds, attributes, and error reporting. They help instrumentation libraries across different languages and frameworks represent similar operations consistently.

While the exact requirements vary by operation, several conventions apply broadly across HTTP requests, database queries, messaging operations, and other kinds of spans.

How to name your spans

Span names should be concise and low-cardinality, describing the class of operation being tracked rather than a particular execution of it.

The recommended naming pattern is generally {verb} {object}, where the action describes what's happening and the target identifies the resource being operated on.

For common operations such as HTTP requests and database queries, automatic instrumentation generally creates and names spans according to the relevant semantic conventions, so you don't need to manage their names yourself.

These guidelines become important when you create custom spans or rename existing ones. In those cases:

• Choose a name that clearly describes the operation, such as "prepare order items" or "validate input". This is how you'll identify the span in your observability tool.
• Avoid including request IDs, user IDs, or any other values that change between executions. When needed, those details should be recorded as span attributes instead.
• Follow operation-specific naming conventions where they exist. For example, an HTTP server span should be named GET /products/{id} instead of GET /products/123. The former groups requests to the same endpoint, while the latter would produce a different span name for every product.

Clarifying the role of a span

OpenTelemetry defines five span kinds: SERVER, CLIENT, PRODUCER, CONSUMER, and INTERNAL, which is the default when no kind is specified.

Semantic conventions prescribe the appropriate kind for specific operations. For example, HTTP server instrumentation must create SERVER spans, while HTTP client instrumentation must create CLIENT spans.

When creating custom spans for internal application operations, you should generally leave the kind unspecified since it already defaults to INTERNAL.

Choosing and defining span attributes

Span attributes provide the context needed to understand a particular execution of an operation. Semantic conventions for spans define the attributes associated with common operations, including their names, meanings, value types, and requirement levels.

For example, the HTTP span conventions define attributes such as http.request.method, http.route, http.response.status_code, and client.address, allowing instrumentation libraries to describe HTTP requests consistently, regardless of the language or framework used.

If you're using automatic instrumentation, these standard attributes are generally populated for you, although the exact set depends on the instrumentation library and the information available at runtime.

When creating custom spans or instrumenting additional attributes to existing ones, start by checking the OpenTelemetry attribute registry for existing attributes that describe your operation.

Reuse standard attributes wherever their definitions match what you're recording, and only introduce custom attribute names for business-specific context that isn't already covered.

Defining span status and error handling

Every span has a status field with three possible values: Unset (the default), Ok, and Error. Instrumentation generally leaves successful operations as Unset and uses Error to indicate failures. Ok can explicitly mark an operation as successful, but instrumentation should not set it by default.

For error handling, the general error-recording conventions provide guidance on identifying and reporting failures, while operation-specific conventions define what constitutes an error in each context.

For example, the HTTP span conventions specify that a 404 Not Found response should generally be treated as an error on a CLIENT span, but not on a SERVER span. They also define when to record the error.type attribute and how its values should be represented.

Metric semantic conventions: defining consistent measurements

Metric semantic conventions standardize how common measurements are recorded, including their names, instrument types, units, attributes, and measurement semantics.

This matters because two services can use the same metric name and still produce incomparable data if one records durations in milliseconds while another uses seconds, or if they measure different parts of an operation.

As with spans, automatic instrumentation generally handles these conventions for you, but you'll need to understand them when creating custom metrics or modifying existing instrumentation.

Instrument types and measurement semantics

For standardized metrics, semantic conventions prescribe the instrument type and define precisely what should be measured.

For example, http.server.request.duration is defined as a Histogram that measures the duration of HTTP requests handled by a server, with values recorded in seconds. When reported alongside an HTTP server span, the measurement should match the span's duration.

Similarly, http.server.active_requests is defined as an UpDownCounter because it tracks the number of requests currently being processed, a value that can increase or decrease.

When creating custom business metrics that aren't covered by existing conventions, choose an appropriate instrument based on the type of measurement you're recording. Our OpenTelemetry metrics article explains the available instruments and when to use them.

Naming your metrics and choosing units

Metric names should clearly identify what's being measured, using lowercase, dot-separated names that follow the OpenTelemetry naming guidelines.

For example, http.server.request.duration identifies an HTTP request duration measured from the server's perspective. The corresponding client-side metric is http.client.request.duration, which measures the request from the caller's perspective. These measurements cover different parts of a request's lifecycle, so their values aren't necessarily interchangeable.

Metric units are defined separately from names using the Unified Code for Units of Measure (UCUM). Common conventions include:

• Seconds (s) for durations.
• Bytes (By) for data sizes.
• Dimensionless unit (1) for ratios and utilization.
• Annotated units such as {request} for counts of specific entities.

Using standard units prevents measurement ambiguity and allows observability tools to interpret and compare values correctly.

When defining your own metrics, first check whether a standard metric already covers the measurement you need. Otherwise, choose a descriptive name, the appropriate instrument type, and a unit that accurately represents the recorded values.

Defining metric attributes

Semantic conventions also specify which attributes should accompany a measurement, giving you consistent dimensions for filtering, grouping, and comparing metrics across services.

OpenTelemetry also accounts for cardinality in its attribute requirement levels. Metric attributes that may have high cardinality can only be defined as Opt-In, meaning instrumentation must not emit them by default. This helps prevent unexpectedly large numbers of time series in your observability backend.

For example, the database client operation duration convention requires the db.system.name attribute to identify the database system being used, such as postgresql or mysql.

Other attributes are conditionally required, including db.operation.name (such as SELECT or INSERT) when the operation name is readily available, and error.type when the operation fails. The convention also recommends db.query.summary to identify the query being executed.

When creating custom metrics, reuse existing semantic convention attributes wherever their definitions apply, and check the metric-specific conventions for additional guidance.

Log semantic conventions: standardizing log context

OpenTelemetry's log semantic conventions standardize the attributes used to describe log records, including their origin and contextual information. They also define how certain events, such as exceptions, should be recorded.

Unlike traces and metrics, log conventions often focus on standardizing metadata for records produced by existing logging libraries, rather than defining measurements or operations to instrument.

This means you can continue using logging frameworks such as Log4j, Winston, or Serilog while applying standard attributes to the logs they produce.

Recording exceptions consistently

One of the clearest examples is the semantic conventions for exceptions in logs, which define how instrumentation should represent exceptions.

Without these conventions, one logging library might record an exception's class name as error_class, another as exception, and a third might include the information only in a formatted message. This makes it harder to identify and group similar failures across services.

OpenTelemetry defines three Stable attributes for this purpose:

• exception.type: Identifies the exception type, preferably using its fully qualified class name, such as java.net.ConnectException.
• exception.message: Contains the exception's error message.
• exception.stacktrace: Records the stack trace in the language's natural representation.

Exception messages and stack traces may contain sensitive information, so ensure they're appropriately sanitized before export.

Applying conventions to other log attributes

Beyond exceptions, OpenTelemetry defines general log attributes that describe where a record came from or how it was collected. For example, log.file.path identifies the source log file, while log.iostream identifies whether a record originated from stdout or stderr.

When adding structured context to your application logs, check the OpenTelemetry attribute registry before introducing custom attributes. Reuse existing conventions wherever their definitions apply, and only define custom attributes for information specific to your application.

Event semantic conventions: naming meaningful occurrences

Event semantic conventions define standard names and attributes for specific occurrences, such as feature flag evaluations, exceptions, and application lifecycle events.

An event is a log record with a non-empty EventName field, so events are found in the logs signal rather than a separate telemetry signal. When an exporter or destination doesn't support EventName, the otel.event.name attribute can carry the event name instead.

Each convention defines the event name and the attributes that describe it, including their requirement levels. For example, the feature flag conventions define feature_flag.evaluation as the event name, with attributes such as feature_flag.key and feature_flag.result.variant describing the evaluation.

The general event conventions are still in Development, so their requirements may change as the specification evolves.

Extending semantic conventions with custom attributes

OpenTelemetry's semantic conventions cover many common technologies and operations, but they can't anticipate every detail specific to your application.

For example, you might want to know the shopping cart value associated with a failed checkout or which customer tier experiences the highest latency. Answering these questions requires recording business context that is unlikely to be represented in the standard conventions.

OpenTelemetry allows you to define custom attributes for these cases, but they should follow the same general principles of consistent naming, clear meaning, and consistent values.

Before creating a custom attribute, always check the official attribute registry to see whether an existing convention already describes what you need.

If you need a custom attribute, follow these guidelines.

1. Choose a namespace that avoids conflicts

OpenTelemetry recommends using namespaces to group related attributes and reduce the risk of naming collisions.

For attributes that might be shared outside your organization, the naming guidelines recommend using your company's reverse domain name as a prefix, such as com.example.shop.cart.value.

For internal applications, a sufficiently unique application prefix such as myshop.cart.value is usually enough, provided it doesn't conflict with an existing semantic convention.

An example is Dash0's semantic conventions registry, which extends OpenTelemetry with attributes such as dash0.resource.type, dash0.operation.name, and dash0.log.pattern. These are grouped under the dash0.* namespace to distinguish them from standard OpenTelemetry attributes and avoid naming conflicts.

Avoid defining custom attributes within existing OpenTelemetry namespaces such as http, db, or messaging, since future conventions could introduce attributes with the same names but different meanings.

The otel.* namespace is explicitly reserved for the OpenTelemetry specification and must not be used for custom attributes.

2. Use descriptive names and consistent values

Follow the same general naming conventions as standard attributes by using lowercase, dot-separated names, with underscores separating words within each component. For example, use myshop.payment.provider instead of paymentProvider.

Also, keep attribute meanings, value types, and units consistent across services. If one service records a provider as stripe and another as Stripe, queries will treat them as different values. Similarly, if myshop.cart.value represents an amount in cents, don't mix cents, dollars, and formatted currency strings.

Document and enforce these definitions so different teams can reuse the same attributes without introducing incompatible representations.

If your services already produce inconsistent attribute names or values, you can normalize them centrally using the Collector's transform processor or the attributes processor.

Semantic conventions stability and migration

OpenTelemetry assigns semantic conventions one of five stability levels:

• Development: Still evolving and may change or be removed without notice.
• Alpha: Suitable for limited, non-critical production use, without compatibility guarantees.
• Beta: Treated as stable whenever possible, though breaking changes may still occur.
• Release Candidate: Feature-complete and nearing stability, with breaking changes expected only under exceptional circumstances.
• Stable: Provides strong compatibility guarantees, making it suitable for dashboards, alerts, and other long-term dependencies.

Stability can differ within the same technology area. For example, HTTP span conventions are Stable, while some HTTP metric conventions are still in Development. A Stable convention also doesn't guarantee that every instrumentation library supports it yet.

Here's where some major convention groups stand as of v1.44.0:

Deprecation is tracked separately from stability. When a convention is deprecated, the specification may identify a replacement or mark it as obsolete.

Changes and renames

As conventions evolve, attribute names and metric definitions sometimes change. This means older instrumentation may emit different telemetry from newer versions, even when both describe the same operations.

Here are some common changes you may encounter:

Some migrations involve more than renaming attributes. For example, the old http.server.duration metric measured request duration in milliseconds, while its replacement, http.server.request.duration, uses seconds.

An alert configured around the old metric's units must therefore be updated, not merely pointed at the new metric name. Otherwise, its threshold could become incorrect without producing an obvious error.

Migrating instrumentation to stable conventions

To help applications transition without immediately breaking existing dashboards and alerts, OpenTelemetry defines the OTEL_SEMCONV_STABILITY_OPT_IN environment variable for instrumentation migrating to stable conventions.

Where supported, it lets you select which convention version an instrumentation library emits:

export OTEL_SEMCONV_STABILITY_OPT_IN="http/dup,database"

In this example:

• http/dup requests both the old and stable HTTP conventions during migration.
• database requests only the stable database conventions.

However, dual emission can increase telemetry volume and produce additional metric series, so it should be used temporarily while dashboards, alerts, and queries are migrated.

Schema URLs and automatic migration

OpenTelemetry also provides schema URLs, which identify the semantic convention schema associated with telemetry.

For example:

https://opentelemetry.io/schemas/1.44.0

A schema describes changes between convention versions, including attribute and metric renames. This allows compatible telemetry processors or backends to translate data from older conventions into newer ones.

The OpenTelemetry Collector provides a schema processor for this purpose, although it remains experimental. The specification also cautions against relying on schema transformations as a guaranteed compatibility mechanism.

Some OpenTelemetry backends like Dash0 also support schema migration at ingestion, allowing you to normalize telemetry to the latest conventions, pin a specific version, or retain the original data. This lets services using different instrumentation versions be queried consistently without requiring every service to upgrade simultaneously.

Regardless of the migration approach, verify that your dashboards, alerts, and queries continue to interpret the resulting telemetry correctly since semantic convention changes can affect not just attribute names, but also measurement units and meanings.

Validating semantic conventions with OpenTelemetry Weaver

Following semantic conventions during instrumentation doesn't guarantee that your telemetry will conform to them. Without validation, mistakes such as incorrect attribute names, missing attributes, or incompatible value types can go unnoticed.

OpenTelemetry Weaver provides tools for validating semantic convention definitions and checking whether actual telemetry conforms to them. Its main capabilities include:

• weaver registry check: Validates a semantic convention registry, including any custom validation rules.
• weaver registry generate: Generates code and documentation from a registry, helping instrumentation and documentation use consistent definitions.
• weaver registry live-check: Checks incoming OTLP telemetry against a registry and reports deviations, such as missing attributes or incorrect value types.
• weaver registry mcp: Exposes conventions through an MCP server, allowing AI coding agents to look up the correct definitions when writing instrumentation.

You can also extend OpenTelemetry's registry with your own conventions, allowing Weaver to validate custom attributes alongside standard ones. The Dash0 semantic conventions repository is a public example of this approach that you can learn from.

If your telemetry already uses inconsistent attributes, you can normalize them centrally using the Collector's attributes, resource, or transform processors.

How Dash0 uses semantic conventions

Semantic conventions are central to Dash0's OpenTelemetry-native approach to observability. Rather than treating incoming telemetry as arbitrary fields to store and query, Dash0 uses standardized definitions to understand the resources, operations, and measurements that the data represents.

For example, Dash0 uses resource attributes to automatically discover, identify, and monitor infrastructure such as Kubernetes workloads, hosts, and cloud resources.

It can recognize when telemetry from different sources describes the same underlying resource and bring the relevant logs, metrics, and traces together. This enables infrastructure monitoring with resource inventories and prebuilt views, without requiring you to manually configure every component.

To see how Dash0 puts OpenTelemetry semantic conventions to work, start your free 14-day trial today.

Final thoughts

As observability becomes increasingly automated with AI, the quality of its analysis will depend on the quality of the meaning encoded in telemetry. Semantic conventions help preserve that meaning from the moment data is produced to the moment someone, or something, needs to understand it.

Of course, a shared vocabulary is only useful when everyone agrees on its meaning. Adopting semantic conventions therefore requires some discipline: reusing established definitions, validating custom instrumentation, and keeping up with changes as the specification evolves.

As you apply these principles, always treat the official OpenTelemetry documentation as the definitive source of truth for the latest conventions.

Frequently asked questions

Are OpenTelemetry semantic conventions mandatory?

No. OpenTelemetry does not require custom instrumentation to follow semantic conventions to produce valid telemetry. However, using them ensures that common operations and resources are described consistently, making telemetry easier to query, correlate, and analyze across different services and tools.

Can I use attributes that aren't defined in OpenTelemetry semantic conventions?

Yes. OpenTelemetry supports custom attributes alongside standardized ones. Before introducing a new attribute, check the official attribute registry to see whether an existing definition fits your needs. Custom attributes should use descriptive names, consistent values, and namespaces that don't conflict with standard conventions.

Can organizations define their own semantic conventions?

Yes. Organizations can maintain their own semantic convention registries to standardize application-specific attributes, metrics, and events across teams. OpenTelemetry Weaver can help generate documentation and code from these definitions and validate telemetry against them. The open-source Dash0 semantic conventions registry is an example.

How do I know which semantic convention version my instrumentation uses?

Check your instrumentation library's documentation and version-specific release notes. Instrumentation libraries adopt semantic conventions independently, so upgrading to the latest SDK doesn't necessarily mean you're emitting the latest conventions.

Some instrumentation also attaches a schema_url to exported telemetry to identify the semantic convention schema it follows. Where present, this provides additional information about the conventions used to describe the data.