Stackdriver stats exporter (#250)

Author: MarceloAquino7

README.rst

@@ -16,6 +16,10 @@ OpenCensus for Python - A stats collection and distributed tracing framework
 
 .. _API Documentation: https://opencensus.io/api/python/trace/usage.html
 
+--------
+ Tracing
+--------
+
 Installation & basic usage
 --------------------------
 
@@ -210,7 +214,7 @@ For Django, you can configure the blacklist in the ``OPENCENSUS_PARAMS`` in ``se
     }
 
 
-.. note:: By default the health check path for the App Engine flexible environment is not traced,
+.. note:: By default, the health check path for the App Engine flexible environment is not traced,
     but you can turn it on by excluding it from the blacklist setting.
 
 Framework Integration
@@ -219,7 +223,7 @@ Framework Integration
 Census supports integration with popular web frameworks including
 Django, Flask, Pyramid, and Webapp2. When the application receives a HTTP request,
 the tracer will automatically generate a span context using the trace
-information extracted from the request headers, and propagated to the
+information extracted from the request headers and propagated to the
 child spans.
 
 Flask
@@ -397,6 +401,70 @@ You can enable Requests integration by specifying ``'requests'`` to ``trace_inte
 
 .. _Requests package: https://pypi.python.org/pypi/requests
 
+------
+ Stats
+------
+
+Stackdriver Stats
+-----------------
+
+The OpenCensus Stackdriver Stats Exporter allows users
+to export metrics to Stackdriver Monitoring.
+The API of this project is still evolving.
+The use of vendoring or a dependency management tool is recommended.
+
+.. _Stackdriver: https://app.google.stackdriver.com/metrics-explorer
+
+Exporter Usage
+~~~~~~~~~~~~~~
+
+Import
+******
+
+    .. code:: python
+
+        from opencensus.stats.exporters import stackdriver_exporter as stackdriver
+        from opencensus.stats import stats as stats_module
+
+Prerequisites
+*************
+
+- OpenCensus Python libraries require Python 2.7 or later.
+- Google Cloud Platform account and project.
+- Google Stackdriver Monitoring enabled on your project (Need help? `Click here`_).
+
+.. _Click here: https://opencensus.io/codelabs/stackdriver
+
+Register the exporter
+*********************
+    .. code:: python
+
+        stats = stats_module.Stats()
+        view_manager = stats.view_manager
+
+        exporter = stackdriver.new_stats_exporter(stackdriver.Options(project_id="<id_value>"))
+        view_manager.register_exporter(exporter)
+        ...
+
+
+Code Reference
+**************
+
+In the *examples* folder, you can find all the necessary steps to get the exporter, register a view, put tags on the measure, and see the values against the Stackdriver monitoring tool once you have defined the *project_id*.
+
+For further details for the Stackdriver implementation, see the file *stackdriver_exporter.py*.
+
++----------------------------------------------------+-------------------------------------+
+| Path & File                                        | Short Description                   |
++====================================================+=====================================+
+| examples/stats/exporter/stackdriver.py             | End to end example                  |
++----------------------------------------------------+-------------------------------------+
+| opencensus/stats/exporters/stackdriver_exporter.py | Stats implementation for Stackdriver|
++----------------------------------------------------+-------------------------------------+
+
+------------------
+ Additional Info
+------------------
 
 Contributing
 ------------

examples/stats/exporter/stackdriver.py

@@ -0,0 +1,62 @@
+# Copyright 2018, OpenCensus 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
+import random
+from opencensus.stats import aggregation as aggregation_module
+from opencensus.stats.exporters import stackdriver_exporter as stackdriver
+from opencensus.stats import measure as measure_module
+from opencensus.stats import stats as stats_module
+from opencensus.stats import view as view_module
+from opencensus.tags import tag_key as tag_key_module
+from opencensus.tags import tag_map as tag_map_module
+from opencensus.tags import tag_value as tag_value_module
+
+MiB = 1 << 20
+FRONTEND_KEY = tag_key_module.TagKey("my.org/keys/frontend")
+VIDEO_SIZE_MEASURE = measure_module.MeasureInt(
+    "my.org/measure/video_size_test2", "size of processed videos", "By")
+VIDEO_SIZE_VIEW_NAME = "my.org/views/video_size_test2"
+VIDEO_SIZE_DISTRIBUTION = aggregation_module.DistributionAggregation(
+                            [0.0, 16.0 * MiB, 256.0 * MiB])
+VIDEO_SIZE_VIEW = view_module.View(VIDEO_SIZE_VIEW_NAME,
+                                "processed video size over time",
+                                [FRONTEND_KEY],
+                                VIDEO_SIZE_MEASURE,
+                                VIDEO_SIZE_DISTRIBUTION)
+
+
+
+stats = stats_module.Stats()
+view_manager = stats.view_manager
+stats_recorder = stats.stats_recorder
+
+exporter = stackdriver.new_stats_exporter(stackdriver.Options(project_id="opencenus-node"))
+view_manager.register_exporter(exporter)
+
+# Register view.
+view_manager.register_view(VIDEO_SIZE_VIEW)
+
+# Sleep for [0, 10] milliseconds to fake work.
+time.sleep(random.randint(1, 10) / 1000.0)
+
+# Process video.
+# Record the processed video size.
+tag_value = tag_value_module.TagValue(1200)
+tag_map = tag_map_module.TagMap()
+tag_map.insert(FRONTEND_KEY, tag_value)
+measure_map = stats_recorder.new_measurement_map()
+measure_map.measure_int_put(VIDEO_SIZE_MEASURE, 25 * MiB)
+
+measure_map.record(tag_map)

opencensus/stats/exporters/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 2018, OpenCensus 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.

opencensus/stats/exporters/base.py

@@ -0,0 +1,42 @@
+# Copyright 2018, OpenCensus 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.
+
+"""Module containing base class for exporters."""
+
+
+class StatsExporter(object):
+    """Base class for opencensus stats exporters.
+
+    Subclasses of :class:`Exporter` must override :meth:`export`.
+    """
+
+    def on_register_view(self, view):
+        """
+        :type view: object of :class:
+            `~opencensus.stats.view.View`
+        :param object of opencensus.stats.view.View view:
+            View object to register
+        """
+        raise NotImplementedError
+
+    def emit(self, view_datas):
+        """Send view and measurement to exporter record method,
+        and then it will record on its own way.
+
+        :type view_datas: object of :class:
+            `~opencensus.stats.view_data.ViewData`
+        :param list of opencensus.stats.view_data.ViewData ViewData:
+            list of ViewData object to send to Stackdriver Monitoring
+        """
+        raise NotImplementedError