Added docs/library-distribution.md

[eyakimov-bbg]

As per the discussion on the SIG meeting on Feb 4th 2020, I've started to write up
the analysis and recommendations of the library distribution strategy.

This aims to address some of the questions raised in #4 and most recently in #37.

The idea is to summarise the current understanding and implications in this document.

I've left a placeholder to summarise the constraints for guaranteeing ABI, perhaps @rnburn can populate this as he's been move knowledgeable in this area so far.

I wanted to share this while its still in WIP to get further input.

[reyang]

nit:

Suggested change

	them are expected to be distributed as either "source" or "binary" artefacts.
	them are expected to be distributed as either "source" or "binary" artifacts.

[reyang]

The API library will also contain implementations of distributed tracing and basic in-proc context propagation.

[eyakimov-bbg]

I've reworded this to include "minimal implementation" as is the terminology used in the reference documentation in the specification. I wanted to focus on the characteristics relevant to the context (i.e. compiled binary artifacts) rather than thoroughly describe the content, but happy to change

[rnburn]

The OpenTelemetry API is header-only so there's no linking.

But to clarify, this is only a problem for certain scenarios. Some examples

1. Your instrumented library hides the singleton objects in its export map. For instance, in this project Get2 won't be a singleton because it's hidden by the export map.
2. The app doesn't define the global OpenTelemetry symbols and DSOs are dlopen-ed with RTLD_LOCAL so that their global symbols aren't shared.

In general, I don't think this creates any issues if you're binding the instrumented libraries early.

[eyakimov-bbg]

Adding notes from weekly SIG discussion:
https://codereview.stackexchange.com/questions/147407/header-only-c-singleton-pattern-implementation
Also the concept of relying on a weak vs strong symbol for "thick" static libraries

[g-easy]

Please add scenario for: library with binary distribution that uses OpenTelemetry for instrumentation.

[rnburn]

Wouldn't that be the Non OpenTelemetry aware application with OpenTelemetry capability library scenario?

[reyang]

As we've discussed in the community meeting, I suggest that we merge the skeleton doc so folks can add sections in parallel.

[rnburn]

I filled out the deployment scenarios and abi-policy.

@g-easy @pyohannes - Does address #37 and #43 ?

[rnburn]

Looks like auto-formatting is failing on the markdown with buildifier.

[pyohannes]

Does address #37 and #43 ?

Not fully, at least for me.

Abstract classes in the OpenTelemetry API must use ABI stable types in their virtual function
signatures.

In the ABI policy only the API is mentioned, whereas I think the exporter interface is not part of the API layer. From that I'd conclude we don't target ABI stability for exporters.

However, in the library distribution doc SDK and exporters are grouped together in the component section:

• OpenTelemetry Implementations or Exporters

This leads me to conclude that recommendations and example scenarios are targeted for both SDK implementations and exporters. From that I'd conclude we target the same ABI compatibility policy for SDKs and exporters.

[reyang]

For typo and small fixes, let's put them in a separate PR.