HTTP semantic conventions declared stable
Early this year, we launched an effort to stabilize HTTP semantic conventions. Today, we proudly announce that the HTTP semantic conventions are the first OpenTelemetry semantic conventions to be declared stable! This inaugural stable v1.23.0 release marks a substantial advancement from earlier versions, featuring:
- Enhancements resulting from
convergence with the Elastic Common Schema,
such as:
- The
url.*namespace, which can be reused in the future by non-HTTP semantic conventions - Replacing the
net.peer.*andnet.host.*namespaces withclient.*andserver.*, which- Works better for logs, where there’s no span kind to indicate which side is peer and which side is host
- Simplifies correlation across client and server telemetry (e.g. since you
can join directly on
server.addressinstead of joining wherenet.peer.addr==net.host.addr) - Provides a clean separation from the
network.*namespace which is now only for low-level network attributes
- More consistency around using the
http.request.*andhttp.response.*namespaces
- The
- Improved consistency with Prometheus through standardization on seconds for metric units.
- Streamlined attribute capture by omitting less useful attributes, reducing telemetry capture, processing, and storage costs.
- Clarified the definition of default values, eliminating ambiguities when attributes are absent.
- HTTP metrics are no longer vulnerable to cardinality explosion
http.request.methodis limited to a (configurable) set of known methodsserver.addressandserver.port, which are influenced by theHostheader, are now Opt-In on HTTP metrics
Migration plan
Due to the significant number of modifications and the extensive user base affected by them, we require existing HTTP instrumentations published by OpenTelemetry to implement a migration plan that will assist users in transitioning to stable HTTP semantic conventions. We intend to use a similar strategy when stabilizing other semantic conventions.
Specifically, when existing HTTP instrumentations published by OpenTelemetry are updated to the stable HTTP semantic conventions, they:
- Need to introduce an environment variable
OTEL_SEMCONV_STABILITY_OPT_INin their existing major version, which accepts:http- emit the stable HTTP and networking conventions, and stop emitting the old HTTP and networking conventions that the instrumentation emitted previously.http/dup- emit both the old and the stable HTTP and networking conventions, allowing for a phased rollout of the stable semantic conventions.- The default behavior (in the absence of one of these values) is to continue emitting whatever version of the old HTTP and networking conventions the instrumentation was emitting previously.
- Need to maintain (security patching at a minimum) their existing major version for at least six months after it starts emitting both sets of conventions.
- May drop the environment variable in their next major version and emit only the stable HTTP and networking conventions.
Summary of changes
In this section, we summarize the changes made to the HTTP semantic conventions from v1.20.0 to v1.23.0 (stable).
Common attributes across HTTP client and server spans
| Change | Comments |
|---|---|
http.method → http.request.method | Now captures only 9 common HTTP methods by default (configurable) plus _OTHER |
http.status_code → http.response.status_code | |
http.request.header.<key> | • Dash ("-") to underscore ("_") normalization in <key> has been removed• On HTTP server spans: now must be provided to sampler |
http.response.header.<key> | Dash ("-") to underscore ("_") normalization in <key> has been removed |
http.request_content_length → http.request.body.size | • Recommended → Opt-In • Not marked stable yet |
http.response_content_length → http.response.body.size | • Recommended → Opt-In • Not marked stable yet |
user_agent.original | • On HTTP client spans: Recommended → Opt-In • On HTTP server spans: now must be provided to sampler • See note if migrating from <= v1.18.0 |
net.protocol.name → network.protocol.name | Recommended → Conditionally required if not http and network.protocol.version is set |
net.protocol.version → network.protocol.version | • Examples fixed: 2.0 → 2 and 3.0 → 3• See note if migrating from <= v1.19.0 |
net.sock.family | Removed |
net.sock.peer.addr → network.peer.address | On HTTP server spans: if http.client_ip was unknown, then also net.sock.peer.addr → client.address; client.address must be provided to sampler |
net.sock.peer.port → network.peer.port | Now captured even if same as server.port |
net.sock.peer.name | Removed |
New: http.request.method_original | Only captured when http.request.method is _OTHER |
New: error.type | New |
References:
HTTP client span attributes
| Change | Comments |
|---|---|
http.url → url.full | |
http.resend_count → http.request.resend_count | |
net.peer.name → server.address | |
net.peer.port → server.port | Now captured even when same as default port for scheme |
References:
HTTP server span attributes
| Change | Comments |
|---|---|
http.route | No change |
http.target → url.path and url.query | Split into two separate attributes |
http.scheme → url.scheme | Now factors in X-Forwarded-Proto, Forwarded#proto headers |
http.client_ip → client.address | If http.client_ip was unknown (i.e., no X-Forwarded-For, Forwarded#for headers), then net.sock.peer.addr → client.address; now must be provided to sampler |
net.host.name → server.address | Now based only on Host, :authority, X-Forwarded-Host, Forwarded#host headers |
net.host.port → server.port | Now based only on Host, :authority, X-Forwarded-Host, Forwarded#host headers |
References:
HTTP client and server span names
The {http.method} portion of span names is replace by HTTP when
{http.method} is _OTHER.
See note if migrating from <= v1.17.0.
References:
HTTP client duration metric
Metric changes:
- Name:
http.client.duration→http.client.request.duration - Unit:
ms→s - Description:
Measures the duration of inbound HTTP requests.→Duration of HTTP server requests. - Histogram buckets: boundaries updated to reflect change from milliseconds to seconds, and zero bucket boundary removed
- Attributes: see table below
| Attribute change | Comments |
|---|---|
http.method → http.request.method | Now captures only 9 common HTTP methods by default plus _OTHER |
http.status_code → http.response.status_code | |
net.peer.name → server.address | |
net.peer.port → server.port | Now captured even when same as default port for scheme |
net.sock.peer.addr | Removed |
net.protocol.name → network.protocol.name | Recommended → Conditionally required if not http and network.protocol.version is set |
net.protocol.version → network.protocol.version | Examples fixed: 2.0 → 2 and 3.0 → 3; see note if migrating from <= v1.19.0 |
New: error.type | New |
References:
HTTP server duration metric
Metric changes:
- Name:
http.server.duration→http.server.request.duration - Unit:
ms→s - Description:
Measures the duration of inbound HTTP requests.→Duration of HTTP server requests. - Histogram buckets: boundaries updated to reflect change from milliseconds to seconds, and zero bucket boundary removed
- Attributes: see table below
| Attribute change | Comments |
|---|---|
http.route | No change |
http.method → http.request.method | Now captures only 9 common HTTP methods by default plus _OTHER |
http.status_code → http.response.status_code | |
http.scheme → url.scheme | Now factors in X-Forwarded-Proto span, Forwarded#proto span headers |
net.protocol.name → network.protocol.name | Recommended → Conditionally required if not http and network.protocol.version is set |
net.protocol.version → network.protocol.version | Examples fixed: 2.0 → 2 and 3.0 → 3; see note if migrating from <= v1.19.0 |
net.host.name → server.address | • Recommended → Opt-In (due to high-cardinality vulnerability since based on HTTP headers) • Now based only on Host span, :authority span, X-Forwarded-Host span, Forwarded#host span headers |
net.host.port → server.port | • Recommended → Opt-In (due to high-cardinality vulnerability since based on HTTP headers) • Now based only on Host span, :authority span, X-Forwarded-Host span, Forwarded#host span headers |
New: error.type | New |
References:
Migrating from a version earlier than v1.20.0?
Migrating from <= v1.19.0
http.flavor→network.protocol.version- Examples fixed:
2.0→2and3.0→3
- Examples fixed:
Migrating from <= v1.18.0
http.user_agent→user_agent.original
Migrating from <= v1.17.0
HTTP server span name
- When
http.routeis available:{http.route}→{summary} {http.route} - When
http.routeis not available:HTTP {http.method}→{summary}
Where {summary} is {http.method}, unless {http.method} is _OTHER, in
which case {summary} is HTTP.
HTTP client span name
HTTP {http.method}→{summary}
Where {summary} is {http.method}, unless {http.method} is _OTHER, in
which case {summary} is HTTP.
Community Kudos
This was a massive community effort: thanks to all who got involved! A special thanks to Liudmila Molkova for sharing her HTTP domain expertise, which helped drive this effort every step of the way.