From 1db6e46d6203883c54b5600d5dd632213b87b9a7 Mon Sep 17 00:00:00 2001 From: Austin Parker Date: Tue, 3 Sep 2019 10:01:51 -0400 Subject: [PATCH 1/8] add resource version rfc --- text/0000-version-resource.md | 53 +++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 text/0000-version-resource.md diff --git a/text/0000-version-resource.md b/text/0000-version-resource.md new file mode 100644 index 000000000..1356d3182 --- /dev/null +++ b/text/0000-version-resource.md @@ -0,0 +1,53 @@ +# Version Resource Type + +**Status:** `proposed` + +Add a composable 'Version' resource type. + +## 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, leading to a situation where a semantic `Version` type that can +encapsulate these identifiers would be useful for analysis systems in order to allow for slicing +data by service, component, or other version. + +## Explanation + +A `Version` is a semantic resource that can be composed with other resources, such as a `Service`, +`Component`, `Library`, `Device`, `Platform`, etc. A `Version` is optional, but reccomended. +The definition of a `Version` is as follows: + +| Key | Value | Description | +|---------|--------|----------------------------------------------| +| semver | string | version string in semver format | +| git_sha | string | version string as a git sha | + +Only one field should be specified in a single `Version`. + +## Internal details + +The exact implementation of this resource would vary based on language, but it would ultimately need to be represented in the data format so that it could be commmunicated to analysis backends. A JSON representation of a version resource follows: + +``` +{ + "version": { + "type": "semver", + "value": "1.0.0", + } +} +``` + +## Trade-offs and mitigations + +The largest drawback to this proposal is that there is a wide variety of things that constitute a 'version string'. By design, we do not attempt to solve for all of them in this proposal - instead, we focus on versions strings that are well-understood to have some semantic meaning attached to them if properly used. + +## 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. + +## Open questions + +What should the exact representation of the version object be? + +Would it make more sense to just have a `version` key that any arbitrary string can be applied to? From 4e7d9f2149c85af4f8bb9851cb8fb24c36933b81 Mon Sep 17 00:00:00 2001 From: Austin Parker Date: Tue, 3 Sep 2019 10:08:45 -0400 Subject: [PATCH 2/8] fix typo --- text/0000-version-resource.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-version-resource.md b/text/0000-version-resource.md index 1356d3182..1a413fccf 100644 --- a/text/0000-version-resource.md +++ b/text/0000-version-resource.md @@ -15,7 +15,7 @@ data by service, component, or other version. ## Explanation A `Version` is a semantic resource that can be composed with other resources, such as a `Service`, -`Component`, `Library`, `Device`, `Platform`, etc. A `Version` is optional, but reccomended. +`Component`, `Library`, `Device`, `Platform`, etc. A `Version` is optional, but recommended. The definition of a `Version` is as follows: | Key | Value | Description | From e45478b9c1a8d9037e708510ed9192a99416bf63 Mon Sep 17 00:00:00 2001 From: Austin Parker Date: Sat, 21 Sep 2019 13:58:13 -0400 Subject: [PATCH 3/8] update due to feedback --- text/0000-version-resource.md | 49 +++++++++++------------------------ 1 file changed, 15 insertions(+), 34 deletions(-) diff --git a/text/0000-version-resource.md b/text/0000-version-resource.md index 1a413fccf..12b2c792d 100644 --- a/text/0000-version-resource.md +++ b/text/0000-version-resource.md @@ -1,53 +1,34 @@ -# Version Resource Type +# Version Semantic Attribute **Status:** `proposed` -Add a composable 'Version' resource type. +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, leading to a situation where a semantic `Version` type that can -encapsulate these identifiers would be useful for analysis systems in order to allow for slicing -data by service, component, or other version. +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 resource that can be composed with other resources, such as a `Service`, -`Component`, `Library`, `Device`, `Platform`, etc. A `Version` is optional, but recommended. -The definition of a `Version` is as follows: +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: -| Key | Value | Description | -|---------|--------|----------------------------------------------| -| semver | string | version string in semver format | -| git_sha | string | version string as a git sha | - -Only one field should be specified in a single `Version`. +`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 -The exact implementation of this resource would vary based on language, but it would ultimately need to be represented in the data format so that it could be commmunicated to analysis backends. A JSON representation of a version resource follows: - -``` -{ - "version": { - "type": "semver", - "value": "1.0.0", - } -} -``` - -## Trade-offs and mitigations - -The largest drawback to this proposal is that there is a wide variety of things that constitute a 'version string'. By design, we do not attempt to solve for all of them in this proposal - instead, we focus on versions strings that are well-understood to have some semantic meaning attached to them if properly used. +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. - -## Open questions - -What should the exact representation of the version object be? - -Would it make more sense to just have a `version` key that any arbitrary string can be applied to? From 3ed56a19f7054148e8f59ed394a73919b99d724d Mon Sep 17 00:00:00 2001 From: Austin Parker Date: Mon, 23 Sep 2019 12:07:08 -0400 Subject: [PATCH 4/8] Update text/0000-version-resource.md Co-Authored-By: Yuri Shkuro --- text/0000-version-resource.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-version-resource.md b/text/0000-version-resource.md index 12b2c792d..2c72fcf00 100644 --- a/text/0000-version-resource.md +++ b/text/0000-version-resource.md @@ -1,6 +1,6 @@ # Version Semantic Attribute -**Status:** `proposed` +**Status:** `approved` Add a standard `version` semantic attribute. From 4f632f546f04904c5d2d562047a038d4edb5b2b6 Mon Sep 17 00:00:00 2001 From: Austin Parker Date: Mon, 23 Sep 2019 12:09:49 -0400 Subject: [PATCH 5/8] update number --- text/0038-version-resource.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 text/0038-version-resource.md diff --git a/text/0038-version-resource.md b/text/0038-version-resource.md new file mode 100644 index 000000000..2c72fcf00 --- /dev/null +++ b/text/0038-version-resource.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. From 87bd1e53f53bee89dc3ed6d26babd79fbe90fbdc Mon Sep 17 00:00:00 2001 From: Austin Parker Date: Mon, 23 Sep 2019 12:10:23 -0400 Subject: [PATCH 6/8] remove old version --- text/0000-version-resource.md | 34 ---------------------------------- 1 file changed, 34 deletions(-) delete mode 100644 text/0000-version-resource.md diff --git a/text/0000-version-resource.md b/text/0000-version-resource.md deleted file mode 100644 index 2c72fcf00..000000000 --- a/text/0000-version-resource.md +++ /dev/null @@ -1,34 +0,0 @@ -# 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. From b4c293f7f249e511feff7e691c92d6eabd681433 Mon Sep 17 00:00:00 2001 From: Bogdan Drutu Date: Tue, 8 Oct 2019 08:23:12 -0700 Subject: [PATCH 7/8] Rename 0038-version-resource.md to 0038-version-semantic-convention.md --- ...38-version-resource.md => 0038-version-semantic-convention.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename text/{0038-version-resource.md => 0038-version-semantic-convention.md} (100%) diff --git a/text/0038-version-resource.md b/text/0038-version-semantic-convention.md similarity index 100% rename from text/0038-version-resource.md rename to text/0038-version-semantic-convention.md From e3aa4bb6fe8fc5e8667d38c7c61e0934cbbac654 Mon Sep 17 00:00:00 2001 From: Bogdan Drutu Date: Tue, 8 Oct 2019 08:33:16 -0700 Subject: [PATCH 8/8] Rename 0038-version-semantic-convention.md to 0038-version-semantic-attribute.md --- ...-semantic-convention.md => 0038-version-semantic-attribute.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename text/{0038-version-semantic-convention.md => 0038-version-semantic-attribute.md} (100%) diff --git a/text/0038-version-semantic-convention.md b/text/0038-version-semantic-attribute.md similarity index 100% rename from text/0038-version-semantic-convention.md rename to text/0038-version-semantic-attribute.md