Produce documentation that outlines http changes from 1.20.0 #43

tigrannajaryan · 2023-05-19T17:25:47Z

I was trying to understand what changes in http conventions and it is not easy to do since it seems the changes happened across more than one PR. One way to get his info is to use git history or git blame, but that's time consuming and error prone and also because we moved the repo I can't be sure I am comparing to the correct baseline (the 1.20.0 is in the spec repo).

It would be great if we could produce a side-by-side comparison of semconv 1.20.0 and <next version>.

arminru · 2023-05-23T09:55:35Z

I compiled the list below, hope this helps:

old attribute	new attribute(s)	PR
http.method	http.request.method	#3355
http.status_code	http.response.status_code	#3355
http.scheme	url.scheme	#3355
http.url	url.full	#3355
http.request_content_length	http.request.body.size	#3355
http.response_content_length	http.response.body.size	#3355
http.target	url.path + url.query + url.fragment	#3355

http.client_ip	client.address	#3402

net.peer.name	server.address + client.address	#3402
net.peer.port	server.port + client.port	#3402
net.host.name	server.address (+ client.address)	#3402
net.host.port	server.port	#3402
net.sock.peer.addr	server.socket.address + client.socket.address	#3402
net.sock.peer.port	server.socket.port + client.socket.port	#3402
net.sock.peer.name	server.socket.domain	#3402
net.sock.host.addr	server.socket.address	#3402
net.sock.host.port	server.socket.port	#3402

net.protocol.name	network.protocol.name	#3426
net.protocol.version	network.protocol.version	#3426
net.host.connection.type	network.connection.type	#3426
net.host.connection.subtype	network.connection.subtype	#3426
net.host.carrier.name	network.carrier.name	#3426
net.host.carrier.mcc	network.carrier.mcc	#3426
net.host.carrier.mnc	network.carrier.mnc	#3426
net.host.carrier.icc	network.carrier.icc	#3426

(new)	network.transport	#3433
(new)	network.type	#3433

net.transport	(removed)	#3433
net.sock.family	(removed)	#3433

arminru · 2023-05-23T09:56:47Z

@lmolkova @trask Would be great if you could double-check the list above for correctness and completeness since you worked on most if not all of these 🙂

tigrannajaryan · 2023-05-23T14:04:51Z

This is a great way to represent it. Thanks @arminru

lmolkova · 2023-05-23T17:34:38Z

Thanks a lot @arminru ! It looks great!

cyrille-leclerc · 2023-06-20T17:25:14Z

Should http.route be changed as well? I'm not sure if http.request.route would be a better fit.

Oberon00 · 2023-06-21T08:35:36Z

@arminru Just looking a bit at the list you compiled, and have some notes:

New attribute server.name: This does not exist. In the linked PR BREAKING: Replace net.peer.*/net.host.* with client.*/server.* (and source.*/destination.*) opentelemetry-specification#3402 it seems to have been mistakenly used in the CHANGELOG only. I just created Fix CHANGELOG.md (server.name does not exist) #126 to fix the CHANGELOG copy in this repository.
Consequently, net.host.name will be server.address in most cases.
While very unlikely in the context of http, net.host.name may theoretically also be client.address. This is the case for all net.host/peer attributes (incl net.sock.host/peer) (they may be set as part of the general span conventions even when not described in the http conventions). For traces, the span kind can be used to distinguish. See also issue network semconv change: local/remote side no longer attributable #62.

arminru · 2023-06-21T11:07:36Z

Thanks for double-checking, @Oberon00. I updated the comment above.

trask · 2023-10-04T02:28:58Z

(added this as a blocker for HTTP semconv stability to make sure it gets done since this will be important for both instrumenters and users who are upgrading their instrumentation to a version that implements the stable HTTP semconv)

trask · 2023-10-27T15:31:56Z

Summary of changes to HTTP semantic conventions since version v1.20.0.

Common attributes across HTTP client and HTTP server spans:

v1.20.0 -> v1.23.0 (stable)

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
- 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
- HTTP Client spans: Recommended -> Opt-In
- HTTP Server spans: now must be provided to sampler
- (see below if updating from version v1.18.0 or earlier)
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 below if updating from version v1.19.0 or earlier)
net.sock.family -> Removed
net.sock.peer.addr -> network.peer.address
- HTTP server spans: if http.client_ip was unknown (i.e. no X-Forwarded-For, Forwarded#for headers), then also net.sock.peer.addr -> client.address (and note 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
New: error.type

HTTP client span attributes:

v1.20.0 -> v1.23.0 (stable)

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

HTTP server span attributes:

v1.20.0 -> v1.23.0 (stable)

http.route (No change)
http.target -> split into url.path and url.query
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)

HTTP client and server span names:

v1.20.0 -> v1.23.0 (stable)

The {http.method} portion of span names is replace by HTTP when {http.method} is _OTHER.

Note: see below if updating from version v1.17.0 or earlier.

HTTP client duration metric

v1.20.0 -> v1.23.0 (stable)

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
Attribute changes:
- 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 -> Opt-In
- net.protocol.version -> network.protocol.version
  - Examples fixed: 2.0 -> 2 and 3.0 -> 3
  - Note: see below if updating from version v1.19.0 or earlier
- New: error.type

HTTP server duration metric

v1.20.0 -> v1.23.0 (stable)

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
Attribute changes:
- 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, Forwarded#proto headers
- net.protocol.name -> network.protocol.name
  - Recommended -> Opt-In
- net.protocol.version -> network.protocol.version
  - Examples fixed: 2.0 -> 2 and 3.0 -> 3
  - Note: see below if updating from version v1.19.0 or earlier
- net.host.name -> server.address
  - Recommended -> Opt-In (due to high-cardinality vulnerability since based on HTTP headers)
  - Now based only on Host, :authority, X-Forwarded-Host, Forwarded#host headers)
- net.host.port -> server.port
  - Recommended -> Opt-In (due to high-cardinality vulnerability since based on HTTP headers)
  - Now based only on Host, :authority, X-Forwarded-Host, Forwarded#host headers)
- New: error.type

If you are coming from an earlier semantic convention version:

If updating from version `v1.19.0` or earlier:

http.flavor -> network.protocol.version
- Examples fixed: 2.0 -> 2 and 3.0 -> 3

If updating from version `v1.18.0` or earlier:

http.user_agent -> user_agent.original

If updating from version `v1.17.0` or earlier:

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.

tigrannajaryan · 2023-10-30T15:02:54Z

Thank you @trask for the summary.

trask · 2023-11-09T18:26:36Z

Closed by https://opentelemetry.io/blog/2023/http-conventions-declared-stable/

github-actions bot assigned reyang May 19, 2023

jsuereth mentioned this issue May 22, 2023

Publish a first release #37

Closed

mladedav mentioned this issue Jun 10, 2023

Update semantic conventions to 1.22 open-telemetry/opentelemetry-rust#1108

Closed

Oberon00 mentioned this issue Jun 21, 2023

Fix CHANGELOG.md (server.name does not exist) #126

Merged

trask assigned trask and unassigned reyang Oct 17, 2023

This was referenced Oct 27, 2023

[azure-core-tracing-opentelemetry] Adopt OpenTelemetry HTTP semconv 1.23.0 Azure/azure-sdk-for-python#32803

Open

[opentelemetry-instrumentation-azure-sdk] Adopt OpenTelemetry HTTP semconv 1.23.1 Azure/azure-sdk-for-js#27585

Open

trask mentioned this issue Nov 2, 2023

Blog post: HTTP semantic conventions declared stable open-telemetry/opentelemetry.io#3472

Merged

trask closed this as completed Nov 9, 2023

This was referenced Nov 14, 2023

[tracing/azotel] Adopt OpenTelemetry HTTP semconv 1.23.0 Azure/azure-sdk-for-go#21968

Open

[azure-core-tracing-opentelemetry] Adopt OpenTelemetry HTTP semconv 1.23.0 Azure/azure-sdk-for-cpp#5162

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Produce documentation that outlines http changes from 1.20.0 #43

Produce documentation that outlines http changes from 1.20.0 #43

tigrannajaryan commented May 19, 2023 •

edited by arminru

Loading

arminru commented May 23, 2023 •

edited

Loading

arminru commented May 23, 2023

tigrannajaryan commented May 23, 2023

lmolkova commented May 23, 2023

cyrille-leclerc commented Jun 20, 2023

Oberon00 commented Jun 21, 2023 •

edited

Loading

arminru commented Jun 21, 2023

trask commented Oct 4, 2023

trask commented Oct 27, 2023 •

edited

Loading

tigrannajaryan commented Oct 30, 2023

trask commented Nov 9, 2023

Produce documentation that outlines http changes from 1.20.0 #43

Produce documentation that outlines http changes from 1.20.0 #43

Comments

tigrannajaryan commented May 19, 2023 • edited by arminru Loading

arminru commented May 23, 2023 • edited Loading

arminru commented May 23, 2023

tigrannajaryan commented May 23, 2023

lmolkova commented May 23, 2023

cyrille-leclerc commented Jun 20, 2023

Oberon00 commented Jun 21, 2023 • edited Loading

arminru commented Jun 21, 2023

trask commented Oct 4, 2023

trask commented Oct 27, 2023 • edited Loading

Common attributes across HTTP client and HTTP server spans:

HTTP client span attributes:

HTTP server span attributes:

HTTP client and server span names:

HTTP client duration metric

HTTP server duration metric

If you are coming from an earlier semantic convention version:

If updating from version v1.19.0 or earlier:

If updating from version v1.18.0 or earlier:

If updating from version v1.17.0 or earlier:

HTTP server span name:

HTTP client span name:

tigrannajaryan commented Oct 30, 2023

trask commented Nov 9, 2023

tigrannajaryan commented May 19, 2023 •

edited by arminru

Loading

arminru commented May 23, 2023 •

edited

Loading

Oberon00 commented Jun 21, 2023 •

edited

Loading

trask commented Oct 27, 2023 •

edited

Loading

If updating from version `v1.19.0` or earlier:

If updating from version `v1.18.0` or earlier:

If updating from version `v1.17.0` or earlier: