-
Notifications
You must be signed in to change notification settings - Fork 192
/
Copy pathhttp-migration.md
234 lines (182 loc) · 12.8 KB
/
http-migration.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
<!--- Hugo front matter used to generate the website version of this page:
linkTitle: HTTP migration
aliases: [../http/migration-guide]
--->
# HTTP semantic convention stability migration
Due to the significant number of modifications and the extensive user base
affected by them, existing HTTP instrumentations published by
OpenTelemetry are required to implement a migration plan that will assist users in
transitioning to the stable HTTP semantic conventions.
Specifically, when existing HTTP instrumentations published by OpenTelemetry are
updated to the stable HTTP semantic conventions, they:
- SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` in
their existing major version, which accepts:
- `http` - emit the stable HTTP and networking conventions, and stop emitting
the old HTTP and networking conventions that the instrumentation emitted
previously.
- `http/dup` - emit both the old and the stable HTTP and networking
conventions, allowing for a phased rollout of the stable semantic
conventions.
- The default behavior (in the absence of one of these values) is to continue
emitting whatever version of the old HTTP and networking conventions the
instrumentation was emitting previously.
- Need to maintain (security patching at a minimum) their existing major version
for at least six months after it starts emitting both sets of conventions.
- May drop the environment variable in their next major version and emit only
the stable HTTP and networking conventions.
> [!NOTE]
> `OTEL_SEMCONV_STABILITY_OPT_IN` is only intended to be used when migrating
> from an experimental semantic convention to its initial stable version.
## Summary of changes
This section summarizes the changes made to the HTTP semantic conventions
from
[v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md)
to
[v1.23.1 (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/README.md).
### Common attributes across HTTP client and server spans
<!-- prettier-ignore-start -->
| Change | Comments |
| --- | --- |
| `http.method` → `http.request.method` | Now captures only 9 common HTTP methods by default (configurable) plus `_OTHER` |
| `http.status_code` → `http.response.status_code` | |
| `http.request.header.<key>` | • Dash (`"-"`) to underscore (`"_"`) normalization in `<key>` has been removed<br>• On HTTP server spans: now must be provided to sampler |
| `http.response.header.<key>` | Dash (`"-"`) to underscore (`"_"`) normalization in `<key>` has been removed |
| `http.request_content_length` → `http.request.body.size` | • Recommended → Opt-In<br>• _Not marked stable yet_ |
| `http.response_content_length` → `http.response.body.size` | • Recommended → Opt-In<br>• _Not marked stable yet_ |
| `user_agent.original` | • On HTTP client spans: Recommended → Opt-In<br>• On HTTP server spans: now must be provided to sampler<br>• See note if [migrating from <= v1.18.0](#migrating-from--v1180) |
| `net.protocol.name` → `network.protocol.name` | Recommended → Conditionally required if not `http` and `network.protocol.version` is set |
| `net.protocol.version` → `network.protocol.version` | • Examples fixed: `2.0` → `2` and `3.0` → `3`<br>• See note if [migrating from <= v1.19.0](#migrating-from--v1190) |
| `net.sock.family` | Removed |
| `net.sock.peer.addr` → `network.peer.address` | On HTTP server spans: if `http.client_ip` was unknown, then also `net.sock.peer.addr` → `client.address`; `client.address` must be provided to sampler |
| `net.sock.peer.port` → `network.peer.port` | Now captured even if same as `server.port` |
| `net.sock.peer.name` | Removed |
| New: `http.request.method_original` | Only captured when `http.request.method` is `_OTHER` |
| New: `error.type` | |
<!-- prettier-ignore-end -->
References:
- [Common attributes v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md#common-attributes)
- [Common attributes v1.23.1 (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/docs/http/http-spans.md#common-attributes)
### HTTP client span attributes
<!-- prettier-ignore-start -->
| Change | Comments |
| --- | --- |
| `http.url` → `url.full` | |
| `http.resend_count` → `http.request.resend_count` | |
| `net.peer.name` → `server.address` | |
| `net.peer.port` → `server.port` | Now captured even when same as default port for scheme |
<!-- prettier-ignore-end -->
References:
- [HTTP client span attributes v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md#http-client)
- [HTTP client span attributes v1.23.1 (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/docs/http/http-spans.md#metric-httpserverrequestduration)
### HTTP server span attributes
<!-- prettier-ignore-start -->
| Change | Comments |
| --- | --- |
| `http.route` | No change |
| `http.target` → `url.path` and `url.query` | Split into two separate attributes |
| `http.scheme` → `url.scheme` | Now factors in [X-Forwarded-Proto][], [Forwarded#proto][] headers |
| `http.client_ip` → `client.address` | If `http.client_ip` was unknown (i.e., no [X-Forwarded-For][], [Forwarded#for][] headers), then `net.sock.peer.addr` → `client.address`; now must be provided to sampler |
| `net.host.name` → `server.address` | Now based only on [Host][Host header], [:authority][HTTP/2 authority], [X-Forwarded-Host][], [Forwarded#host][] headers |
| `net.host.port` → `server.port` | • Now based only on [Host][Host header], [:authority][HTTP/2 authority], [X-Forwarded-Host][X-Forwarded-Host], [Forwarded#host][] headers<br>• Now captured even when same as default port for scheme |
| `net.sock.host.addr` → `network.local.address` | |
| `net.sock.host.port` → `network.local.port` | No longer defaults to `server.port` when `network.local.address` is set. |
<!-- prettier-ignore-end -->
References:
- [HTTP server span attributes v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md#http-server)
- [HTTP server span attributes v1.23.1 (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/docs/http/http-spans.md#metric-httpserverrequestduration)
### HTTP client and server span names
The `{http.method}` portion of span names is replace by `HTTP` when
`{http.method}` is `_OTHER`.
See note if [migrating from `<= v1.17.0`](#migrating-from--v1170).
References:
- [HTTP client and server span names v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md#name)
- [HTTP client and server span names v1.23.1 (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/docs/http/http-spans.md#metric-httpserverrequestduration)
### HTTP client duration metric
Metric changes:
- **Name**: `http.client.duration` → `http.client.request.duration`
- **Unit**: `ms` → `s`
- **Description**: `Measures the duration of inbound HTTP requests.` →
`Duration of HTTP server requests.`
- **Histogram buckets**: boundaries updated to reflect change from milliseconds
to seconds, and zero bucket boundary removed
- **Attributes**: see table below
<!-- prettier-ignore-start -->
| Attribute change | Comments |
| --- | --- |
| `http.method` → `http.request.method` | Now captures only 9 common HTTP methods by default plus `_OTHER` |
| `http.status_code` → `http.response.status_code` | |
| `net.peer.name` → `server.address` | |
| `net.peer.port` → `server.port` | Now captured even when same as default port for scheme |
| `net.sock.peer.addr` | Removed |
| `net.protocol.name` → `network.protocol.name` | Recommended → Conditionally required if not `http` and `network.protocol.version` is set |
| `net.protocol.version` → `network.protocol.version` | Examples fixed: `2.0` → `2` and `3.0` → `3`; see note if [migrating from `<= v1.19.0`](#migrating-from--v1190) |
| New: `error.type` | |
<!-- prettier-ignore-end -->
References:
- [Metric `http.client.duration` v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md#metric-httpclientduration)
- [Metric `http.client.request.duration` v1.23.1 (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/docs/http/http-metrics.md#metric-httpserverrequestduration)
### HTTP server duration metric
Metric changes:
- **Name**: `http.server.duration` → `http.server.request.duration`
- **Unit**: `ms` → `s`
- **Description**: `Measures the duration of inbound HTTP requests.` →
`Duration of HTTP server requests.`
- **Histogram buckets**: boundaries updated to reflect change from milliseconds
to seconds, and zero bucket boundary removed
- **Attributes**: see table below
<!-- prettier-ignore-start -->
| Attribute change | Comments |
| --- | --- |
| `http.route` | No change |
| `http.method` → `http.request.method` | Now captures only 9 common HTTP methods by default plus `_OTHER` |
| `http.status_code` → `http.response.status_code` | |
| `http.scheme` → `url.scheme` | Now factors in [`X-Forwarded-Proto` span][X-Forwarded-Proto], [`Forwarded#proto` span][Forwarded#proto] headers |
| `net.protocol.name` → `network.protocol.name` | Recommended → Conditionally required if not `http` and `network.protocol.version` is set |
| `net.protocol.version` → `network.protocol.version` | Examples fixed: `2.0` → `2` and `3.0` → `3`; see note if [migrating from `<= v1.19.0`](#migrating-from--v1190) |
| `net.host.name` → `server.address` | • Recommended → Opt-In (due to high-cardinality vulnerability since based on HTTP headers)<br>• Now based only on [`Host` span][Host header], [`:authority` span][HTTP/2 authority], [`X-Forwarded-Host` span][X-Forwarded-Host], [`Forwarded#host` span][Forwarded#host] headers |
| `net.host.port` → `server.port` | • Recommended → Opt-In (due to high-cardinality vulnerability since based on HTTP headers)<br>• Now based only on [`Host` span][Host header], [`:authority` span][HTTP/2 authority], [`X-Forwarded-Host` span][X-Forwarded-Host], [`Forwarded#host` span][Forwarded#host] headers |
| New: `error.type` | |
<!-- prettier-ignore-end -->
References:
- [Metric `http.server.duration` v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md#metric-httpserverduration)
- [Metric `http.server.request.duration` v1.23.1 (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/docs/http/http-metrics.md#metric-httpserverrequestduration)
## Migrating from a version prior to v1.20.0?
In addition to the changes made to the HTTP semantic conventions
from
[v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md)
to
[v1.23.1 (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/README.md),
there are additional changes if you are migrating to v1.23.1 from a version prior to v1.20.0.
### Migrating from `<= v1.19.0`
- `http.flavor` → `network.protocol.version`
- Examples fixed: `2.0` → `2` and `3.0` → `3`
### Migrating from `<= v1.18.0`
- `http.user_agent` → `user_agent.original`
### Migrating from `<= v1.17.0`
#### HTTP server span name
- When `http.route` is available:<br> `{http.route}` →
`{summary} {http.route}`
- When `http.route` is not available:<br> `HTTP {http.method}` →
`{summary}`
Where `{summary}` is `{http.method}`, unless `{http.method}` is `_OTHER`, in
which case `{summary}` is `HTTP`.
#### HTTP client span name
- `HTTP {http.method}` → `{summary}`
Where `{summary}` is `{http.method}`, unless `{http.method}` is `_OTHER`, in
which case `{summary}` is `HTTP`.
### Migrating from `<= v1.16.0`
This page does not cover these versions.
[Host header]: https://tools.ietf.org/html/rfc7230#section-5.4
[HTTP/2 authority]: https://tools.ietf.org/html/rfc9113#section-8.3.1
[Forwarded#for]:
https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#for
[Forwarded#proto]:
https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto
[Forwarded#host]:
https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#host
[X-Forwarded-For]:
https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-For
[X-Forwarded-Proto]:
https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto
[X-Forwarded-Host]:
https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Host