diff --git a/specification/api-tracing.md b/specification/api-tracing.md index cd1e1342f5f..6702d1ef596 100644 --- a/specification/api-tracing.md +++ b/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 diff --git a/specification/data-http.md b/specification/data-http.md index e3f3bc72d22..32b6a53ffc6 100644 --- a/specification/data-http.md +++ b/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