Merge branch 'main' into file-config-example

CHANGELOG.md

@@ -19,6 +19,8 @@ release.
   ([#3837](https://github.com/open-telemetry/opentelemetry-specification/pull/3837))
 - Mark Exemplars as stable.
   ([#3870](https://github.com/open-telemetry/opentelemetry-specification/pull/3870))
+- Mark synchronous gauge as stable.
+  ([#4019](https://github.com/open-telemetry/opentelemetry-specification/pull/4019))
 
 ### Logs
 
@@ -37,6 +39,8 @@ release.
 
 - Clarify syntax for environment variable substitution regular expression
   ([#4001](https://github.com/open-telemetry/opentelemetry-specification/pull/4001))
+- Error out on invalid identifiers in environment variable substitution.
+  ([#4002](https://github.com/open-telemetry/opentelemetry-specification/pull/4002))
 - Add end to end examples for file configuration
   ([#4018](https://github.com/open-telemetry/opentelemetry-specification/pull/4018))
 

specification/configuration/file-configuration.md

@@ -91,6 +91,15 @@ more non line break characters (i.e. any character except `\n`). If a referenced
 environment variable is not defined and does not have a `DEFAULT_VALUE`, it MUST
 be replaced with an empty value.
 
+When parsing a configuration file that contains a reference not matching
+the references regular expression but does match the following PCRE2
+regular expression, the parser MUST return an empty result (no partial
+results are allowed) and an error describing the parse failure to the user.
+
+```regexp
+\$\{(?<INVALID_IDENTIFIER>[^}]+)\}
+```
+
 Node types MUST be interpreted after environment variable substitution takes
 place. This ensures the environment string representation of boolean, integer,
 or floating point fields can be properly converted to expected types.
@@ -128,6 +137,7 @@ string_key_with_default: ${UNDEFINED_KEY:-fallback}   # UNDEFINED_KEY is not def
 undefined_key: ${UNDEFINED_KEY}                       # Invalid reference, UNDEFINED_KEY is not defined and is replaced with ""
 ${STRING_VALUE}: value                                # Invalid reference, substitution is not valid in mapping keys and reference is ignored
 recursive_key: ${REPLACE_ME}                          # Valid reference to REPLACE_ME
+# invalid_identifier_key: ${STRING_VALUE:?error}      # If uncommented, this is an invalid identifier, it would fail to parse
 ```
 
 Environment variable substitution results in the following YAML:

specification/metrics/api.md

@@ -57,6 +57,7 @@ linkTitle: API
   * [Multiple-instrument callbacks](#multiple-instrument-callbacks)
 - [Compatibility requirements](#compatibility-requirements)
 - [Concurrency requirements](#concurrency-requirements)
+- [References](#references)
 
 <!-- tocstop -->
 
@@ -804,8 +805,6 @@ httpServerDuration.Record(100, new HttpRequestAttributes { method = "GET", schem
 
 ### Gauge
 
-**Status**: [Experimental](../document-status.md)
-
 `Gauge` is a [synchronous Instrument](#synchronous-instrument-api) which can be
 used to record non-additive value(s) (e.g. the background noise level - it makes
 no sense to record the background noise level value from multiple rooms and sum
@@ -1327,3 +1326,19 @@ specific guarantees and safeties.
 
 **Instrument** - All methods of any Instrument are safe to be called
 concurrently.
+
+## References
+
+- [OTEP0003 Consolidate pre-aggregated and raw metrics APIs](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0003-measure-metric-type.md)
+- [OTEP0008 Metrics observer specification](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0008-metric-observer.md)
+- [OTEP0009 Metric Handle API specification](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0009-metric-handles.md)
+- [OTEP0010 Rename "Cumulative" to "Counter" in the metrics API](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0010-cumulative-to-counter.md)
+- [OTEP0049 Metric `LabelSet` specification](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0049-metric-label-set.md)
+- [OTEP0070 Rename metric instrument Handles to "Bound Instruments"](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0070-metric-bound-instrument.md)
+- [OTEP0072 Metric observer specification (refinement)](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0072-metric-observer.md)
+- [OTEP0080 Remove the Metric API Gauge instrument](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0080-remove-metric-gauge.md)
+- [OTEP0088 Metric Instruments](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0088-metric-instrument-optional-refinements.md)
+- [OTEP0090 Remove the LabelSet object from the metrics API](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0090-remove-labelset-from-metrics-api.md)
+- [OTEP0098 Explain the metric instruments](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0098-metric-instruments-explained.md)
+- [OTEP0108 Metric instrument naming guidelines](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0108-naming-guidelines.md)
+- [OTEP0146 Scenarios for Metrics API/SDK Prototyping](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0146-metrics-prototype-scenarios.md)

specification/metrics/data-model.md

@@ -54,6 +54,7 @@ aliases: [/docs/reference/specification/metrics/datamodel]
   * [Sums: Delta-to-Cumulative](#sums-delta-to-cumulative)
     + [Sums: detecting alignment issues](#sums-detecting-alignment-issues)
     + [Sums: Missing Timestamps](#sums-missing-timestamps)
+- [References](#references)
 - [Footnotes](#footnotes)
 
 <!-- tocstop -->
@@ -1276,6 +1277,12 @@ For comparison, see the simple logic used in
 [statsd sums](https://github.com/statsd/statsd/blob/master/stats.js#L281)
 where all points are added, and lost points are ignored.
 
+## References
+
+- [OTEP0049 Metric `LabelSet` specification](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0049-metric-label-set.md)
+- [OTEP0113 Integrate Exemplars with Metrics](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0113-exemplars.md)
+- [OTEP0146 Scenarios for Metrics API/SDK Prototyping](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0146-metrics-prototype-scenarios.md)
+
 ## Footnotes
 
 \[1\] OTLP supports data point kinds that do not satisfy these conditions; they are

specification/metrics/noop.md

@@ -33,6 +33,7 @@ linkTitle: No-Op
   * [Asynchronous UpDownCounter Observations](#asynchronous-updowncounter-observations)
   * [Asynchronous Gauge](#asynchronous-gauge)
   * [Asynchronous Gauge Observations](#asynchronous-gauge-observations)
+- [References](#references)
 
 <!-- tocstop -->
 
@@ -263,3 +264,7 @@ concurrently.
 
 The No-Op Asynchronous Gauge MUST NOT validate or retain any state about
 observations made for the instrument.
+
+## References
+
+- [OTEP0146 Scenarios for Metrics API/SDK Prototyping](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0146-metrics-prototype-scenarios.md)

specification/metrics/sdk.md

@@ -84,6 +84,7 @@ linkTitle: SDK
 - [Numerical limits handling](#numerical-limits-handling)
 - [Compatibility requirements](#compatibility-requirements)
 - [Concurrency requirements](#concurrency-requirements)
+- [References](#references)
 
 <!-- tocstop -->
 
@@ -1775,3 +1776,9 @@ and `Shutdown` are safe to be called concurrently.
 
 **MetricExporter** - `ForceFlush` and `Shutdown` are safe to be called
 concurrently.
+
+## References
+
+- [OTEP0113 Integrate Exemplars with Metrics](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0113-exemplars.md)
+- [OTEP0126 A Proposal For SDK Support for Configurable Batching and Aggregations (Basic Views)](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0126-Configurable-Metric-Aggregations.md)
+- [OTEP0146 Scenarios for Metrics API/SDK Prototyping](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0146-metrics-prototype-scenarios.md)

specification/metrics/sdk_exporters/otlp.md

@@ -60,3 +60,7 @@ The recognized (case-insensitive) values for `OTEL_EXPORTER_OTLP_METRICS_DEFAULT
   Use [Explicit Bucket Histogram Aggregation](../sdk.md#explicit-bucket-histogram-aggregation).
 * `base2_exponential_bucket_histogram`:
   Use [Base2 Exponential Bucket Histogram Aggregation](../sdk.md#base2-exponential-bucket-histogram-aggregation).
+
+## References
+
+- [OTEP0131 OTLP Exporters Configurable Export Behavior](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0131-otlp-export-behavior.md)