Define span structure for HTTP retries and redirects (#2078)

This PR clarifies semantic conventions for HTTP retries and redirects and defines a span structure and linking as well as span attributes for retries. Changes were discussed recently at Instrumentation SIG meetings.

This change addresses a scenario which is in the scope for bringing the existing HTTP semantic conventions for tracing to an initial stable state, see related [otep #174](open-telemetry/oteps#174).

CHANGELOG.md

@@ -236,6 +236,8 @@ release.
   ([#1916](https://github.com/open-telemetry/opentelemetry-specification/pull/1916))
 - Change meaning and discourage use of `faas.trigger` for FaaS clients (outgoing).
   ([#1921](https://github.com/open-telemetry/opentelemetry-specification/pull/1921))
+- Define span structure for HTTP retries and redirects.
+  ([#2078](https://github.com/open-telemetry/opentelemetry-specification/pull/2078))
 - Clarify difference between container.name and k8s.container.name
   ([#1980](https://github.com/open-telemetry/opentelemetry-specification/pull/1980))
 

semantic_conventions/trace/http.yaml

@@ -104,6 +104,13 @@ groups:
         brief: >
           The size of the uncompressed response payload body after transport decoding. Not set if transport encoding not used.
         examples: 5493
+      - id: retry_count
+        type: int
+        brief: >
+          The ordinal number of request re-sending attempt.
+        required:
+          conditional: If and only if a request was retried.
+        examples: 3
       - ref: net.peer.name
         sampling_relevant: true
       - ref: net.peer.ip

specification/trace/semantic_conventions/http.md

@@ -14,11 +14,14 @@ and various HTTP versions like 1.1, 2 and SPDY.
 - [Status](#status)
 - [Common Attributes](#common-attributes)
   * [HTTP request and response headers](#http-request-and-response-headers)
+  * [HTTP request retries and redirects](#http-request-retries-and-redirects)
 - [HTTP client](#http-client)
 - [HTTP server](#http-server)
   * [HTTP server definitions](#http-server-definitions)
   * [HTTP Server semantic conventions](#http-server-semantic-conventions)
 - [HTTP client-server example](#http-client-server-example)
+- [HTTP retries examples](#http-retries-examples)
+- [HTTP redirects examples](#http-redirects-examples)
 
 <!-- tocstop -->
 
@@ -70,6 +73,7 @@ Don't set the span status description if the reason can be inferred from `http.s
 | `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 |
+| `http.retry_count` | int | The ordinal number of request re-sending attempt. | `3` | If and only if a request was retried. |
 | [`net.peer.ip`](span-general.md) | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | No |
 | [`net.peer.name`](span-general.md) | string | Remote hostname or similar, see note below. | `example.com` | No |
 | [`net.peer.port`](span-general.md) | int | Remote port number. | `80`; `8080`; `443` | No |
@@ -121,6 +125,17 @@ Users MAY explicitly configure instrumentations to capture them even though it i
 
 [network attributes]: span-general.md#general-network-connection-attributes
 
+### HTTP request retries and redirects
+
+Retries and redirects cause more than one physical HTTP request to be sent.
+A CLIENT span SHOULD be created for each one of these physical requests.
+No span is created corresponding to the "logical" (encompassing) request.
+
+For retries, `http.retry_count` attribute SHOULD be added to each retry span
+with the value that reflects the ordinal number of request retry attempt.
+
+See [examples](#http-retries-examples) for more details.
+
 ## HTTP client
 
 This span type represents an outbound HTTP request.
@@ -280,3 +295,67 @@ If set, it would be
 but due to `http.scheme`, `http.host` and `http.target` being set, it would be redundant.
 As explained above, these separate values are preferred but if for some reason the URL is available but the other values are not,
 URL can replace `http.scheme`, `http.host` and `http.target`.
+
+## HTTP retries examples
+
+Example of retries in the presence of a trace started by an inbound request:
+
+```
+request (SERVER, trace=t1, span=s1)
+  |
+  -- GET / - 500 (CLIENT, trace=t1, span=s2)
+  |   |
+  |   --- server (SERVER, trace=t1, span=s3)
+  |
+  -- GET / - 500 (CLIENT, trace=t1, span=s4, http.retry_count=1)
+  |   |
+  |   --- server (SERVER, trace=t1, span=s5)
+  |
+  -- GET / - 200 (CLIENT, trace=t1, span=s6, http.retry_count=2)
+      |
+      --- server (SERVER, trace=t1, span=s7)
+```
+
+Example of retries with no trace started upfront:
+
+```
+GET / - 500 (CLIENT, trace=t1, span=s1)
+ |
+ --- server (SERVER, trace=t1, span=s2)
+
+GET / - 500 (CLIENT, trace=t2, span=s1, http.retry_count=1)
+ |
+ --- server (SERVER, trace=t2, span=s2)
+
+GET / - 200 (CLIENT, trace=t3, span=s1, http.retry_count=2)
+ |
+ --- server (SERVER, trace=t3, span=s1)
+```
+
+## HTTP redirects examples
+
+Example of redirects in the presence of a trace started by an inbound request:
+
+```
+request (SERVER, trace=t1, span=s1)
+  |
+  -- GET / - 302 (CLIENT, trace=t1, span=s2)
+  |   |
+  |   --- server (SERVER, trace=t1, span=s3)
+  |
+  -- GET /hello - 200 (CLIENT, trace=t1, span=s4 ])
+      |
+      --- server (SERVER, trace=t1, span=s5)
+```
+
+Example of redirects with no trace started upfront:
+
+```
+GET / - 302 (CLIENT, trace=t1, span=s1)
+ |
+ --- server (SERVER, trace=t1, span=s2)
+
+GET /hello - 200 (CLIENT, trace=t2, span=s1 ])
+ |
+ --- server (SERVER, trace=t2, span=s2)
+```