api: update the tracer api

[dmehala]

Description

Update the API:

• extract_or_create_span always returns a span, either the extracted one or a new span if the extraction fail.
• override_sampling_priority accepts SamplingPriority.

Motivation

create_span always returns a span, while extract_span may or may not return a span. Logically, one can think the behavior of extract_or_create_span should first attempt to extract_span, and if the extraction fails, it should then call create_span. At least, that's what the name of the function suggest and I think the desired behavior.

The other one is for simplicity's sake.

[pablomartinezbernardo]

What is our policy for incompatible changes in the sdk? We are not following semver right?

[dmehala]

I think we used to follow semver. At least, that's the policy we are following rn.

[dgoffredo]

  // Return a span extracted from the specified `reader` (see `extract_span`).
  // If there is no span to extract, or if an error occurs during extraction,
  // then return a span that is the root of a new trace (see `create_span`).
  // Optionally specify a `config` indicating the attributes of the span.

Fight the entropy!

At least, that's what the name of the function suggest and I think the desired behavior

Desired by whom? The advantage of allowing extraction errors to be returned is that the caller can, if desired, log the error. I anticipated "traces/sampling broken in Istio thingy" bugs whose root cause is extraction failing without making any noise. Likely you weighed this possibility and decided the benefit of Expected<Span> → Span outweighed the risk.