[SDK] Support MeterConfigurator updates and example

CHANGELOG.md

@@ -72,6 +72,11 @@ Increment the:
   [#4573](https://github.com/open-telemetry/opentelemetry-cpp/pull/4573)
 * [API] Remove regex from trace_state.h
   [#4570](https://github.com/open-telemetry/opentelemetry-cpp/pull/4570)
+* [SDK] Add `MeterProvider::UpdateMeterConfigurator()` and example. Instruments
+  observe the enabled state of the Meter that created them, so they do not
+  have to be recreated. Data recorded before a Meter is disabled is still
+  exported
+  [#4313](https://github.com/open-telemetry/opentelemetry-cpp/pull/4313)
 
 * [API] `TraceState::Set` now overwrites an entry with the same key, and
  `TraceState::FromHeader` discards duplicate keys.

examples/CMakeLists.txt

@@ -29,6 +29,7 @@ add_subdirectory(multi_processor)
 add_subdirectory(environment_carrier)
 add_subdirectory(tracer_configurator)
 add_subdirectory(logger_configurator)
+add_subdirectory(meter_configurator)
 add_subdirectory(explicit_parent)
 
 if(OTELCPP_WITH_EXAMPLES_HTTP)

examples/logger_configurator/main.cc

@@ -28,8 +28,6 @@
 #include <thread>
 #include <utility>
 
-#include <string>
-#include <vector>
 #include "opentelemetry/sdk/logs/exporter.h"
 #include "opentelemetry/sdk/logs/processor.h"
 

examples/meter_configurator/BUILD

@@ -0,0 +1,20 @@
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+load("@rules_cc//cc:cc_test.bzl", "cc_test")
+
+cc_test(
+    name = "example_meter_configurator",
+    srcs = [
+        "main.cc",
+    ],
+    tags = [
+        "ostream",
+        "tested_example",
+    ],
+    deps = [
+        "//api",
+        "//exporters/ostream:ostream_metric_exporter",
+        "//sdk/src/metrics",
+    ],
+)

examples/meter_configurator/CMakeLists.txt

@@ -0,0 +1,13 @@
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+add_executable(example_meter_configurator main.cc)
+target_link_libraries(
+  example_meter_configurator
+  PRIVATE opentelemetry-cpp::metrics
+          opentelemetry-cpp::ostream_metrics_exporter)
+
+if(BUILD_TESTING)
+  add_test(NAME examples.meter_configurator
+           COMMAND "$<TARGET_FILE:example_meter_configurator>")
+endif()

examples/meter_configurator/README.md

@@ -0,0 +1,291 @@
+# Meter Configurator Example
+
+This example demonstrates how to set a `MeterConfigurator` on construction
+of the `MeterProvider` and to update it at runtime using
+`MeterProvider::UpdateMeterConfigurator` to enable or disable specific
+meters without restarting the application or recreating the meters.
+
+`MeterProvider::UpdateMeterConfigurator` recomputes and applies a new
+`MeterConfig` to all existing meters, and the updated configurator is also
+used for meters created afterwards. It is safe to call concurrently with
+`MeterProvider::GetMeter` and with instrument creation and recording on
+existing meters.
+
+Three meters with unique instrumentation scope names are used to simulate
+a user application:
+
+- `my_application`: simulated user application
+- `my_library`: simulated user library
+- `external_library`: simulated external third-party library
+
+The example walks through a simulated cost management and debugging
+workflow in four stages:
+
+- Stage 1: Startup. All meters are enabled and all three scopes report
+  metrics.
+- Stage 2: Steady state. The noisy `external_library` metrics are not
+  needed, so its meter is disabled.
+- Stage 3: A user reports unexpected behavior. Re-enable the
+  `external_library` meter to investigate.
+- Stage 4: The investigation completes and the `external_library` meter is
+  disabled again.
+
+Instruments observe the enabled state of the meter that created them, so
+they do not need to be recreated after a configurator update. An instrument
+created while its meter is disabled starts recording once the meter is
+enabled, and stops again when the meter is disabled. This matters for
+third-party instrumentation, which an application cannot force to rebuild
+its instruments.
+
+When a meter is disabled, new measurements are dropped and its asynchronous
+callbacks are not called. Anything recorded before it was disabled is still
+exported.
+
+This example uses cumulative temporality, so while `external_library` is
+disabled it keeps reporting its last total (`1` in stage 2, `2` in stage 4).
+The measurement made during stage 2 is dropped, which is why stage 3 reports
+`2` and not `3`.
+
+## Build and run
+
+```sh
+~/build/examples/meter_configurator/example_meter_configurator
+```
+
+**Expected output:**
+
+Metrics are exported to stdout via the `OStreamMetricExporter`. The example
+calls `ForceFlush` at the end of each stage. The periodic reader also
+collects once when it starts, so the exact number and ordering of exported
+batches varies between runs; the transcript below shows one run and is not
+an exact expected output.
+
+```sh
+Stage 1: startup, all meters enabled
+  my_application, my_library and external_library report metrics
+{
+  scope name    : my_application
+  schema url    :
+  version       :
+  start time    : Mon Jul 27 09:32:35 2026
+  end time      : Mon Jul 27 09:32:35 2026
+  instrument name       : my_application.work_items
+  description   : Work items processed by the application
+  unit          : {item}
+  type          : SumPointData
+  value         : 1
+  attributes            :
+  resources     :
+        service.name: meter_configurator_example
+        telemetry.sdk.language: cpp
+        telemetry.sdk.name: opentelemetry
+        telemetry.sdk.version: 1.29.0-dev
+}
+{
+  scope name    : my_library
+  schema url    :
+  version       :
+  start time    : Mon Jul 27 09:32:35 2026
+  end time      : Mon Jul 27 09:32:35 2026
+  instrument name       : my_library.calls
+  description   : Calls into the library
+  unit          : {call}
+  type          : SumPointData
+  value         : 1
+  attributes            :
+  resources     :
+        service.name: meter_configurator_example
+        telemetry.sdk.language: cpp
+        telemetry.sdk.name: opentelemetry
+        telemetry.sdk.version: 1.29.0-dev
+}
+{
+  scope name    : external_library
+  schema url    :
+  version       :
+  start time    : Mon Jul 27 09:32:35 2026
+  end time      : Mon Jul 27 09:32:35 2026
+  instrument name       : external_library.requests
+  description   : Requests handled by the external library
+  unit          : {request}
+  type          : SumPointData
+  value         : 1
+  attributes            :
+  resources     :
+        service.name: meter_configurator_example
+        telemetry.sdk.language: cpp
+        telemetry.sdk.name: opentelemetry
+        telemetry.sdk.version: 1.29.0-dev
+}
+
+Stage 2: steady state, external_library meter disabled
+  external_library stops recording, its last value is still reported
+{
+  scope name    : my_application
+  schema url    :
+  version       :
+  start time    : Mon Jul 27 09:32:35 2026
+  end time      : Mon Jul 27 09:32:35 2026
+  instrument name       : my_application.work_items
+  description   : Work items processed by the application
+  unit          : {item}
+  type          : SumPointData
+  value         : 2
+  attributes            :
+  resources     :
+        service.name: meter_configurator_example
+        telemetry.sdk.language: cpp
+        telemetry.sdk.name: opentelemetry
+        telemetry.sdk.version: 1.29.0-dev
+}
+{
+  scope name    : my_library
+  schema url    :
+  version       :
+  start time    : Mon Jul 27 09:32:35 2026
+  end time      : Mon Jul 27 09:32:35 2026
+  instrument name       : my_library.calls
+  description   : Calls into the library
+  unit          : {call}
+  type          : SumPointData
+  value         : 2
+  attributes            :
+  resources     :
+        service.name: meter_configurator_example
+        telemetry.sdk.language: cpp
+        telemetry.sdk.name: opentelemetry
+        telemetry.sdk.version: 1.29.0-dev
+}
+{
+  scope name    : external_library
+  schema url    :
+  version       :
+  start time    : Mon Jul 27 09:32:35 2026
+  end time      : Mon Jul 27 09:32:35 2026
+  instrument name       : external_library.requests
+  description   : Requests handled by the external library
+  unit          : {request}
+  type          : SumPointData
+  value         : 1
+  attributes            :
+  resources     :
+        service.name: meter_configurator_example
+        telemetry.sdk.language: cpp
+        telemetry.sdk.name: opentelemetry
+        telemetry.sdk.version: 1.29.0-dev
+}
+
+Stage 3: investigating, external_library meter re-enabled
+  external_library records again
+{
+  scope name    : my_application
+  schema url    :
+  version       :
+  start time    : Mon Jul 27 09:32:35 2026
+  end time      : Mon Jul 27 09:32:35 2026
+  instrument name       : my_application.work_items
+  description   : Work items processed by the application
+  unit          : {item}
+  type          : SumPointData
+  value         : 3
+  attributes            :
+  resources     :
+        service.name: meter_configurator_example
+        telemetry.sdk.language: cpp
+        telemetry.sdk.name: opentelemetry
+        telemetry.sdk.version: 1.29.0-dev
+}
+{
+  scope name    : my_library
+  schema url    :
+  version       :
+  start time    : Mon Jul 27 09:32:35 2026
+  end time      : Mon Jul 27 09:32:35 2026
+  instrument name       : my_library.calls
+  description   : Calls into the library
+  unit          : {call}
+  type          : SumPointData
+  value         : 3
+  attributes            :
+  resources     :
+        service.name: meter_configurator_example
+        telemetry.sdk.language: cpp
+        telemetry.sdk.name: opentelemetry
+        telemetry.sdk.version: 1.29.0-dev
+}
+{
+  scope name    : external_library
+  schema url    :
+  version       :
+  start time    : Mon Jul 27 09:32:35 2026
+  end time      : Mon Jul 27 09:32:35 2026
+  instrument name       : external_library.requests
+  description   : Requests handled by the external library
+  unit          : {request}
+  type          : SumPointData
+  value         : 2
+  attributes            :
+  resources     :
+        service.name: meter_configurator_example
+        telemetry.sdk.language: cpp
+        telemetry.sdk.name: opentelemetry
+        telemetry.sdk.version: 1.29.0-dev
+}
+
+Stage 4: investigation complete, external_library meter disabled again
+  external_library stops recording, its last value is still reported
+{
+  scope name    : my_application
+  schema url    :
+  version       :
+  start time    : Mon Jul 27 09:32:35 2026
+  end time      : Mon Jul 27 09:32:35 2026
+  instrument name       : my_application.work_items
+  description   : Work items processed by the application
+  unit          : {item}
+  type          : SumPointData
+  value         : 4
+  attributes            :
+  resources     :
+        service.name: meter_configurator_example
+        telemetry.sdk.language: cpp
+        telemetry.sdk.name: opentelemetry
+        telemetry.sdk.version: 1.29.0-dev
+}
+{
+  scope name    : my_library
+  schema url    :
+  version       :
+  start time    : Mon Jul 27 09:32:35 2026
+  end time      : Mon Jul 27 09:32:35 2026
+  instrument name       : my_library.calls
+  description   : Calls into the library
+  unit          : {call}
+  type          : SumPointData
+  value         : 4
+  attributes            :
+  resources     :
+        service.name: meter_configurator_example
+        telemetry.sdk.language: cpp
+        telemetry.sdk.name: opentelemetry
+        telemetry.sdk.version: 1.29.0-dev
+}
+{
+  scope name    : external_library
+  schema url    :
+  version       :
+  start time    : Mon Jul 27 09:32:35 2026
+  end time      : Mon Jul 27 09:32:35 2026
+  instrument name       : external_library.requests
+  description   : Requests handled by the external library
+  unit          : {request}
+  type          : SumPointData
+  value         : 2
+  attributes            :
+  resources     :
+        service.name: meter_configurator_example
+        telemetry.sdk.language: cpp
+        telemetry.sdk.name: opentelemetry
+        telemetry.sdk.version: 1.29.0-dev
+}
+```