diff --git a/CHANGELOG.md b/CHANGELOG.md index 2181cdc6bec..fdbee8bab21 100644 --- a/CHANGELOG.md +++ b/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)) diff --git a/specification/configuration/file-configuration.md b/specification/configuration/file-configuration.md index 148d1b1e637..5e8739094c4 100644 --- a/specification/configuration/file-configuration.md +++ b/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 +\$\{(?[^}]+)\} +``` + 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: diff --git a/specification/metrics/api.md b/specification/metrics/api.md index 3a857307940..3eafb13776f 100644 --- a/specification/metrics/api.md +++ b/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) @@ -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) diff --git a/specification/metrics/data-model.md b/specification/metrics/data-model.md index a66a754e1a5..f6a283c2e28 100644 --- a/specification/metrics/data-model.md +++ b/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) @@ -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 diff --git a/specification/metrics/noop.md b/specification/metrics/noop.md index ebd08e4fc36..15fe126b18c 100644 --- a/specification/metrics/noop.md +++ b/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) @@ -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) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 9c9a48bd85b..791457cd6ab 100644 --- a/specification/metrics/sdk.md +++ b/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) @@ -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) diff --git a/specification/metrics/sdk_exporters/otlp.md b/specification/metrics/sdk_exporters/otlp.md index 545c63e3a81..86719ea22f7 100644 --- a/specification/metrics/sdk_exporters/otlp.md +++ b/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)