Add a new AddLink() operation to Span.

specification/trace/api.md

@@ -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
+
+A `Span` MUST have the ability to add `Link`s associated with it after its creation - see [Links](#link).
+
+Observe that `Link`s added after `Span` creation are not considered by [Samplers](sdk.md#sampler)
+to make a sampling decision.
+
 #### Set Status
 
 Sets the `Status` of the `Span`. If used, this will override the default `Span`
@@ -797,6 +783,41 @@ 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`.
+
+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.
+
+Links SHOULD preserve the order in which they're set.
+
+Note that [Samplers](sdk.md#sampler) can only consider information already
+present during span creation. Any `Link`s added later cannot change their
+decisions.
+
 ## Concurrency
 
 For languages which support concurrent execution the Tracing APIs provide