Add span links for HTTP retries and redirects

CHANGELOG.md

@@ -225,6 +225,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,13 @@ 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 and redirects examples](#http-retries-and-redirects-examples)
 
 <!-- tocstop -->
 
@@ -70,6 +72,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 +124,25 @@ 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.
+
+In order to represent the relationship between multiple spans created for retries
+or redirects, `Link` SHOULD be used with each subsequent span linked to the
+span for the immediately previous physical request. These spans SHOULD be
+created as siblings. In case there is no trace started before retries or
+redirects execution, these spans will correspond to different traces. Users are
+expected to interpret span links to understand the behavior of a "logical"
+request in the presence of retries and redirects.
+
+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-and-redirects-examples) for more details.
+
 ## HTTP client
 
 This span type represents an outbound HTTP request.
@@ -280,3 +302,65 @@ 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 and redirects 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, links=[ {trace=t1, span=s2} ], http.retry_count=1)
+  |   |
+  |   --- server (SERVER, trace=t1, span=s5)
+  |
+  -- GET / - 200 (CLIENT, trace=t1, span=s6, links=[ {trace=t1, span=s4} ], 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, links=[ {trace=t1, span=s1} ], http.retry_count=1)
+ |
+ --- server (SERVER, trace=t2, span=s2)
+
+GET / - 200 (CLIENT, trace=t3, span=s1, links=[ {trace=t2, span=s1} ], http.retry_count=2)
+ |
+ --- server (SERVER, trace=t3, span=s1)
+```
+
+Example of redirect 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, links=[ {trace=t1, span=s2} ])
+      |
+      --- server (SERVER, trace=t1, span=s5)
+```
+
+Example of redirect 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, links=[ {trace=t1, span=s1} ])
+ |
+ --- server (SERVER, trace=t2, span=s2)
+```