Rename built-in ExemplarFilters (#2919)

CHANGELOG.md

@@ -16,6 +16,9 @@ release.
 
 ### Metrics
 
+- Rename built-in ExemplarFilters to AlwaysOn, AlwaysOff and TraceBased.
+  ([#2919](https://github.com/open-telemetry/opentelemetry-specification/pull/2919))
+
 ### Logs
 
 ### Resource
@@ -28,6 +31,10 @@ release.
 
 ### SDK Configuration
 
+- Rename knowns values for "OTEL_METRICS_EXEMPLAR_FILTER" to "always_on",
+  "always_off" and "trace_based".
+  ([#2919](https://github.com/open-telemetry/opentelemetry-specification/pull/2919))
+
 ### Telemetry Schemas
 
 ### Common

specification/metrics/sdk.md

@@ -33,6 +33,10 @@ linkTitle: SDK
 - [Attribute limits](#attribute-limits)
 - [Exemplar](#exemplar)
   * [ExemplarFilter](#exemplarfilter)
+  * [Built-in ExemplarFilters](#built-in-exemplarfilters)
+    + [AlwaysOn](#alwayson)
+    + [AlwaysOff](#alwaysoff)
+    + [TraceBased](#tracebased)
   * [ExemplarReservoir](#exemplarreservoir)
   * [Exemplar defaults](#exemplar-defaults)
 - [MetricReader](#metricreader)
@@ -651,7 +655,9 @@ A Metric SDK SHOULD provide extensible hooks for Exemplar sampling, specifically
 ### ExemplarFilter
 
 The `ExemplarFilter` interface MUST provide a method to determine if a
-measurement should be sampled.
+measurement should be sampled. Sampled here simply makes the measurement
+eligible for being included as an exemplar. `ExemplarReservoir` makes the final
+decision if a measurement becomes an exemplar.
 
 This interface SHOULD have access to:
 
@@ -662,8 +668,24 @@ This interface SHOULD have access to:
   [Span](../trace/api.md#span).
 - A `timestamp` that best represents when the measurement was taken.
 
-See [Defaults and Configuration](#defaults-and-configuration) for built-in
-filters.
+### Built-in ExemplarFilters
+
+OpenTelemetry supports a number of built-in exemplar filters to choose from.
+The default is `TraceBased`.
+
+#### AlwaysOn
+
+An ExemplarFilter which makes all measurements eligible for being an Exemplar.
+
+#### AlwaysOff
+
+An ExemplarFilter which makes no measurements eligible for being an Exemplar.
+Using this ExemplarFilter is as good as disabling Exemplar feature.
+
+#### TraceBased
+
+An ExemplarFilter which makes those measurements eligible for being an
+Exemplar, which are recorded in the context of a sampled parent span.
 
 ### ExemplarReservoir
 

specification/sdk-environment-variables.md

@@ -294,9 +294,9 @@ Known values for `OTEL_LOGS_EXPORTER` are:
 
 Known values for `OTEL_METRICS_EXEMPLAR_FILTER` are:
 
-- `"none"`: No measurements are eligible for exemplar sampling.
-- `"all"`: All measurements are eligible for exemplar sampling.
-- `"with_sampled_trace"`: Only allow measurements with a sampled parent span in context.
+- `"always_on"`: [AlwaysOn](./metrics/sdk.md#alwayson)
+- `"always_off"`: [AlwaysOff](./metrics/sdk.md#alwaysoff)
+- `"trace_based"`: [TraceBased](./metrics/sdk.md#tracebased)
 
 ### Periodic exporting MetricReader