Repo and Directory structure

[open-telemetry]

Repo and Directory structure

[freeformz]

You can have multiple modules in the same repo, but it takes careful consideration: https://github.com/golang/go/wiki/Modules#faqs--multi-module-repositories.

To date I don't understand what is meant by "API" and "SDK", but I feel like those should maybe be in the same place. If they are in the same place, what would be outside?

[tigrannajaryan]

To date I don't understand what is meant by "API" and "SDK", but I feel like those should maybe be in the same place. If they are in the same place, what would be outsid

@freeformz this should help https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/library-guidelines.md

[tigrannajaryan]

My understanding is that having separate modules for API and SDK is desirable in the situation when the SDK has a lot more dependencies than the API and you do not want all those dependencies to pollute the end-user application if they only import the API.

Question: how much of a problem is this? Isn't Go compiler smart enough not to link with any of the dependencies referenced in go.mod of the module but otherwise unused (not imported) by the end-user application?

Are there any other downsides to placing API and SDK in the same module (but obviously in different packages)?

[freeformz]

@tigrannajaryan Thanks for that link, yes that helps, although the motivations for the separation of API and SDK are still a little too abstract for my liking.

For instance I can write (and have written) a package (or set of packages) that provides an API for users AND for others to provide protocol independent functionality for the purposes of enriching the standard data and exporting it to services.

WRT single vs multiple repos though, what is the motivation for this? Where is that documented?

[tigrannajaryan]

Thanks for that link, yes that helps, although the motivations for the separation of API and SDK are still a little too abstract for my liking.

For me the primary motivation is ability to use libraries instrumented with OpenTelemetry without enabling telemetry delivery (or as a third-party library author not being required to maintain instrumented and non-instrumented versions of my lib). That's pretty specific in my opinion. Other reasons are listed in the linked doc, and probably different people have different opinions about what is the primary motivation.

If you can think of a better way to achieve the goals stated in the doc please feel free to suggest a different approach.

For instance I can write (and have written) a package (or set of packages) that provides an API for users AND for others to provide protocol independent functionality for the purposes of enriching the standard data and exporting it to services.

I do not quite understand what this means and how it relates to the subject matter, please clarify.

WRT single vs multiple repos though, what is the motivation for this? Where is that documented?

I am likely not the best person to answer this question, I am not aware of any discussions or docs in OpenTelemetry on this topic. Today's SIG meeting is the first time I was exposed to the issue in the context of OpenTelemetry project.

[rghetia]

WRT single vs multiple repos though, what is the motivation for this? Where is that documented?

The problem (if there is one) is specific to Go. In Java, you can build many packages from same repo and you could potentially depend on different version for different package. For example, you could have dependency on

• api-0.1.0.jar
• sdk-0.1.9.jar

OR one could have dependency only on api but not sdk

• api-0.1.0.jar
• private-sdk-0.1.2.jar (custom sdk or third party sdk).

In Go, would that be possible with one repo?

In Go,

[freeformz]

@tigrannajaryan A library needs to declare it's dependencies and let it's users determine how to configure them. So if I write a library that is instrumented with OpenTelemetry I need to expose a way for the user of the library to attach an exporter, sampler, etc. I'm asking other questions in the specification gitter, because the wording in the spec (the doc you linked) seems kind of nuts to me. So I'm obviously missing something.

@rghetia Yes, but see my link above about multiple modules in a single repo.

In Go....
A repo can contain one or more modules.
Modules are a collection of packages.
Modules are versioned packages aren't.
A module can require multiple major versions of another module, but those are resolved to only a single version of each major module version. Ex: api @ v1.0.12 (import api) and api @ v2.0.5 (import api/v2)

So, AFAICT it would be possible to do what you are saying with:
(a) A single repo and a single module that contains two packages (api & sdk). (ot/ot-go/api, ot/ot-go/sdk, ot/ot-go/v2/api, ot/ot-go/v2/sdk, etc);
(b) a single repo with 2 modules (ot/ot-go/sdk, ot/ot-go/api, ot/ot-go/sdk/v2, ot/ot-go/api/v2, etc)
(c) two repos, each with their own module (ot/ot-go-sdk, ot/ot-go-api, ot/ot-go-sdk/v2, ot/ot-go-api/v2).

(a) ties all releases to the same tags. So when v1.0.1 is tagged it applies to both api & sdk. This can be a good thing or a bad thing depending on your constraints.
(b) allows for tagging api and sdk separately: Ex: api/v1.0.1 and sdk/v1.0.0. But there are some other things to consider for using / testing / etc that are mentioned in the module's wiki. Most importantly it may be necessary to use replace in some development situations, which I don't have a great handle on.
(c) Since api and sdk would be in their own repos, each can be tagged / released separately using unprefixed tags as normal.

[rghetia]

@rghetia Yes, but see my link above about multiple modules in a single repo.

For some reason, I missed that. Thanks for the link. It is clear. We can start with 'a' and change it to 'b' if necessary.

[rghetia]

current directory structure seems good.