Merge branch 'main' into log-clone

CHANGELOG.md

@@ -11,8 +11,19 @@ release.
 
 ### Traces
 
+- Remove restriction that sampler description is immutable.
+  ([#4137](https://github.com/open-telemetry/opentelemetry-specification/pull/4137))
+
 ### Metrics
 
+- Clarify prometheus exporter should have `host` and `port` configuration options.
+  ([#4147](https://github.com/open-telemetry/opentelemetry-specification/pull/4147))
+- Clarify metric reader / metric exporter relationship for temporality
+  preference and default aggregation. Explicitly define configuration options
+  for temporality preference and default aggregation of built-in exporters, and
+  make default values explicit.
+  ([#4142](https://github.com/open-telemetry/opentelemetry-specification/pull/4142))
+
 ### Logs
 
 - The SDK MAY provide an operation that makes a deep clone of a `ReadWriteLogRecord`.

specification/logs/event-api.md

@@ -47,9 +47,10 @@ logs to have a common format within that structure. When OpenTelemetry
 instrumentation emits logs, those logs SHOULD be formatted as Events. All
 semantic conventions defined for logs MUST be formatted as Events.
 
-The Event format is as follows. All Events have a `name` attribute, and all
-Events with the same `name` MUST conform to the same schema for both their
-`Attributes` and their `Body`.
+The Event format is as follows. All Events have a
+[`event.name` attribute](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md),
+and all Events with the same `event.name` MUST conform to the same schema for
+both their `Attributes` and their `Body`.
 
 ## Event API use cases
 

specification/metrics/sdk.md

@@ -1221,12 +1221,12 @@ determines the following capabilities:
 * Handling the [ForceFlush](#forceflush) and [Shutdown](#shutdown) signals from
   the SDK.
 
-To construct a `MetricReader` when setting up an SDK, the caller
-SHOULD provide at least the following:
+To construct a `MetricReader` when setting up an SDK, at least the following
+SHOULD be provided:
 
 * The `exporter` to use, which is a `MetricExporter` instance.
-* The default output `aggregation` (optional), a function of instrument kind.  If not configured, the [default aggregation](#default-aggregation) SHOULD be used.
-* The default output `temporality` (optional), a function of instrument kind.  If not configured, the Cumulative temporality SHOULD be used.
+* The default output `aggregation` (optional), a function of instrument kind. This function SHOULD be obtained from the `exporter`. If not configured, the [default aggregation](#default-aggregation) SHOULD be used.
+* The output `temporality` (optional), a function of instrument kind. This function SHOULD be obtained from the `exporter`. If not configured, the Cumulative temporality SHOULD be used.
 * **Status**: [Development](../document-status.md) - The default aggregation cardinality limit to use, a function of instrument kind.  If not configured, a default value of 2000 SHOULD be used.
 * **Status**: [Development](../document-status.md) - The [MetricFilter](#metricfilter) to apply to metrics and attributes during `MetricReader#Collect`.
 * Zero of more [MetricProducer](#metricproducer)s (optional) to collect metrics from in addition to metrics from the SDK.

specification/metrics/sdk_exporters/in-memory.md

@@ -10,8 +10,15 @@ In-memory Metrics Exporter is a [Push Metric
 Exporter](../sdk.md#push-metric-exporter) which accumulates metrics data in the
 local memory and allows to inspect it (useful for e.g. unit tests).
 
-In-memory Metrics Exporter MUST support both Cumulative and Delta
-[Temporality](../data-model.md#temporality).
+In-memory Metrics Exporter MUST provide configuration to set
+the [MetricReader](../sdk.md#metricreader) output `temporality` as a function of
+instrument kind. This option MAY be named `temporality`, and MUST set
+temporality to Cumulative for all instrument kinds by default.
+
+In-memory Metrics Exporter MAY provide configuration to set
+the [MetricReader](../sdk.md#metricreader) default `aggregation` as a function
+of instrument kind. This option MAY be named `default_aggregation`, and MUST use
+the [default aggregation](../sdk.md#default-aggregation) by default.
 
 If a language provides a mechanism to automatically configure a
 [MetricReader](../sdk.md#metricreader) to pair with the associated

specification/metrics/sdk_exporters/otlp.md

@@ -12,8 +12,15 @@ OTLP Metrics Exporter is a [Push Metric
 Exporter](../sdk.md#push-metric-exporter) which sends metrics via the
 [OpenTelemetry Protocol](../../protocol/README.md).
 
-OTLP Metrics Exporter MUST support both Cumulative and Delta
-[Aggregation Temporality](../data-model.md#temporality).
+OTLP Metrics Exporter MUST provide configuration to influence
+the [MetricReader](../sdk.md#metricreader) output `temporality` as a function of
+instrument kind. This option MAY be named `temporality`, and MUST set
+temporality preference to Cumulative for all instrument kinds by default.
+
+OTLP Metrics Exporter MUST provide configuration to influence
+the [MetricReader](../sdk.md#metricreader) default `aggregation` as a function
+of instrument kind. This option MAY be named `default_aggregation`, and MUST set
+the [default aggregation](../sdk.md#default-aggregation) for all instrument kinds by default.
 
 The exporter MUST provide configuration according to the [OpenTelemetry Protocol
 Exporter](../../protocol/exporter.md) specification.
@@ -33,12 +40,12 @@ then by default:
 * The exporter MUST configure the default aggregation on the basis of instrument kind using
   the `OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION` variable as described below if it is implemented.
 
-## Additional Configuration
+## Additional Environment Variable Configuration
 
-| Name                                                       | Description                                                         | Default                     |
-|------------------------------------------------------------|---------------------------------------------------------------------|-----------------------------|
-| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE`        | The aggregation temporality to use on the basis of instrument kind. | `cumulative`                |
-| `OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION` | The default aggregation to use for histogram instruments.           | `explicit_bucket_histogram` |
+| Name                                                       | Description                                                                                            | Default                     |
+|------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|-----------------------------|
+| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE`        | Configure the exporter's aggregation `temporality` option (see above) on the basis of instrument kind. | `cumulative`                |
+| `OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION` | Configure the exporter's `default_aggregation` option (see above) for Histogram instrument kind.   | `explicit_bucket_histogram` |
 
 The recognized (case-insensitive) values for `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` are:
 

specification/metrics/sdk_exporters/prometheus.md

@@ -38,8 +38,25 @@ A Prometheus Exporter for an OpenTelemetry metrics SDK MUST NOT add
 There MUST be at most one `target` info metric exposed by an SDK
 Prometheus exporter.
 
+A Prometheus Exporter MUST set
+the [MetricReader](../sdk.md#metricreader) `temporality` as a function of
+instrument kind to be `cumulative` for all instrument kinds.
+
 ## Configuration
 
+A Prometheus Exporter SHOULD support a configuration option to set the host
+that metrics are served on. The option MAY be named `host`, and MUST be `localhost`
+by default.
+
+A Prometheus Exporter SHOULD support a configuration option to set the port
+that metrics are served on. The option MAY be named `port`, and MUST be `9464` by
+default.
+
+A Prometheus Exporter SHOULD support a configuration option to set
+the [MetricReader](../sdk.md#metricreader) default `aggregation` as a function
+of instrument kind. This option MAY be named `default_aggregation`, and MUST use
+the [default aggregation](../sdk.md#default-aggregation) by default.
+
 A Prometheus Exporter MAY offer configuration to add resource attributes as metric attributes.
 By default, it MUST NOT add any resource attributes as metric attributes.
 The configuration SHOULD allow the user to select which resource attributes to copy (e.g.

specification/metrics/sdk_exporters/stdout.md

@@ -14,8 +14,15 @@ stdout/console.
 name for their language. For example, ConsoleExporter, StdoutExporter,
 StreamExporter, etc.
 
-"Standard output" Metrics Exporter MUST support both Cumulative and Delta
-[Temporality](../data-model.md#temporality).
+"Standard output" Metrics Exporter MUST provide configuration to set
+the [MetricReader](../sdk.md#metricreader) output `temporality` as a function of
+instrument kind. This option MAY be named `temporality`, and MUST set
+temporality to Cumulative for all instrument kinds by default.
+
+"Standard output" Metrics Exporter MAY provide configuration to set
+the [MetricReader](../sdk.md#metricreader) default `aggregation` as a function
+of instrument kind. This option MAY be named `default_aggregation`, and MUST use
+the [default aggregation](../sdk.md#default-aggregation) by default.
 
 If a language provides a mechanism to automatically configure a
 [MetricReader](../sdk.md#metricreader) to pair with the associated

specification/overview.md

@@ -287,8 +287,7 @@ information.
 #### Views
 
 [Views](metrics/sdk.md#view) are configurations that specify how the data from an `Instrument` should be processed,
-aggregated, and exported. They can be applied globally through the `MeterProvider` or more
-specifically at the `Meter` level. A `View` allows the customization of metric data beyond the default
+aggregated, and exported. They can be configured through the `MeterProvider`. A `View` allows the customization of metric data beyond the default
 collection behavior, enabling specific aggregations, transformations, and filtering of metrics.
 
 ## Log Signal

specification/trace/sdk.md

@@ -364,7 +364,9 @@ Returns the sampler name or short description with the configuration. This may
 be displayed on debug pages or in the logs. Example:
 `"TraceIdRatioBased{0.000100}"`.
 
-Description MUST NOT change over time and caller can cache the returned value.
+Description MAY change over time, for example, if the sampler supports dynamic
+configuration or otherwise adjusts its parameters.
+Callers SHOULD NOT cache the returned value.
 
 ### Built-in samplers