|
| 1 | +# OpenTelemetry Rationale |
| 2 | + |
| 3 | +When creating a library, often times designs and decisions are made that get lost over time. This |
| 4 | +document tries to collect information on design decisions to answer common questions that may come |
| 5 | +up when you explore the SDK. |
| 6 | + |
| 7 | +## Versioning and Releasing |
| 8 | + |
| 9 | +The OpenTelemetry Applications and OpenTelemetry Spec itself use semver v2. |
| 10 | + |
| 11 | +## Goals |
| 12 | + |
| 13 | +### API Stability |
| 14 | + |
| 15 | +Once the API for a given signal (spans, logs, metrics, baggage) has been officially released, that API module will function with any SDK that has the same major version, and equal or greater minor or patch version. |
| 16 | + |
| 17 | +For example, libraries that are instrumented with `opentelemetry-api 1.0.1` will function with SDK library `opentelemetry-sdk 1.11.33` or `opentelemetry-sdk 1.3.4`. |
| 18 | + |
| 19 | +### SDK Stability: |
| 20 | + |
| 21 | +Public portions of the SDK (constructors, configuration, end-user interfaces) must remain backwards compatible. |
| 22 | +Internal interfaces are allowed to break. |
| 23 | + |
| 24 | +## Methods |
| 25 | + |
| 26 | +### Mature Signals |
| 27 | +API modules for mature (i.e. released) signals will be included in the `opentelemetry-api` module. |
| 28 | + |
| 29 | +### Immature or experimental signals |
| 30 | +API modules for experimental signals will not be included in the `opentelemetry-api` module, and must be installed manually. API modules will remain at version v0.x.y to make it abundantly clear that depending on them is at your own risk. For example, the `opentelemetry-metrics-api` v0.x.y module will provide experimental access to the unfinished metrics API. NO STABILITY GUARANTEES ARE MADE. |
| 31 | + |
| 32 | +## Examples |
| 33 | + |
| 34 | +Purely for illustration purposes, not intended to represent actual releases: |
| 35 | + |
| 36 | +#### V1.0.0 Release (tracing, baggage, propagators, context) |
| 37 | + |
| 38 | +- `opentelemetry-api` 1.0.0 |
| 39 | + - Contains APIs for tracing, baggage, propagators, context |
| 40 | +- `opentelemetry-tracing` 1.0.0 |
| 41 | + - Contains the tracing SDK |
| 42 | +- `opentelemetry-sdk` 1.0.0 |
| 43 | + - Contains SDK components for tracing, baggage, propagators, and context |
| 44 | + |
| 45 | +##### Contains the following experimental packages |
| 46 | + |
| 47 | +- `opentelemetry-api-metrics` 0.x.y |
| 48 | + - Contains the EXPERIMENTAL API for metrics. There are no stability guarantees. |
| 49 | +- `opentelemetry-metrics` 0.x.y |
| 50 | + - Contains the EXPERIMENTAL SDK for metrics. There are no stability guarantees. |
| 51 | + |
| 52 | +#### V1.15.0 Release (with metrics) |
| 53 | + |
| 54 | +- `opentelemetry-api` 1.15.0 |
| 55 | + - Contains APIs for tracing, baggage, propagators, context, and metrics |
| 56 | +- `opentelemetry-tracing` 1.15.0 |
| 57 | + - Contains tracing SDK |
| 58 | +- `opentelemetry-metrics` 1.15.0 |
| 59 | + - Contains metrics SDK |
| 60 | +- `opentelemetry-sdk` 1.15.0 |
| 61 | + - Contains SDK components for tracing, baggage, propagators, context and metrics |
0 commit comments