Urllib3 instrumentation & tests

.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__ = 'peter.lombardo@instana.com'
 
-__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/urllib3.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")

instana/probe.py

@@ -10,4 +10,4 @@
 #    c. Detect and instrument any libraries
 
 opts = options.Options()
-ot.global_tracer = tracer.InstanaTracer(opts)
+ot.tracer = tracer.InstanaTracer(opts)

instana/recorder.py

@@ -16,7 +16,7 @@
 
 class InstanaRecorder(SpanRecorder):
     sensor = None
-    registered_spans = ("django", "memcache", "rpc-client", "rpc-server", "wsgi")
+    registered_spans = ("django", "memcache", "rpc-client", "rpc-server", "urllib3", "wsgi")
     entry_kind = ["entry", "server", "consumer"]
     exit_kind = ["exit", "client", "producer"]
     queue = queue.Queue()

instana/runtime.py

@@ -12,4 +12,4 @@ def hook(module):
             print("==========================================================")
 
         opts = options.Options()
-        ot.global_tracer = tracer.InstanaTracer(opts)
+        ot.tracer = tracer.InstanaTracer(opts)

instana/span.py

@@ -8,11 +8,12 @@ class InstanaSpan(object):
     n = None
     f = None
     ec = 0
-    error = False
+    error = None
     data = None
 
     def __init__(self, **kwds):
-        self.__dict__.update(kwds)
+        for key in kwds:
+            self.__dict__[key] = kwds[key]
 
 
 class Data(object):

instana/tracer.py

@@ -2,31 +2,22 @@
 from basictracer import BasicTracer
 import instana.recorder as r
 import opentracing as ot
+import instana
 import instana.options as o
-import instana.sensor as s
 
 from basictracer.context import SpanContext
 from basictracer.span import BasicSpan
 from instana.http_propagator import HTTPPropagator
 from instana.text_propagator import TextPropagator
 from instana.util import generate_id
 
-# In case a user or app creates multiple tracers, we limit to just
-# one sensor per process otherwise metrics collection is duplicated,
-# triplicated etc.
-gSensor = None
-
 
 class InstanaTracer(BasicTracer):
     sensor = None
+    current_span = None
 
     def __init__(self, options=o.Options()):
-        global gSensor
-        if gSensor is None:
-            self.sensor = s.Sensor(options)
-            gSensor = self.sensor
-        else:
-            self.sensor = gSensor
+        self.sensor = instana.global_sensor
         super(InstanaTracer, self).__init__(
             r.InstanaRecorder(self.sensor), r.InstanaSampler())
 
@@ -67,14 +58,19 @@ def start_span(
             ctx.sampled = self.sampler.sampled(ctx.trace_id)
 
         # Tie it all together
-        return BasicSpan(
+        self.current_span = BasicSpan(
             self,
             operation_name=operation_name,
             context=ctx,
             parent_id=(None if parent_ctx is None else parent_ctx.span_id),
             tags=tags,
             start_time=start_time)
 
+        return self.current_span
+
+    def current_context(self):
+        return self.current_span.context
+
     def inject(self, span_context, format, carrier):
         if format in self._propagators:
             self._propagators[format].inject(span_context, carrier)

instana/wsgi.py

@@ -1,5 +1,5 @@
 import opentracing as ot
-from instana import tracer, options
+from instana import internal_tracer
 import opentracing.ext.tags as tags
 
 
@@ -8,16 +8,14 @@ class iWSGIMiddleware(object):
 
     def __init__(self, app):
         self.app = app
-        opts = options.Options()
-        ot.global_tracer = tracer.InstanaTracer(opts)
         self
 
     def __call__(self, environ, start_response):
         env = environ
 
         def new_start_response(status, headers, exc_info=None):
             """Modified start response with additional headers."""
-            ot.global_tracer.inject(span.context, ot.Format.HTTP_HEADERS, headers)
+            internal_tracer.inject(span.context, ot.Format.HTTP_HEADERS, headers)
             res = start_response(status, headers, exc_info)
 
             sc = status.split(' ')[0]
@@ -31,10 +29,10 @@ def new_start_response(status, headers, exc_info=None):
             return res
 
         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("wsgi", child_of=ctx)
+            ctx = internal_tracer.extract(ot.Format.HTTP_HEADERS, env)
+            span = internal_tracer.start_span("wsgi", child_of=ctx)
         else:
-            span = ot.global_tracer.start_span("wsgi")
+            span = internal_tracer.start_span("wsgi")
 
         span.set_tag(tags.HTTP_URL, env['PATH_INFO'])
         span.set_tag("http.params", env['QUERY_STRING'])

requirements.txt

@@ -1,4 +1,3 @@
-nose>=1.0
 fysom>=2.1.2
 opentracing>=1.2.1
 basictracer>=2.2.0