HTTP semantic convention stability migration

Due to the significant number of modifications and the extensive user base affected by them, existing HTTP instrumentations published by OpenTelemetry are required to implement a migration plan that will assist users in transitioning to the stable HTTP semantic conventions.

Specifically, when existing HTTP instrumentations published by OpenTelemetry are updated to the stable HTTP semantic conventions, they:

  • SHOULD introduce an environment variable OTEL_SEMCONV_STABILITY_OPT_IN in 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

This section summarizes the changes made to the HTTP semantic conventions from v1.20.0 to v1.23.1 (stable).

Common attributes across HTTP client and server spans

ChangeComments
http.methodhttp.request.methodNow captures only 9 common HTTP methods by default (configurable) plus _OTHER
http.status_codehttp.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_lengthhttp.request.body.size• Recommended → Opt-In
Not marked stable yet
http.response_content_lengthhttp.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.namenetwork.protocol.nameRecommended → Conditionally required if not http and network.protocol.version is set
net.protocol.versionnetwork.protocol.version• Examples fixed: 2.02 and 3.03
• See note if migrating from <= v1.19.0
net.sock.familyRemoved
net.sock.peer.addrnetwork.peer.addressOn HTTP server spans: if http.client_ip was unknown, then also net.sock.peer.addrclient.address; client.address must be provided to sampler
net.sock.peer.portnetwork.peer.portNow captured even if same as server.port
net.sock.peer.nameRemoved
New: http.request.method_originalOnly captured when http.request.method is _OTHER
New: error.type

References:

HTTP client span attributes

ChangeComments
http.urlurl.full
http.resend_counthttp.request.resend_count
net.peer.nameserver.address
net.peer.portserver.portNow captured even when same as default port for scheme

References:

HTTP server span attributes

ChangeComments
http.routeNo change
http.targeturl.path and url.querySplit into two separate attributes
http.schemeurl.schemeNow factors in X-Forwarded-Proto, Forwarded#proto headers
http.client_ipclient.addressIf http.client_ip was unknown (i.e., no X-Forwarded-For, Forwarded#for headers), then net.sock.peer.addrclient.address; now must be provided to sampler
net.host.nameserver.addressNow based only on Host, :authority, X-Forwarded-Host, Forwarded#host headers
net.host.portserver.port• Now based only on Host, :authority, X-Forwarded-Host, Forwarded#host headers
• Now captured even when same as default port for scheme
net.sock.host.addrnetwork.local.address
net.sock.host.portnetwork.local.portNo longer defaults to server.port when network.local.address is set.

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.durationhttp.client.request.duration
  • Unit: mss
  • 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 changeComments
http.methodhttp.request.methodNow captures only 9 common HTTP methods by default plus _OTHER
http.status_codehttp.response.status_code
net.peer.nameserver.address
net.peer.portserver.portNow captured even when same as default port for scheme
net.sock.peer.addrRemoved
net.protocol.namenetwork.protocol.nameRecommended → Conditionally required if not http and network.protocol.version is set
net.protocol.versionnetwork.protocol.versionExamples fixed: 2.02 and 3.03; see note if migrating from <= v1.19.0
New: error.type

References:

HTTP server duration metric

Metric changes:

  • Name: http.server.durationhttp.server.request.duration
  • Unit: mss
  • 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 changeComments
http.routeNo change
http.methodhttp.request.methodNow captures only 9 common HTTP methods by default plus _OTHER
http.status_codehttp.response.status_code
http.schemeurl.schemeNow factors in X-Forwarded-Proto span, Forwarded#proto span headers
net.protocol.namenetwork.protocol.nameRecommended → Conditionally required if not http and network.protocol.version is set
net.protocol.versionnetwork.protocol.versionExamples fixed: 2.02 and 3.03; see note if migrating from <= v1.19.0
net.host.nameserver.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.portserver.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

References:

Migrating from a version prior to v1.20.0?

In addition to the changes made to the HTTP semantic conventions from v1.20.0 to v1.23.1 (stable), there are additional changes if you are migrating to v1.23.1 from a version prior to v1.20.0.

Migrating from <= v1.19.0

  • http.flavornetwork.protocol.version
    • Examples fixed: 2.02 and 3.03

Migrating from <= v1.18.0

  • http.user_agentuser_agent.original

Migrating from <= v1.17.0

HTTP server span name

  • When http.route is available:
    {http.route}{summary} {http.route}
  • When http.route is 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.

Migrating from <= v1.16.0

This page does not cover these versions.