Add spec for Span Link and Span Continuation

[gregkalapos]

This PR specifies Span links and Span Continuation. The first is about introducing links between spans (and transactions), the second handles incoming HTTP requests with traceparent headers from outside Elastic APM.

Solves: #596

• May the instrumentation collect sensitive information, such as secrets or PII (ex. in headers)?
  • No
    • There won't be any new information collected. The agent will introduce a new array which will contain transaction/span ids and trace ids. This only introduces links between things which the agent already collects.
• Link to meta issue: https://github.com/elastic/observability-dev/issues/1947 related issue: Traceparent header from outside Elastic #286
• Create PR as draft
• Approval by at least one other agent
• Mark as Ready for Review (automatically requests reviews from all agents and PM via CODEOWNERS)
  • Remove PM from reviewers if impact on product is negligible
  • Remove agents from reviewers if the change is not relevant for them
• Approved by at least 2 agents + PM (if relevant)
• Merge after 7 days passed without objections
• Create implementation issues (ideally add a milestone)
• Create a status table and add it to the meta issue

[gregkalapos]

Open questions:

• Where do we put this?
  Currently it’s a new file, other throughs I had:

  • tracing-spans.md and tracing-transactions.md: Since this applies to both spans and transactions I think putting into any of those would be confusing and may suggest that this only applies to one of them.
  • tracing-distributed-tracing.md: especially with OTel, this isn’t necessarily distributed tracing.
    So my first idea is to add a new file .

• At this point labels aren’t handled here. Should we add those as well or take care of those later? At this point it’s not yet done in APM Server.

[ghost]

💚 Build Succeeded

the below badges are clickable and redirect to their specific view in the CI or DOCS

Expand to view the summary

Build stats

• Start Time: 2022-04-26T17:14:07.923+0000

• Duration: 3 min 18 sec

[felixbarny]

• Where do we put this?
  +1 to put it in a separate file

• At this point labels aren’t handled here. Should we add those as well or take care of those later? At this point it’s not yet done in APM Server.

It's fine to add support for span link labels later, I think.
I don't really know what they're used for tbh. Could you do some research to find out in which situations one might use them and how important these use cases are?

[basepi]

Could span link attributes (as supported by otel) be useful for metadata around the link? Perhaps for differentiating links sourced from external traceparent headers vs those added manually or for batching?

[SergeyKleyman]

I have minor suggestion regarding the naming: trace_continuation_strategy instead of span_continuation_strategy since it controls whether agent continues or breaks a trace. WDYT?

[felixbarny]

This PR proposes trace_continuation_strategy. If I wrote span_continuation_strategy somewhere else, that's a typo. The spec is the single source of truth.

[trentm]

LGTM with a suggestion to link between the docs, now that they are separated.

[gregkalapos]

Summary from a zoom discussion

• Attributes (aka tags or labels): The OTel API offers a way to add attributes to each span link. Every span link has a list of key value pairs. So far we haven't seen any real world use case for using these, so we decided to not add support for it at this point. Without real use cases it's hard to answer questions like: "how should the UI look like for span attributes?" This can be revisited later and we can easily extend our spec to accommodate this. @basepi had a question above which could have been covered by supporting attributes, so the answer to that with this decision is that we won't cover it in the first iteration.
• Project id described in this comment: Same decision - won't be in the first iteration, but we can add it later. Main reason here is that it'd increase complexity significantly (each agent should properly test it) with a very limited benefit for very specific use cases. Plus we can add it easily later.

[gregkalapos]

We discussed this with @felixbarny - agreed to merge this now in order to unblock some other issues and not wait 7 days this time.