Add a Start Span section to the OT Shim.

[carlosalberto]

Addresses an item in #2147

For some reason I had lost this section, so adding it again. Namely, the important information is:

• When specifying Span references, use the first one as parent, and all of them as Links (this is what the OT Shims do). The reference type is added as a opentracing.ref_type attribute on the Link itself.
• Add a small Span References section, to clarify that the OT ChildOf and FollowsFrom reference types must not be confused with OTel Links.
• Tags/attributes specified at Span creation MUST be set before the Span is actually created, in case they are passed to some internal API, e.g. the Sampling API. See this Java issue.

Please review @jmacd @yurishkuro

[carlosalberto]

Hey @yurishkuro - updated the text to mention that:

1. From the specified references, the first value with type CHILD_OF is the parent, and if no value with this type exists, use the first value. The remaining values are used as Links.
2. The values added as Links will have a new attribute (part of the Link itself), i.e. opentracing.ref_type=child_of|follows_from. The parent does not keep any attribute - should we add one for that case too?

Let me know whether this aligns with what you have in mind.

(Semantic convention generation is not working for whatever reason, will figure that out)

[github-actions]

This PR was marked stale due to lack of activity. It will be closed in 7 days.

[yurishkuro]

keep

[github-actions]

This PR was marked stale due to lack of activity. It will be closed in 7 days.

[jmacd]

The reference type itself is discarded (we MAY use it later on, if we define equivalent semantics).

I take it this refers to the context that is taken for the parent? Sounds like the shim StartSpan() could be extended to select the OTel SpanKind but we probably won't. 👍

[carlosalberto]

@jmacd Actually that's an outdated part of the description (fixed now), as now we keep the reference type as a Link attribute (opentracing.ref_type).

Sounds like the shim StartSpan() could be extended to select the OTel SpanKind but we probably won't.

I think that, as the semantics are not strictly equivalent, we would have to spend some cycles to define this. Let me know if you think it's important to consider this.

[jmacd]

Let me know if you think it's important to consider this.

I do not! 😀