Document compatibility between modules

[pellared]

Documents #3548

[MrAlias]

Overall looks good. Thanks for adding this.

[Aneurysm9]

I'm not sure this is the correct approach here. I understand it is what we have done to this point and expect to continue doing, but I think it is in conflict with the specification's versioning guidelines.

Never create a dependency conflict between packages which rely on different versions of OpenTelemetry.

It is possible (maybe even likely) that an instrumentation library will require a newer version of the OTel API while the application still requires an older version of the SDK. This puts the user in the position of needing to choose between updating an instrumented dependency or staying on a known-working version of the SDK.

What options do we have for avoiding this coupling? I think mutual dependencies from the API back to the SDK modules that depend on its internal packages is a non-starter. What about managed duplication through code generation? Are there other approaches we could take?

[codecov]

Codecov Report

Merging #3806 (a04c8fb) into main (01bbea3) will increase coverage by 0.0%.
The diff coverage is n/a.

Additional details and impacted files

@@          Coverage Diff          @@
##            main   #3806   +/-   ##
=====================================
  Coverage   81.6%   81.7%           
=====================================
  Files        167     167           
  Lines      12459   12462    +3     
=====================================
+ Hits       10179   10182    +3     
  Misses      2065    2065           
  Partials     215     215           

Impacted Files	Coverage Δ
exporters/jaeger/jaeger.go	90.3% <0.0%> (-0.9%)	⬇️
sdk/metric/pipeline.go	90.6% <0.0%> (+<0.1%)	⬆️
sdk/trace/batch_span_processor.go	81.1% <0.0%> (+0.8%)	⬆️

[pellared]

What about managed duplication through code generation?

That is exactly what I propose here

We could address the problem e.g. by using "code generation" to "copy/paste" the common code that is shared between modules.

Having that said, I think we should document the current state before we address the issue.

[ericklaus-wf]

I think the situation is more complicated than described in this documentation update. It isn't the case that modules are only compatible at the same version (go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.11.1 is only compatible with go.opentelemetry.io/otel v1.11.1). Instead, modules are only guaranteed compatible at releases from the same commit, which may be different versions.

For example, go.opentelemetry.io/otel/exporters/otlp/otlpmetric@v0.32.1 is compatible with go.opentelemetry.io/otel@v1.11.1 but is not compatible with go.opentelemetry.io/otel@v1.11.2. The only way to discover compatible versions is to manually inspect each git tag, looking for tags at the same commit. That feels like a pretty onerous burden, but documenting it here will at least make it clearer to your integrators what they're signing up for.

[MadVikingGod]

@pellared I did a bit of work to identify which modules take dependencies on cross-module internal packages here.

[pellared]

Closing. I assigned #3548 to myself.

[pellared]

I think the situation is more complicated than described in this documentation update. It isn't the case that modules are only compatible at the same version (go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.11.1 is only compatible with go.opentelemetry.io/otel v1.11.1). Instead, modules are only guaranteed compatible at releases from the same commit, which may be different versions.

For example, go.opentelemetry.io/otel/exporters/otlp/otlpmetric@v0.32.1 is compatible with go.opentelemetry.io/otel@v1.11.1 but is not compatible with go.opentelemetry.io/otel@v1.11.2. The only way to discover compatible versions is to manually inspect each git tag, looking for tags at the same commit. That feels like a pretty onerous burden, but documenting it here will at least make it clearer to your integrators what they're signing up for.

Correct. cf20bc3 😉