Replace AWS X-Ray Environment Span Link section

[tylerbenson]

TC decided that users should be able to give priority (controlling the parent/child relationship) to AWS X-Ray's Active Tracing span context (as propagated via the _X_AMZN_TRACE_ID environment variable) by configuring a different order in the OTEL_PROPAGATORS.

There is a separate effort to allow span contexts from additional propagators to be added as span links instead of just overwriting them. That will enable this previous behavior to be maintained.

Here's a POC implementation in Java: open-telemetry/opentelemetry-java-contrib#1032
Note, this POC includes an additional propagator aws that handles the behavior for both xray and xray-lambda. This can easily be removed but included as a demonstration.

Merge requirement checklist

• CONTRIBUTING.md guidelines followed.
• CHANGELOG.md updated for non-trivial changes.
• schema-next.yaml updated with changes to existing conventions.

Fixes open-telemetry/opentelemetry-specification#3605

[tylerbenson]

For reference, here's the TC decision. (This PR only addresses the first bullet point.)

• AWS x-ray has two propagators available
  • ONE does x-ray propagation via attributes / headers
  • ONE does x-ray propagation via the ENV variable
• We improve Propagation API such that:
  • There is a guaranteed ordering of propagators and you know which one will "win" as parent
  • Propagators that have viable "parent" spans but are not chosen are placed into a "SpanLink" context and instead linked to a span, preserving parent-connections.
• We update Tracer
  • There is a new "context" attribute that contains SpanLinks
  • New spans created will add links from this attribute.

This means that users wishing to preserve existing x-ray behavior would specify propagators "baggage, w3c, x-ray, x-ray-env". Users wishing the new behavior would specific propagators "baggage, w3c, x-ray-env, x-ray".

[trask]

any ideas for alternative name for xray-env?

"env" refers to an implementation detail, and doesn't help much with remembering which one to use in which use case

[trask]

nitty suggestions

[tylerbenson]

(To resolve the merge conflict, I rebased on main and moved the changelog entry... the rest of the PR contents are the same.)

I'm dismissing the "Changes requested". I thought I would point out an obvious defect, but it seems to be a point of much discussion, so I'll assume that I did not fully grasp the problem/proposal.

I think @Oberon00 raises a good question that I hadn't thought about previously, and would like to better understand the implications, especially if this is merged and implemented with the existing composite propagator behavior.

[jack-berg]

Assuming the intent is the update this once the notion of defining intended span links in context is formalized, I approve. Left a few comments to hopefully reduce the context required for readers.