Merge branch 'master' into better-django

Author: pglombardo

Configuration.md

@@ -7,7 +7,7 @@ The sensor tries to communicate with the Instana agent via IP 127.0.0.1 and as a
 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_HOST = '127.0.0.1'
 export INSTANA_AGENT_PORT = '42699'
 ```
 

README.md

@@ -34,6 +34,10 @@ For Django version 1.9.x, instead set:
 To enable the Flask instrumentation, set the following environment variable in your _application boot environment_ and then restart your application:
 
   `export AUTOWRAPT_BOOTSTRAP=flask`
+  
+## WSGI Compliant Stacks
+
+The Instana sensor bundles with it WSGI middleware.  The usage of this middleware is automated for various frameworks but for those that arent' supported yet, see the [WSGI documentation](WSGI.md) for details on how to manually add it to your stack.
 
 ## Runtime Monitoring Only
 
@@ -53,6 +57,26 @@ This Python instrumentation spawns a lightweight background thread to periodical
 
 If you use uWSGI in forking workers mode, you must specify `--lazy-apps` (or `lazy-apps = true` in ini style) to load the application in the worker instead of the master process.
 
+### uWSGI Example: Command-line
+
+```sh
+uwsgi --socket 0.0.0.0:5000 --protocol=http -w wsgi -p 4 --enable-threads --lazy-apps
+```
+
+### uWSGI Example: ini file
+
+```ini
+[uwsgi]
+http = :5000
+master = true
+processes = 4
+enable-threads = true # required
+lazy-apps = true # if using "processes", set lazy-apps to true
+
+# Set the Instana sensor environment variable here
+env = AUTOWRAPT_BOOTSTRAP=flask
+```
+
 ## Usage
 
 The instana package will automatically collect key metrics from your Python processes.  Just install and go.

WSGI.md

@@ -0,0 +1,40 @@
+The Instana sensor includes WSGI middleware that can be added to any WSGI compliant stack.  This is automated for various stacks but can also be done manually for those we haven't added support for yet.
+
+The general usage is:
+
+```python
+import instana
+from instana.wsgi import iWSGIMiddleware
+
+# Wrap the wsgi app in Instana middleware (iWSGIMiddleware)
+wsgiapp = iWSGIMiddleware(MyWSGIApplication())
+```
+
+We are working to automate this for all major frameworks but in the meantime, here are some specific quick starts for those we don't have automatic support for yet.
+
+## CherryPy
+
+```python
+import cherrypy
+import instana
+from instana.wsgi import iWSGIMiddleware
+
+# My CherryPy application
+class Root(object):
+    @cherrypy.expose
+    def index(self):
+        return "hello world"
+
+cherrypy.config.update({'engine.autoreload.on': False})
+cherrypy.server.unsubscribe()
+cherrypy.engine.start()
+
+# Wrap the wsgi app in Instana middleware (iWSGIMiddleware)
+wsgiapp = iWSGIMiddleware(cherrypy.tree.mount(Root()))
+```
+
+In this example, we use uwsgi as the webserver and booted with:
+
+`uwsgi --socket 127.0.0.1:8080 --protocol=http --wsgi-file mycherry.py --callable wsgiapp -H ~/.local/share/virtualenvs/cherrypyapp-C1BUba0z`
+
+Where `~/.local/share/virtualenvs/cherrypyapp-C1BUba0z` is the path to my local virtualenv from pipenv

example/opentracing.py renamed to example/opentracing_vanilla.py

@@ -24,7 +24,7 @@
 __copyright__ = 'Copyright 2017 Instana Inc.'
 __credits__ = ['Pavlo Baron', 'Peter Giacomo Lombardo']
 __license__ = 'MIT'
-__version__ = '0.7.5'
+__version__ = '0.7.8'
 __maintainer__ = 'Peter Giacomo Lombardo'
 __email__ = '[email protected]'
 

instana/__init__.py

@@ -70,7 +70,14 @@ def lookup_agent_host(self, e):
         host = a.AGENT_DEFAULT_HOST
         port = a.AGENT_DEFAULT_PORT
 
-        if "INSTANA_AGENT_IP" in os.environ:
+        if "INSTANA_AGENT_HOST" in os.environ:
+            host = os.environ["INSTANA_AGENT_HOST"]
+            if "INSTANA_AGENT_PORT" in os.environ:
+                port = int(os.environ["INSTANA_AGENT_PORT"])
+
+        elif "INSTANA_AGENT_IP" in os.environ:
+            # Deprecated: INSTANA_AGENT_IP environment variable
+            # To be removed in a future version
             host = os.environ["INSTANA_AGENT_IP"]
             if "INSTANA_AGENT_PORT" in os.environ:
                 port = int(os.environ["INSTANA_AGENT_PORT"])

instana/fsm.py

@@ -1,14 +1,40 @@
 from __future__ import absolute_import
-import opentracing.ext.tags as ext
 import instana
+from instana.log import logger
 import opentracing
+import opentracing.ext.tags as ext
 import wrapt
 
 
 try:
-    import urllib3
+    import urllib3 # noqa
+
+    def collect(instance, args, kwargs):
+        """ Build and return a fully qualified URL for this request """
+        try:
+            kvs = {}
+
+            kvs['host'] = instance.host
+            kvs['port'] = instance.port
 
-    @wrapt.patch_function_wrapper('urllib3', 'PoolManager.urlopen')
+            if args is not None and len(args) is 2:
+                kvs['method'] = args[0]
+                kvs['path'] = args[1]
+            else:
+                kvs['method'] = kwargs['method']
+                kvs['path'] = kwargs['url']
+
+            if type(instance) is urllib3.connectionpool.HTTPSConnectionPool:
+                kvs['url'] = 'https://%s:%d%s' % (kvs['host'], kvs['port'], kvs['path'])
+            else:
+                kvs['url'] = 'http://%s:%d%s' % (kvs['host'], kvs['port'], kvs['path'])
+        except Exception as e:
+            logger.debug(e)
+            return kvs
+        else:
+            return kvs
+
+    @wrapt.patch_function_wrapper('urllib3', 'HTTPConnectionPool.urlopen')
     def urlopen_with_instana(wrapped, instance, args, kwargs):
         context = instana.internal_tracer.current_context()
 
@@ -18,8 +44,12 @@ def urlopen_with_instana(wrapped, instance, args, kwargs):
 
         try:
             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])
+
+            kvs = collect(instance, args, kwargs)
+            if 'url' in kvs:
+                span.set_tag(ext.HTTP_URL, kvs['url'])
+            if 'method' in kvs:
+                span.set_tag(ext.HTTP_METHOD, kvs['method'])
 
             instana.internal_tracer.inject(span.context, opentracing.Format.HTTP_HEADERS, kwargs["headers"])
             rv = wrapped(*args, **kwargs)

instana/instrumentation/urllib3.py

@@ -0,0 +1,56 @@
+class JsonSpan(object):
+    t = 0
+    p = None
+    s = 0
+    ts = 0
+    ta = "py"
+    d = 0
+    n = None
+    f = None
+    ec = 0
+    error = None
+    data = None
+
+    def __init__(self, **kwds):
+        for key in kwds:
+            self.__dict__[key] = kwds[key]
+
+
+class Data(object):
+    service = None
+    http = None
+    baggage = None
+    custom = None
+    sdk = None
+
+    def __init__(self, **kwds):
+        self.__dict__.update(kwds)
+
+
+class HttpData(object):
+    host = None
+    url = None
+    status = 0
+    method = None
+
+    def __init__(self, **kwds):
+        self.__dict__.update(kwds)
+
+
+class CustomData(object):
+    tags = None
+    logs = None
+
+    def __init__(self, **kwds):
+        self.__dict__.update(kwds)
+
+
+class SDKData(object):
+    name = None
+    Type = None
+    arguments = None
+    Return = None
+    custom = None
+
+    def __init__(self, **kwds):
+        self.__dict__.update(kwds)

instana/json_span.py

@@ -16,8 +16,13 @@ def __init__(self, **kwds):
             self.log_level = logging.DEBUG
 
         if "INSTANA_AGENT_IP" in os.environ:
+            # Deprecated: INSTANA_AGENT_IP environment variable
+            # To be removed in a future version
             self.agent_host = os.environ["INSTANA_AGENT_IP"]
 
+        if "INSTANA_AGENT_HOST" in os.environ:
+            self.agent_host = os.environ["INSTANA_AGENT_HOST"]
+
         if "INSTANA_AGENT_PORT" in os.environ:
             self.agent_port = os.environ["INSTANA_AGENT_PORT"]
 

instana/options.py

@@ -6,7 +6,7 @@
 
 import opentracing.ext.tags as ext
 from basictracer import Sampler, SpanRecorder
-from .span import CustomData, Data, HttpData, InstanaSpan, SDKData
+from .json_span import CustomData, Data, HttpData, JsonSpan, SDKData
 from .agent_const import AGENT_TRACES_URL
 
 import sys
@@ -65,21 +65,21 @@ def clear_spans(self):
 
     def record_span(self, span):
         """
-        Convert the passed BasicSpan into an InstanaSpan and
+        Convert the passed BasicSpan into an JsonSpan and
         add it to the span queue
         """
         if self.sensor.agent.can_send() or "INSTANA_TEST" in os.environ:
-            instana_span = None
+            json_span = None
 
             if span.operation_name in self.registered_spans:
-                instana_span = self.build_registered_span(span)
+                json_span = self.build_registered_span(span)
             else:
-                instana_span = self.build_sdk_span(span)
+                json_span = self.build_sdk_span(span)
 
-            self.queue.put(instana_span)
+            self.queue.put(json_span)
 
     def build_registered_span(self, span):
-        """ Takes a BasicSpan and converts it into a registered InstanaSpan """
+        """ Takes a BasicSpan and converts it into a registered JsonSpan """
         data = Data(http=HttpData(host=self.get_host_name(span),
                                   url=self.get_string_tag(span, ext.HTTP_URL),
                                   method=self.get_string_tag(span, ext.HTTP_METHOD),
@@ -90,7 +90,7 @@ def build_registered_span(self, span):
         entityFrom = {'e': self.sensor.agent.from_.pid,
                       'h': self.sensor.agent.from_.agentUuid}
 
-        return InstanaSpan(
+        return JsonSpan(
                     n=span.operation_name,
                     t=span.context.trace_id,
                     p=span.parent_id,
@@ -103,7 +103,7 @@ def build_registered_span(self, span):
                     data=data)
 
     def build_sdk_span(self, span):
-        """ Takes a BasicSpan and converts into an SDK type InstanaSpan """
+        """ Takes a BasicSpan and converts into an SDK type JsonSpan """
 
         custom_data = CustomData(tags=span.tags,
                                  logs=self.collect_logs(span))
@@ -116,7 +116,7 @@ def build_sdk_span(self, span):
         entityFrom = {'e': self.sensor.agent.from_.pid,
                       'h': self.sensor.agent.from_.agentUuid}
 
-        return InstanaSpan(
+        return JsonSpan(
                     t=span.context.trace_id,
                     p=span.parent_id,
                     s=span.context.span_id,