Skip to content

Commit 2ea0b86

Browse files
committed
review: remove explicit config, clarify framework/server config
1 parent dc9a168 commit 2ea0b86

File tree

2 files changed

+10
-7
lines changed

2 files changed

+10
-7
lines changed

docs/http/http-spans.md

+10-7
Original file line numberDiff line numberDiff line change
@@ -316,33 +316,35 @@ HTTP server frameworks and their instrumentations have a limited knowledge about
316316

317317
Certain web frameworks may provide additional information about server. For example CGI specification defines `SERVER_NAME` and `SERVER_PORT` ([RFC 3875][rfc-servername]) variables. HTTP servers usually know server names as they are provided by users in the configuration. See for example, the Apache [`ServerName`][ap-sn] or NGINX [`server_name`][nx-sn] directive.
318318

319-
Still, the original logical service name might not be available to the server HTTP instrumentation and instrumentations MAY provide an option to let users set `server.*` attributes.
319+
Still, the original logical server name might not be available to the HTTP server instrumentation or be inaccurate.
320320

321321
#### Setting `server.address` and `server.port` attributes
322322

323+
In the context of HTTP server, `server.address` and `server.port` attributes capture logical host and port name and intended, whenever possible, to be the same on the client and server sides.
324+
323325
HTTP server instrumentations SHOULD do the best effort when populating `server.address` and `server.port` attributes and determine them by using the first of the following that applies:
324326

325-
* Explicit user configuration (if supported).
326-
* Server name and port available through web framework or HTTP server configuration (if known to the instrumentation).
327-
* The [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's passed in the absolute form.
328327
* The original host which may be passed by the reverse proxy in the `host` identifier of the [`Forwarded`][Forwarded] header or in the [`X-Forwarded-Host`][X-Forwarded-Host] header.
328+
* Server name and port available through web framework or HTTP server properties if they're based on the user configuration. Instrumentations SHOULD NOT use properties that rely on the `Host` header.
329+
* The [request target][request target] if it's passed in the absolute form.
329330
* The `Host` header.
330331

331-
As a result, `server.*` attributes capture logical host and port name and intended to be the same on the client and server sides. Application developers MAY capture private host information using applicable [resource attributes](/docs/resource/README.md).
332-
333332
> **Note**: The `Host` header specifies host and port number of the server. The same applies to the `host` identifier of `Forwarded` header, the `X-Forwarded-Host` header, or the authority component in the request target. Instrumentations SHOULD populate both `server.address` and `server.port` attributes by parsing the applicable property.
334333
335334
The `server.address` SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup.
336335

336+
Application developers MAY overwrite potentially inaccurate values of `server.*` attributes using a [SpanProcessor][SpanProcessor] and MAY capture private host information using applicable [resource attributes](/docs/resource/README.md).
337+
337338
#### Simple client/server example
338339

339340
![simple-http-server.png](simple-http-server.png)
340341

341342
#### Client/server example with reverse proxy
342343

343-
![reverser-proxy-http-server.png](reverser-proxy-http-server.png)
344+
![reverse-proxy-http-server.png](reverse-proxy-http-server.png)
344345

345346
[HTTP Host header]: https://tools.ietf.org/html/rfc7230#section-5.4
347+
[request target]: https://www.rfc-editor.org/rfc/rfc9110.html#target.resource
346348
[Forwarded]: https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded
347349
[X-Forwarded-Host]: https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Host
348350
[rfc-servername]: https://tools.ietf.org/html/rfc3875#section-4.1.14
@@ -573,3 +575,4 @@ Span name: `POST /uploads/:document_id`.
573575
| `error.type` | `WebSocketDisconnect` |
574576

575577
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
578+
[SpanProcessor]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/trace/sdk.md#span-processor

0 commit comments

Comments
 (0)