Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Define span structure for HTTP retries and redirects #2078

Merged
merged 23 commits into from
Mar 9, 2022
Merged
Show file tree
Hide file tree
Changes from 13 commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
b1e3531
Draft conventions for retries and redirects
denisivan0v Oct 26, 2021
ef29b45
Added more info for retry and redirect spans
denisivan0v Oct 26, 2021
7c60c1c
Types fixes
denisivan0v Oct 28, 2021
5911b39
Update CHANGELOG.md
denisivan0v Oct 28, 2021
ac65882
Merge branch 'main' into retries-and-redirects
denisivan0v Nov 16, 2021
b098514
Merge branch 'main' into retries-and-redirects
denisivan0v Nov 23, 2021
ba45f4c
TOC updated
denisivan0v Nov 23, 2021
90c75e1
table-check fix
denisivan0v Nov 23, 2021
5cd8846
preventing PR from auto-closing
denisivan0v Dec 16, 2021
52e17bf
preventing PR from auto-closing
denisivan0v Dec 30, 2021
939efee
Merge branch 'main' into retries-and-redirects
denisivan0v Jan 25, 2022
9071d9b
preventing PR from auto-closing
denisivan0v Jan 27, 2022
bb26521
Feedback addressed
denisivan0v Feb 1, 2022
6126bed
Update specification/trace/semantic_conventions/http.md
denisivan0v Feb 2, 2022
bb2c4e0
Typo
denisivan0v Feb 2, 2022
05bcac7
Links part temporary removed
denisivan0v Mar 2, 2022
12a879d
Merge branch 'main' into retries-and-redirects
denisivan0v Mar 2, 2022
f39ac22
Merge branch 'main' into retries-and-redirects
bogdandrutu Mar 5, 2022
7f7d801
Split retries and redirects into own headings
denisivan0v Mar 8, 2022
d09044a
Merge branch 'retries-and-redirects' of https://github.com/denisivan0…
denisivan0v Mar 8, 2022
dd4312f
Trigger CI build
denisivan0v Mar 8, 2022
49f9dd2
Bookmark fix
denisivan0v Mar 8, 2022
91a7cad
Merge branch 'main' into retries-and-redirects
tigrannajaryan Mar 9, 2022
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,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))

Expand Down
7 changes: 7 additions & 0 deletions semantic_conventions/trace/http.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
denisivan0v marked this conversation as resolved.
Show resolved Hide resolved
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
Expand Down
84 changes: 84 additions & 0 deletions specification/trace/semantic_conventions/http.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 -->

Expand Down Expand Up @@ -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 |
Expand Down Expand Up @@ -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.
denisivan0v marked this conversation as resolved.
Show resolved Hide resolved

In order to represent relationship between multiple spans created for retries
denisivan0v marked this conversation as resolved.
Show resolved Hide resolved
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
denisivan0v marked this conversation as resolved.
Show resolved Hide resolved
denisivan0v marked this conversation as resolved.
Show resolved Hide resolved
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.
Expand Down Expand Up @@ -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
denisivan0v marked this conversation as resolved.
Show resolved Hide resolved

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)
denisivan0v marked this conversation as resolved.
Show resolved Hide resolved
| |
| --- 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)
```