Updated package initialization; automatic tracer instantiation

Author: pglombardo

instana/__init__.py

@@ -1,8 +1,17 @@
+from __future__ import absolute_import
+import opentracing
+from .sensor import Sensor
+from .tracer import InstanaTracer
+from .options import Options
+
 """
-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 +22,30 @@
 __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
+
+
+def load_instrumentation():
+    # Import & initialize instrumentation
+    from .instrumentation import urllib3

instana/tracer.py

@@ -2,31 +2,21 @@
 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
 
     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())
 

tests/__init__.py

@@ -2,13 +2,9 @@
 import os
 import time
 import threading
-import opentracing
-import instana.tracer
 from .apps.flaskalino import app as flaskalino
 os.environ["INSTANA_TEST"] = "true"
 
-opentracing.global_tracer = instana.tracer.InstanaTracer()
-
 # Spawn our background Flask app that the tests will throw
 # requests at.  Don't continue until the test app is fully
 # up and running.