Allow adding links after span creation

CHANGELOG.md

@@ -11,6 +11,12 @@ release.
 
 ### Traces
 
+- Introduce the concept of Instrumentation Scope to replace/extend Instrumentation
+  Library. The Tracer is now associated with Instrumentation Scope
+  ([#2276](https://github.com/open-telemetry/opentelemetry-specification/pull/2276)).
+- Allow adding links after span creation, add new `AddLink` method.
+  ([#2278](https://github.com/open-telemetry/opentelemetry-specification/pull/2278))
+
 ### Metrics
 
 ### Logs
@@ -178,6 +184,9 @@ release.
   variable to point to the correct HTTP port and correct description of
   `OTEL_TRACES_EXPORTER`.
   ([#2333](https://github.com/open-telemetry/opentelemetry-specification/pull/2333))
+- Add `OTEL_EXPORTER_JAEGER_PROTOCOL` environment variable to select the protocol
+  used by the Jaeger exporter.
+  ([#2341](https://github.com/open-telemetry/opentelemetry-specification/pull/2341))
 
 ### Metrics
 

spec-compliance-matrix.md

@@ -29,7 +29,7 @@ formats is required. Implementing more than one format is optional.
 | Set active Span                                                                                  |          | N/A | +    | +   | +      | +    | +      | +   | +    | +   | +    | +     |
 | [Tracer](specification/trace/api.md#tracer-operations)                                           |          |     |      |     |        |      |        |     |      |     |      |       |
 | Create a new Span                                                                                |          | +   | +    | +   | +      | +    | +      | +   | +    | +   | +    | +     |
-| Documentation defines adding attributes at span creation as preferred                            |          |     |      |     |        |      |        |     |      |     | +    |       |
+| Documentation defines adding attributes and links at span creation as preferred                  |          |     |      |     |        |      |        |     |      |     |      |       |
 | Get active Span                                                                                  |          | N/A | +    | +   | +      | +    | +      | +   | +    | +   | +    | +     |
 | Mark Span active                                                                                 |          | N/A | +    | +   | +      | +    | +      | +   | +    | +   | +    | +     |
 | Safe for concurrent calls                                                                        |          | +   | +    | +   | +      | +    | +      | +   | +    | +   | +    | +     |
@@ -64,7 +64,7 @@ formats is required. Implementing more than one format is optional.
 | Array of primitives (homogeneous)                                                                |          | +   | +    | +   | +      | +    | +      | +   | +    | +   | +    | +     |
 | `null` values documented as invalid/undefined                                                    |          | +   | +    | +   | +      | +    | N/A    | +   |      | +   |      | N/A   |
 | Unicode support for keys and string values                                                       |          | +   | +    | +   | +      | +    | +      | +   | +    | +   | +    | +     |
-| [Span linking](specification/trace/api.md#specifying-links)                                      |          |     |      |     |        |      |        |     |      |     |      |       |
+| [AddLink](specification/trace/api.md#add-links)                                                  |          |     |      |     |        |      |        |     |      |     |      |       |
 | Links can be recorded on span creation                                                           |          | +   | +    |     |        | +    | +      | +   | +    | +   | +    |       |
 | Links order is preserved                                                                         |          | +   | +    |     |        | +    | +      | +   | +    | +   | +    |       |
 | [Span events](specification/trace/api.md#add-events)                                             |          |     |      |     |        |      |        |     |      |     |      |       |

specification/common/common.md

@@ -117,7 +117,7 @@ at this time, as discussed in
 [data points](../metrics/datamodel.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#add-links) 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

@@ -118,7 +118,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#add-links), 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

@@ -515,7 +515,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##add-links) functionality. This information
 is however preserved as the `opentracing.ref_type` attribute.
 
 ## In process Propagation exceptions

specification/trace/api.md

@@ -25,11 +25,11 @@
 - [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 Links](#add-links)
     + [Add Events](#add-events)
     + [Set Status](#set-status)
     + [UpdateName](#updatename)
@@ -284,7 +284,7 @@ the entire operation and, optionally, one or more sub-spans for its sub-operatio
 - A start timestamp
 - An end timestamp
 - [`Attributes`](../common/common.md#attributes)
-- A list of [`Link`s](#specifying-links) to other `Span`s
+- A list of [`Link`s](#add-links) to other `Span`s
 - A list of timestamped [`Event`s](#add-events)
 - A [`Status`](#set-status).
 
@@ -369,8 +369,14 @@ The API MUST accept the following parameters:
   The API documentation MUST state that adding attributes at span creation is preferred
   to calling `SetAttribute` later, as samplers can only consider information
   already present during span creation.
+- [`Link`s](../overview.md#links-between-spans) - an ordered sequence of links.
+  Additionally, these links may be used to make a sampling decision as
+  noted in [sampling description](sdk.md#sampling). An empty collection will be
+  assumed if not specified.
 
-- `Link`s - an ordered sequence of Links, see API definition [here](#specifying-links).
+  The API documentation MUST state that adding links at span creation is
+  preferred to calling `AddLink` later, as samplers can only consider information
+  already present during span creation.
 - `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.
@@ -405,30 +411,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/common.md#attributes) 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
@@ -497,6 +479,38 @@ Note that [Samplers](sdk.md#sampler) can only consider information already
 present during span creation. Any changes done later, including new or changed
 attributes, cannot change their decisions.
 
+#### Add Links
+
+A `Span` SHOULD have the ability to add `Link`s associated with it. 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/common.md#attributes) further describing
+  the link.
+
+The Span interface SHOULD 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 set multiple `Link`s at once, where the `Link`s are passed in a
+  single method call.
+
+Spans SHOULD preserve the order in which Links are 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.
+
 #### Add Events
 
 A `Span` MUST have the ability to add events. Events have a time associated