Prepare release, include fixes with abi breaking changes

[marcalff]

Prepare future releases with breaking changes.

Due to expected changes in the spec, there will be breaking changes in the API/ABI.

Due to changes in the implementation, there are also known changes in the SDK interface, which can break applications when using shared libraries.

It is desirable to group many fixes that causes breaking changes at once, so listing here all the known issues that impact API/ABI.

It is also desirable to define the overall strategy to introduce breaking changes.

API/ABI:

• [Metrics API/SDK] Add InstrumentationScope attributes in MeterProvider::GetMeter() #2033 (API + SDK)
• [Trace API/SDK] Add InstrumentationScope attributes in TracerProvider::GetTracer() #2032 (API + SDK)
• Separate TextMapCarrier into Injector and Extractor interfaces #1922 (API)
• Allow creation of AttributeValue from nostd::span<const char*> #1416 (API)
• Can the API avoid returning shared_ptr<Span>  #828 (API) -> Providing alternate Span creation API to return nostd::unique_ptr.
• [Metrics API] The Record method of class Histogram now must have a context param, but in the Add method of class Counter it is optional #2155
• [Metrics API/SDK] - Support multiple Instrument callbacks #1753
• [Metrics API] Add support for histogram advice API #2132
• Add Synchronous Gauge instrument to the metrics API/SDK #2279

SDK:

• [EXPORTER] OTLP/GRPC Exporter options for metrics/logs do not honor _METRICS_/_LOGS_ environment variables. #1845 (remove exporter options struct inheritance)
• [Trace SDK] OTLP Trace Exporter secure connection configuration options #1402 (new members in exporter options struct)

[lalitb]

Adding few more issues in the list -

• Separate TextMapCarrier into Injector and Extractor interfaces #1922 (API)
• Allow creation of AttributeValue from nostd::span<const char*> #1416 (API)
• Can the API avoid returning shared_ptr<Span>  #828 (API) -> Providing alternate Span creation API to return nostd::unique_ptr.

[marcalff]

On hold until the spec change is settled:

open-telemetry/opentelemetry-specification#3186

If there is an ABI change, we may need to expose both old and new ABI at the same time, by using something similar to

#define OPENTELEMETRY_BEGIN_OLD_NAMESPACE(VER) \
  namespace opentelemetry { namespace VER {

#define OPENTELEMETRY_END_OLD_NAMESPACE \
  }}

#define OPENTELEMETRY_OLD_NAMESPACE(VER) opentelemetry :: VER

and then expose old abi (for binary compatibility) and new abi, as follows:

OPENTELEMETRY_BEGIN_OLD_NAMESPACE(v1)
... declaration for class Span in v1 goes here, code unchanged ...
OPENTELEMETRY_END_OLD_NAMESPACE

#define OPENTELEMETRY_ABI_VERSION_NO 2

OPENTELEMETRY_BEGIN_NAMESPACE
... declaration for class Span in v2 goes here, with added methods ...
OPENTELEMETRY_END_NAMESPACE

[owent]

Adding logs API changes:

• Update logs sdk and api to follow specification #1884 .

[lalitb]

#1884

the Logs API and SDK are still not stable, so we don't need to increment ABI version specifically for them.

[lalitb]

The original intent of having OPENTELEMETRY_ABI_VERSION_NO was to increment this version whenever there is ABI breaking change, in-order to catch any ABI breaking issues as unresolved symbols during link time, and thus avoid any weird memory corruption issues at runtime. It was thought not to maintain older API versions, probably to keep the API simple and easy to maintain.

As per the otel-cpp Versioning.md document, created in response to Versioning and stability guidelines defined by Specs which was also reviewed at that time by specs contributor -

In case of ABI breaking changes, a new inline namespace version will be introduced, and the existing linked applications can continue using the older version unless they relink with newer version.

But this is good to continue discussing maintaining older versions, and there is no reason we can't change our existing guidelines for betterment.

[owent]

Adding trace and instrumentation scope SDK changes:

• [SDK] Add ForceFlush for all LogRecordExporters and SpanExporters. #2000
• Add attributes for InstrumentationScope #2004

[github-actions]

This issue was marked as stale due to lack of activity.

[lalitb]

Add #2155 to the list.

[marcalff]

Please comment on the linked PR #2222 for the technical discussion.