Proposal: Add a version semantic attribute (#38)

* add resource version rfc * fix typo * update due to feedback * Update text/0000-version-resource.md Co-Authored-By: Yuri Shkuro <yurishkuro@users.noreply.github.com> * update number * remove old version * Rename 0038-version-resource.md to 0038-version-semantic-convention.md * Rename 0038-version-semantic-convention.md to 0038-version-semantic-attribute.md
open-telemetry · Oct 8, 2019 · cbf9d17 · cbf9d17
1 parent 52d0866
commit cbf9d17
Showing 1 changed file with 34 additions and 0 deletions.
diff --git a/text/0038-version-semantic-attribute.md b/text/0038-version-semantic-attribute.md
@@ -0,0 +1,34 @@
+# Version Semantic Attribute
+
+**Status:** `approved`
+
+Add a standard `version` semantic attribute.
+
+## Motivation
+
+When creating trace data or metrics, it can be extremely useful to know the specific version that
+emitted the iota of span or measurement being viewed. However, versions can mean different things
+to different systems and users. In addition, downstream analysis systems may wish to expose
+functionality related to the type of a version (such as detecting when versions are newer or older).
+To support this, we should standardize a `version` attribute with optional hints as to the type of the
+version.
+
+## Explanation
+
+A `version` is a semantic attribute that can be applied to other resources, such as `Service`,
+`Component`, `Library`, `Device`, `Platform`, etc. A `version` attribute is optional, but recommended.
+The definition of a `version` is a key-value attribute pair of `string` to `string`, with naming schemas
+available to hint at the type of a version, such as the following:
+
+`version=semver:1.2.3` (a semantic version)
+`version=git:8ae73a` (a git sha hash)
+`version=0.0.4.2.20190921` (a untyped version)
+
+## Internal details
+
+Since this is just an attribute pair, no special handling is required, although SDKs may provide helper methods
+to construct schema-appropriate values.
+
+## Prior art and alternatives
+
+Tagging service resources with their version is generally suggested by analysis tools -- see [JAEGER_TAGS](https://www.jaegertracing.io/docs/1.8/client-features/) for an example -- but lacks standardization.