Spec adding a span links API

[trentm]

We are discussing adding span link support. This is a tracking issue to update the APM agent specs for potentially adding/update public agent APIs to support users adding span links via manual instrumentation.

Open Questions

• Do we even want to expose it or should it be internal?
• Add to OTel bridge spec and implementations?

[trentm]

Some initial thoughts.

• Do we even want to expose it or should it be internal?

For the Node.js APM agent, the most natural API would be to add a links option to the current SpanOptions so that the existing .startSpan(...) API could accept link info. This would naturally expose the API to JavaScript users. We could chose to not mention the option in index.d.ts which would technically not expose the API to TypeScript users, but that is somewhat splitting hairs. Mainly it is a decision whether or not to document it. Providing a separate "only used by internal instrumentations" ._startSpan(...) is possible, too, but is some added complexity.

My understanding is similar for the Python APM agent: the natural way to add it to the API for internal use would effectively expose it as well. The only "public or not" barrier would be whether the option is documented.

I don't yet see a reason to not expose it. At least for the OTel JavaScript API, the tracing API is stable, including how to provide link info at Span creation. My current assumption is that our Span link API would match the OTel API.

• Add to OTel bridge spec and implementations?

I would assume, yes, though it could be separate work from the current initial OTel bridge spec and implementations if that is easier.