Stabilize AddLink operation in Trace API

[pellared]

What are you trying to achieve?

Mark https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#add-link as stable.

[pyohannes]

• Add links after activity (span) creation opentelemetry-dotnet#5273
• Add add_link API  opentelemetry-rust#1515
• Add Span#addLink, for adding link after span start opentelemetry-java#6084
• Add Span.add_link() method to add link after span start. opentelemetry-python#3618
• [API] Add a new AddLink() operation to Span opentelemetry-cpp#2380

[pyohannes]

cc @carlosalberto, who is working on stabilizing this.

[jack-berg]

The add link operation was discussed extensively before merging, but was straight forward to implement once we agreed that was the direction we wanted to go. I don't see any reason why we should delay stabilization.

[cijothomas]

https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md#traces This shows only OTel C++ has implemented this. Most likely this matrix is out-of-date.

@carlosalberto Could you help to make this matrix updated, so it is easy to tell who all have implemented this?

[jack-berg]

Most likely this matrix is out-of-date.

In java, I've only been updating the compliance matrix once we have stable support for something. Not sure this is correct, since it eliminates the spec compliance matrix as a tool for evaluating the stability readiness of experimental features. Maybe I could populate the cell with a symbol which conveys the feature is available but experimental?

[cijothomas]

Most likely this matrix is out-of-date.

In java, I've only been updating the compliance matrix once we have stable support for something. Not sure this is correct, since it eliminates the spec compliance matrix as a tool for evaluating the stability readiness of experimental features. Maybe I could populate the cell with a symbol which conveys the feature is available but experimental?

There was no specific guidelines about when should the matrix be filled in - whether it is done after feature is done in stable or just preview/experimental. Your suggestion of using some symbol to indicate experimental/preview is good! (Though we may need to establish and apply that convention for everything else in the matrix already)

edit: The existing matrix shows Exemplars in Java, though they are still experimental....

[jack-berg]

The exemplars example is strange. In java, we turn on exemplars by default even tho they are experimental. We justified this for a variety of reasons, including that exemplars are stable in the data model. However, the APIs for configuring exemplars are still experimental.

So exemplars are a bit of an oddity for java - somewhere in between stable / experimental - but generally I've resisted filling out the compliance matrix until stable.

[carlosalberto]

Btw, one important point in order to stabilize this is deciding on a way to tell whether a Link was added before OR after Span creation. We had talked in the past about timestamp either as an attribute or an OTLP field, which was also of interest to the Sampling SIG, but it turns out (based on a conversation I had with them last Thursday), this is not the case anymore.

So overall, the question is how important it is to have such timestamp, if any?

cc @Oberon00

[carlosalberto]

Related to #3698

[jack-berg]

We're waiting to decide if #3698 is a prerequisite for stabilization. This was discussed in the 2/13/24 spec SIG, and nobody expressed an opinion that #3698 was blocking. Will give a few more days for anyone to speak up that this is blocking.