Prometheus exporter (#294)

Author: vcasadei

README.rst

@@ -443,28 +443,29 @@ The use of vendoring or a dependency management tool is recommended.
 
 .. _Stackdriver: https://app.google.stackdriver.com/metrics-explorer
 
-Exporter Usage
-~~~~~~~~~~~~~~
+Stackdriver Exporter Usage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Import
-******
+Stackdriver Import
+************************
 
     .. code:: python
 
         from opencensus.stats.exporters import stackdriver_exporter as stackdriver
         from opencensus.stats import stats as stats_module
 
-Prerequisites
-*************
+Stackdriver 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
-*********************
+Register the Stackdriver exporter
+**********************************
+
     .. code:: python
 
         stats = stats_module.Stats()
@@ -475,8 +476,8 @@ Register the exporter
         ...
 
 
-Code Reference
-**************
+Stackdriver 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*.
 
@@ -490,6 +491,62 @@ For further details for the Stackdriver implementation, see the file *stackdrive
 | opencensus/stats/exporters/stackdriver_exporter.py | Stats implementation for Stackdriver|
 +----------------------------------------------------+-------------------------------------+
 
+Prometheus Stats
+-----------------
+
+The OpenCensus `Prometheus`_ Stats Exporter allows users
+to export metrics to Prometheus monitoring solution.
+The API of this project is still evolving.
+The use of vendoring or a dependency management tool is recommended.
+
+.. _Prometheus: https://prometheus.io/
+
+Prometheus Exporter Usage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Prometheus Import
+********************
+
+    .. code:: python
+
+        from opencensus.stats.exporters import prometheus_exporter as prometheus
+        from opencensus.stats import stats as stats_module
+
+Prometheus Prerequisites
+***************************
+
+- OpenCensus Python libraries require Python 2.7 or later.
+- Prometheus up and running.
+
+Register the Prometheus exporter
+***********************************
+
+    .. code:: python
+
+        stats = stats_module.Stats()
+        view_manager = stats.view_manager
+
+        exporter = prometheus.new_stats_exporter(prometheus.Options(namespace="<namespace>"))
+        view_manager.register_exporter(exporter)
+        ...
+
+
+Prometheus 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 Prometheus monitoring tool.
+
+For further details for the Prometheus implementation, see the file *prometheus_exporter.py*.
+
+
++----------------------------------------------------+-------------------------------------+
+| Path & File                                        | Short Description                   |
++====================================================+=====================================+
+| examples/stats/exporter/prometheus.py              | End to end example                  |
++----------------------------------------------------+-------------------------------------+
+| opencensus/stats/exporters/prometheus_exporter.py  | Stats implementation for Prometheus |
++----------------------------------------------------+-------------------------------------+
+
 ------------------
  Additional Info
 ------------------

examples/stats/exporter/prometheus.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python
+
+# 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 random
+import time
+
+from opencensus.stats import aggregation as aggregation_module
+from opencensus.stats.exporters import prometheus_exporter as prometheus
+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
+from pprint import pprint
+
+MiB = 1 << 20
+FRONTEND_KEY = tag_key_module.TagKey("my.org/keys/frontend")
+VIDEO_SIZE_MEASURE = measure_module.MeasureInt(
+    "my.org/measures/video_size", "size of processed videos", "By")
+VIDEO_SIZE_VIEW_NAME = "my.org/views/video_size"
+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)
+
+
+def main():
+    stats = stats_module.Stats()
+    view_manager = stats.view_manager
+    stats_recorder = stats.stats_recorder
+
+    exporter = prometheus.new_stats_exporter(prometheus.Options(namespace="opencensus"))
+    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(str(random.randint(1, 10000)))
+    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)
+
+    # Use the line below to see the data on prometheus
+    # while True:
+    #     pass
+
+    # Get aggregated stats and print it to console.
+    view_data = view_manager.get_view(VIDEO_SIZE_VIEW_NAME)
+    pprint(vars(view_data))
+    for k, v in view_data._tag_value_aggregation_data_map.items():
+      pprint(k)
+      pprint(vars(v))
+
+
+if __name__ == '__main__':
+    main()

opencensus/stats/exporters/__init__.py

@@ -28,7 +28,7 @@ def on_register_view(self, view):
         :param object of opencensus.stats.view.View view:
             View object to register
         """
-        raise NotImplementedError
+        raise NotImplementedError  # pragma: NO COVER
 
     def emit(self, view_datas):
         """Send view and measurement to exporter record method,
@@ -39,4 +39,4 @@ def emit(self, view_datas):
         :param list of opencensus.stats.view_data.ViewData ViewData:
             list of ViewData object to send to Stackdriver Monitoring
         """
-        raise NotImplementedError
+        raise NotImplementedError  # pragma: NO COVER