[docs] add metrics examples (open-telemetry#2371)

Alex Boten · web-flow · commit 8ff97ea4473f · 2022-01-14T11:45:40.000-08:00
diff --git a/docs/examples/metrics/README.rst b/docs/examples/metrics/README.rst
@@ -0,0 +1,48 @@
+OpenTelemetry Metrics SDK
+=========================
+
+.. warning::
+   OpenTelemetry Python metrics are in an experimental state. The APIs within
+   :mod:`opentelemetry.sdk._metrics` are subject to change in minor/patch releases and there are no
+   backward compatability guarantees at this time.
+
+Start the Collector locally to see data being exported. Write the following file:
+
+.. code-block:: yaml
+
+    # otel-collector-config.yaml
+    receivers:
+        otlp:
+            protocols:
+                grpc:
+
+    exporters:
+        logging:
+
+    processors:
+        batch:
+
+    service:
+        pipelines:
+            metrics:
+                receivers: [otlp]
+                exporters: [logging]
+  
+Then start the Docker container:
+
+.. code-block:: sh
+
+    docker run \
+        -p 4317:4317 \
+        -v $(pwd)/otel-collector-config.yaml:/etc/otel/config.yaml \
+        otel/opentelemetry-collector-contrib:latest
+
+.. code-block:: sh
+
+    $ python example.py
+
+The resulting metrics will appear in the output from the collector and look similar to this:
+
+.. code-block:: sh
+
+TODO
diff --git a/docs/examples/metrics/example.py b/docs/examples/metrics/example.py
@@ -0,0 +1,14 @@
+from opentelemetry._metrics import get_meter_provider, set_meter_provider
+from opentelemetry.exporter.otlp.proto.grpc._metric_exporter import (
+    OTLPMetricExporter,
+)
+from opentelemetry.sdk._metrics import MeterProvider
+
+provider = MeterProvider()
+exporter = OTLPMetricExporter(insecure=True)
+# TODO: fill in details for metric reader
+set_meter_provider(provider)
+
+meter = get_meter_provider().get_meter("getting-started")
+counter = meter.create_counter("first_counter")
+# TODO: fill in details for additional metrics
diff --git a/docs/examples/metrics/otel-collector-config.yaml b/docs/examples/metrics/otel-collector-config.yaml
@@ -0,0 +1,16 @@
+receivers:
+    otlp:
+        protocols:
+            grpc:
+
+exporters:
+    logging:
+
+processors:
+    batch:
+
+service:
+    pipelines:
+        metrics:
+            receivers: [otlp]
+            exporters: [logging]
diff --git a/docs/getting_started/metrics_example.py b/docs/getting_started/metrics_example.py
@@ -13,4 +13,17 @@
 # limitations under the License.
 
 # metrics.py
-# TODO
+# This is still work in progress as the metrics SDK is being implemented
+
+from opentelemetry._metrics import get_meter_provider, set_meter_provider
+from opentelemetry.sdk._metrics import MeterProvider
+from opentelemetry.sdk._metrics.export import ConsoleMetricExporter
+
+provider = MeterProvider()
+exporter = ConsoleMetricExporter()
+# TODO: fill in details for metric reader
+set_meter_provider(provider)
+
+meter = get_meter_provider().get_meter("getting-started")
+counter = meter.create_counter("first_counter")
+# TODO: fill in details for additional metrics
diff --git a/docs/sdk/metrics.rst b/docs/sdk/metrics.rst
@@ -0,0 +1,17 @@
+opentelemetry.sdk._metrics package
+==================================
+
+.. warning::
+   OpenTelemetry Python metrics are in an experimental state. The APIs within
+   :mod:`opentelemetry.sdk._metrics` are subject to change in minor/patch releases and there are no
+   backward compatability guarantees at this time.
+
+   Once logs become stable, this package will be be renamed to ``opentelemetry.sdk.metrics``.
+
+Submodules
+----------
+
+.. automodule:: opentelemetry.sdk._metrics
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/sdk/sdk.rst b/docs/sdk/sdk.rst
@@ -8,6 +8,7 @@ OpenTelemetry Python SDK
 
     resources
     trace
+    metrics
     logs
     error_handler
     environment_variables
