Specification Principles

This document defines common principles that will help designers create and extend the OpenTelemetry specification to adapt to new use cases and fix issues.

OpenTelemetry Mission and Values

It should be taken in context of the overall values of OpenTelemetry, which lays out the following core values:

Additionally, it lays out the following core Engineering Values:

In addition to these core values, there are a set of things we’ve learned about Specification work and drive how we write our Specification.

Specification Principles

Here are the key principles of the OpenTelemetry Specification:

Note that at times some of these principles are at odds with each other. For example, keeping things stable may put constraints on possible simplicity. These principles are a rubric to guide design, and form a spectrum through which we evaluate additions or changes to the Specification.

Let’s look at each in more detail.

Be User Driven

The specification is useless without the ecosystem it enables. Changes should focus on real world use cases, and real user needs. Additionally, changes should be implementable across the entire OpenTelemetry ecosystem.

This means proposals should think “end to end” not “add this one little thing”.

Projects and proposals should provide prototypes or implementations before changes are made to the Specification.

We have a few simple rules of thumb regarding prototypes:

  • API/SDK changes should be prototyped in three languages. The goal is coverage of possible API designs, not any specific language:
    • One language should cover typed Object-Oriented ecosystems (Java, .NET, etc.)
    • One language should cover dynamically typed ecosystems (Python, JavaScript)
    • One language should cover structural ecosystems (Go, Rust)
  • Protocol changes should be prototyped both on the client and the server.
  • Prototypes can be unmerged Pull Requests, existing projects, etc. but must demonstrate the feature with confidence that the Specification of it will be successful.

Be General

The specification needs to be implementable across a wide range of languages, frameworks, ecosystems and communities. The specification should allow OpenTelemetry components to provide idiomatic experiences to their users.

The specification should focus on what not how. When describing how, use non-normative language or supplementary guidelines, like this document.

Be Stable

Don’t. Break. Users.

Yes, this is a repeat of the overall OpenTelemetry mission of Stability. That’s how important stability is.

To achieve OpenTelemetry’s mission of “Telemetry should be built-in”, we need to create a set of components that are safe for users to depend on. Instability breaks trust, and hurts the mission of being a solution which application and library authors are glad to integrate with their software out of the box.

When things do change, the specification (and implementation) should do the heavy lifting to ensure seamless, smooth experience for the OpenTelemetry ecosystem.

Be Consistent

Don’t make users learn new concepts and behaviors for each feature they interact with in OpenTelemetry. This has three sub-principles:

  • Favor simple, broadly applicable features.
  • Prefer similar concepts and behaviors between signals.
  • Reuse naming conventions between signals, components, where possible.

Be Simple

Simple is better than complicated. Abstractions should pay for themselves. OpenTelemetry has a large scope and many components. Solving a complex problem with simple design and solution leads to a much lower maintenance burden and easier evolution in the future.

Additionally, a Specification is read and interpreted by many individuals. Complex language, nuanced wording and unclear descriptions lead to confusion and often times poor user experience as sections are not interpreted as desired.