Spec adding a span links API

[trentm]

Refs: #594

Notes for reviewers

• I've used "span-links-tmp.md" as a placeholder. Once #600 is in, I'll append that content to "span-links.md".

Checklist

• May the instrumentation collect sensitive information, such as secrets or PII (ex. in headers)?
  • [ ] Yes
  • [ ] Add a section to the spec how agents should apply sanitization (such as sanitize_field_names)
  • [x] No
  • [x] Why? Span links only include trace and span IDs.
  • [ ] n/a
• [x] Link to meta issue: #594
• [x] Create PR as draft
• [x] Approval by at least one other agent
• [x] 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
• [x] Approved by at least 2 agents + PM (if relevant)
• [x] Merge after 7 days passed without objections
• [ ] Create implementation issues through the meta issue template (this will automate issue creation for individual agents)

[apmmachine]

:green_heart: 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-05-02T04:32:00.078+0000 * Duration: 3 min 48 sec

[trentm]

The following are some comments/notes on how each of the APM agent APIs could add span links support, if it is decided that is worthwhile for each language agent. Do not take these as requirements at all -- you all know the various APM agents better than I.

Node.js APM agent

Here is the OTel API:

• SpanOptions that are passed to span creation APIs: https://github.com/open-telemetry/opentelemetry-js-api/blob/main/src/trace/SpanOptions.ts#L35-L36
• the Link interface: https://github.com/open-telemetry/opentelemetry-js-api/blob/main/src/trace/link.ts

The addition to the Node.js APM agent public API could be:

  // Link, Attributes, and `links` are intended to be compatible with OTel's
  // equivalent APIs in "opentelemetry-js-api/src/trace/link.ts", with the
  // exception that attributes are not yet accepted.
  export interface Link {
    /** A traceparent-format string, Transaction, or Span. */
    context: Transaction | Span | string; // This is a SpanContext in OTel.
  }

  export interface TransactionOptions {
    startTime?: number;
    childOf?: Transaction | Span | string;
    links?: Link[];
  }

  export interface SpanOptions {
    startTime?: number;
    childOf?: Transaction | Span | string;
    links?: Link[];
    exitSpan?: boolean;
  }

The context here mirrors the existing childOf option to startSpan(...) that encapsulates the needed link data. OTel has a SpanContext object that encapsulates this data.

Usage in JS code would look something like:

const span = apm.startSpan("my-span-name", {
  links: [{ context: record.messageAttributes.traceparent }]
})

The following was considered and rejected: Minimally the API could be reduced to the following. However, that means supporting two different calling forms if/when attributes are supported, which is unnecessarily complexity for a rarely used option.

const span = apm.startSpan("my-span-name", {
  links: [record.messageAttributes.traceparent]
})

[trentm]

Python APM agent

In opentelemetry-python/../src/opentelemetry/trace/__init__.py the start span API is:

    @abstractmethod
    def start_span(
        self,
        name: str,
        context: Optional[Context] = None,
        links: _Links = None,
        ...
    ) -> "Span":

    @contextmanager
    @abstractmethod
    def start_as_current_span(
        self,
        name: str,
        context: Optional[Context] = None,
        links: _Links = None,
        ...
    ) -> Iterator["Span"]:

# where `_Links` is basically (modulo some typings) a list of:

class Link:
    def __init__(self, context, attributes):
        # ...

The Python APM agent could perhaps add a similar links argument to elasticapm.capture_span and elasticapm.async_capture_span. Also to Client.begin_transaction()?

[trentm]

Go APM agent

Presumably a links could be added to SpanOptions (and TransactionOptions?) similar to OTel's SpanConfig, though the Link struct would differ.

type SpanOptions struct {
  // ...
  links      []Link
}