Provide guidelines for low-cardinality span names (#416)

Author: yurishkuro

specification/api-tracing.md

@@ -200,7 +200,7 @@ sub-operations.
 
 `Span`s encapsulate:
 
-- The operation name
+- The span name
 - An immutable [`SpanContext`](#spancontext) that uniquely identifies the
   `Span`
 - A parent span in the form of a [`Span`](#span), [`SpanContext`](#spancontext),
@@ -212,6 +212,24 @@ sub-operations.
 - A list of timestamped [`Event`s](#add-events)
 - A [`Status`](#set-status).
 
+The _span name_ is a human-readable string which concisely identifies the work
+represented by the Span, for example, an RPC method name, a function name,
+or the name of a subtask or stage within a larger computation. The span name
+should be the most general string that identifies a (statistically) interesting
+_class of Spans_, rather than individual Span instances. That is, "get_user" is
+a reasonable name, while "get_user/314159", where "314159" is a user ID, is not
+a good name due to its high cardinality.
+
+For example, here are potential span names for an endpoint that gets a
+hypothetical account information:
+
+| Span Name         | Guidance     |
+| ----------------- | ------------ |
+| `get`             | Too general  |
+| `get_account/42`  | Too specific |
+| `get_account`     | Good, and account_id=42 would make a nice Span attribute |
+| `get_account/{accountId}` | Also good (using the "HTTP route") |
+
 The `Span`'s start and end timestamps reflect the elapsed real time of the
 operation. A `Span`'s start time SHOULD be set to the current time on [span
 creation](#span-creation). After the `Span` is created, it SHOULD be possible to
@@ -238,7 +256,7 @@ as a separate operation.
 
 The API MUST accept the following parameters:
 
-- The operation name. This is a required parameter.
+- The span name. This is a required parameter.
 - The parent Span or parent Span context, and whether the new `Span` should be a
   root `Span`. API MAY also have an option for implicit parent context
   extraction from the current context as a default behavior.
@@ -428,7 +446,7 @@ started with the explicit timestamp from the past at the moment where the final
 
 Required parameters:
 
-- The new **operation name**, which supersedes whatever was passed in when the
+- The new **span name**, which supersedes whatever was passed in when the
   `Span` was started
 
 #### End

specification/data-http.md

@@ -21,10 +21,19 @@ and various HTTP versions like 1.1, 2 and SPDY.
 
 ## Name
 
-Given an [RFC 3986](https://tools.ietf.org/html/rfc3986) compliant URI of the form `scheme:[//host[:port]]path[?query][#fragment]`,
-the span name of the span SHOULD be set to the URI path value,
-unless another value that represents the identity of the request and has a lower cardinality can be identified
-(e.g. the route for server spans; see below).
+HTTP spans MUST follow the overall [guidelines for span names](./api-tracing.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
+path as span name, but MAY provide hooks to allow custom logic to override the
+default span name.
 
 ## Status