Design document on the API / SDK split and guidelines for what to put where

[Oberon00]

I don't think we have a document that clearly documents the goals the API / SDK split has. I think this could often help answer questions such as "Does this component belong in the SDK or the API?". I also think it is essential for the long term evolution of the API.

Example goals the separate API may or may not have:

1. Have a lightweight artifact that 3rd-parties will be able to take a dependency on without increasing their memory/dependency footprint too much. This facilitates native support for tracing. I'm pretty sure the API has this goal.
2. Allow different implementations of the telemetry library. For example, vendor-specific, or environment-specific (e.g. optimized for embedded).

[bogdandrutu]

Is this not enough https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/library-guidelines.md#language-library-generic-design?

[Oberon00]

Thank you for pointing me to that, I somehow missed this!
I think this does indeed cover what I wanted. I noticed it could use some updates (a few TBD here and there) and it is also geared towards library-writers not spec-writers, but generally it looks good.

[jkwatson]

I do think that "minimal implementation" needs clarification, given that there doesn't appear to be consensus at the moment as to what that means. ;)

[Oberon00]

Well, it's clearly defined there: The minimum so that the application builds and links without errors.

[jkwatson]

Well, it's clearly defined there: The minimum so that the application builds and links without errors.

I disagree. That's required, but I don't see anything that says if it's the only thing they can do, or whether they should also do anything more.

[Oberon00]

In https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/library-guidelines.md#api-and-minimal-implementation

The API dependency contains a minimal implementation of the API.

(bold added by me)

And also:

It is also important that minimal implementation incurs as little performance penalty as possible

By doing as little as possible (minimal) we incur as little performance overhead as possible.

Although I have to concede that these sentences might not have been meant to mean as much as they they can be interpreted to mean, so maybe I should reopen this issue to have a more clear text and possibly different decision there?

[jkwatson]

Yes, I think it has ended up extremely unclear, especially as it relates to context propagation, both in and out of process. There is very little consistency or agreement about what "minimal" means in this regard at the moment. See #719, #721, and today's spec meeting. ;)