Revert "Remove metrics from main branch (open-telemetry#1568)"

This reverts commit 24edd3d.

CHANGELOG.md

@@ -261,8 +261,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Removed
 - Remove Configuration
   ([#1523](https://github.com/open-telemetry/opentelemetry-python/pull/1523))
-- Remove Metrics as part of stable, marked as experimental
-  ([#1568](https://github.com/open-telemetry/opentelemetry-python/pull/1568))
 
 ## [0.17b0](https://github.com/open-telemetry/opentelemetry-python/releases/tag/v0.17b0) - 2021-01-20
 

docs/api/api.rst

@@ -8,5 +8,6 @@ OpenTelemetry Python API
 
     baggage
     context
+    metrics
     trace
     environment_variables

docs/api/metrics.rst

@@ -0,0 +1,7 @@
+opentelemetry.metrics package
+=============================
+
+Module contents
+---------------
+
+.. automodule:: opentelemetry.metrics

docs/examples/basic_meter/README.rst

@@ -0,0 +1,42 @@
+Basic Meter
+===========
+
+These examples show how to use OpenTelemetry to capture and report metrics.
+
+There are three different examples:
+
+* basic_metrics: Shows how to create a metric instrument, how to configure an
+  exporter and a controller and also how to capture data by using the direct
+  calling convention.
+
+* calling_conventions: Shows how to use the direct, bound and batch calling conventions.
+
+* observer: Shows how to use the observer instrument.
+
+The source files of these examples are available :scm_web:`here <docs/examples/basic_meter/>`.
+
+Installation
+------------
+
+.. code-block:: sh
+
+    pip install opentelemetry-api
+    pip install opentelemetry-sdk
+    pip install psutil # needed to get ram and cpu usage in the observer example
+
+Run the Example
+---------------
+
+.. code-block:: sh
+
+    python <example_name>.py
+
+The output will be shown in the console after few seconds.
+
+Useful links
+------------
+
+- OpenTelemetry_
+- :doc:`../../api/metrics`
+
+.. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/

docs/examples/basic_meter/basic_metrics.py

@@ -0,0 +1,87 @@
+# 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.
+#
+"""
+This module serves as an example for a simple application using metrics.
+
+It shows:
+- How to configure a meter passing a stateful or stateless.
+- How to configure an exporter and how to create a controller.
+- How to create some metrics instruments and how to capture data with them.
+- How to use views to specify aggregation types for each metric instrument.
+"""
+import sys
+import time
+
+from opentelemetry import metrics
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.metrics.export import ConsoleMetricsExporter
+
+print(
+    "Starting example, values will be printed to the console every 5 seconds."
+)
+
+# Stateful determines whether how metrics are collected: if true, metrics
+# accumulate over the process lifetime. If false, metrics are reset at the
+# beginning of each collection interval.
+stateful = True
+
+# Sets the global MeterProvider instance
+metrics.set_meter_provider(MeterProvider())
+
+# The Meter is responsible for creating and recording metrics. Each meter has a
+# unique name, which we set as the module's name here.
+meter = metrics.get_meter(__name__)
+
+# Exporter to export metrics to the console
+exporter = ConsoleMetricsExporter()
+
+# start_pipeline will notify the MeterProvider to begin collecting/exporting
+# metrics with the given meter, exporter and interval in seconds
+metrics.get_meter_provider().start_pipeline(meter, exporter, 5)
+
+# Metric instruments allow to capture measurements
+requests_counter = meter.create_counter(
+    name="requests",
+    description="number of requests",
+    unit="1",
+    value_type=int,
+)
+
+requests_size = meter.create_valuerecorder(
+    name="requests_size",
+    description="size of requests",
+    unit="1",
+    value_type=int,
+)
+
+# Labels are used to identify key-values that are associated with a specific
+# metric that you want to record. These are useful for pre-aggregation and can
+# be used to store custom dimensions pertaining to a metric
+staging_labels = {"environment": "staging"}
+testing_labels = {"environment": "testing"}
+
+# Update the metric instruments using the direct calling convention
+requests_counter.add(25, staging_labels)
+requests_size.record(100, staging_labels)
+time.sleep(10)
+
+requests_counter.add(50, staging_labels)
+requests_size.record(5000, staging_labels)
+time.sleep(5)
+
+requests_counter.add(35, testing_labels)
+requests_size.record(2, testing_labels)
+
+input("...\n")

docs/examples/basic_meter/calling_conventions.py

@@ -0,0 +1,66 @@
+# 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.
+#
+"""
+This example shows how to use the different modes to capture metrics.
+It shows the usage of the direct, bound and batch calling conventions.
+"""
+import time
+
+from opentelemetry import metrics
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.metrics.export import ConsoleMetricsExporter
+
+# Use the meter type provided by the SDK package
+metrics.set_meter_provider(MeterProvider())
+meter = metrics.get_meter(__name__)
+metrics.get_meter_provider().start_pipeline(meter, ConsoleMetricsExporter(), 5)
+
+requests_counter = meter.create_counter(
+    name="requests",
+    description="number of requests",
+    unit="1",
+    value_type=int,
+)
+
+clicks_counter = meter.create_counter(
+    name="clicks", description="number of clicks", unit="1", value_type=int,
+)
+
+labels = {"environment": "staging"}
+
+print("Updating using direct calling convention...")
+# You can record metrics directly using the metric instrument. You pass in
+# labels that you would like to record for.
+requests_counter.add(25, labels)
+time.sleep(10)
+
+print("Updating using a bound instrument...")
+# You can record metrics with bound metric instruments. Bound metric
+# instruments are created by passing in labels. A bound metric instrument
+# is essentially metric data that corresponds to a specific set of labels.
+# Therefore, getting a bound metric instrument using the same set of labels
+# will yield the same bound metric instrument.
+bound_requests_counter = requests_counter.bind(labels)
+bound_requests_counter.add(100)
+time.sleep(5)
+
+print("Updating using batch calling convention...")
+# You can record metrics in a batch by passing in labels and a sequence of
+# (metric, value) pairs. The value would be recorded for each metric using the
+# specified labels for each.
+meter.record_batch(labels, ((requests_counter, 50), (clicks_counter, 70)))
+time.sleep(5)
+
+input("...\n")

docs/examples/basic_meter/http_metrics.py

@@ -0,0 +1,42 @@
+# 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.
+#
+"""
+This module shows how you can enable collection and exporting of http metrics
+related to instrumentations.
+"""
+import requests
+
+from opentelemetry import metrics
+from opentelemetry.instrumentation.requests import RequestsInstrumentor
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.metrics.export import ConsoleMetricsExporter
+
+# Sets the global MeterProvider instance
+metrics.set_meter_provider(MeterProvider())
+
+# Exporter to export metrics to the console
+exporter = ConsoleMetricsExporter()
+
+# Instrument the requests library
+RequestsInstrumentor().instrument()
+
+# Indicate to start collecting and exporting requests related metrics
+metrics.get_meter_provider().start_pipeline(
+    RequestsInstrumentor().meter, exporter, 5
+)
+
+response = requests.get("http://example.com")
+
+input("...\n")

docs/examples/basic_meter/observer.py

@@ -0,0 +1,60 @@
+# 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.
+#
+"""
+This example shows how the Observer metric instrument can be used to capture
+asynchronous metrics data.
+"""
+import psutil
+
+from opentelemetry import metrics
+from opentelemetry.sdk.metrics import MeterProvider, ValueObserver
+from opentelemetry.sdk.metrics.export import ConsoleMetricsExporter
+
+metrics.set_meter_provider(MeterProvider())
+meter = metrics.get_meter(__name__)
+metrics.get_meter_provider().start_pipeline(meter, ConsoleMetricsExporter(), 5)
+
+
+# Callback to gather cpu usage
+def get_cpu_usage_callback(observer):
+    for (number, percent) in enumerate(psutil.cpu_percent(percpu=True)):
+        labels = {"cpu_number": str(number)}
+        observer.observe(percent, labels)
+
+
+meter.register_valueobserver(
+    callback=get_cpu_usage_callback,
+    name="cpu_percent",
+    description="per-cpu usage",
+    unit="1",
+    value_type=float,
+)
+
+
+# Callback to gather RAM memory usage
+def get_ram_usage_callback(observer):
+    ram_percent = psutil.virtual_memory().percent
+    observer.observe(ram_percent, {})
+
+
+meter.register_valueobserver(
+    callback=get_ram_usage_callback,
+    name="ram_percent",
+    description="RAM memory usage",
+    unit="1",
+    value_type=float,
+)
+
+input("Metrics will be printed soon. Press a key to finish...\n")