Add a new AddLink() operation to Span. (open-telemetry#3678)

Fixes open-telemetry#454 

Related to open-telemetry#3337 

As the Messaging SIG merged its last OTEP 222, we will be adding operations
that require Links after Span creation, taking a direct route with `AddLink()`,
albeit without any of the new members suggested in open-telemetry#3337, e.g. `timestamp` (to be
discussed in a separate issue).

```
AddLink(spanContext, attributes /* optional */)
```

CHANGELOG.md

@@ -11,6 +11,9 @@ release.
 
 ### Traces
 
+- Add a new AddLink() operation to Span (experimental).
+  ([#3678](https://github.com/open-telemetry/opentelemetry-specification/pull/3678))
+
 ### Metrics
 
 ### Logs

spec-compliance-matrix.md

@@ -67,6 +67,7 @@ formats is required. Implementing more than one format is optional.
 | Unicode support for keys and string values                                                       |          | +   | +    | +   | +      | +    | +      | +   | +    | +   | +    | +     |
 | [Span linking](specification/trace/api.md#specifying-links)                                      | Optional | Go  | Java | JS  | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift |
 | Links can be recorded on span creation                                                           |          | +   | +    |     | +      | +    | +      | +   | +    | +   | +    |       |
+| Links can be recorded after span creation                                                        |          |     |      |     |        |      |        |     |      |     |      |       |
 | Links order is preserved                                                                         |          | +   | +    |     | +      | +    | +      | +   | +    | +   | +    |       |
 | [Span events](specification/trace/api.md#add-events)                                             |          |     |      |     |        |      |        |     |      |     |      |       |
 | AddEvent                                                                                         |          | +   | +    | +   | +      | +    | +      | +   | +    | +   | +    | +     |

specification/common/README.md

@@ -123,7 +123,7 @@ at this time, as discussed in
 [data points](../metrics/data-model.md#metric-points),
 [Spans](../trace/api.md#set-attributes), Span
 [Events](../trace/api.md#add-events), Span
-[Links](../trace/api.md#specifying-links) and
+[Links](../trace/api.md#link) and
 [Log Records](../logs/data-model.md) may contain a collection of attributes. The
 keys in each such collection are unique, i.e. there MUST NOT exist more than one
 key-value pair with the same key. The enforcement of uniqueness may be performed

specification/compatibility/opencensus.md

@@ -180,7 +180,7 @@ using the OpenCensus <-> OpenTelemetry bridge.
    This leads to some issues with OpenCensus APIs that allowed flexible
    specification of parent spans post-initialization.
 2. Links added to spans after the spans are created. This is [not supported in
-   OpenTelemetry](../trace/api.md#specifying-links), therefore OpenCensus spans
+   OpenTelemetry](../trace/api.md#link), therefore OpenCensus spans
    that have links added to them after creation will be mapped to OpenTelemetry
    spans without the links.
 3. OpenTelemetry specifies that samplers are

specification/compatibility/opentracing.md

@@ -544,7 +544,7 @@ OpenTracing defines two types of references:
 
 OpenTelemetry does not define strict equivalent semantics for these
 references. These reference types must not be confused with the
-[Link](../trace/api.md#specifying-links) functionality. This information
+[Link](../trace/api.md#link) functionality. This information
 is however preserved as the `opentracing.ref_type` attribute.
 
 ## In process Propagation exceptions

specification/trace/api.md

@@ -4,7 +4,7 @@ linkTitle: API
 
 # Tracing API
 
-**Status**: [Stable, Feature-freeze](../document-status.md)
+**Status**: [Stable, Feature-freeze](../document-status.md), except where otherwise specified
 
 <details>
 <summary>Table of Contents</summary>
@@ -35,13 +35,15 @@ linkTitle: API
     + [IsRecording](#isrecording)
     + [Set Attributes](#set-attributes)
     + [Add Events](#add-events)
+    + [Add Link](#add-link)
     + [Set Status](#set-status)
     + [UpdateName](#updatename)
     + [End](#end)
     + [Record Exception](#record-exception)
   * [Span lifetime](#span-lifetime)
   * [Wrapping a SpanContext in a Span](#wrapping-a-spancontext-in-a-span)
 - [SpanKind](#spankind)
+- [Link](#link)
 - [Concurrency](#concurrency)
 - [Included Propagators](#included-propagators)
 - [Behavior of the API in the absence of an installed SDK](#behavior-of-the-api-in-the-absence-of-an-installed-sdk)
@@ -300,7 +302,7 @@ the entire operation and, optionally, one or more sub-spans for its sub-operatio
 - A start timestamp
 - An end timestamp
 - [`Attributes`](../common/README.md#attribute)
-- A list of [`Link`s](#specifying-links) to other `Span`s
+- A list of [`Link`s](#link) to other `Span`s
 - A list of timestamped [`Event`s](#add-events)
 - A [`Status`](#set-status).
 
@@ -386,7 +388,7 @@ The API MUST accept the following parameters:
   to calling `SetAttribute` later, as samplers can only consider information
   already present during span creation.
 
-- `Link`s - an ordered sequence of Links, see API definition [here](#specifying-links).
+- `Link`s - an ordered sequence of Links, see [API definition](#link).
 - `Start timestamp`, default to current time. This argument SHOULD only be set
   when span creation time has already passed. If API is called at a moment of
   a Span logical start, API user MUST NOT explicitly set this argument.
@@ -423,27 +425,10 @@ For example, a `Propagator` performing context extraction may need this.
 
 #### Specifying links
 
-During `Span` creation, a user MUST have the ability to record links to other
-`Span`s. Linked `Span`s can be from the same or a different trace -- see [Links
-between spans](../overview.md#links-between-spans). `Link`s cannot be added after
-Span creation.
-
-A `Link` is structurally defined by the following properties:
-
-- `SpanContext` of the `Span` to link to.
-- Zero or more [`Attributes`](../common/README.md#attribute) further describing
-  the link.
-
-The Span creation API MUST provide:
-
-- An API to record a single `Link` where the `Link` properties are passed as
-  arguments. This MAY be called `AddLink`. This API takes the `SpanContext` of
-  the `Span` to link to and optional `Attributes`, either as individual
-  parameters or as an immutable object encapsulating them, whichever is most
-  appropriate for the language. Implementations MAY ignore links with an
-  [invalid](#isvalid) `SpanContext`.
-
-Links SHOULD preserve the order in which they're set.
+During `Span` creation, a user MUST have the ability to record links to other `Span`s.
+Linked `Span`s can be from the same or a different trace -- see [links](#link).
+`Link`s added at `Span` creation may be considered by [Samplers](sdk.md#sampler)
+to make a sampling decision.
 
 ### Span operations
 
@@ -556,6 +541,13 @@ keys"](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/REA
 Note that [`RecordException`](#record-exception) is a specialized variant of
 `AddEvent` for recording exception events.
 
+#### Add Link
+
+**Status**: [Experimental](../document-status.md)
+
+A `Span` MUST have the ability to add `Link`s associated with it after its creation - see [Links](#link).
+`Link`s added after `Span` creation may not be considered by [Samplers](sdk.md#sampler).
+
 #### Set Status
 
 Sets the `Status` of the `Span`. If used, this will override the default `Span`
@@ -797,6 +789,38 @@ To summarize the interpretation of these kinds:
 | `CONSUMER` | | yes | maybe | |
 | `INTERNAL` | | | | |
 
+## Link
+
+A user MUST have the ability to record links to other `SpanContext`s.
+Linked `SpanContext`s can be from the same or a different trace -- see [Links
+between spans](../overview.md#links-between-spans).
+
+A `Link` is structurally defined by the following properties:
+
+- `SpanContext` of the `Span` to link to.
+- Zero or more [`Attributes`](../common/README.md#attribute) further describing
+  the link.
+
+The API MUST provide:
+
+- An API to record a single `Link` where the `Link` properties are passed as
+  arguments. This MAY be called `AddLink`. This API takes the `SpanContext` of
+  the `Span` to link to and optional `Attributes`, either as individual
+  parameters or as an immutable object encapsulating them, whichever is most
+  appropriate for the language. Implementations MAY ignore links with an
+  [invalid](#isvalid) `SpanContext`.
+
+The Span interface MAY provide:
+
+- An API to add multiple `Link`s at once, where the `Link`s are passed in a
+  single method call.
+
+Span SHOULD preserve the order in which `Link`s are set.
+
+The API documentation MUST state that adding links at span creation is preferred
+to calling `AddLink` later, for contexts that are available during span creation,
+because head sampling decisions can only consider information present during span creation.
+
 ## Concurrency
 
 For languages which support concurrent execution the Tracing APIs provide