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

Introduce Telemetry Schemas #152

Merged
merged 6 commits into from
Apr 26, 2021
Merged

Introduce Telemetry Schemas #152

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
e9afbf7
Introduce Telemetry Schemas
tigrannajaryan Apr 12, 2021
0c4c7c0
Rewrite "API and SDK Changes" section
tigrannajaryan Apr 13, 2021
683bca5
Spelling fix
tigrannajaryan Apr 13, 2021
bba4f26
Mention in Summary that Schema URL includes the version number
tigrannajaryan Apr 14, 2021
7b1a5d3
Add Freeze Schema in the Alternates Considered
tigrannajaryan Apr 19, 2021
9c2715f
Clarify that Otel schema version number is equal to spec schema versi…
tigrannajaryan Apr 19, 2021
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
Prev Previous commit
Next Next commit
Add Freeze Schema in the Alternates Considered
  • Loading branch information
@tigrannajaryan
tigrannajaryan committed Apr 19, 2021
commit 7b1a5d380d91796e986bedd0f19453d324f79102
14 changes: 14 additions & 0 deletions text/0152-telemetry-schemas.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -974,6 +974,20 @@ that wish to support the notion of telemetry schemas.

## Alternates Considered
tigrannajaryan marked this conversation as resolved.
Show resolved Hide resolved

### Freeze Schema

Instead of introducing formal schemas, schema files and version we can require
that the instrumentation once it is created never changes. Attributes are never
Copy link
Member

Choose a reason for hiding this comment

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

As long as the instrumentation conforms to the semantic conventions before and after, that should be fine, shouldn't it?

I think rather than freezing the schema completely, we only need to ban changes that would create an entry in the YAML file defined in this OTEP. So renaming is not allowed, adding new attributes is. Changing the meaning of an attribute is also not allowed, but I think this can also not automatically handled with the schema YAML, although the version specified there could then be used in the backend for version-specific handling.

Copy link
Member Author

Choose a reason for hiding this comment

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

Yes, certain changes would be fine with the approach you propose. I still don't think this alternate approach is sufficient. I don't believe it solves the problems we want to solve. In my opinion being able to rename attributes or metrics is a basic requirement. Given how much time we spend arguing about attribute names here in Otel semantic conventions and how much uncertainty is there that the name is right even after the attribute is accepted I believe we will inevitably run into a situation when name changes are wanted.

I saw schema troubles in the past. For example with metrics emitted by Otel Collector, we renamed metrics and broke Collector dashboards in a proprietary monitoring tool. When schemas are not explicitly declared and are not a visible concept they still change and things break, just less explicitly visibly so.

Again, we can argue that we should be careful and come up with semantic conventions that we think are right and then never change them. I think it is an attempt to achieve perfection that is very difficult to do and at the same time increases the barrier to introducing semantic conventions because the cost of making a mistake is very high. I think we should lower that cost a bit. It should still be expensive to change semantic conventions (we don't want to encourage that too much), but it should not be impossible.

renamed, the emitted telemetry always remains the same, with the exception of
changes that cannot affect existing telemetry consumers.

This was considered but does not seem to be an acceptable proposal. Mistakes
happen, semantic conventions may need to be changed because they were
incorrectly defined, there may be bugs in instrumentation that need to be fixed,
etc. We believe that attempting to freeze the schema and only allow fully
backward compatible changes in emitted telemetry is too restrictive and very
difficult to follow long term.

### Name Aliases

This approach solves a smaller subset of schema evolution problems: change of
Expand Down