From a96c0ae144eb6447a6be770db06e0f88d516ca12 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Fri, 14 Aug 2020 22:06:16 +0200 Subject: [PATCH 1/2] Clarify span name criteria. --- specification/trace/api.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 7736aa5f8b5..d43e4a83eff 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -216,13 +216,16 @@ the entire operation and, optionally, one or more sub-spans for its sub-operatio - 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. +The _span name_ 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. +While a human-readable span name can be useful, one SHOULD NOT compromise +on the generality of the span name to improve human-readability. For example, here are potential span names for an endpoint that gets a hypothetical account information: From f7e714dce11031b368caa86357d9caddf8c1914c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Fri, 14 Aug 2020 22:18:32 +0200 Subject: [PATCH 2/2] Clarify that human-readility is still something we want. --- specification/trace/api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index d43e4a83eff..4a3c9ec21ce 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -221,11 +221,11 @@ 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. +rather than individual Span instances while still being human-readable. 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. -While a human-readable span name can be useful, one SHOULD NOT compromise -on the generality of the span name to improve human-readability. +Generality SHOULD be prioritized over human-readability. + For example, here are potential span names for an endpoint that gets a hypothetical account information: