[WIP] Implementation of Python Stats API (#149)

Author: kcooperstein

.gitignore

@@ -19,6 +19,7 @@ develop-eggs
 lib
 lib64
 __pycache__
+venv/
 
 # Installer logs
 pip-log.txt
@@ -53,6 +54,7 @@ docs/_build_doc2dash
 
 # Virtual environment
 env/
+venv/
 coverage.xml
 
 # System test environment variables.

docs/trace/usage.rst

@@ -1,5 +1,5 @@
-OpenCensus Trace for Python
-===========================
+OpenCensus for Python - A stats collection and distributed tracing framework
+============================================================================
 
     `Census`_ for Python. Census provides a framework to measure a server's resource
     usage and collect performance stats. This repository contains Python related
@@ -14,7 +14,7 @@ OpenCensus Trace for Python
 
 -  `API Documentation`_
 
-.. _API Documentation: http://opencensus.io/opencensus-python/trace/usage.html
+.. _API Documentation: https://opencensus.io/api/python/trace/usage.html
 
 Installation & basic usage
 --------------------------
@@ -23,14 +23,10 @@ Installation & basic usage
 
     ::
 
-        pip install opencensus-trace
-        pipenv install opencensus-trace
+        pip install opencensus
+        pipenv install opencensus
 
-        # install the Stackdriver exporter by including the extras package
-        pip install opencensus-trace[stackdriver]
-        pipenv install opencensus-trace[stackdriver]
-
-2. Initialize a tracer for application:
+2. Initialize a tracer for your application:
 
     .. code:: python
 
@@ -135,7 +131,7 @@ Propagators
 ~~~~~~~~~~~
 
 You can specify the propagator type for serializing and deserializing the
-``SpanContex`` and its headers. There are currently two built in propagators:
+``SpanContext`` and its headers. There are currently two built in propagators:
 ``GoogleCloudFormatPropagator`` and ``TextFormatPropagator``.
 
 This example shows how to use the ``GoogleCloudFormatPropagator``:
@@ -186,8 +182,8 @@ For Django, you can configure the blacklist in the ``OPENCENSUS_PARAMS`` in ``se
 Framework Integration
 ---------------------
 
-Opencensus supports integration with popular web frameworks including
-Django, Flask, and Webapp2. When the application receives a HTTP request,
+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
 child spans.
@@ -209,41 +205,6 @@ requests will be automatically traced.
     # `GoogleCloudFormatPropagator` as propagator.
     middleware = FlaskMiddleware(app)
 
-The middleware also supports the factory pattern.
-
-.. code:: python
-
-    from opencensus.trace.ext.flask.flask_middleware import FlaskMiddleware
-    middleware = FlaskMiddleware()
-    app = flask.Flask(__name__)
-    middleware.init_app(app)
-
-The Flask application configuration can also be used to specify the sampler,
-exporter, propagator in the middleware.
-
-.. code:: python
-
-    OPENCENSUS_TRACE = {
-        'SAMPLER': opencensus.trace.samplers.probability.ProbabilitySampler,
-        'REPORTER': opencensus.trace.exporters.print_exporter.PrintExporter,
-        'PROPAGATOR': opencensus.trace.propagation.google_cloud_format.
-                      GoogleCloudFormatPropagator,
-    }
-
-You can configure the sampling rate and other parameters using the ``OPENCENSUS_TRACE_PARAMS``
-key in the app configuration:
-
-.. code:: python
-
-    OPENCENSUS_TRACE_PARAMS = {
-        'BLACKLIST_PATHS': ['/_ah/health'],
-        'GCP_EXPORTER_PROJECT': None,
-        'SAMPLING_RATE': 0.5,
-        'ZIPKIN_EXPORTER_SERVICE_NAME': 'my_service',
-        'ZIPKIN_EXPORTER_HOST_NAME': 'localhost',
-        'ZIPKIN_EXPORTER_PORT': 9411,
-    }
-
 Django
 ~~~~~~
 
@@ -266,7 +227,7 @@ And add this line to the ``INSTALLED_APPS`` section:
         'opencensus.trace.ext.django',
     ]
 
-You can configure the the sampler, exporter, propagator using the ``OPENCENSUS_TRACE`` setting in
+You can configure the sampler, exporter, propagator using the ``OPENCENSUS_TRACE`` setting in
 ``settings.py``:
 
 .. code:: python
@@ -292,18 +253,56 @@ setting in ``settings.py``:
         'ZIPKIN_EXPORTER_PORT': 9411,
     }
 
-Webapp2
+
+Pyramid
 ~~~~~~~
 
+In your application, add the pyramid tween and your requests will be
+traced.
+
 .. code:: python
 
-    from opencensus.trace.tracers import webapp2_tracer
+    def main(global_config, **settings):
+        config = Configurator(settings=settings)
 
-    tracer = webapp2_tracer.WebApp2Tracer()
+        config.add_tween('opencensus.trace.ext.pyramid'
+                         '.pyramid_middleware.OpenCensusTweenFactory')
 
-    with tracer.span(name='span1'):
-        do_something_to_trace()
+To configure the sampler, exporter, and propagator, pass the instances
+into the pyramid settings
+
+.. code:: python
 
+    from opencensus.trace.exporters import print_exporter
+    from opencensus.trace.propagation import google_cloud_format
+    from opencensus.trace.samplers import probability
+
+    settings = {}
+    settings['OPENCENSUS_TRACE'] = {
+        'EXPORTER': print_exporter.PrintExporter(),
+        'SAMPLER': probability.ProbabilitySampler(rate=0.5),
+        'PROPAGATOR': google_cloud_format.GoogleCloudFormatPropagator(),
+    }
+
+    config = Configurator(settings=settings)
+
+gRPC Integration
+----------------
+
+OpenCensus provides the implementation of interceptors for both the client side
+and server side to instrument the gRPC requests and responses. The client
+interceptors are used to create a decorated channel that intercepts client
+gRPC calls and server interceptors act as decorators over handlers.
+
+gRPC interceptor is a new feature in the grpcio1.8.0 release, please upgrade
+your grpcio to the latest version to use this feature.
+
+For sample usage, please refer to the hello world example in the examples
+directory.
+
+More information about the gRPC interceptors please see the `proposal`_.
+
+.. _proposal: https://github.com/mehrdada/proposal/blob/python-interceptors/L13-Python-Interceptors.md
 
 Service Integration
 -------------------
@@ -345,22 +344,24 @@ to ``trace_integrations`` using ``'postgresql'``.
 SQLAlchemy
 ~~~~~~~~~~
 
-You can trace usage of `sqlalchemy package`_, regardless of the underlying database, by
-specifying ``'sqlalchemy'`` to ``trace_integrations``.
+You can trace usage of the `sqlalchemy package`_, regardless of the underlying
+database, by specifying ``'sqlalchemy'`` to ``trace_integrations``.
 
 .. _SQLAlchemy package: https://pypi.org/project/SQLAlchemy
 
-.. note:: If you enable tracing of SQLAlchemy and the underlying database
+.. note:: If you enable tracing of SQLAlchemy as well as the underlying database
     driver, you will get duplicate spans. Instead, just trace SQLAlchemy.
 
 Requests
 ~~~~~~~~
 
-Census can trace HTTP requests made with the `Requests`_ library. The request URL,
+Census can trace HTTP requests made with the `Requests package`_. The request URL,
 method, and status will be collected.
 
 You can enable Requests integration by specifying ``'requests'`` to ``trace_integrations``.
 
+.. _Requests package: https://pypi.python.org/pypi/requests
+
 
 Contributing
 ------------

opencensus/stats/__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/aggregation.py

@@ -0,0 +1,126 @@
+# 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.
+
+from opencensus.stats import bucket_boundaries
+from opencensus.stats import aggregation_data
+
+
+class BaseAggregation(object):
+    """Aggregation describes how the data collected is aggregated by type of
+    aggregation and buckets
+
+    :type buckets: list(:class: '~opencensus.stats.bucket_boundaries.
+                                BucketBoundaries')
+    :param buckets: list of endpoints if the aggregation represents a
+                    distribution
+
+    """
+    def __init__(self, buckets=None):
+        self._aggregation_type = "none"
+        self._buckets = buckets or []
+
+    @property
+    def aggregation_type(self):
+        """The aggregation type of the current aggregation"""
+        return self._aggregation_type
+
+    @property
+    def buckets(self):
+        """The buckets of the current aggregation"""
+        return self._buckets
+
+
+class SumAggregation(BaseAggregation):
+    """Sum Aggregation escribes that data collected and aggregated with this
+    method will be summed
+
+    :type sum: int or float
+    :param sum: the sum of the data collected and aggregated
+
+    """
+    def __init__(self, sum=None):
+        super(SumAggregation, self).__init__()
+        self._aggregation_type = "sum"
+        if sum is not None:
+            self._sum = aggregation_data.SumAggregationDataFloat(sum_data=sum)
+        else:
+            self._sum = aggregation_data.SumAggregationDataFloat(sum_data=0)
+
+    @property
+    def aggregation_type(self):
+        """The aggregation type of the current aggregation"""
+        return self._aggregation_type
+
+    @property
+    def sum(self):
+        """The sum of the current aggregation"""
+        return self._sum
+
+
+class CountAggregation(BaseAggregation):
+    """Describes that the data collected and aggregated with this method will
+    be turned into a count value
+
+    :type count: int
+    :param count: represents the count of this aggregation
+
+    """
+    def __init__(self, count=0):
+        super(CountAggregation, self).__init__()
+        self._aggregation_type = "count"
+        self._count = aggregation_data.CountAggregationData(count)
+
+    @property
+    def aggregation_type(self):
+        """The aggregation type of the current aggregation"""
+        return self._aggregation_type
+
+    @property
+    def count(self):
+        """The count of the current aggregation"""
+        return self._count
+
+
+class DistributionAggregation(BaseAggregation):
+    """Distribution Aggregation indicates that the desired aggregation is a
+    histogram distribution
+
+    :type boundaries: list(:class:'~opencensus.stats.bucket_boundaries.
+                            BucketBoundaries')
+    :param boundaries: the bucket endpoints
+
+    :type distribution: histogram
+    :param distribution: histogram of the values of the population
+
+    """
+    def __init__(self, boundaries=None, distribution=None):
+        super(DistributionAggregation, self).__init__(boundaries)
+        self._aggregation_type = "distribution"
+        self._boundaries = bucket_boundaries.BucketBoundaries(boundaries)
+        self._distribution = distribution if distribution is not None else {}
+
+    @property
+    def aggregation_type(self):
+        """The aggregation type of the current aggregation"""
+        return self._aggregation_type
+
+    @property
+    def boundaries(self):
+        """The boundaries of the current aggregation"""
+        return self._boundaries
+
+    @property
+    def distribution(self):
+        """The distribution of the current aggregation"""
+        return self._distribution