Skip to content

Commit bfb8bd7

Browse files
jack-bergjack-berg
authored
Fix inconsistent metric usage of http.target (open-telemetry#2818)
1 parent e2856b8 commit bfb8bd7

File tree

1 file changed

+14
-34
lines changed

1 file changed

+14
-34
lines changed

‎specification/metrics/semantic_conventions/http-metrics.md‎

Lines changed: 14 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -43,17 +43,20 @@ Below is a table of HTTP client metric instruments.
4343
Below is a table of the attributes that SHOULD be included on `duration` and `size` metric events
4444
and whether they should be on server, client, or both types of HTTP metric events:
4545

46-
| Name | Type | Requirement Level | Notes and examples |
47-
|----------------------|---------------------|--------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
48-
| `http.method` | `client` & `server` | Required | The HTTP request method. E.g. `"GET"` |
49-
| `http.scheme` | `server` | Required | The URI scheme identifying the used protocol in lowercase: `"http"` or `"https"` |
50-
| `http.status_code` | `client` & `server` | Conditionally Required: if and only if one was received/sent. | [HTTP response status code][]. E.g. `200` (String) |
51-
| `http.flavor` | `client` & `server` | Recommended | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. |
52-
| `net.peer.name` | `client` | Required | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. |
53-
| `net.peer.port` | `client` | Conditionally Required: If not default (`80` for `http`, `443` for `https`). | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. |
54-
| `net.sock.peer.addr` | `client` | Recommended | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) |
55-
| `net.host.name` | `server` | Required | Host of the local HTTP server that received the request. |
56-
| `net.host.port` | `server` | Conditionally Required: If not default (`80` for `http`, `443` for `https`). | Port of the local HTTP server that received the request. |
46+
| Name | Type | Requirement Level | Notes and examples |
47+
|----------------------|---------------------|------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
48+
| `http.method` | `client` & `server` | Required | The HTTP request method. E.g. `"GET"` |
49+
| `http.scheme` | `server` | Required | The URI scheme identifying the used protocol in lowercase: `"http"` or `"https"` |
50+
| `http.route` | `server` | Conditionally Required: If and only if it's available | The matched route (path template in the format used by the respective server framework). See note below [1]. E.g. `"/path/{id}/?q={}"`. |
51+
| `http.status_code` | `client` & `server` | Conditionally Required: if and only if one was received/sent. | [HTTP response status code][]. E.g. `200` (String) |
52+
| `http.flavor` | `client` & `server` | Recommended | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. |
53+
| `net.peer.name` | `client` | Required | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. |
54+
| `net.peer.port` | `client` | Conditionally Required: If not default (`80` for `http`, `443` for `https`). | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. |
55+
| `net.sock.peer.addr` | `client` | Recommended | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) |
56+
| `net.host.name` | `server` | Required | Host of the local HTTP server that received the request. |
57+
| `net.host.port` | `server` | Conditionally Required: If not default (`80` for `http`, `443` for `https`). | Port of the local HTTP server that received the request. |
58+
59+
**[1]:** 'http.route' MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
5760

5861
The following attributes SHOULD be included in the `http.server.active_requests` observation:
5962

@@ -67,26 +70,3 @@ The following attributes SHOULD be included in the `http.server.active_requests`
6770
[HTTP host header]: https://www.rfc-editor.org/rfc/rfc9110.html#name-host-and-authority
6871
[HTTP response status code]: https://www.rfc-editor.org/rfc/rfc9110.html#name-status-codes
6972
[HTTP reason phrase]: https://www.rfc-editor.org/rfc/rfc9110.html#section-15.1
70-
71-
### Parameterized attributes
72-
73-
To avoid high cardinality the following attributes SHOULD substitute any parameters when added as attributes to http metric events as described below:
74-
75-
| Attribute name | Type | Requirement Level | Notes and examples |
76-
|----------------|---------|-------------------|--------------------------------------------------------------------------------------------------------|
77-
| `http.url` | `client` | Required | The originally requested URL |
78-
| `http.target` | `server` | Required | The full request target as passed in a [HTTP request target][] or equivalent, e.g. `"/path/{id}/?q={}"`. |
79-
80-
[Http request target]: https://www.rfc-editor.org/rfc/rfc9110.html#name-determining-the-target-reso
81-
82-
Many REST APIs encode parameters into the URI path, e.g. `/api/users/123` where `123`
83-
is a user id, which creates high cardinality value space not suitable for attributes on metric events.
84-
In case of HTTP servers, these endpoints are often mapped by the server
85-
frameworks to more concise _HTTP routes_, e.g. `/api/users/{user_id}`, which are
86-
recommended as the low cardinality attribute values. However, the same approach usually
87-
does not work for HTTP client attributes, especially when instrumentation is provided
88-
by a lower-level middleware that is not aware of the specifics of how the URIs
89-
are formed. Therefore, HTTP client attributes SHOULD be using conservative, low
90-
cardinality names formed from the available parameters of an HTTP request,
91-
such as `"HTTP {METHOD_NAME}"`. These attributes MUST NOT default to using URI
92-
path.

0 commit comments

Comments
 (0)