docs: Add an example for preferred temporality and aggregation for metric reader (#2832)

* example

* remove test

* comments

* docs

* docs

* seconds

Author: lzchen

docs/examples/metrics/README.rst renamed to docs/examples/metrics/instruments/README.rst

@@ -0,0 +1,34 @@
+MetricReader configuration scenarios
+====================================
+
+These examples show how to customize the metrics that are output by the SDK using configuration on metric readers. There are multiple examples:
+
+* preferred_aggregation.py: Shows how to configure the preferred aggregation for metric instrument types.
+* preferred_temporality.py: Shows how to configure the preferred temporality for metric instrument types.
+
+The source files of these examples are available :scm_web:`here <docs/examples/metrics/reader/>`.
+
+
+Installation
+------------
+
+.. code-block:: sh
+
+    pip install -r requirements.txt
+
+Run the Example
+---------------
+
+.. code-block:: sh
+
+    python <example_name>.py
+
+The output will be shown in the console.
+
+Useful links
+------------
+
+- OpenTelemetry_
+- :doc:`../../../api/metrics`
+
+.. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/

docs/examples/metrics/example.py renamed to docs/examples/metrics/instruments/example.py

@@ -0,0 +1,50 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import time
+
+from opentelemetry.metrics import get_meter_provider, set_meter_provider
+from opentelemetry.sdk.metrics import Counter, MeterProvider
+from opentelemetry.sdk.metrics.export import (
+    ConsoleMetricExporter,
+    PeriodicExportingMetricReader,
+)
+from opentelemetry.sdk.metrics.view import LastValueAggregation
+
+# Use console exporter for the example
+exporter = ConsoleMetricExporter()
+
+aggregation_last_value = {Counter: LastValueAggregation()}
+
+# Create a metric reader with custom preferred aggregation
+reader = PeriodicExportingMetricReader(
+    exporter,
+    preferred_aggregation=aggregation_last_value,
+    export_interval_millis=5_000,
+)
+
+provider = MeterProvider(metric_readers=[reader])
+set_meter_provider(provider)
+
+meter = get_meter_provider().get_meter("preferred-aggregation", "0.1.2")
+
+counter = meter.create_counter("my-counter")
+
+# A counter normally would have an aggregation type of SumAggregation,
+# in which it's value would be determined by a cumulative sum.
+# In this example, the counter is configured with the LastValueAggregation,
+# which will only hold the most recent value.
+for x in range(10):
+    counter.add(x)
+    time.sleep(2.0)

docs/examples/metrics/otel-collector-config.yaml renamed to docs/examples/metrics/instruments/otel-collector-config.yaml

@@ -0,0 +1,58 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import time
+
+from opentelemetry.metrics import get_meter_provider, set_meter_provider
+from opentelemetry.sdk.metrics import Counter, MeterProvider
+from opentelemetry.sdk.metrics.export import (
+    AggregationTemporality,
+    ConsoleMetricExporter,
+    PeriodicExportingMetricReader,
+)
+
+# Use console exporter for the example
+exporter = ConsoleMetricExporter()
+
+temporality_cumulative = {Counter: AggregationTemporality.CUMULATIVE}
+temporality_delta = {Counter: AggregationTemporality.DELTA}
+# Create a metric reader with cumulative preferred temporality
+# The metrics that are exported using this reader will represent a cumulative value
+reader = PeriodicExportingMetricReader(
+    exporter,
+    preferred_temporality=temporality_cumulative,
+    export_interval_millis=5_000,
+)
+# Create a metric reader with delta preferred temporality
+# The metrics that are exported using this reader will represent a delta value
+reader2 = PeriodicExportingMetricReader(
+    exporter,
+    preferred_temporality=temporality_delta,
+    export_interval_millis=5_000,
+)
+provider = MeterProvider(metric_readers=[reader, reader2])
+set_meter_provider(provider)
+
+meter = get_meter_provider().get_meter("preferred-temporality", "0.1.2")
+
+counter = meter.create_counter("my-counter")
+
+# Two metrics are expected to be printed to the console per export interval.
+# The metric originating from the metric reader with a preferred temporality
+# of cumulative will keep a running sum of all values added.
+# The metric originating from the metric reader with a preferred temporality
+# of delta will have the sum value reset each export interval.
+for x in range(10):
+    counter.add(x)
+    time.sleep(2.0)

docs/examples/metrics/reader/README.rst

@@ -3,12 +3,12 @@ View common scenarios
 
 These examples show how to customize the metrics that are output by the SDK using Views. There are multiple examples:
 
-* change_aggregation: Shows how to configure to change the default aggregation for an instrument.
-* change_name: Shows how to change the name of a metric.
-* limit_num_of_attrs: Shows how to limit the number of attributes that are output for a metric.
-* drop_metrics_from_instrument: Shows how to drop measurements from an instrument.
+* change_aggregation.py: Shows how to configure to change the default aggregation for an instrument.
+* change_name.py: Shows how to change the name of a metric.
+* limit_num_of_attrs.py: Shows how to limit the number of attributes that are output for a metric.
+* drop_metrics_from_instrument.py: Shows how to drop measurements from an instrument.
 
-The source files of these examples are available :scm_web:`here <docs/examples/views/>`.
+The source files of these examples are available :scm_web:`here <docs/examples/metrics/views/>`.
 
 
 Installation
@@ -31,6 +31,6 @@ Useful links
 ------------
 
 - OpenTelemetry_
-- :doc:`../../api/metrics`
+- :doc:`../../../api/metrics`
 
 .. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/