Introduce Telemetry Schema

[tigrannajaryan]

This came as in the context of #1301

My proposal for Telemetry Schema is below. I'd like to have a preliminary discussion before I create a full OTEP.

What constitutes a breaking change

For metrics here is an incomplete list of changes that may be breaking for readers of the telemetry (e.g. for dashboards in the backends):

• Renaming of the metric or of a metric label.
• Elimination of a label (dimension) of a metric.
• Introduction of a label to a metric.
• Splitting of a metric into multiple metric across a label dimension.
• Combining of multiple metrics into one metric with an additional label dimension.
• Change of value data type, aggregation or temporality.
• Change of the unit.
• Change of the scale of the values.

For spans:

• Change of the span name.
• Renaming of an attribute.
• Elimination of an attribute.
• Change of the data type of the attribute value.
• Possibly, addition of an attribute.
• Change of an event name or change of an attribute as described above.

For logs:

• Change of the log record name.
• Renaming of an attribute.
• Elimination of an attribute.
• Change of the data type of the attribute value.
• Possibly, addition of an attribute.
• Change of the body (similar to attribute changes).

[EDIT] We will also need to define relevant changes for Resources.

For future discussions I suggest we call the shape and structure of all of the data that is referenced above the schema of telemetry.

How we handle the changes

Unlike API, I believe changes described above are more likely to occur during the lifelime of an instrumentation library. I do not think we should aim to lock the telemetry schema and disallow changes listed above. Such locking would place a huge limitation on how instrumentation can evolve and would make it nearly impossible to fix mistakes in the semantic conventions, in the schema or in the implementation of the instrumentation (which will inevitably happen sooner or later).

I suggest that we do the following:

• For 1.0 GA we do not provide stability guarantees for telemetry schema emitted by instrumentation.
• We introduce a formal DSL for defining telemetry schema (for traces, metrics ans logs).
• Telemetry schema should be versioned (independently from API, from SDK and from instrumentation library versions). Over time the schema may evolve and instrumentation libraries may emit data confirming to newer versions of the schema.
• Telemetry schema should implicitly or explicitly define transformations that are necessary to convert telemetry between different schema versions when such conversion is possible. When conversion is not possible it constitutes a truly breaking change - I would like to discuss whether we allow or prohibit this.
• Telemetry emitters (e.g. instrumentation libraries) should include the schema or a reference to the schema in the emitted telemetry.
• Telemetry interpreters (e.g. dashboards on the backend) should pay attention to the schema of the received telemetry. If necessary, telemetry interpreters may transform the telemetry data from the received schema version to the target schema version as expected at the point of use (e.g. a dashboard will define which schema version it expects).
• OpenTelemetry will publish telemetry schema as part of the specification. The schema will be the formalized equivalent of semantic conventions. The schema will be available to be referred and downloaded at well known URLs.
• OTLP will be modified to allow inclusion of the schema or schema reference (URL) in the emitted telemetry.
• OpenTelemetry instrumentation libraries will include the schema URL in all emitted telemetry.
• We will create tooling that validates that emitted telemetry confirms to the declared schema. This can be used by instrumentation libraries in debug builds.
• Possibly, we will implement a processor in Collector that automatically transforms telemetry to a desired target schema version, so that it can be consumed by a backend that does not know how to deal with different schemas.
• Telemetry schema will become available as a concept in one of 1.x releases. Until then OpenTelemetry users should be advised that breaking changes to instrumentation may happen (however, we will try to minimize such changes until the telemetry schemas are introduced).
• Third-party libraries, instrumentation or applications will be advised to define and publish their own telemetry schema and include the schema reference in the emitted telemetry.

I can put together an OTEP that describes this proposal in more details.

FYI, @open-telemetry/specs-approvers

[tigrannajaryan]

Triaging hint: this should be "after-ga".

[tigrannajaryan]

I plan to work on this.

[jmacd]

Like https://schema.org/ for telemetry data. 😀

[tigrannajaryan]

@jmacd to clarify: I am working on a design of a machine-readable representation for schemas and recommendations on how observability systems should handle schema changes over time. Once that foundation is in place we can then define Otel schema in that particular representation.