Versioning and Stability for OpenTelemetry

CHANGELOG.md

@@ -14,6 +14,7 @@ New:
 
 Updates:
 
+- Versioning and stability guarantees for OpenTelemetry clients([#1291](https://github.com/open-telemetry/opentelemetry-specification/pull/1291))
 - Additional Cassandra semantic attributes
   ([#1217](https://github.com/open-telemetry/opentelemetry-specification/pull/1217))
 - OTEL_EXPORTER environment variable replaced with OTEL_TRACE_EXPORTER and

README.md

@@ -25,6 +25,7 @@ Technical committee holds regular meetings, notes are held
 
 - [Overview](specification/overview.md)
 - [Glossary](specification/glossary.md)
+- [Versioning and stability for OpenTelemetry clients](specification/versioning-and-stability.md)
 - [Library Guidelines](specification/library-guidelines.md)
   - [Package/Library Layout](specification/library-layout.md)
   - [General error handling guidelines](specification/error-handling.md)
@@ -44,7 +45,7 @@ Technical committee holds regular meetings, notes are held
 - About the Project
   - [Timeline](#project-timeline)
   - [Notation Conventions and Compliance](#notation-conventions-and-compliance)
-  - [Versioning](#versioning)
+  - [Versioning the Specification](#versioning-the-specification)
   - [Acronym](#acronym)
   - [Contributions](#contributions)
   - [License](#license)
@@ -64,7 +65,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
 An implementation of the [specification](./specification/overview.md) is not compliant if it fails to satisfy one or more of the "MUST", "MUST NOT", "REQUIRED", "SHALL", or "SHALL NOT" requirements defined in the [specification](./specification/overview.md).
 Conversely, an implementation of the [specification](./specification/overview.md) is compliant if it satisfies all the "MUST", "MUST NOT", "REQUIRED", "SHALL", and "SHALL NOT" requirements defined in the [specification](./specification/overview.md).
 
-## Versioning
+## Versioning the Specification
 
 Changes to the [specification](./specification/overview.md) are versioned according to [Semantic Versioning 2.0](https://semver.org/spec/v2.0.0.html) and described in [CHANGELOG.md](CHANGELOG.md). Layout changes are not versioned. Specific implementations of the specification should specify which version they implement.
 

specification/error-handling.md

@@ -62,7 +62,7 @@ The mechanism by which end users set or register a custom error handler should f
 ### Examples
 
 These are examples of how end users might register custom error handlers.
-Examples are for illustration purposes only. Language library authors
+Examples are for illustration purposes only. OpenTelemetry client authors
 are free to deviate from these provided that their design matches the requirements outlined above.
 
 #### Go

specification/glossary.md

@@ -8,11 +8,21 @@ Some other fundamental terms are documented in the [overview document](overview.
 
 <!-- toc -->
 
+- [User Roles](#user-roles)
+  * [Application Owner](#application-owner)
+  * [Library Author](#library-author)
+  * [Instrumentation Author](#instrumentation-author)
+  * [Plugin Author](#plugin-author)
 - [Common](#common)
+  * [Signals](#signals)
+  * [Packages](#packages)
+  * [ABI Compatibility](#abi-compatibility)
   * [In-band and Out-of-band Data](#in-band-and-out-of-band-data)
   * [Manual Instrumentation](#manual-instrumentation)
   * [Automatic Instrumentation](#automatic-instrumentation)
   * [Telemetry SDK](#telemetry-sdk)
+  * [Constructors](#constructors)
+  * [SDK Plugins](#sdk-plugins)
   * [Exporter Library](#exporter-library)
   * [Instrumented Library](#instrumented-library)
   * [Instrumentation Library](#instrumentation-library)
@@ -28,8 +38,46 @@ Some other fundamental terms are documented in the [overview document](overview.
 
 <!-- tocstop -->
 
+## User Roles
+
+### Application Owner
+
+The maintainer of an application or service, responsible for configuring and managing the lifecycle of the OpenTelemetry SDK.
+
+### Library Author
+
+The maintainer of a shared library which is depended upon by many applications, and targeted by OpenTelemetry instrumentation.
+
+### Instrumentation Author
+
+The maintainer of OpenTelemetry instrumentation written against the OpenTelemetry API.
+This may be instrumentation written within application code, within a shared library, or within an instrumentation library.
+
+### Plugin Author
+
+The maintainer of an OpenTelemetry SDK Plugin, written against OpenTelemetry SDK plugin interfaces.
+
 ## Common
 
+### Signals
+
+OpenTelemetry is structured around signals, or categories of telemetry.
+Metrics, logs, traces, and baggage are examples of signals.
+Each signal represents a coherent, stand-alone set of functionality.
+Each signal follows a separate lifecycle, defining its current stability level.
+
+### Packages
+
+In this specification, the term **package** describes a set of code which represents a single dependency, which may be imported into a program independently from other packages.
+This concept may map to a different term in some languages, such as "module."
+Note that in some languages, the term "package" refers to a different concept.
+
+### ABI Compatibility
+
+An ABI (application binary interface) is an interface which defines interactions between software components at the machine code level, for example between an application executable and a compiled binary of a shared object library. ABI compatibility means that a new compiled version of a library may be correctly linked to a target executable without the need for that executable to be recompiled.
+
+ABI compatibility is important for some languages, especially those which provide a form of machine code. For other languages, ABI compatibility may not be a relevant requirement.
+
 <a name="in-band"></a>
 <a name="out-of-band"></a>
 
@@ -66,9 +114,17 @@ Denotes the library that implements the *OpenTelemetry API*.
 See [Library Guidelines](library-guidelines.md#sdk-implementation) and
 [Library resource semantic conventions](resource/semantic_conventions/README.md#telemetry-sdk).
 
+### Constructors
+
+Constructors are public code used by Application Owners to initialize and configure the OpenTelemetry SDK and contrib packages. Examples of constructors include configuration objects, environment variables, and builders.
+
+### SDK Plugins
+
+Plugins are libraries which extend the OpenTelemetry SDK. Examples of plugin interfaces are the `SpanProcessor`, `Exporter`, and `Sampler` interfaces.
+
 ### Exporter Library
 
-Libraries which are compatible with the [Telemetry SDK](#telemetry-sdk) and provide functionality to emit telemetry to consumers.
+Exporters are SDK Plugins which implement the `Exporter` interface, and emit telemetry to consumers.
 
 ### Instrumented Library
 

specification/library-guidelines.md

@@ -1,52 +1,53 @@
-# OpenTelemetry Language Library Design Principles
+# OpenTelemetry Client Design Principles
 
-This document defines common principles that will help designers create language libraries that are easy to use, are uniform across all supported languages, yet allow enough flexibility for language-specific expressiveness.
+This document defines common principles that will help designers create OpenTelemetry clients that are easy to use, are uniform across all supported languages, yet allow enough flexibility for language-specific expressiveness.
 
-The language libraries are expected to provide full features out of the box and allow for innovation and experimentation through extensibility points.
+OpenTelemetry clients are expected to provide full features out of the box and allow for innovation and experimentation through extensibility.
 
-The document does not attempt to describe a language library API. For API specs see [specification](../README.md).
+Please read the [overview](overview.md) first, to understand the fundamental architecture of OpenTelemetry.
 
-_Note to Language Library Authors:_ OpenTelemetry specification, API and SDK implementation guidelines are work in progress. If you notice incomplete or missing information, contradictions, inconsistent styling and other defects please let specification writers know by creating an issue in this repository or posting in [Gitter](https://gitter.im/open-telemetry/opentelemetry-specification). As implementors of the specification you will often have valuable insights into how the specification can be improved. The Specification SIG and members of Technical Committee highly value your opinion and welcome your feedback.
+This document does not attempt to describe the details or functionality of the OpenTelemetry client API. For API specs see the [API specifications](../README.md).
+
+_Note to OpenTelemetry client Authors:_ OpenTelemetry specification, API and SDK implementation guidelines are work in progress. If you notice incomplete or missing information, contradictions, inconsistent styling and other defects please let specification writers know by creating an issue in this repository or posting in [Gitter](https://gitter.im/open-telemetry/opentelemetry-specification). As implementors of the specification you will often have valuable insights into how the specification can be improved. The Specification SIG and members of Technical Committee highly value your opinion and welcome your feedback.
 
 ## Requirements
 
 1. The OpenTelemetry API must be well-defined and clearly decoupled from the implementation. This allows end users to consume API only without also consuming the implementation (see points 2 and 3 for why it is important).
 
-2. Third party libraries and frameworks that add instrumentation to their code will have a dependency only on the API of OpenTelemetry language library. The developers of third party libraries and frameworks do not care (and cannot know) what specific implementation of OpenTelemetry is used in the final application.
+2. Third party libraries and frameworks that add instrumentation to their code will have a dependency only on the API of OpenTelemetry client. The developers of third party libraries and frameworks do not care (and cannot know) what specific implementation of OpenTelemetry is used in the final application.
 
 3. The developers of the final application normally decide how to configure OpenTelemetry SDK and what extensions to use. They should be also free to choose to not use any OpenTelemetry implementation at all, even though the application and/or its libraries are already instrumented.  The rationale is that third-party libraries and frameworks which are instrumented with OpenTelemetry must still be fully usable in the applications which do not want to use OpenTelemetry (so this removes the need for framework developers to have "instrumented" and "non-instrumented" versions of their framework).
 
 4. The SDK must be clearly separated into wire protocol-independent parts that implement common logic (e.g. batching, tag enrichment by process information, etc.) and protocol-dependent telemetry exporters. Telemetry exporters must contain minimal functionality, thus enabling vendors to easily add support for their specific protocol.
 
 5. The SDK implementation should include the following exporters:
+    - OTLP.
     - Jaeger.
     - Zipkin.
     - Prometheus.
-    - OpenTelemetry Protocol (when the protocol is specified and approved).
     - Standard output (or logging) to use for debugging and testing as well as an input for the various log proxy tools.
     - In-memory (mock) exporter that accumulates telemetry data in the local memory and allows to inspect it (useful for e.g. unit tests).
 
     Note: some of these support multiple protocols (e.g. gRPC, Thrift, etc). The exact list of protocols to implement in the exporters is TBD.
 
-    Other vendor-specific exporters (exporters that implement vendor protocols) should not be included in language libraries and should be placed elsewhere (the exact approach for storing and maintaining vendor-specific exporters will be defined in the future).
+    Other vendor-specific exporters (exporters that implement vendor protocols) should not be included in OpenTelemetry clients and should be placed elsewhere (the exact approach for storing and maintaining vendor-specific exporters will be defined in the future).
 
-## Language Library Generic Design
+## OpenTelemetry Client Generic Design
 
-Here is a generic design for a language library (arrows indicate calls):
+Here is a generic design for an OpenTelemetry client (arrows indicate calls):
 
-![Language Library Design Diagram](../internal/img/library-design.png)
+![OpenTelemetry client Design Diagram](../internal/img/library-design.png)
 
 ### Expected Usage
 
-The OpenTelemetry Language Library is composed of 2 packages: API package and SDK package.
-In this specification, _package_ is used as a conceptual separation and does not prescribe the exact structure of the artifacts making up the language implementations.
-Whether the API and SDK packages are bundled as two all-in-one artifacts or split across multiple ones (e.g. one for api-trace, one for api-metric, one for sdk-trace, one for sdk-metric) is considered an implementation detail as long as the API artifact(s) stay separate from the SDK artifact(s).
+The OpenTelemetry client is composed of 4 types of [packages](glossary.md#packages): API packages, SDK packages, a Semantic Conventions package, and plugin packages.
+The API and the SDK are split into multiple packages, based on signal type (e.g. one for api-trace, one for api-metric, one for sdk-trace, one for sdk-metric) is considered an implementation detail as long as the API artifact(s) stay separate from the SDK artifact(s).
 
-Third-party libraries and frameworks that want to be instrumented in OpenTelemetry-compatible way will have a dependency on the API package. The developers of these third-party libraries will add calls to telemetry API to produce telemetry data.
+Libraries, frameworks, and applications that want to be instrumented with OpenTelemetry take a dependency only on the API packages. The developers of these third-party libraries will make calls to the API to produce telemetry data.
 
-Applications that use third-party libraries that are instrumented with OpenTelemetry API will have a choice to enable or not enable the actual delivery of telemetry data. The application can also call telemetry API directly to produce additional telemetry data.
+Applications that use third-party libraries that are instrumented with OpenTelemetry API control whether or not to install the SDK and generate telemetry data. When the SDK is not installed, the API calls should be no-ops which generate minimal overhead.
 
-In order to enable telemetry the application must take a dependency on the OpenTelemetry SDK, which implements the delivery of the telemetry. The application must also configure exporters so that the SDK knows where and how to deliver the telemetry. The details of how exporters are enabled and configured are language specific.
+In order to enable telemetry the application must take a dependency on the OpenTelemetry SDK. The application must also configure exporters and other plugins so that telemetry can be correctly generated and delivered to their analysis tool(s) of choice. The details of how plugins are enabled and configured are language specific.
 
 ### API and Minimal Implementation
 
@@ -102,21 +103,21 @@ The end-user application may decide to take a dependency on alternative implemen
 
 SDK provides flexibility and extensibility that may be used by many implementations. Before developing an alternative implementation, please, review extensibility points provided by OpenTelemetry.
 
-An example use case for alternate implementations is automated testing. A mock implementation can be plugged in during automated tests. For example it can store all generated telemetry data in memory and provide a capability to inspect this stored data. This will allow the tests to verify that the telemetry is generated correctly. Language Library authors are encouraged to provide such mock implementation.
+An example use-case for alternate implementations is automated testing. A mock implementation can be plugged in during automated tests. For example, it can store all generated telemetry data in memory and provide a capability to inspect this stored data. This will allow the tests to verify that the telemetry is generated correctly. OpenTelemetry client authors are encouraged to provide such a mock implementation.
 
-Note that mocking is also possible by using SDK and a Mock `Exporter` without needed to swap out the entire SDK.
+Note that mocking is also possible by using SDK and a Mock `Exporter` without needing to swap out the entire SDK.
 
 The mocking approach chosen will depend on the testing goals and at which point exactly it is desirable to intercept the telemetry data path during the test.
 
 ### Version Labeling
 
 API and SDK packages must use semantic version numbering. API package version number and SDK package version number are decoupled and can be different (and they both can be also different from the Specification version number that they implement). API and SDK packages MUST be labeled with their own version number.
 
-This decoupling of version numbers allows language library authors to make API and SDK package releases independently without the need to coordinate and match version numbers with the Specification.
+This decoupling of version numbers allows OpenTelemetry client authors to make API and SDK package releases independently without the need to coordinate and match version numbers with the Specification.
 
-Because API and SDK package version numbers are not coupled, every API and SDK package release MUST clearly mention the Specification version number that they implement. In addition, if a particular version of SDK package is only compatible with a specific version of API package, then this compatibility information must be also published by language library authors. Language library authors MUST include this information in the release notes. For example, the SDK package release notes may say: "SDK 0.3.4, use with API 0.1.0, implements OpenTelemetry Specification 0.1.0".
+Because API and SDK package version numbers are not coupled, every API and SDK package release MUST clearly mention the Specification version number that they implement. In addition, if a particular version of SDK package is only compatible with a specific version of API package, then this compatibility information must be also published by OpenTelemetry client authors. OpenTelemetry client authors MUST include this information in the release notes. For example, the SDK package release notes may say: "SDK 0.3.4, use with API 0.1.0, implements OpenTelemetry Specification 0.1.0".
 
-_TODO: How should third party library authors who use OpenTelemetry for instrumentation guide their end users to find the correct SDK package?_
+_TODO: How should third-party library authors who use OpenTelemetry for instrumentation guide their end users to find the correct SDK package?_
 
 ### Performance and Blocking
 

specification/metrics/sdk.md

@@ -169,7 +169,7 @@ failed or timed out.
 
 `Shutdown` SHOULD complete or abort within some timeout. `Shutdown` can be
 implemented as a blocking API or an asynchronous API which notifies the caller
-via a callback or an event. Language library authors can decide if they want to
+via a callback or an event. OpenTelemetry client authors can decide if they want to
 make the shutdown timeout configurable.
 
 #### SDK: Instrument Registration