Merge branch 'main' of https://github.com/open-telemetry/opentelemetr…

…y-specification into parse-and-configure
open-telemetry · Oct 11, 2023 · 2719093 · 2719093
2 parents a475548 + 3a1dde9
commit 2719093
Show file tree

Hide file tree

Showing 9 changed files with 266 additions and 32 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,28 +11,75 @@ release.
 
 ### Traces
 
+- Add a new AddLink() operation to Span (experimental).
+  ([#3678](https://github.com/open-telemetry/opentelemetry-specification/pull/3678))
+
+### Metrics
+
+### Logs
+
+### Resource
+
+### OpenTelemetry Protocol
+
+### Compatibility
+
+### SDK Configuration
+
+### Common
+
+### Supplementary Guidelines
+
+## v1.26.0 (2023-10-10)
+
+### Context
+
+- No changes.
+
+### Traces
+
 - `ParentBased` sampler is a decorator (not a composite).
   ([#3706](https://github.com/open-telemetry/opentelemetry-specification/pull/3706))
 
 ### Metrics
 
+- Consistently use "advisory parameters" instead of "advice parameters".
+  ([#3693](https://github.com/open-telemetry/opentelemetry-specification/pull/3693))
 - Stabilize `ExplicitBucketBoundaries` instrument advisory parameter.
   ([#3694](https://github.com/open-telemetry/opentelemetry-specification/pull/3694))
 
 ### Logs
 
+- Update two apache access logs mappings.
+  ([#3712](https://github.com/open-telemetry/opentelemetry-specification/pull/3712))
+
 ### Resource
 
+- No changes.
+
 ### OpenTelemetry Protocol
 
+- No changes.
+
 ### Compatibility
 
+- Prometheus exporters omit empty resources and scopes without attributes.
+  ([#3660](https://github.com/open-telemetry/opentelemetry-specification/pull/3660))
+
 ### SDK Configuration
 
+- Fix description of OTEL_ATTRIBUTE_COUNT_LIMIT
+  ([#3714](https://github.com/open-telemetry/opentelemetry-specification/pull/3714))
+
 ### Common
 
+- Add upgrading and version management documentation
+  ([#3695](https://github.com/open-telemetry/opentelemetry-specification/pull/3695))
+
 ### Supplementary Guidelines
 
+- No changes.
+
 ## v1.25.0 (2023-09-13)
 
 ### Context
@@ -89,8 +136,6 @@ release.
   ([#3471](https://github.com/open-telemetry/opentelemetry-specification/pull/3471))
 - Prometheus: Allow changing metric names by default when translating from Prometheus to OpenTelemetry.
   ([#3679](https://github.com/open-telemetry/opentelemetry-specification/pull/3679))
-- Prometheus exporters omit empty resources and scopes without attributes.
-  ([#3660](https://github.com/open-telemetry/opentelemetry-specification/pull/3660))
 
 ### SDK Configuration
 

diff --git a/spec-compliance-matrix.md b/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                                                                                         |          | +   | +    | +   | +      | +    | +      | +   | +    | +   | +    | +     |

diff --git a/specification/common/README.md b/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

diff --git a/specification/compatibility/opencensus.md b/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

diff --git a/specification/compatibility/opentracing.md b/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

diff --git a/specification/configuration/sdk-environment-variables.md b/specification/configuration/sdk-environment-variables.md
@@ -148,7 +148,7 @@ See the SDK [Attribute Limits](../common/README.md#attribute-limits) section for
 | Name                              | Description                          | Default | Notes |
 | --------------------------------- | ------------------------------------ | ------- | ----- |
 | OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | no limit|       |
-| OTEL_ATTRIBUTE_COUNT_LIMIT        | Maximum allowed span attribute count | 128     |       |
+| OTEL_ATTRIBUTE_COUNT_LIMIT        | Maximum allowed attribute count      | 128     |       |
 
 ## Span Limits
 

diff --git a/specification/logs/data-model-appendix.md b/specification/logs/data-model-appendix.md
@@ -387,7 +387,7 @@ When mapping from the unified model to HEC, we apply this additional mapping:
     <td>%a</td>
     <td>string</td>
     <td>Client address</td>
-    <td>Attributes["client.address"]</td>
+    <td>Attributes["client.socket.address"]</td>
   </tr>
   <tr>
     <td>%A</td>
@@ -399,7 +399,7 @@ When mapping from the unified model to HEC, we apply this additional mapping:
     <td>%h</td>
     <td>string</td>
     <td>Client hostname.</td>
-    <td>Attributes["server.address"]</td>
+    <td>Attributes["client.address"]</td>
   </tr>
   <tr>
     <td>%m</td>

diff --git a/specification/trace/api.md b/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