From a9e6632211ae1594c711f35e1430ebfaca144002 Mon Sep 17 00:00:00 2001
From: Trask Stalnaker <trask.stalnaker@gmail.com>
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 172c3722e0..a815eb8baa 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 eaa2e5ec40..22a0acefe4 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 |
| :------------------- | :---------------------------------------------- |