From a9e6632211ae1594c711f35e1430ebfaca144002 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 3 Feb 2023 08:33:10 -0800 Subject: [PATCH] Changes to http span name (#3165) --- CHANGELOG.md | 5 ++++ .../trace/semantic_conventions/http.md | 23 ++++++++----------- 2 files changed, 15 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 172c3722e0c..a815eb8baa7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,6 +27,11 @@ release. - Rename google openshift platform attribute from `google_cloud_openshift` to `gcp_openshift` to match the existing `cloud.provider` prefix. [#3095](https://github.com/open-telemetry/opentelemetry-specification/pull/3095) +- Changes http server span names from `{http.route}` to `{http.method} {http.route}` + (when route is available), and from `HTTP {http.method}` to `{http.method}` (when + route is not available). + Changes http client span names from `HTTP {http.method}` to `{http.method}`. + ([#3165](https://github.com/open-telemetry/opentelemetry-specification/pull/3165)) ### Compatibility diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index eaa2e5ec40f..22a0acefe42 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -30,16 +30,14 @@ and various HTTP versions like 1.1, 2 and SPDY. ## Name HTTP spans MUST follow the overall [guidelines for span names](../api.md#span). -Many REST APIs encode parameters into URI path, e.g. `/api/users/123` where `123` -is a user id, which creates high cardinality value space not suitable for span -names. In case of HTTP servers, these endpoints are often mapped by the server -frameworks to more concise *HTTP routes*, e.g. `/api/users/{user_id}`, which are -recommended as the low cardinality span names. However, the same approach usually -does not work for HTTP client spans, especially when instrumentation is provided -by a lower-level middleware that is not aware of the specifics of how the URIs -are formed. Therefore, HTTP client spans SHOULD be using conservative, low -cardinality names formed from the available parameters of an HTTP request, -such as `"HTTP {METHOD_NAME}"`. Instrumentation MUST NOT default to using URI +HTTP server span names SHOULD be `{http.method} {http.route}` if there is a +(low-cardinality) `http.route` available. +HTTP server span names SHOULD be `{http.method}` if there is no (low-cardinality) +`http.route` available. +HTTP client spans have no `http.route` attribute since client-side instrumentation +is not generally aware of the "route", and therefore HTTP client spans SHOULD use +`{http.method}`. +Instrumentation MUST NOT default to using URI path as span name, but MAY provide hooks to allow custom logic to override the default span name. @@ -232,7 +230,6 @@ This span type represents an inbound HTTP request. For an HTTP server span, `SpanKind` MUST be `Server`. Given an inbound request for a route (e.g. `"/users/:userID?"`) the `name` attribute of the span SHOULD be set to this route. -If the route does not include the application root, it SHOULD be prepended to the span name. If the route cannot be determined, the `name` attribute MUST be set as defined in the general semantic conventions for HTTP. @@ -301,7 +298,7 @@ Note that in some cases host and port identifiers in the `Host` header might be As an example, if a browser request for `https://example.com:8080/webshop/articles/4?s=1` is invoked from a host with IP 192.0.2.4, we may have the following Span on the client side: -Span name: `HTTP GET` +Span name: `GET` | Attribute name | Value | | :------------------- | :-------------------------------------------------------| @@ -315,7 +312,7 @@ Span name: `HTTP GET` The corresponding server Span may look like this: -Span name: `/webshop/articles/:article_id`. +Span name: `GET /webshop/articles/:article_id`. | Attribute name | Value | | :------------------- | :---------------------------------------------- |