Add a new AddLink() operation to Span.

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>
@@ -29,19 +29,20 @@ linkTitle: API
 - [Span](#span)
   * [Span Creation](#span-creation)
     + [Determining the Parent Span from a Context](#determining-the-parent-span-from-a-context)
-    + [Specifying links](#specifying-links)
   * [Span operations](#span-operations)
     + [Get Context](#get-context)
     + [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 +301,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 +387,9 @@ 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).
+  `Link`s added at `Span` creation are considered by [Samplers](sdk.md#sampler)
+   to make a sampling decision
 - `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.
@@ -421,30 +424,6 @@ A `SpanContext` cannot be set as active in a `Context` directly, but by
 [wrapping it into a Span](#wrapping-a-spancontext-in-a-span).
 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.
-
 ### Span operations
 
 With the exception of the function to retrieve the `Span`'s `SpanContext` and
@@ -556,6 +535,13 @@ keys"](semantic_conventions/README.md) which have prescribed semantic meanings.
 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 +783,43 @@ To summarize the interpretation of these kinds:
 | `CONSUMER` | | yes | maybe | |
 | `INTERNAL` | | | | |
 
+## Link
+
+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).
+
+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.
+- `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.
+
+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` and `timestamp`, 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`. Alternatively, this functionality MAY be provided
+  through the `AddEvent` operation instead with the respective addition of the new
+  parameters, e.g. the `SpanContext` to link to.
+
+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.
+
+Note that [Samplers](sdk.md#sampler) may only consider information already
+present during span creation. Any `Link`s added later may not change the sampling
+decision.
+
 ## Concurrency
 
 For languages which support concurrent execution the Tracing APIs provide