-
Notifications
You must be signed in to change notification settings - Fork 405
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
What is the difference between the API and SDK? #1186
Comments
See if this spec doc helps clarify this more : https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/library-guidelines.md API is what is required to "instrument" - describe the shape of telemetry - like name of span, its attributes, metric values, etc. SDK implements the API (replacing no-ops with actual implementation), and also deals with concepts of sampling, exporting telemetry to backends etc. The idea behind API and SDK being separate is : One is free to replace the official SDK with their own custom implementation, without requiring re-instrumenting of the app/library. API has higher stability guarantees, as any change to API requires re-instrumenting. If SDK has breaking changes, it only affects a smaller portion of the applications as setting up SDK is typically a one-time operation done at app startup, as opposed to API calls which could be spread throughout the applications (and thus could be very costly to re-instrument) |
I think the concepts make sense, but (at least for me) the naming difference is quite subtle/confusing. At least I haven't seen this naming used before in the Rust ecosystem. |
I see. Thanks a lot @cijothomas for the explanation. I agree with @djc that it does make sense but the difference is quite subtle and maybe a bit hard for Rust developers coming to this library/ecosystem. |
One thing that might help (though I understand this would be a big change, so I don't expect it to happen) would be to make the The |
Currently, I think the The issue with having the There is also a bit of precedent with having the root crate for an ecosystem just be the interface... take While my preference would be for
I think the immediate first step is to examine reverse dependencies of |
I think after creating this initial commit on Also I dug up the old issue #721, even then though I was definitely more in favor of |
This looks good. Probably also move |
That's a good point. I wonder in that case should we just make |
Seems reasonable. I wonder if there's a better/more descriptive name we can think of for |
@jtescher Figured it'd be good to get you to chime in here. |
I think the point that is most difficult to make a "great" DX is that the API and SDK packages have to be separated as the intention of otel is to allow other third party SDK implementations. But given that we have to have two packages, I think whatever is clearest that one is the "main" package that all apps and libraries should use, and the other is the "chosen sdk impl that the app has specified and libraries should not rely on". In that sense having the main api be |
My vote would be to name crates explicitly to indicate purpose - opentelemetry_api and opentelemetry_sdk should be the names, and there should be no need for a "opentelemetry" crate, as it is not clear what it is referring to. If there is a desire to make a uber crate bringing a bunch of commonly used crates, it could be named "opentelemetry-starter" or "opentelemetry-all-in-one" or similar to make the intention clear. OpenTelemetry .NET called their SDK as simply "OpenTelemetry" (there is almost never a need for anyone to install SDK separately, as Exporters automatically bring the SDK), and API as OpenTelemetry.API. But almost every other language implementations call API as "opentelemetry-api" and SDK as "opentelemetry-sdk", with nothing called just 'opentelemetry'. Java : https://search.maven.org/search?q=g:io.opentelemetry |
I'll continue with the PR above then to ready it for merge. |
An additional argument for
Might want to hold until we come to a concensus.
We could do that or the reverse it should work either direction. |
Though not a good comparison with otel-cpp as we don't release any binary packages, but only source distribution. we segregate api and sdk in separate namespaces. So for trace signal,
So no "api" prefix/naming for API code. And C++ community is in general used-to with this convention. My thoughts are - The naming of these packages should adhere to the conventions commonly observed within the language community. As these packages are intended for Rust developers, they should reflect the general ideology and principles of how things operate within the Rust ecosystem. |
Given the established pattern in Rust community, I think I'll change my view - "opentelemetry" crate can be the API (similar to how |
Cool. With that, I'll change the proposal to:
Working on the PR today. |
`opentelemetry` is going to be deprecated in favor of separated crates. open-telemetry/opentelemetry-rust#1186
`opentelemetry` is going to be deprecated in favor of separated crates. open-telemetry/opentelemetry-rust#1186 Signed-off-by: Harold Dost <h.dost@criteo.com>
`opentelemetry` is going to be deprecated in favor of separated crates. open-telemetry/opentelemetry-rust#1186 Signed-off-by: Harold Dost <h.dost@criteo.com>
Reopen as we have other PRs related to this effort |
## Description Updates `opentelemetry-otlp` from 0.13.0 to 0.14.0 Changes `opentelemetry` to `opentelemetry_sdk` dependency and updates to 0.21.0 Changes `opentelemetry_api` to `opentelemetry` and updates to 0.21.0 see open-telemetry/opentelemetry-rust#1186 for more info superseeds #4858
## Description Updates `opentelemetry-otlp` from 0.13.0 to 0.14.0 Changes `opentelemetry` to `opentelemetry_sdk` dependency and updates to 0.21.0 Changes `opentelemetry_api` to `opentelemetry` and updates to 0.21.0 see open-telemetry/opentelemetry-rust#1186 for more info superseeds #4858
As a user of
opentelemetry
, there are quite a few terms to learn when navigating the various packages to achieve some goal.One of the things I've found confusing is the separation between the
opentelemetry_api
andopentelemetry_sdk
. As an outsider that may be missing some project-specific context, those two terms sound like they ought to be interchangeable. My general understanding of SDKs are that they're libraries or sets of libraries that help you build against or on top of APIs. I don't understand why they're separate in OpenTelemetry world and it always feels somewhat random to me what things I need to import from the API or SDK crate.The OpenTelemetry glossary doesn't help that much:
Could this be clarified further in the docs or (I assume not) could the crates just be combined?
The text was updated successfully, but these errors were encountered: