Merge pull request #43 from instana/urllib3

Urllib3 instrumentation & tests

Author: pglombardo

.gitignore

@@ -42,6 +42,7 @@ htmlcov/
 .coverage.*
 .cache
 nosetests.xml
+nosetests.json
 coverage.xml
 *,cover
 .hypothesis/

.travis.yml

@@ -5,5 +5,5 @@ python:
   - "3.4"
   - "3.5"
   - "3.6"
-install: "pip install -r requirements.txt"
+install: "pip install -r test_requirements.txt"
 script: nosetests -v

Configuration.md

@@ -1 +1,21 @@
-TBD
+# Configuration
+
+## Agent Communication
+
+The sensor tries to communicate with the Instana agent via IP 127.0.0.1 and as a fallback via the host's default gateway for containerized environments. Should the agent not be available under either of these IPs, e.g. due to iptables or other networking tricks, you can use environment variables to configure where the Instana host agent lives.
+
+To use these, these environment variables should be set in the environment of the running Python process.
+
+```shell
+export INSTANA_AGENT_IP = '127.0.0.1'
+export INSTANA_AGENT_PORT = '42699'
+```
+
+## Debugging & More Verbosity
+
+Setting `INSTANA_DEV` to a non nil value will enable extra logging output generally useful
+for development.
+
+```Python
+export INSTANA_DEV="true"
+```

README.md

@@ -35,14 +35,6 @@ To enable the Flask instrumentation, set the following environment variable in y
 
   `export AUTOWRAPT_BOOTSTRAP=flask`
 
-## Runtime Monitoring Only
-
-_Note: When the Django or Flask instrumentation is used, runtime monitoring is automatically included.  Use this section if you only want to see runtime metrics._
-
-To enable runtime monitoring (without request tracing), set the following environment variable in your _application boot environment_ and then restart your application:
-
-  `export AUTOWRAPT_BOOTSTRAP=runtime`
-  
 ## uWSGI
 
 ### Threads
@@ -57,9 +49,27 @@ If you use uWSGI in forking workers mode, you must specify `--lazy-apps` (or `la
 
 The instana package will automatically collect key metrics from your Python processes.  Just install and go.
 
-## Tracing
+## OpenTracing
+
+This Python package supports [OpenTracing](http://opentracing.io/).  When using this package, the OpenTracing tracer (`opentracing.tracer`) is automatically set to the `InstanaTracer`.
+
+```Python
+import opentracing
+
+parent_span = opentracing.tracer.start_span(operation_name="asteroid")
+# ... work
+child_span = opentracing.tracer.start_span(operation_name="spacedust", child_of=parent_span)
+child_span.set_tag(ext.SPAN_KIND, ext.SPAN_KIND_RPC_CLIENT)
+# ... work
+child_span.finish()
+# ... work
+parent_span.finish()
+```
+
+## Configuration
+
+See [Configuration.md](https://github.com/instana/python-sensor/blob/master/Configuration.md)
 
-This Python package supports [OpenTracing](http://opentracing.io/).
 
 ## Documentation
 

instana/__init__.py

@@ -1,8 +1,20 @@
+from __future__ import absolute_import
+import opentracing
+from .sensor import Sensor
+from .tracer import InstanaTracer
+from .options import Options
+
+# Import & initialize instrumentation
+from .instrumentation import urllib3
+
 """
-Instana sensor and tracer. It consists of two modules that can be used as entry points:
+The Instana package has two core components: the sensor and the tracer.
+
+The sensor is individual to each python process and handles process metric
+collection and reporting.
 
-- sensor: activates the meter to collect and transmit all kind of built-in metrics
-- tracer: OpenTracing tracer implementation. It implicitly activates the meter
+The tracer upholds the OpenTracing API and is responsible for reporting
+span data to Instana.
 """
 
 __author__ = 'Instana Inc.'
@@ -13,4 +25,25 @@
 __maintainer__ = 'Peter Giacomo Lombardo'
 __email__ = '[email protected]'
 
-__all__ = ['sensor', 'tracer']
+# For any given Python process, we only want one sensor as multiple would
+# collect/report metrics in duplicate, triplicate etc..
+#
+# Usage example:
+#
+# import instana
+# instana.global_sensor
+#
+global_sensor = Sensor(Options())
+
+# The global OpenTracing compatible tracer used internally by
+# this package.
+#
+# Usage example:
+#
+# import instana
+# instana.internal_tracer.start_span(...)
+#
+internal_tracer = InstanaTracer()
+
+# Set ourselves as the tracer.
+opentracing.tracer = internal_tracer

instana/django.py

@@ -1,6 +1,6 @@
 from __future__ import print_function
 import opentracing as ot
-from instana import tracer, options
+from instana import internal_tracer
 import opentracing.ext.tags as ext
 import os
 
@@ -12,17 +12,15 @@ class InstanaMiddleware(object):
     """ Django Middleware to provide request tracing for Instana """
     def __init__(self, get_response):
         self.get_response = get_response
-        opts = options.Options(service="Django")
-        ot.global_tracer = tracer.InstanaTracer(opts)
         self
 
     def __call__(self, request):
         env = request.environ
         if 'HTTP_X_INSTANA_T' in env and 'HTTP_X_INSTANA_S' in env:
-            ctx = ot.global_tracer.extract(ot.Format.HTTP_HEADERS, env)
-            span = ot.global_tracer.start_span("django", child_of=ctx)
+            ctx = internal_tracer.extract(ot.Format.HTTP_HEADERS, env)
+            span = internal_tracer.start_span("django", child_of=ctx)
         else:
-            span = ot.global_tracer.start_span("django")
+            span = internal_tracer.start_span("django")
 
         span.set_tag(ext.HTTP_URL, env['PATH_INFO'])
         span.set_tag("http.params", env['QUERY_STRING'])
@@ -37,7 +35,7 @@ def __call__(self, request):
             span.set_tag("ec", ec+1)
 
         span.set_tag(ext.HTTP_STATUS_CODE, response.status_code)
-        ot.global_tracer.inject(span.context, ot.Format.HTTP_HEADERS, response)
+        internal_tracer.inject(span.context, ot.Format.HTTP_HEADERS, response)
         span.finish()
         return response
 

instana/django19.py

@@ -1,6 +1,6 @@
 from __future__ import print_function
 import opentracing as ot
-from instana import tracer, options
+from instana import internal_tracer
 import opentracing.ext.tags as ext
 import os
 
@@ -11,18 +11,16 @@
 class InstanaMiddleware19(object):
     """ Django 1.9 Middleware to provide request tracing for Instana """
     def __init__(self):
-        opts = options.Options(service="Django")
-        ot.global_tracer = tracer.InstanaTracer(opts)
         self.span = None
         self
 
     def process_request(self, request):
         env = request.environ
         if 'HTTP_X_INSTANA_T' in env and 'HTTP_X_INSTANA_S' in env:
-            ctx = ot.global_tracer.extract(ot.Format.HTTP_HEADERS, env)
-            span = ot.global_tracer.start_span("django", child_of=ctx)
+            ctx = internal_tracer.extract(ot.Format.HTTP_HEADERS, env)
+            span = internal_tracer.start_span("django", child_of=ctx)
         else:
-            span = ot.global_tracer.start_span("django")
+            span = internal_tracer.start_span("django")
 
         span.set_tag(ext.HTTP_URL, env['PATH_INFO'])
         span.set_tag("http.params", env['QUERY_STRING'])
@@ -38,7 +36,7 @@ def process_response(self, request, response):
                 self.span.set_tag("ec", ec+1)
 
             self.span.set_tag(ext.HTTP_STATUS_CODE, response.status_code)
-            ot.global_tracer.inject(self.span.context, ot.Format.HTTP_HEADERS, response)
+            internal_tracer.inject(self.span.context, ot.Format.HTTP_HEADERS, response)
             self.span.finish()
             self.span = None
         return response

instana/fsm.py

@@ -124,7 +124,7 @@ def announce_sensor(self, e):
                 cmdinfo = cmd.read()
             cmdline = cmdinfo.split('\x00')
         else:
-            cmdline = [os.path.basename(sys.executable)]
+            cmdline = [sys.executable]
             cmdline += sys.argv
 
         d = Discovery(pid=pid,

instana/instrumentation/__init__.py

@@ -0,0 +1,37 @@
+from __future__ import absolute_import
+import opentracing.ext.tags as ext
+import instana
+import opentracing
+import wrapt
+
+
+@wrapt.patch_function_wrapper('urllib3', 'PoolManager.urlopen')
+def urlopen_with_instana(wrapped, instance, args, kwargs):
+    try:
+        context = instana.internal_tracer.current_context()
+        span = instana.internal_tracer.start_span("urllib3", child_of=context)
+        span.set_tag(ext.HTTP_URL, args[1])
+        span.set_tag(ext.HTTP_METHOD, args[0])
+
+        instana.internal_tracer.inject(span.context, opentracing.Format.HTTP_HEADERS, kwargs["headers"])
+        rv = wrapped(*args, **kwargs)
+
+        span.set_tag(ext.HTTP_STATUS_CODE, rv.status)
+        if 500 <= rv.status <= 599:
+            span.set_tag("error", True)
+            ec = span.tags.get('ec', 0)
+            span.set_tag("ec", ec+1)
+
+    except Exception as e:
+        span.log_kv({'message': e})
+        span.set_tag("error", True)
+        ec = span.tags.get('ec', 0)
+        span.set_tag("ec", ec+1)
+        span.finish()
+        raise
+    else:
+        span.finish()
+        return rv
+
+
+instana.log.debug("Instrumenting urllib3")