Update doc examples to include metrics (#217)

Author: aabmass

docs-requirements.txt

@@ -1,9 +1,6 @@
 -c dev-constraints.txt
 Sphinx
 sphinx-autodoc-typehints
-# unpin these entirely once the metrics SDK is available in a new version
-opentelemetry-api==1.10a0
-opentelemetry-sdk==1.10a0
 -e ./opentelemetry-exporter-gcp-trace
 -e ./opentelemetry-exporter-gcp-monitoring
 -e ./opentelemetry-propagator-gcp

docs/examples/cloud_monitoring/README.rst

@@ -31,7 +31,7 @@ Viewing Output
 
 After running the example:
     * Go to the `Cloud Monitoring Metrics Explorer page <https://console.cloud.google.com/monitoring/metrics-explorer>`_.
-    * In "Find resource type and metric" enter "OpenTelemetry/request_counter".
+    * In "Select a Metric" enter "workload.googleapis.com/request_counter".
     * You can filter by labels and change the graphical output here as well.
 
 Troubleshooting
@@ -40,9 +40,9 @@ Troubleshooting
 ``One or more points were written more frequently than the maximum sampling period configured for the metric``
 ##############################################################################################################
 
-Currently, Cloud Monitoring allows one write every 10 seconds for any unique tuple (metric_name, metric_label_value_1, metric_label_value_2, ...). The exporter should rate limit on its own but issues arise if:
+Currently, Cloud Monitoring allows one write every 5 seconds for any unique tuple (metric_name, metric_label_value_1, metric_label_value_2, ...). The exporter should rate limit on its own but issues arise if:
 
-    * You are restarting the server more than once every 10 seconds.
+    * You are restarting the server more than once every 5 seconds.
     * You have a multiple exporters (possibly on different threads) writing to the same tuple.
 
-For both cases, you can pass ``add_unique_identifier=True`` to the CloudMonitoringMetricsExporter constructor. This adds a UUID label_value, making the tuple unique again. For the first case, you can also choose to just wait longer than 10 seconds between restarts.
+For both cases, you can pass ``add_unique_identifier=True`` to the CloudMonitoringMetricsExporter constructor. This adds a UUID label_value, making the tuple unique again. For the first case, you can also choose to just wait longer than 5 seconds between restarts.

docs/examples/cloud_monitoring/basic_metrics.py

@@ -20,22 +20,36 @@
     CloudMonitoringMetricsExporter,
 )
 from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
+from opentelemetry.sdk.resources import Resource
 
-metrics.set_meter_provider(MeterProvider())
-meter = metrics.get_meter(__name__)
-metrics.get_meter_provider().start_pipeline(
-    meter, CloudMonitoringMetricsExporter(), 5
+metrics.set_meter_provider(
+    MeterProvider(
+        metric_readers=[
+            PeriodicExportingMetricReader(
+                CloudMonitoringMetricsExporter(), export_interval_millis=5000
+            )
+        ],
+        resource=Resource.create(
+            {
+                "service.name": "basic_metrics",
+                "service.namespace": "examples",
+                "service.instance.id": "instance123",
+            }
+        ),
+    )
 )
+meter = metrics.get_meter(__name__)
 
+# Creates metric workload.googleapis.com/request_counter with monitored resource generic_task
 requests_counter = meter.create_counter(
     name="request_counter",
     description="number of requests",
     unit="1",
-    value_type=int,
 )
 
 staging_labels = {"environment": "staging"}
 
 for i in range(20):
     requests_counter.add(25, staging_labels)
-    time.sleep(10)
+    time.sleep(5)

docs/examples/cloud_monitoring/requirements.txt

@@ -0,0 +1,25 @@
+cachetools==5.2.0
+certifi==2022.9.24
+charset-normalizer==2.1.1
+Deprecated==1.2.13
+google-api-core==2.10.2
+google-auth==2.14.1
+google-cloud-monitoring==2.11.3
+googleapis-common-protos==1.57.0
+grpcio==1.50.0
+grpcio-status==1.50.0
+idna==3.4
+opentelemetry-api==1.14.0
+../../../opentelemetry-exporter-gcp-monitoring
+opentelemetry-sdk==1.14.0
+opentelemetry-semantic-conventions==0.35b0
+proto-plus==1.22.1
+protobuf==4.21.9
+pyasn1==0.4.8
+pyasn1-modules==0.2.8
+requests==2.28.1
+rsa==4.9
+six==1.16.0
+typing_extensions==4.4.0
+urllib3==1.26.12
+wrapt==1.14.1

docs/examples/cloud_trace_exporter/requirements.txt

@@ -1,23 +1,25 @@
-cachetools==4.2.1
-certifi==2020.12.5
-chardet==4.0.0
-google-api-core==1.26.3
-google-auth==1.28.0
-google-cloud-core==1.6.0
-google-cloud-trace==0.24.0
-googleapis-common-protos==1.53.0
-grpcio==1.37.0
-idna==2.10
-opentelemetry-api==1.0.0
+cachetools==5.2.0
+certifi==2022.9.24
+charset-normalizer==2.1.1
+Deprecated==1.2.13
+google-api-core==2.10.2
+google-auth==2.14.1
+google-cloud-trace==1.7.3
+googleapis-common-protos==1.57.0
+grpcio==1.50.0
+grpcio-status==1.50.0
+idna==3.4
+opentelemetry-api==1.14.0
 ../../../opentelemetry-exporter-gcp-trace/
-opentelemetry-sdk==1.0.0
-packaging==20.9
-protobuf==3.18.3
+opentelemetry-sdk==1.14.0
+opentelemetry-semantic-conventions==0.35b0
+proto-plus==1.22.1
+protobuf==4.21.9
 pyasn1==0.4.8
 pyasn1-modules==0.2.8
-pyparsing==2.4.7
-pytz==2021.1
-requests==2.25.1
-rsa==4.7.2
-six==1.15.0
-urllib3==1.26.5
+requests==2.28.1
+rsa==4.9
+six==1.16.0
+typing_extensions==4.4.0
+urllib3==1.26.12
+wrapt==1.14.1

docs/examples/flask_e2e/README.rst

@@ -2,10 +2,11 @@
 End-to-End Example with Flask
 =============================
 
-This end-to-end example shows how to instrument a Flask app with
-OpenTelemetry to send traces to Cloud Trace. In addition, there is a client
-script that uses ``requests`` to call the Flask app and propagate context with
-the GCP context propagator.
+This end-to-end example shows how to instrument a Flask app with OpenTelemetry to send traces
+to Cloud Trace and metrics to Cloud Monitoring. OpenTelemetry instrumentation for Flask and
+requests will automatically generate spans and metrics for you. In addition, there is a client
+script that uses ``requests`` to call the Flask app and propagate context with the GCP context
+propagator.
 
 To run this example you first need to:
     * Create a Google Cloud project. You can `create one here <https://console.cloud.google.com/projectcreate>`_.
@@ -29,6 +30,7 @@ Install Dependencies
 .. code-block:: sh
 
     pip install opentelemetry-exporter-gcp-trace \
+        opentelemetry-exporter-gcp-monitoring \
         opentelemetry-propagator-gcp \
         opentelemetry-api \
         opentelemetry-sdk \
@@ -71,16 +73,32 @@ Checking Output
 ---------------
 
 After running any of these examples, you can go to `Cloud Trace overview
-<https://console.cloud.google.com/traces/list>`_ to see the results. You
-should see something like the image below with a root span covering the whole
-client request and a child span covering the Flask server processing the
-request.
+<https://console.cloud.google.com/traces/list>`_ and `Cloud Monitoring Metrics Explorer page
+<https://console.cloud.google.com/monitoring/metrics-explorer>`_ to see the results. You should
+see something like the image below with a root span covering the whole client request and a
+child span covering the Flask server processing the request. For metrics, you should see
+various metrics created for monitored resource ``generic_task`` with "category" Http e.g.
+``workload.googleapis.com/http.server.duration``. Client side metrics should be populated as
+well e.g. ``workload.googleapis.com/http.client.duration``.
 
 .. image:: gct_result.png
   :alt: GCT result
 
+.. image:: metrics_explorer.png
+  :alt: Metrics explorer search
+
+.. image:: gcm_latency.png
+  :alt: GCM heatmap of client latency
 
 Further Reading
 ---------------
 
+Troubleshooting
+--------------------------
+
+``google.api_core.exceptions.Aborted: 409 [...] error: Too many concurrent edits to the project configuration. Please try again.``
+##################################################################################################################################
+
+This is a transient error when a metric is first written to Cloud Monitoring. Try again and things should work fine.
+
 * `More information about exporters in general <https://opentelemetry-python.readthedocs.io/en/stable/getting-started.html#configure-exporters-to-emit-spans-elsewhere>`_

docs/examples/flask_e2e/client.py

@@ -14,18 +14,32 @@
 # limitations under the License.
 
 import requests
-from opentelemetry import trace
+from opentelemetry import metrics, trace
+from opentelemetry.exporter.cloud_monitoring import (
+    CloudMonitoringMetricsExporter,
+)
 from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
 from opentelemetry.instrumentation.requests import RequestsInstrumentor
 from opentelemetry.propagate import set_global_textmap
 from opentelemetry.propagators.cloud_trace_propagator import (
     CloudTraceFormatPropagator,
 )
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
+from opentelemetry.sdk.resources import Resource
 from opentelemetry.sdk.trace import TracerProvider
 from opentelemetry.sdk.trace.export import BatchSpanProcessor
 
 set_global_textmap(CloudTraceFormatPropagator())
 
+resource = Resource.create(
+    {
+        "service.name": "flask_e2e_client",
+        "service.namespace": "examples",
+        "service.instance.id": "instance554",
+    }
+)
+
 tracer_provider = TracerProvider()
 cloud_trace_exporter = CloudTraceSpanExporter()
 tracer_provider.add_span_processor(
@@ -34,9 +48,21 @@
     # tweaked to optimize your performance
     BatchSpanProcessor(cloud_trace_exporter)
 )
+
+meter_provider = MeterProvider(
+    metric_readers=[
+        PeriodicExportingMetricReader(
+            CloudMonitoringMetricsExporter(), export_interval_millis=5000
+        )
+    ],
+    resource=resource,
+)
+
 trace.set_tracer_provider(tracer_provider)
+metrics.set_meter_provider(meter_provider)
 
 tracer = trace.get_tracer(__name__)
+meter = metrics.get_meter(__name__)
 
 RequestsInstrumentor().instrument()
 

docs/examples/flask_e2e/gcm_latency.png

@@ -1,37 +1,39 @@
-asgiref==3.3.4
-cachetools==4.2.1
-certifi==2020.12.5
-chardet==4.0.0
-click==7.1.2
-Flask==1.1.2
-google-api-core==1.26.3
-google-auth==1.28.0
-google-cloud-core==1.6.0
-google-cloud-trace==0.24.0
-googleapis-common-protos==1.53.0
-grpcio==1.37.0
-idna==2.10
-itsdangerous==1.1.0
-Jinja2==2.11.3
-MarkupSafe==1.1.1
-opentelemetry-api==1.0.0
+cachetools==5.2.0
+certifi==2022.9.24
+charset-normalizer==2.1.1
+click==8.1.3
+Deprecated==1.2.13
+Flask==2.2.2
+google-api-core==2.10.2
+google-auth==2.14.1
+google-cloud-monitoring==2.11.3
+google-cloud-trace==1.7.3
+googleapis-common-protos==1.57.0
+grpcio==1.50.0
+grpcio-status==1.50.0
+idna==3.4
+itsdangerous==2.1.2
+Jinja2==3.1.2
+MarkupSafe==2.1.1
+opentelemetry-api==1.14.0
+../../../opentelemetry-exporter-gcp-monitoring
 ../../../opentelemetry-exporter-gcp-trace
 ../../../opentelemetry-propagator-gcp
-opentelemetry-instrumentation==0.19b0
-opentelemetry-instrumentation-flask==0.19b0
-opentelemetry-instrumentation-requests==0.19b0
-opentelemetry-instrumentation-wsgi==0.19b0
-opentelemetry-sdk==1.0.0
-opentelemetry-util-http==0.19b0
-packaging==20.9
-protobuf==3.18.3
+opentelemetry-instrumentation==0.35b0
+opentelemetry-instrumentation-requests==0.35b0
+opentelemetry-instrumentation-flask==0.35b0
+opentelemetry-instrumentation-wsgi==0.35b0
+opentelemetry-sdk==1.14.0
+opentelemetry-semantic-conventions==0.35b0
+opentelemetry-util-http==0.35b0
+proto-plus==1.22.1
+protobuf==4.21.9
 pyasn1==0.4.8
 pyasn1-modules==0.2.8
-pyparsing==2.4.7
-pytz==2021.1
-requests==2.25.1
-rsa==4.7.2
-six==1.15.0
-urllib3==1.26.5
-Werkzeug==1.0.1
-wrapt==1.12.1
+requests==2.28.1
+rsa==4.9
+six==1.16.0
+typing_extensions==4.4.0
+urllib3==1.26.12
+Werkzeug==2.2.2
+wrapt==1.14.1