Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Proposal: Add a version semantic attribute #38

Merged
merged 12 commits into from
Oct 8, 2019
Merged

Proposal: Add a version semantic attribute #38

Changes from 3 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
1db6e46
add resource version rfc
austinlparker Sep 3, 2019
c14b92e
Merge branch 'master' into versionResource
austinlparker Sep 3, 2019
4e7d9f2
fix typo
austinlparker Sep 3, 2019
e45478b
update due to feedback
austinlparker Sep 21, 2019
59986bf
Merge branch 'master' into versionResource
yurishkuro Sep 23, 2019
3ed56a1
Update text/0000-version-resource.md
austinlparker Sep 23, 2019
4f632f5
update number
austinlparker Sep 23, 2019
87bd1e5
remove old version
austinlparker Sep 23, 2019
5a07d7a
Merge branch 'master' into versionResource
bogdandrutu Sep 26, 2019
b4c293f
Rename 0038-version-resource.md to 0038-version-semantic-convention.md
Oct 8, 2019
1f568d7
Merge branch 'master' into versionResource
bogdandrutu Oct 8, 2019
e3aa4bb
Rename 0038-version-semantic-convention.md to 0038-version-semantic-a…
Oct 8, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 53 additions & 0 deletions text/0000-version-resource.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# Version Resource Type

**Status:** `proposed`
austinlparker marked this conversation as resolved.
Show resolved Hide resolved

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 recommended.
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",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not "semver": "1.0.0"?

Copy link
Contributor

@z1c0 z1c0 Sep 19, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this meant in addition to existing resource objects?
e.g.

{
	"type": "container",
	"labels": {
           ....
	},
       "version" : {
       ....
       }
}

(example from OpenCensus: https://github.com/census-instrumentation/opencensus-specs/blob/master/resource/Resource.md#exporter-translation)

"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?