Add tracing blacklist (#71)

Author: liyanhui1228

README.rst

@@ -135,6 +135,34 @@ SpanContext and headers. Currently support
     # Serialize
     header = propagator.to_header(span_context)
 
+Blacklist Paths
+~~~~~~~~~~~~~~~
+
+You can specify which paths you do not want to trace by configuring the
+blacklist paths. By default the health check path in GAE Flex is not traced,
+but you can turn it on in the setting.
+
+Here is the sample code for configuring the blacklist:
+
+For Flask:
+
+.. code:: python
+
+    from opencensus.trace.ext.flask.flask_middleware import FlaskMiddleware
+
+    app = flask.Flask(__name__)
+
+    blacklist_paths = ['_ah/health']
+    middleware = FlaskMiddleware(app, blacklist_paths=blacklist_paths)
+
+For Django:
+
+Add this line in the OPENCENSUS_PARAMS:
+
+::
+
+    'BLACKLIST_PATHS': ['_ah/health',]
+
 Framework Integration
 ---------------------
 
@@ -188,6 +216,20 @@ Customize the sampler, exporter, propagator in the ``settings.py`` file:
                       'GoogleCloudFormatPropagator',
     }
 
+Configure the sampling rate and other params:
+
+::
+
+    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,
+
+    }
+
 Then the requests will be automatically traced.
 
 Webapp2

trace/opencensus/trace/ext/django/config.py

@@ -26,11 +26,15 @@
 }
 
 DEFAULT_DJANGO_TRACER_PARAMS = {
-    'SAMPLING_RATE': 0.5,
+    # https://cloud.google.com/appengine/docs/flexible/python/
+    # how-instances-are-managed#health_checking
+    '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,
+
 }
 
 

trace/opencensus/trace/ext/django/middleware.py

@@ -30,12 +30,14 @@
 
 _DJANGO_TRACE_HEADER = 'HTTP_X_CLOUD_TRACE_CONTEXT'
 
+BLACKLIST_PATHS = 'BLACKLIST_PATHS'
 GCP_EXPORTER_PROJECT = 'GCP_EXPORTER_PROJECT'
 SAMPLING_RATE = 'SAMPLING_RATE'
 ZIPKIN_EXPORTER_SERVICE_NAME = 'ZIPKIN_EXPORTER_SERVICE_NAME'
 ZIPKIN_EXPORTER_HOST_NAME = 'ZIPKIN_EXPORTER_HOST_NAME'
 ZIPKIN_EXPORTER_PORT = 'ZIPKIN_EXPORTER_PORT'
 
+
 log = logging.getLogger(__name__)
 
 
@@ -94,6 +96,8 @@ def __init__(self, get_response=None):
         self._exporter = settings.EXPORTER
         self._propagator = settings.PROPAGATOR
 
+        self._blacklist_paths = settings.params.get(BLACKLIST_PATHS)
+
         # Initialize the sampler
         if self._sampler.__name__ == 'ProbabilitySampler':
             _rate = settings.params.get(
@@ -129,6 +133,10 @@ def process_request(self, request):
         :type request: :class:`~django.http.request.HttpRequest`
         :param request: Django http request.
         """
+        # Do not trace if the url is blacklisted
+        if utils.disable_tracing_url(request.path, self._blacklist_paths):
+            return
+
         # Add the request to thread local
         execution_context.set_opencensus_attr(
             REQUEST_THREAD_LOCAL_KEY,
@@ -161,6 +169,10 @@ def process_view(self, request, view_func, *args, **kwargs):
         """Process view is executed before the view function, here we get the
         function name add set it as the span name.
         """
+        # Do not trace if the url is blacklisted
+        if utils.disable_tracing_url(request.path, self._blacklist_paths):
+            return
+
         try:
             # Get the current span and set the span name to the current
             # function name of the request.
@@ -171,6 +183,10 @@ def process_view(self, request, view_func, *args, **kwargs):
             log.error('Failed to trace request', exc_info=True)
 
     def process_response(self, request, response):
+        # Do not trace if the url is blacklisted
+        if utils.disable_tracing_url(request.path, self._blacklist_paths):
+            return response
+
         try:
             tracer = _get_current_request_tracer()
             tracer.add_label_to_current_span(

trace/opencensus/trace/ext/flask/flask_middleware.py

@@ -19,6 +19,7 @@
 from opencensus.trace import execution_context
 from opencensus.trace.propagation import google_cloud_format
 from opencensus.trace.exporters import print_exporter
+from opencensus.trace.ext import utils
 from opencensus.trace.samplers import always_on
 from opencensus.trace import request_tracer
 
@@ -37,6 +38,9 @@ class FlaskMiddleware(object):
     :type app: :class: `~flask.Flask`
     :param app: A flask application.
 
+    :type blacklist_paths: list
+    :param blacklist_paths: Paths that do not trace.
+
     :type sampler: :class: `type`
     :param sampler: Class for creating new Sampler objects. It should extend
                     from the base :class:`.Sampler` type and implement
@@ -48,8 +52,16 @@ class FlaskMiddleware(object):
     :param exporter: Class for creating new exporter objects. Default to
                      :class:`.PrintExporter`. The rest option is
                      :class:`.FileExporter`.
+
+    :type propagator: :class: 'type'
+    :param propagator: Class for creating new propagator objects. Default to
+                       :class:`.GoogleCloudFormatPropagator`. The rest option
+                       are :class:`.BinaryFormatPropagator`,
+                       :class:`.TextFormatPropagator` and
+                       :class:`.TraceContextPropagator`.
     """
-    def __init__(self, app, sampler=None, exporter=None, propagator=None):
+    def __init__(self, app, blacklist_paths=None, sampler=None, exporter=None,
+                 propagator=None):
         if sampler is None:
             sampler = always_on.AlwaysOnSampler()
 
@@ -60,6 +72,7 @@ def __init__(self, app, sampler=None, exporter=None, propagator=None):
             propagator = google_cloud_format.GoogleCloudFormatPropagator()
 
         self.app = app
+        self.blacklist_paths = blacklist_paths
         self.sampler = sampler
         self.exporter = exporter
         self.propagator = propagator
@@ -74,6 +87,10 @@ def _before_request(self):
 
         See: http://flask.pocoo.org/docs/0.12/api/#flask.Flask.before_request
         """
+        # Do not trace if the url is blacklisted
+        if utils.disable_tracing_url(flask.request.url, self.blacklist_paths):
+            return
+
         try:
             header = get_flask_header()
             span_context = self.propagator.from_header(header)
@@ -100,6 +117,10 @@ def _after_request(self, response):
 
         See: http://flask.pocoo.org/docs/0.12/api/#flask.Flask.after_request
         """
+        # Do not trace if the url is blacklisted
+        if utils.disable_tracing_url(flask.request.url, self.blacklist_paths):
+            return response
+
         try:
             tracer = execution_context.get_opencensus_tracer()
             tracer.add_label_to_current_span(

trace/opencensus/trace/ext/utils.py

@@ -12,6 +12,18 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import re
+
+# By default the blacklist urls are not tracing, currently just include the
+# health check url. The paths are literal string matched instead of regular
+# expressions. Do not include the '/' at the beginning of the path.
+DEFAULT_BLACKLIST_PATHS = [
+    '_ah/health',
+]
+
+# Pattern for matching the 'https://', 'http://', 'ftp://' part.
+URL_PATTERN = '^(https?|ftp):\\/\\/'
+
 
 def get_func_name(func):
     """Return a name which includes the module name and function name."""
@@ -23,3 +35,31 @@ def get_func_name(func):
         return '{}.{}'.format(module_name, func_name)
 
     return func_name
+
+
+def disable_tracing_url(url, blacklist_paths=None):
+    """Disable tracing on the provided blacklist paths, by default not tracing
+    the health check request.
+
+    If the url path starts with the blacklisted path, return True.
+
+    :type blacklist_paths: list
+    :param blacklist_paths: Paths that not tracing.
+
+    :rtype: bool
+    :returns: True if not tracing, False if tracing.
+    """
+    if blacklist_paths is None:
+        blacklist_paths = DEFAULT_BLACKLIST_PATHS
+
+    # Remove the 'https?|ftp://' if exists
+    url = re.sub(URL_PATTERN, '', url)
+
+    # Split the url by the first '/' and get the path part
+    url_path = url.split('/', 1)[1]
+
+    for path in blacklist_paths:
+        if url_path.startswith(path):
+            return True
+
+    return False

trace/tests/system/django/app/settings.py

@@ -72,16 +72,9 @@
                   'GoogleCloudFormatPropagator',
 }
 
-DEFAULT_DJANGO_TRACER_PARAMS = {
-    'SAMPLING_RATE': 0.5,
-    'GCP_REPORTER_PROJECT': os.environ.get('GCLOUD_PROJECT_PYTHON'),
-    'ZIPKIN_REPORTER_SERVICE_NAME': 'my_service',
-    'ZIPKIN_REPORTER_HOST_NAME': 'localhost',
-    'ZIPKIN_REPORTER_PORT': 9411,
-}
-
 OPENCENSUS_TRACE_PARAMS = {
     'SAMPLING_RATE': 0.5,
+    'BLACKLIST_PATHS': ['_ah/health',]
 }
 
 # Internationalization

trace/tests/unit/ext/django/test_middleware.py

@@ -198,6 +198,57 @@ def test_process_request(self):
 
         self.assertEqual(span.name, 'mock.mock.Mock')
 
+    def test_blacklist_path(self):
+        from django.test import RequestFactory
+
+        from opencensus.trace.ext.django import middleware
+        from opencensus.trace.tracer import base
+        from opencensus.trace.tracer import noop_tracer
+        from opencensus.trace.ext import utils
+        from opencensus.trace import execution_context
+
+        execution_context.clear()
+
+        blacklist_paths = ['test_blacklist_path',]
+        params = {'BLACKLIST_PATHS': ['test_blacklist_path',]}
+        patch_params = mock.patch(
+            'opencensus.trace.ext.django.middleware.settings.params',
+            params)
+
+        with patch_params:
+            middleware_obj = middleware.OpencensusMiddleware()
+
+        django_request = RequestFactory().get('/test_blacklist_path')
+        disabled = utils.disable_tracing_url(django_request.path,
+                                             blacklist_paths)
+        self.assertTrue(disabled)
+        self.assertEqual(middleware_obj._blacklist_paths, blacklist_paths)
+
+        # test process_request
+        middleware_obj.process_request(django_request)
+
+        tracer = middleware._get_current_request_tracer()
+        span = tracer.current_span()
+
+        # process view
+        view_func = mock.Mock()
+        middleware_obj.process_view(django_request, view_func)
+
+        tracer = middleware._get_current_request_tracer()
+        span = tracer.current_span()
+
+        assert isinstance(span, base.NullContextManager)
+
+        # process response
+        django_response = mock.Mock()
+        django_response.status_code = 200
+
+        middleware_obj.process_response(django_request, django_response)
+
+        tracer = middleware._get_current_request_tracer()
+        span = tracer.current_span()
+        assert isinstance(span, base.NullContextManager)
+
     def test_process_response(self):
         from django.test import RequestFactory
 

trace/tests/unit/ext/flask/test_flask_middleware.py

@@ -34,6 +34,10 @@ def create_app():
         def index():
             return 'test flask trace'  # pragma: NO COVER
 
+        @app.route('/_ah/health')
+        def health_check():
+            return 'test health check'  # pragma: NO COVER
+
         return app
 
     def tearDown(self):
@@ -109,6 +113,31 @@ def test__before_request(self):
             span_context = tracer.span_context
             self.assertEqual(span_context.trace_id, trace_id)
 
+    def test__before_request_blacklist(self):
+        from opencensus.trace import execution_context
+        from opencensus.trace.tracer import base
+        from opencensus.trace.tracer import noop_tracer
+
+        flask_trace_header = 'X_CLOUD_TRACE_CONTEXT'
+        trace_id = '2dd43a1d6b2549c6bc2a1a54c2fc0b05'
+        span_id = 1234
+        flask_trace_id = '{}/{}'.format(trace_id, span_id)
+
+        app = self.create_app()
+        flask_middleware.FlaskMiddleware(app=app)
+        context = app.test_request_context(
+            path='/_ah/health',
+            headers={flask_trace_header: flask_trace_id})
+
+        with context:
+            app.preprocess_request()
+            tracer = execution_context.get_opencensus_tracer()
+            assert isinstance(tracer, noop_tracer.NoopTracer)
+
+            span = tracer.current_span()
+
+            assert isinstance(span, base.NullContextManager)
+
     def test_header_encoding(self):
         # The test is for detecting the encoding compatibility issue in
         # Python2 and Python3 and what flask does for encoding the headers.
@@ -203,3 +232,24 @@ def test__after_request_sampled(self):
             headers={flask_trace_header: flask_trace_id})
 
         self.assertEqual(response.status_code, 200)
+
+    def test__after_request_blacklist(self):
+        from opencensus.trace import execution_context
+        from opencensus.trace.tracer import noop_tracer
+
+        flask_trace_header = 'X_CLOUD_TRACE_CONTEXT'
+        trace_id = '2dd43a1d6b2549c6bc2a1a54c2fc0b05'
+        span_id = 1234
+        flask_trace_id = '{}/{}'.format(trace_id, span_id)
+
+        app = self.create_app()
+        flask_middleware.FlaskMiddleware(app=app)
+
+        response = app.test_client().get(
+            '/_ah/health',
+            headers={flask_trace_header: flask_trace_id})
+
+        tracer = execution_context.get_opencensus_tracer()
+
+        self.assertEqual(response.status_code, 200)
+        assert isinstance(tracer, noop_tracer.NoopTracer)