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

…y-specification into config-extension-components
open-telemetry · Jan 25, 2024 · 1e4f201 · 1e4f201
2 parents a31b3e8 + 703a0af
commit 1e4f201
Show file tree

Hide file tree

Showing 12 changed files with 127 additions and 48 deletions.
diff --git a/.markdown_link_check_config.json b/.markdown_link_check_config.json
@@ -10,7 +10,7 @@
       "replacement": "{{BASEURL}}/"
     },
     {
-      "pattern": "^https://github.com/open-telemetry/opentelemetry-specification/(blob|tree)/[^/]+/(specification|supplementary-guidelines)/",
+      "pattern": "^https://github.com/open-telemetry/opentelemetry-specification/(blob|tree)/main/(specification|supplementary-guidelines)/",
       "replacement": "LINK-CHECK-ERROR-USE-LOCAL-PATH-TO-DOC-PAGE-NOT-EXTERNAL-URL/"
     }
   ],

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,6 +13,44 @@ release.
 
 ### Metrics
 
+### Logs
+
+- Fix `Resource` field type in Logs Data Model.
+  ([#3826](https://github.com/open-telemetry/opentelemetry-specification/pull/3826))
+
+### Resource
+
+### OpenTelemetry Protocol
+
+### Compatibility
+
+### SDK Configuration
+
+- Add file configuration section to spec compliance matrix.
+  ([#3804](https://github.com/open-telemetry/opentelemetry-specification/pull/3804))
+
+### Common
+
+### Supplementary Guidelines
+
+## v1.29.0 (2024-01-10)
+
+### Context & Baggage
+
+- Align definition of Baggage with W3C Specification.
+  ([#3800](https://github.com/open-telemetry/opentelemetry-specification/pull/3800))
+
+### Traces
+
+- Update OpenTelemetry to Zipkin Transformation to handle attributes from older semantic conventions in a backwards compatible way.
+  ([#3794](https://github.com/open-telemetry/opentelemetry-specification/pull/3794))
+
+### Metrics
+
+- Define experimental MetricFilter as a mechanism to filter collected metrics by the MetricReader
+  ([#3566](https://github.com/open-telemetry/opentelemetry-specification/pull/3566))
+- Add optional configuration for Prometheus exporters to optionally remove unit and type suffixes.
+  ([#3777](https://github.com/open-telemetry/opentelemetry-specification/pull/3777))
 - Add optional configuration for Prometheus exporters to optionally drop `otel_scope_info` metric.
   ([#3796](https://github.com/open-telemetry/opentelemetry-specification/pull/3796))
 
@@ -22,10 +60,15 @@ release.
 
 ### OpenTelemetry Protocol
 
+- Use `TracesData`, `MetricsData` and `LogsData` proto messages for file exporter.
+
 ### Compatibility
 
 ### SDK Configuration
 
+- Define file configuration file format and env var substitution
+  ([#3744](https://github.com/open-telemetry/opentelemetry-specification/pull/3744))
+
 ### Common
 
 - Clarify that attribute keys are case-sensitive.
@@ -48,14 +91,10 @@ release.
 
 ### Metrics
 
-- Define experimental MetricFilter as a mechanism to filter collected metrics by the MetricReader
-  ([#3566](https://github.com/open-telemetry/opentelemetry-specification/pull/3566))
 - Add optional configuration for Prometheus exporters to promote resource attributes to metric attributes
   ([#3761](https://github.com/open-telemetry/opentelemetry-specification/pull/3761))
 - Clarifications and flexibility in Exemplar speicification.
   ([#3760](https://github.com/open-telemetry/opentelemetry-specification/pull/3760))
-- Add optional configuration for Prometheus exporters to optionally remove unit and type suffixes.
-  ([#3777](https://github.com/open-telemetry/opentelemetry-specification/pull/3777))
 
 ### Logs
 

diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md
@@ -284,7 +284,7 @@ Note: Support for environment variables is optional.
 | OTEL_LOG_LEVEL                                           | -   | -    | +   | [-][py1059] | +    | -      | +   |      | -   | -    | -     |
 | OTEL_PROPAGATORS                                         | -   | +    |     | +           | +    | +      | +   | -    | -   | -    | -     |
 | OTEL_BSP_*                                               | +   | +    | +   | +           | +    | +      | +   | +    | -   | +    | -     |
-| OTEL_BLRP_*                                              |     | +    |     |             |      |        |     |      |     | +    |       |
+| OTEL_BLRP_*                                              |     | +    |     |             |      |        |     | +    |     | +    |       |
 | OTEL_EXPORTER_OTLP_*                                     | +   | +    |     | +           | +    | +      | +   | +    | +   | +    | -     |
 | OTEL_EXPORTER_ZIPKIN_*                                   | -   | +    |     | +           | +    | -      | +   | -    | -   | +    | -     |
 | OTEL_TRACES_EXPORTER                                     | -   | +    | +   | +           | +    | +      | +   | -    | -   | -    |       |
@@ -308,6 +308,24 @@ Note: Support for environment variables is optional.
 | OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE        | -   | +    | +   | +           |      |        | +   |      |     | +    |       |
 | OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION |     | +    |     |             |      |        |     |      |     |      |       |
 
+## File Configuration
+
+See [File Configuration](./specification/configuration/file-configuration.md)
+for details.
+
+| Feature                                                          | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift |
+|------------------------------------------------------------------|----|------|----|--------|------|--------|-----|------|-----|------|-------|
+| `Parse` a configuration file                                     |    |      |    |        |      |        |     |      |     |      |       |
+| The `Parse` operation accepts the configuration YAML file format |    |      |    |        |      |        |     |      |     |      |       |
+| The `Parse` operation performs environment variable substitution |    |      |    |        |      |        |     |      |     |      |       |
+| The `Parse` operation returns configuration model                |    |      |    |        |      |        |     |      |     |      |       |
+| `Create` SDK components                                          |    |      |    |        |      |        |     |      |     |      |       |
+| The `Create` operation accepts configuration model               |    |      |    |        |      |        |     |      |     |      |       |
+| The `Create` operation returns `TracerProvider`                  |    |      |    |        |      |        |     |      |     |      |       |
+| The `Create` operation returns `MeterProvider`                   |    |      |    |        |      |        |     |      |     |      |       |
+| The `Create` operation returns `LoggerProvider`                  |    |      |    |        |      |        |     |      |     |      |       |
+| The `Create` operation returns `Propagators`                     |    |      |    |        |      |        |     |      |     |      |       |
+
 ## Exporters
 
 | Feature                                                                        | Optional | Go | Java | JS | Python      | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift |

diff --git a/specification/baggage/api.md b/specification/baggage/api.md
@@ -24,14 +24,20 @@
 
 ## Overview
 
-`Baggage` is used to annotate telemetry, adding context and information to
-metrics, traces, and logs. It is a set of name/value pairs describing
-user-defined properties. Each name in `Baggage` MUST be associated with
-exactly one value.
+`Baggage` is a set of application-defined properties contextually associated
+with a distributed request or workflow execution (see also the [W3C Baggage
+Specification][w3c]). Baggage can be used, among other things, to annotate
+telemetry, adding contextual information to metrics, traces, and logs.
+
+In OpenTelemetry `Baggage` is represented as a set of name/value pairs
+describing user-defined properties. Each name in `Baggage` MUST be associated
+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.
 
 The Baggage API consists of:
 
-- the `Baggage`
+- the `Baggage` as a logical container
 - functions to interact with the `Baggage` in a `Context`
 
 The functions described here are one way to approach interacting with the
@@ -146,7 +152,7 @@ reasons.
 
 The API layer or an extension package MUST include the following `Propagator`s:
 
-* A `TextMapPropagator` implementing the [W3C Baggage Specification](https://www.w3.org/TR/baggage).
+* A `TextMapPropagator` implementing the [W3C Baggage Specification][w3c].
 
 See [Propagators Distribution](../context/api-propagators.md#propagators-distribution)
 for how propagators are to be distributed.
@@ -165,3 +171,5 @@ additional requirements these operations need to follow.
 If a new name/value pair is added and its name is the same as an existing name,
 than the new pair MUST take precedence. The value is replaced with the added
 value (regardless if it is locally generated or received from a remote peer).
+
+[w3c]: https://www.w3.org/TR/baggage
diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md
@@ -415,7 +415,7 @@ source. This field is optional.
 
 ### Field: `Resource`
 
-Type: `map<string, any>`.
+Type: [Resource](../resource/sdk.md).
 
 Description: Describes the source of the log, aka
 [resource](../overview.md#resources). Multiple occurrences of events coming from

diff --git a/specification/metrics/api.md b/specification/metrics/api.md
@@ -132,19 +132,19 @@ This API MUST accept the following parameters:
   within that library or application.
 * `version`: Specifies the version of the instrumentation scope if the scope
   has a version (e.g. a library version). Example value: `1.0.0`.
-  
+
   Users can provide a `version`, but it is up to their discretion. Therefore,
   this API needs to be structured to accept a `version`, but MUST NOT obligate
   a user to provide one.
 * [since 1.4.0] `schema_url`: Specifies the Schema URL that should be recorded
   in the emitted telemetry.
-  
+
   Users can provide a `schema_url`, but it is up to their discretion.
   Therefore, this API needs to be structured to accept a `schema_url`, but MUST
   NOT obligate a user to provide one.
 * [since 1.13.0] `attributes`: Specifies the instrumentation scope attributes
   to associate with emitted telemetry.
-  
+
   Users can provide attributes to associate with the instrumentation scope, but
   it is up to their discretion. Therefore, this API MUST be structured to
   accept a variable number of attributes, including none.
@@ -308,32 +308,32 @@ pattern](https://en.wikipedia.org/wiki/Asynchronous_method_invocation).
 The API to construct synchronous instruments MUST accept the following parameters:
 
 * A `name` of the Instrument.
-  
+
   The `name` needs to be provided by a user. If possible, the API SHOULD be
   structured so a user is obligated to provide this parameter. If it is not
   possible to structurally enforce this obligation, the API MUST be documented
   in a way to communicate to users that this parameter is needed.
-  
+
   The API SHOULD be documented in a way to communicate to users that the `name`
   parameter needs to conform to the [instrument name
   syntax](#instrument-name-syntax). The API SHOULD NOT validate the `name`;
   that is left to implementations of the API.
 * A `unit` of measure.
-  
+
   Users can provide a `unit`, but it is up to their discretion. Therefore, this
   API needs to be structured to accept a `unit`, but MUST NOT obligate a user
   to provide one.
-  
+
   The `unit` parameter needs to support the [instrument unit
   rule](#instrument-unit). Meaning, the API MUST accept a case-sensitive string
   that supports ASCII character encoding and can hold at least 63 characters.
   The API SHOULD NOT validate the `unit`.
 * A `description` describing the Instrument in human-readable terms.
-  
+
   Users can provide a `description`, but it is up to their discretion.
   Therefore, this API needs to be structured to accept a `description`, but
   MUST NOT obligate a user to provide one.
-  
+
   The `description` needs to support the [instrument description
   rule](#instrument-description). Meaning, the API MUST accept a string that
   supports at least [BMP (Unicode Plane
@@ -361,32 +361,32 @@ order of callback execution is not specified.
 The API to construct asynchronous instruments MUST accept the following parameters:
 
 * A `name` of the Instrument.
-  
+
   The `name` needs to be provided by a user. If possible, the API SHOULD be
   structured so a user is obligated to provide this parameter. If it is not
   possible to structurally enforce this obligation, the API MUST be documented
   in a way to communicate to users that this parameter is needed.
-  
+
   The API SHOULD be documented in a way to communicate to users that the `name`
   parameter needs to conform to the [instrument name
   syntax](#instrument-name-syntax). The API SHOULD NOT validate the `name`,
   that is left to implementations of the API.
 * A `unit` of measure.
-  
+
   Users can provide a `unit`, but it is up to their discretion. Therefore, this
   API needs to be structured to accept a `unit`, but MUST NOT obligate a user
   to provide one.
-  
+
   The `unit` parameter needs to support the [instrument unit
   rule](#instrument-unit). Meaning, the API MUST accept a case-sensitive string
   that supports ASCII character encoding and can hold at least 63 characters.
   The API SHOULD NOT validate the `unit`.
 * A `description` describing the Instrument in human-readable terms.
-  
+
   Users can provide a `description`, but it is up to their discretion.
   Therefore, this API needs to be structured to accept a `description`, but
   MUST NOT obligate a user to provide one.
-  
+
   The `description` needs to support the [instrument description
   rule](#instrument-description). Meaning, the API MUST accept a string that
   supports at least [BMP (Unicode Plane
@@ -404,7 +404,7 @@ The API to construct asynchronous instruments MUST accept the following paramete
   The API SHOULD NOT validate `advisory` parameters.
 * `callback` functions that report [Measurements](#measurement) of the created
   instrument.
-  
+
   Users can provide `callback` functions, but it is up to their discretion.
   Therefore, this API MUST be structured to accept a variable number of
   `callback` functions, including none.
@@ -532,19 +532,19 @@ certain programming languages or systems, for example `null`, `undefined`).
 This API MUST accept the following parameter:
 
 * A numeric increment value.
-  
+
   The increment value needs to be provided by a user. If possible, this API
   SHOULD be structured so a user is obligated to provide this parameter. If it
   is not possible to structurally enforce this obligation, this API MUST be
   documented in a way to communicate to users that this parameter is needed.
-  
+
   The increment value is expected to be non-negative. This API SHOULD be
   documented in a way to communicate to users that this value is expected to be
   non-negative. This API SHOULD NOT validate this value, that is left to
   implementations of the API.
 * [Attributes](../common/README.md#attribute) to associate with the increment
   value.
-  
+
   Users can provide attributes to associate with the increment value, but it is
   up to their discretion. Therefore, this API MUST be structured to accept a
   variable number of attributes, including none.
@@ -579,7 +579,7 @@ counterPowerUsed.Add(200, new PowerConsumption { customer = "Jerry" }, ("is_gree
 ### Asynchronous Counter
 
 Asynchronous Counter is an [asynchronous Instrument](#asynchronous-instrument-api)
-which reports [monotonically](https://wikipedia.org/wiki/Monotonic_function)
+which reports [monotonically](https://en.wikipedia.org/wiki/Monotonic_function)
 increasing value(s) when the instrument is being observed.
 
 Example uses for Asynchronous Counter:
@@ -773,13 +773,13 @@ This API MUST accept the following parameter:
   structured so a user is obligated to provide this parameter. If it is not
   possible to structurally enforce this obligation, this API MUST be documented
   in a way to communicate to users that this parameter is needed.
-  
+
   The value is expected to be non-negative. This API SHOULD be documented in a
   way to communicate to users that this value is expected to be non-negative.
   This API SHOULD NOT validate this value, that is left to implementations of
   the API.
 * [Attributes](../common/README.md#attribute) to associate with the value.
-  
+
   Users can provide attributes to associate with the value, but it is up to
   their discretion. Therefore, this API MUST be structured to accept a variable
   number of attributes, including none.
@@ -1017,7 +1017,7 @@ class Device:
 supports increments and decrements.
 
 Note: if the value is
-[monotonically](https://wikipedia.org/wiki/Monotonic_function) increasing, use
+[monotonically](https://en.wikipedia.org/wiki/Monotonic_function) increasing, use
 [Counter](#counter) instead.
 
 Example uses for `UpDownCounter`:
@@ -1113,7 +1113,7 @@ This API MUST accept the following parameter:
   possible to structurally enforce this obligation, this API MUST be documented
   in a way to communicate to users that this parameter is needed.
 * [Attributes](../common/README.md#attribute) to associate with the value.
-  
+
   Users can provide attributes to associate with the value, but it is up to
   their discretion. Therefore, this API MUST be structured to accept a variable
   number of attributes, including none.
@@ -1146,7 +1146,7 @@ processes and sum them up, so we get the total heap usage) when the instrument
 is being observed.
 
 Note: if the value is
-[monotonically](https://wikipedia.org/wiki/Monotonic_function) increasing, use
+[monotonically](https://en.wikipedia.org/wiki/Monotonic_function) increasing, use
 [Asynchronous Counter](#asynchronous-counter) instead; if the value is
 non-additive, use [Asynchronous Gauge](#asynchronous-gauge) instead.
 

diff --git a/specification/protocol/README.md b/specification/protocol/README.md
@@ -4,8 +4,13 @@ linkTitle: Protocol
 
 # OpenTelemetry Protocol
 
-The OpenTelemetry protocol (OTLP) specification has moved to
-[github.com/open-telemetry/opentelemetry-proto/docs/README.md](https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/README.md).
+The OpenTelemetry protocol (OTLP) design goals, requirements, and
+[specification] have moved to
+[github.com/open-telemetry/opentelemetry-proto/docs](https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/).
+
+You can also view the specification from the OpenTelemetry website, see [OTLP][specification].
 
 For additional OTLP implementation requirements in the OpenTelemetry SDKs, see
 [SDK Exporter](exporter.md).
+
+[specification]: https://opentelemetry.io/docs/specs/otlp/
diff --git a/specification/protocol/design-goals.md b/specification/protocol/design-goals.md
@@ -1,5 +1,7 @@
 <!--- Hugo front matter used to generate the website version of this page:
 linkTitle: Design Goals
+redirect: https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/design-goals.md 301!
+manualLinkTarget: _blank
 --->
 
 # Design Goals for OpenTelemetry Wire Protocol

diff --git a/specification/protocol/file-exporter.md b/specification/protocol/file-exporter.md
@@ -48,7 +48,7 @@ This defines the first version of the serialization scheme.
 The data must be encoded according to the format specified in the
 [OTLP JSON Encoding](https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/specification.md#json-protobuf-encoding).
 
-Only top-level objects, `ExportTraceServiceRequest`, `ExportMetricsServiceRequest`, and `ExportLogsServiceRequest` are supported.
+Only top-level objects, `TracesData`, `MetricsData`, and `LogsData` are supported.
 
 Files must contain exactly one type of data: traces, metrics, or logs.
 

diff --git a/specification/protocol/otlp.md b/specification/protocol/otlp.md
@@ -1,8 +1,8 @@
 <!--- Hugo front matter used to generate the website version of this page:
 linkTitle: Specification
+redirect: /docs/specs/otlp/ 301!
 --->
 
 # OpenTelemetry Protocol Specification
 
-This page has moved to
-[github.com/open-telemetry/opentelemetry-proto/docs/specification.md](https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/specification.md).
+This page has moved to [OTLP](https://opentelemetry.io/docs/specs/otlp/).