Upgrade procedures for OpenTelemetry #147
Conversation
text/0000-upgrade-procedures
Outdated
|
|
||
| Plugin Interfaces refer to extension points provided by the SDK. These include interfaces for controlling sampling, exporting data, and various other lifecycle hooks. Note that these interfaces are not part of the API. They are part of the SDK. | ||
|
|
||
| Instrumentation refers to any code which calls the API. This includes the instrumentation provided by the OpenTelemetry project, third party instrumentation, plus application code and libraries which instrument themselves natively. |
There was a problem hiding this comment.
nit: "Instrumentation refers to any code which calls the API to produce instrumentation signals". (albeit non-instrumentation usage of the API is limited to SDK or SDK replacements)
There was a problem hiding this comment.
So, in this doc I want to define the term Instrumentation to specify any caller of the API package, vs any implementor of the package interfaces. In other words, focus on the directionality of the dependency and not the use case. The relevant information for the reader is to understand that directionality, not the use case. I will try to make it super clear that the term "instrumentation" cover other random use cases as well, as far as this document is concerned.
There was a problem hiding this comment.
I guess @jsuereth was saying "SDK is not an instrumentation" (although SDK calls the API)?
There was a problem hiding this comment.
@jsuereth want to follow up on this when I add it to the spec?
text/0000-upgrade-procedures
Outdated
|
|
||
| The primary blocker to upgrading the SDK is out of date Plugins. If a new version of the SDK were to break existing Plugin Interfaces, no user would be able to upgrade their SDK until the Plugins they depend on have been upgraded. Users could be caught between instrumentation they depend on requiring a version of the API which is not compatible with the version of the SDK which supports their Plugins. | ||
|
|
||
| By following a deprecation pattern with Plugin Interfaces, we create a one year window in which the Plugin ecosystem can upgrade after the release of a new SDK. We believe this is sufficient time for any Plugin which is actively maintained to make an upgrade, and for defunct Plugins to be identified and replaced. |
There was a problem hiding this comment.
I've been thinking a lot about this here, and I want to through out an idea i've been noodling on.
- Keep this 1-year plugin interface deprecation policy for most SDK plugin interfaces.
- To alleviate concerns around 1-year timeline we provide a longer timeline on the Collector
- We keep a 3-year compatibility guarantee on OTLP exporter to collector
- We provide longer stability guarantees of "plugins API"s through the Collector
This is a non blocking comment, and just a thought I've had when reading this. I think what you've written represents a balance of "what we can do" and "what users will want". However, I know from "build plugin" space that 1-year can actually be "fast" for some old and highly used (but unchanged) plugins. I'm not sure that'll be true in our space but want to call out the parallel. Build plugins likely are more akin to instrumentation, but I still worry 1 year will be too short for the edge case scenarios we'll see people solve.
There was a problem hiding this comment.
I think that would be @tigrannajaryan/@bogdandrutu/collector-maintainers decision.
In general, I think we can support most deprecated plugin interfaces indefinitely, and the window is actually much wider. But I' prefer not to officially make such a long timeline a rule, as there may be edge cases where a Plugin Interface is being changed in order to support a change in the underlying framework architecture, and maintaining the old plugin interface is actually very burdensome.
There was a problem hiding this comment.
I would view this as a floor applied across the entire project. If individual SIGs wanted to provide longer compatibility guarantees then I wouldn't see this as necessarily precluding them from doing so.
There was a problem hiding this comment.
I thought this document was exclusively about language APIs and SDKs. Do we need a separate doc, or at least a section, for the collector?
I think of the collector as having only plugin interfaces, no APIs. Also, since the collector is written in a single language (Go), we can be a lot more specific about the meaning of compatibility.
There was a problem hiding this comment.
@punya correct this document is just about the OpenTelemetry clients. In my opinion the Collector should have the same minimal guarantee (One year support for deprecated plugin interfaces), but I agree that there should be a stability and support document written which is specific to the Collector.
text/0000-upgrade-procedures
Outdated
|
|
||
| Bugs fixes, security patches, and performance improvements are released as patch versions of the SDK. Support for new versions of the API are released as minor versions. New Plugin Interfaces and configuration options are also released as minor versions. | ||
|
|
||
| Breaking changes to Plugin Interfaces are handled through deprecation. Instead of breaking a Plugin Interface, a new interface is created and the existing interface is marked as deprecated. Plugins which target the deprecated interface continue to work, and the SDK provides default implementations of any missing functionality. After one year, the deprecated Plugin Interface is removed as a major version release of the SDK. |
There was a problem hiding this comment.
For some languages adding the new element to the existing interface along with a default implementation will probably be a better fit. cc @jkwatson
There was a problem hiding this comment.
If it's truly a breaking change, then a new interface would need to be provided. But, the old interface should still be supported.
There was a problem hiding this comment.
Totally. Some languages are more flexible than others, so its not the case that every language will experience deprecation at the same rate. The intent is to only apply these rules for situations where a deprecation would lead to a breaking change to plugin implementations.
|
Minor nit...if this were a |
|
Hi all! I believe I have addressed all concerns. @open-telemetry/technical-committee please review and approve. |
|
Merging as we have 4 reviews (and no changes requested). @tedsuo let's follow an issue in the Specification to get this integrated there, etc. |
This OTEP clarifies the stability requirements in the Versioning and Support document.
A google doc version of this OTEP is available here, in case you find that format easier to comment on:
https://docs.google.com/document/d/1p_KDgfBo6_7kO7cvio4ZrcjsJqZqr3UyT00zimUI7qY/edit#