Pyramid support (#121)

Author: bplotnick

README.rst

@@ -183,7 +183,7 @@ Framework Integration
 ---------------------
 
 Census supports integration with popular web frameworks including
-Django, Flask, and Webapp2. When the application receives a HTTP request,
+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.
@@ -253,6 +253,39 @@ setting in ``settings.py``:
         'ZIPKIN_EXPORTER_PORT': 9411,
     }
 
+
+Pyramid
+~~~~~~~
+
+In your application, add the pyramid tween and your requests will be
+traced.
+
+.. code:: python
+
+    def main(global_config, **settings):
+        config = Configurator(settings=settings)
+
+        config.add_tween('opencensus.trace.ext.pyramid'
+                         '.pyramid_middleware.OpenCensusTweenFactory')
+
+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
 ----------------
 

examples/trace/helloworld/pyramid/__init__.py

@@ -0,0 +1,46 @@
+# Copyright 2017, 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 requests
+
+from pyramid.config import Configurator
+from pyramid.response import Response
+from pyramid.tweens import MAIN
+from pyramid.view import view_config
+
+
+@view_config(route_name='hello')
+def hello(request):
+    return Response('Hello world!')
+
+
+@view_config(route_name='trace_requests')
+def trace_requests(request):
+    response = requests.get('http://www.google.com')
+    return Response(str(response.status_code))
+
+
+def main(global_config, **settings):
+    config = Configurator(settings=settings)
+
+    config.add_route('hello', '/')
+    config.add_route('trace_requests', '/requests')
+
+    config.add_tween('opencensus.trace.ext.pyramid'
+                     '.pyramid_middleware.OpenCensusTweenFactory',
+                     over=MAIN)
+
+    config.scan()
+
+    return config.make_wsgi_app()

examples/trace/helloworld/pyramid/app/__init__.py

@@ -0,0 +1,47 @@
+# Copyright 2017, 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 wsgiref.simple_server import make_server
+
+from opencensus.trace import config_integration
+from opencensus.trace.exporters import print_exporter
+from opencensus.trace.samplers import probability
+
+from app import main
+
+
+INTEGRATIONS = ['requests']
+
+
+config_integration.trace_integrations(INTEGRATIONS)
+
+
+def run_app():
+    settings = {}
+
+    exporter = print_exporter.PrintExporter()
+    sampler = probability.ProbabilitySampler(rate=1)
+
+    settings['OPENCENSUS_TRACE'] = {
+        'EXPORTER': exporter,
+        'SAMPLER': sampler,
+    }
+
+    app = main({}, **settings)
+    server = make_server('localhost', 8080, app)
+    server.serve_forever()
+
+
+if __name__ == '__main__':
+    run_app()

examples/trace/helloworld/pyramid/simple.py

@@ -0,0 +1,63 @@
+# Copyright 2017, 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.trace.samplers import always_on
+from opencensus.trace.exporters import print_exporter
+from opencensus.trace.propagation import google_cloud_format
+
+DEFAULT_PYRAMID_TRACER_CONFIG = {
+    'SAMPLER': always_on.AlwaysOnSampler(),
+    'EXPORTER': print_exporter.PrintExporter(),
+    'PROPAGATOR': google_cloud_format.GoogleCloudFormatPropagator()
+}
+
+
+DEFAULT_PYRAMID_TRACER_PARAMS = {
+    # https://cloud.google.com/appengine/docs/flexible/python/
+    # how-instances-are-managed#health_checking
+    'BLACKLIST_PATHS': ['_ah/health'],
+}
+
+
+class PyramidTraceSettings(object):
+    def __init__(self, registry):
+        self.settings = registry.settings.get(
+            'OPENCENSUS_TRACE',
+            DEFAULT_PYRAMID_TRACER_CONFIG)
+
+        self.params = registry.settings.get(
+            'OPENCENSUS_TRACE_PARAMS',
+            DEFAULT_PYRAMID_TRACER_PARAMS)
+
+        _set_default_configs(self.settings, DEFAULT_PYRAMID_TRACER_CONFIG)
+
+        _set_default_configs(self.params, DEFAULT_PYRAMID_TRACER_PARAMS)
+
+    def __getattr__(self, attr):
+        # If not in defaults, it is something we cannot parse.
+        if attr not in DEFAULT_PYRAMID_TRACER_CONFIG:
+            raise AttributeError('Attribute {} does not exist.'.format(attr))
+
+        return self.settings[attr]
+
+
+def _set_default_configs(user_settings, default):
+    """Set the default value to user settings if user not specified
+    the value.
+    """
+    for key in default:
+        if key not in user_settings:
+            user_settings[key] = default[key]
+
+    return user_settings

opencensus/trace/ext/pyramid/__init__.py

@@ -0,0 +1,124 @@
+# Copyright 2017, 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 logging
+
+from opencensus.trace.ext import utils
+from opencensus.trace.ext.pyramid.config import PyramidTraceSettings
+
+from opencensus.trace import attributes_helper
+from opencensus.trace import execution_context
+from opencensus.trace import tracer as tracer_module
+
+
+HTTP_METHOD = attributes_helper.COMMON_ATTRIBUTES['HTTP_METHOD']
+HTTP_URL = attributes_helper.COMMON_ATTRIBUTES['HTTP_URL']
+HTTP_STATUS_CODE = attributes_helper.COMMON_ATTRIBUTES['HTTP_STATUS_CODE']
+
+_PYRAMID_TRACE_HEADER = 'X_CLOUD_TRACE_CONTEXT'
+
+BLACKLIST_PATHS = 'BLACKLIST_PATHS'
+
+
+log = logging.getLogger(__name__)
+
+
+class OpenCensusTweenFactory(object):
+    """Pyramid tweens are like wsgi middleware, but have access to things
+    like the request, response, and application registry.
+
+    The tween factory is a globally importable callable whose
+    constructor takes a request handler and application registry. It
+    will be called with a pyramid request object.
+
+    For details on pyramid tweens, see
+    https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/hooks.html#creating-a-tween
+    """
+    def __init__(self, handler, registry):
+        """Constructor for the pyramid tween
+
+        :param handler: Either the main Pyramid request handling
+        function or another tween
+        :type handler: function
+        :param registry: The pyramid application registry
+        :type registry: :class:`pyramid.registry.Registry`
+        """
+        self.handler = handler
+        self.registry = registry
+        settings = PyramidTraceSettings(registry)
+
+        self.sampler = settings.SAMPLER
+        self.exporter = settings.EXPORTER
+        self.propagator = settings.PROPAGATOR
+
+        self._blacklist_paths = settings.params.get(BLACKLIST_PATHS)
+
+    def __call__(self, request):
+        self._before_request(request)
+
+        response = self.handler(request)
+
+        self._after_request(request, response)
+
+        return response
+
+    def _before_request(self, request):
+        if utils.disable_tracing_url(request.path, self._blacklist_paths):
+            return
+
+        try:
+            header = get_context_header(request)
+            span_context = self.propagator.from_header(header)
+
+            tracer = tracer_module.Tracer(
+                span_context=span_context,
+                sampler=self.sampler,
+                exporter=self.exporter,
+                propagator=self.propagator)
+
+            span = tracer.start_span()
+
+            # Set the span name as the name of the current module name
+            span.name = '[{}]{}'.format(
+                request.method,
+                request.path)
+
+            tracer.add_attribute_to_current_span(
+                attribute_key=HTTP_METHOD,
+                attribute_value=request.method)
+            tracer.add_attribute_to_current_span(
+                attribute_key=HTTP_URL,
+                attribute_value=request.path)
+        except Exception:  # pragma: NO COVER
+            log.error('Failed to trace request', exc_info=True)
+
+    def _after_request(self, request, response):
+        if utils.disable_tracing_url(request.path, self._blacklist_paths):
+            return
+
+        try:
+            tracer = execution_context.get_opencensus_tracer()
+            tracer.add_attribute_to_current_span(
+                HTTP_STATUS_CODE,
+                str(response.status_code))
+
+            tracer.end_span()
+            tracer.finish()
+        except Exception:  # pragma: NO COVER
+            log.error('Failed to trace request', exc_info=True)
+
+
+def get_context_header(request):
+    """Get trace context header from pyramid request headers."""
+    return request.headers.get(_PYRAMID_TRACE_HEADER)

opencensus/trace/ext/pyramid/config.py

@@ -6,6 +6,7 @@ mock==2.0.0
 mysql-connector==2.1.6
 psycopg2==2.7.3.1
 pymysql==0.7.11
+pyramid==1.9.1
 pytest==3.2.2
 pytest-cov==2.5.1
 retrying==1.3.3