Review: move start time attributes to separate list

open-telemetry · Sep 13, 2021 · 2671561 · 2671561
1 parent d4430d3
commit 2671561
Showing 1 changed file with 35 additions and 19 deletions.
diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md
@@ -14,6 +14,7 @@ and various HTTP versions like 1.1, 2 and SPDY.
   - [Name](#name)
   - [Status](#status)
   - [Common Attributes](#common-attributes)
+    - [Attribute provision time](#attribute-provision-time)
   - [HTTP client](#http-client)
   - [HTTP server](#http-server)
     - [HTTP server definitions](#http-server-definitions)
@@ -53,20 +54,20 @@ Don't set the span status description if the reason can be inferred from `http.s
 ## Common Attributes
 
 <!-- semconv http -->
-| Attribute  | Type | Description  | Examples  | Required | Required at span creation time |
-|---|---|---|---|---|---|
-| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Yes | Yes |
-| `http.url` | string | Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | No | Yes, when provided |
-| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | No | No |
-| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). An empty Host header should also be reported, see note. [2] | `www.example.org` | No |  Yes, when provided |
-| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | No | No |
-| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | If and only if one was received/sent. | No |
-| `http.flavor` | string | Kind of HTTP protocol used. [3] | `1.0` | No | No |
-| `http.user_agent` | string | Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | No | No |
-| `http.request_content_length` | int | The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2) header. For requests using transport encoding, this should be the compressed size. | `3495` | No | No |
-| `http.request_content_length_uncompressed` | int | The size of the uncompressed request payload body after transport decoding. Not set if transport encoding not used. | `5493` | No | No |
-| `http.response_content_length` | int | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2) header. For requests using transport encoding, this should be the compressed size. | `3495` | No |  No |
-| `http.response_content_length_uncompressed` | int | The size of the uncompressed response payload body after transport decoding. Not set if transport encoding not used. | `5493` | No | No |
+| Attribute  | Type | Description  | Examples  | Required |
+|---|---|---|---|---|
+| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Yes |
+| `http.url` | string | Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | No |
+| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | No |
+| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). An empty Host header should also be reported, see note. [2] | `www.example.org` | No |
+| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | No |
+| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | If and only if one was received/sent. |
+| `http.flavor` | string | Kind of HTTP protocol used. [3] | `1.0` | No |
+| `http.user_agent` | string | Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | No |
+| `http.request_content_length` | int | The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2) header. For requests using transport encoding, this should be the compressed size. | `3495` | No |
+| `http.request_content_length_uncompressed` | int | The size of the uncompressed request payload body after transport decoding. Not set if transport encoding not used. | `5493` | No |
+| `http.response_content_length` | int | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2) header. For requests using transport encoding, this should be the compressed size. | `3495` | No |
+| `http.response_content_length_uncompressed` | int | The size of the uncompressed response payload body after transport decoding. Not set if transport encoding not used. | `5493` | No |
 
 **[1]:** `http.url` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case the attribute's value should be `https://www.example.com/`.
 
@@ -89,6 +90,21 @@ It is recommended to also use the general [network attributes][], especially `ne
 
 [network attributes]: span-general.md#general-network-connection-attributes
 
+### Attribute provision time
+
+Attributes provided at creation time may affect [sampling](../sdk.md#sampling) decision.
+
+All **required** attributes that are populated by instrumentation and **available at span creation time**, MUST be provided:
+
+- `http.method`
+- `http.url`
+- `http.target`
+- `http.host`
+- `net.peer.name`
+- `net.peer.port`
+- `net.peer.ip`
+- `http.server_name` (server only)
+
 ## HTTP client
 
 This span type represents an outbound HTTP request.
@@ -174,11 +190,11 @@ If the route does not include the application root, it SHOULD be prepended to th
 If the route cannot be determined, the `name` attribute MUST be set as defined in the general semantic conventions for HTTP.
 
 <!-- semconv http.server -->
-| Attribute  | Type | Description  | Examples  | Required | Required at span creation time |
-|---|---|---|---|---|---|
-| `http.server_name` | string | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this attribute MUST NOT be set ( `net.host.name` should be used instead). [1] | `example.com` | See below | Yes, if provided |
-| `http.route` | string | The matched route (path template). | `/users/:userID?` | No | No |
-| `http.client_ip` | string | The IP address of the original client behind all proxies, if known (e.g. from [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)). [2] | `83.164.160.102` | No | No |
+| Attribute  | Type | Description  | Examples  | Required |
+|---|---|---|---|---|
+| `http.server_name` | string | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this attribute MUST NOT be set ( `net.host.name` should be used instead). [1] | `example.com` | See below |
+| `http.route` | string | The matched route (path template). | `/users/:userID?` | No |
+| `http.client_ip` | string | The IP address of the original client behind all proxies, if known (e.g. from [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)). [2] | `83.164.160.102` | No |
 
 **[1]:** `http.url` is usually not readily available on the server side but would have to be assembled in a cumbersome and sometimes lossy process from other information (see e.g. open-telemetry/opentelemetry-python/pull/148). It is thus preferred to supply the raw data that is available.