Merge branch 'main' into stabilize-add-link

open-telemetry · Mar 5, 2024 · bd2f3ea · bd2f3ea
2 parents 0729a85 + 64f2340
commit bd2f3ea
Show file tree

Hide file tree

Showing 10 changed files with 111 additions and 58 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,14 +7,26 @@ release.
 
 ## Unreleased
 
+- Fix: remove `name` from LogRecord example in the File Exporter example [#3886](https://github.com/open-telemetry/opentelemetry-specification/pull/3886)
+
 ### Context
 
 ### Traces
 
 ### Metrics
 
+- Remove implementation specific specification from metric API.
+  ([#3890](https://github.com/open-telemetry/opentelemetry-specification/pull/3890))
+- Formalize the interaction between cardinality limit and overflow attribute.
+  ([#3912](https://github.com/open-telemetry/opentelemetry-specification/pull/3912))
+
 ### Logs
 
+- Remove implementation detail from Logs Bridge API.
+  ([#3884](https://github.com/open-telemetry/opentelemetry-specification/pull/3884))
+- Clarify that logs attributes are a superset of standard attributes.
+  ([#3852](https://github.com/open-telemetry/opentelemetry-specification/pull/3852))
+
 ### Resource
 
 ### OpenTelemetry Protocol
@@ -25,6 +37,9 @@ release.
 
 ### Common
 
+- Tighten stability requirements for well-known attribute values.
+  ([#3879](https://github.com/open-telemetry/opentelemetry-specification/pull/3879))
+
 ### Supplementary Guidelines
 
 ## v1.30.0 (2024-02-15)
@@ -91,6 +106,8 @@ release.
 
 - Align definition of Baggage with W3C Specification.
   ([#3800](https://github.com/open-telemetry/opentelemetry-specification/pull/3800))
+- Specify allowed characters for Baggage keys and values.
+  ([#3801](https://github.com/open-telemetry/opentelemetry-specification/pull/3801))
 
 ### Traces
 

diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md
@@ -199,19 +199,19 @@ formats is required. Implementing more than one format is optional.
 | The metrics Exporter `ForceFlush` can inform the caller whether it succeeded, failed or timed out.                                                                     |          |    | +    | +   | -      |      | +      | +   |      | +   | +    |       |
 | The metrics Exporter provides a `shutdown` function.                                                                                                                   |          | +  | +    | +   | -      |      | +      | +   |  +   | +   | +    |       |
 | The metrics Exporter `shutdown` function do not block indefinitely.                                                                                                    |          | +  | +    | +   | -      |      | +      |     |      | +   | +    |       |
-| The metrics SDK samples `Exemplar`s from measurements.                                                                                                                 |          |    | +    |     | -      |      | -      |     |      |     | -    |       |
-| Exemplar sampling can be disabled.                                                                                                                                     |          |    | -    |     | -      |      | -      |     |      |     | -    |       |
-| The metrics SDK supports SDK-wide exemplar filter configuration                                                                                                        |          |    | +    |     | -      |      | -      |     |      |     | -    |       |
-| The metrics SDK supports `TraceBased` exemplar filter                                                                                                                  |          |    | +    |     | -      |      | -      |     |      |     | -    |       |
-| The metrics SDK supports `AlwaysOn` exemplar filter                                                                                                                    |          |    | +    |     | -      |      | -      |     |      |     | -    |       |
-| The metrics SDK supports `AlwaysOff` exemplar filter                                                                                                                   |          |    | +    |     | -      |      | -      |     |      |     | -    |       |
-| Exemplars retain any attributes available in the measurement that are not preserved by aggregation or view configuration.                                              |          |    | +    |     | -      |      | -      |     |      |     | -    |       |
-| Exemplars contain the associated trace id and span id of the active span in the Context when the measurement was taken.                                                |          |    | +    |     | -      |      | -      |     |      |     | -    |       |
-| Exemplars contain the timestamp when the measurement was taken.                                                                                                        |          |    | +    |     | -      |      | -      |     |      |     | -    |       |
-| The metrics SDK provides an `ExemplarReservoir` interface or extension point.                                                                                          | X        |    | -    |     | -      |      | -      | +   |      |     | -    |       |
-| An `ExemplarReservoir` has an `offer` method with access to the measurement value, attributes, `Context` and timestamp.                                                | X        |    | -    |     | -      |      | -      | +   |      |     | -    |       |
-| The metrics SDK provides a `SimpleFixedSizeExemplarReservoir` that is used by default for all aggregations except `ExplicitBucketHistogram`.                           |          |    | +    |     | -      |      | -      | +   |      |     | -    |       |
-| The metrics SDK provides an `AlignedHistogramBucketExemplarReservoir` that is used by default for `ExplicitBucketHistogram` aggregation.                               |          |    | +    |     | -      |      | -      |     |      |     | -    |       |
+| The metrics SDK samples `Exemplar`s from measurements.                                                                                                                 |          |    | +    |     | -      |      | +      |     |      |     | -    |       |
+| Exemplar sampling can be disabled.                                                                                                                                     |          |    | -    |     | -      |      | +      |     |      |     | -    |       |
+| The metrics SDK supports SDK-wide exemplar filter configuration                                                                                                        |          |    | +    |     | -      |      | +      |     |      |     | -    |       |
+| The metrics SDK supports `TraceBased` exemplar filter                                                                                                                  |          |    | +    |     | -      |      | +      |     |      |     | -    |       |
+| The metrics SDK supports `AlwaysOn` exemplar filter                                                                                                                    |          |    | +    |     | -      |      | +      |     |      |     | -    |       |
+| The metrics SDK supports `AlwaysOff` exemplar filter                                                                                                                   |          |    | +    |     | -      |      | +      |     |      |     | -    |       |
+| Exemplars retain any attributes available in the measurement that are not preserved by aggregation or view configuration.                                              |          |    | +    |     | -      |      | +      |     |      |     | -    |       |
+| Exemplars contain the associated trace id and span id of the active span in the Context when the measurement was taken.                                                |          |    | +    |     | -      |      | +      |     |      |     | -    |       |
+| Exemplars contain the timestamp when the measurement was taken.                                                                                                        |          |    | +    |     | -      |      | +      |     |      |     | -    |       |
+| The metrics SDK provides an `ExemplarReservoir` interface or extension point.                                                                                          | X        |    | -    |     | -      |      | +      | +   |      |     | -    |       |
+| An `ExemplarReservoir` has an `offer` method with access to the measurement value, attributes, `Context` and timestamp.                                                | X        |    | -    |     | -      |      | +      | +   |      |     | -    |       |
+| The metrics SDK provides a `SimpleFixedSizeExemplarReservoir` that is used by default for all aggregations except `ExplicitBucketHistogram`.                           |          |    | +    |     | -      |      | +      | +   |      |     | -    |       |
+| The metrics SDK provides an `AlignedHistogramBucketExemplarReservoir` that is used by default for `ExplicitBucketHistogram` aggregation.                               |          |    | +    |     | -      |      | +      |     |      |     | -    |       |
 | A metric Producer accepts an optional metric Filter                                                                                                                    |          |    |      |     |        |      | -      |     |      |     |      |       |
 | The metric Reader implementation supports registering metric Filter and passing them  its registered metric Producers                                                  |          |    |      |     |        |      | -      |     |      |     |      |       |
 | The metric SDK's metric Producer implementations uses the metric Filter                                                                                                |          |    |      |     |        |      | -      |     |      |     |      |       |

diff --git a/specification/baggage/api.md b/specification/baggage/api.md
@@ -35,6 +35,32 @@ with _exactly one value_. This is more restrictive than the [W3C Baggage
 Specification, § 3.2.1.1](https://www.w3.org/TR/baggage/#baggage-string)
 which allows duplicate entries for a given name.
 
+Baggage **names** are any valid UTF-8 strings. Language API SHOULD NOT
+restrict which strings are used as baggage **names**. However, the
+specific `Propagator`s that are used to transmit baggage entries across
+component boundaries may impose their own restrictions on baggage names.
+For example, the [W3C Baggage specification](https://www.w3.org/TR/baggage/#key)
+restricts the baggage keys to strings that satisfy the `token` definition
+from [RFC7230, Section 3.2.6](https://tools.ietf.org/html/rfc7230#section-3.2.6).
+For maximum compatibility, alpha-numeric names are strongly recommended
+to be used as baggage names.
+
+Baggage **values** are any valid UTF-8 strings. Language API MUST accept
+any valid UTF-8 string as baggage **value** in `Set` and return the same
+value from `Get`.
+
+Language API MUST treat both baggage names and values as case sensitive.
+See also [W3C Baggage Rationale](https://github.com/w3c/baggage/blob/main/baggage/HTTP_HEADER_FORMAT_RATIONALE.md#case-sensitivity-of-keys).
+
+Example:
+
+```
+baggage.Set('a', 'B% 💼');
+baggage.Set('A', 'c');
+baggage.Get('a'); // returns "B% 💼"
+baggage.Get('A'); // returns "c"
+```
+
 The Baggage API consists of:
 
 - the `Baggage` as a logical container

diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md
@@ -46,9 +46,6 @@ graph TD
 
 `Logger`s can be accessed with a `LoggerProvider`.
 
-In implementations of the API, the `LoggerProvider` is expected to be the stateful
-object that holds any configuration.
-
 Normally, the `LoggerProvider` is expected to be accessed from a central place.
 Thus, the API SHOULD provide a way to set/register and access a global default
 `LoggerProvider`.

diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md
@@ -442,13 +442,15 @@ is optional.
 
 ### Field: `Attributes`
 
-Type: `map<string, any>`.
+Type: [`map<string, any>`](#type-mapstring-any).
 
 Description: Additional information about the specific event occurrence. Unlike
 the `Resource` field, which is fixed for a particular source, `Attributes` can
 vary for each occurrence of the event coming from the same source. Can contain
-information about the request context (other than TraceId/SpanId). SHOULD follow
-OpenTelemetry [semantic conventions for attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md).
+information about the request context (other than [Trace Context Fields](#trace-context-fields)).
+The log attribute model MUST support [`any` type](#type-any),
+a superset of [standard Attribute](../common/README.md#attribute),
+to preserve the semantics of structured attributes emitted by the applications.
 This field is optional.
 
 #### Errors and Exceptions

diff --git a/specification/metrics/api.md b/specification/metrics/api.md
@@ -103,9 +103,6 @@ the metrics API:
 
 `Meter`s can be accessed with a `MeterProvider`.
 
-In implementations of the API, the `MeterProvider` is expected to be the
-stateful object that holds any configuration.
-
 Normally, the `MeterProvider` is expected to be accessed from a central place.
 Thus, the API SHOULD provide a way to set/register and access a global default
 `MeterProvider`.
@@ -599,9 +596,9 @@ language idiomatic name(s), for example `CreateUInt64ObservableCounter`,
 `CreateDoubleObservableCounter`, `CreateObservableCounter<UInt64>`,
 `CreateObservableCounter<double>`.
 
-It is highly recommended that implementations use the name `ObservableCounter`
-(or any language idiomatic variation, e.g. `observable_counter`) unless there is
-a strong reason not to do so. Please note that the name has nothing to do with
+It is highly recommended that the name `ObservableCounter` (or any language
+idiomatic variation, e.g. `observable_counter`) be used unless there is a
+strong reason not to do so. Please note that the name has nothing to do with
 [asynchronous
 pattern](https://en.wikipedia.org/wiki/Asynchronous_method_invocation) and
 [observer pattern](https://en.wikipedia.org/wiki/Observer_pattern).
@@ -922,9 +919,9 @@ idiomatic name(s), for example `CreateUInt64ObservableGauge`,
 `CreateDoubleObservableGauge`, `CreateObservableGauge<UInt64>`,
 `CreateObservableGauge<double>`.
 
-It is highly recommended that implementations use the name `ObservableGauge`
-(or any language idiomatic variation, e.g. `observable_gauge`) unless there is
-a strong reason not to do so. Please note that the name has nothing to do with
+It is highly recommended that the name `ObservableGauge` (or any language
+idiomatic variation, e.g. `observable_gauge`) be used unless there is a strong
+reason not to do so. Please note that the name has nothing to do with
 [asynchronous
 pattern](https://en.wikipedia.org/wiki/Asynchronous_method_invocation) and
 [observer pattern](https://en.wikipedia.org/wiki/Observer_pattern).
@@ -1165,10 +1162,10 @@ decide the language idiomatic name(s), for example
 `CreateObservableUpDownCounter<UInt64>`,
 `CreateObservableUpDownCounter<double>`.
 
-It is highly recommended that implementations use the name
-`ObservableUpDownCounter` (or any language idiomatic variation, e.g.
-`observable_up_down_counter`) unless there is a strong reason not to do so. Please
-note that the name has nothing to do with [asynchronous
+It is highly recommended that the name `ObservableUpDownCounter` (or any
+language idiomatic variation, e.g. `observable_up_down_counter`) be used unless
+there is a strong reason not to do so. Please note that the name has nothing to
+do with [asynchronous
 pattern](https://en.wikipedia.org/wiki/Asynchronous_method_invocation) and
 [observer pattern](https://en.wikipedia.org/wiki/Observer_pattern).
 

diff --git a/specification/metrics/data-model.md b/specification/metrics/data-model.md
@@ -23,7 +23,7 @@ aliases: [/docs/reference/specification/metrics/datamodel]
     + [OpenTelemetry Protocol data model: Producer recommendations](#opentelemetry-protocol-data-model-producer-recommendations)
     + [OpenTelemetry Protocol data model: Consumer recommendations](#opentelemetry-protocol-data-model-consumer-recommendations)
     + [Point kinds](#point-kinds)
-- [Metric points](#metric-points)
+- [Metric Points](#metric-points)
   * [Sums](#sums)
   * [Gauge](#gauge)
   * [Histogram](#histogram)
@@ -381,10 +381,15 @@ designed for compatibility with existing metric formats.
 
 - [Summary](#summary-legacy)
 
-## Metric points
+## Metric Points
 
 **Status**: [Stable](../document-status.md)
 
+Metric points are the basic building blocks of metrics. Depending on the [point
+kind](#point-kinds), a metric point may have different fields. The following
+sections describe the fields for each point kind and how these points form
+metrics.
+
 ### Sums
 
 [Sum](https://github.com/open-telemetry/opentelemetry-proto/blob/v0.9.0/opentelemetry/proto/metrics/v1/metrics.proto#L230)s