add trace_future

CHANGELOG.md

 # v2.9.15
 
+* add `trace_future`
+

docs/index.rst

@@ -30,6 +30,7 @@ Visit the project's page at GitHub_!
            exceptions
            processes
            cassandra
+           opentracing
 
 
 Indices and tables

docs/opentracing.rst

+**This module is available only if you have opentracing installed**
+
+OpenTracing
+===========
+
+trace_future
+------------
+
+.. autofunction:: satella.opentracing.trace_future
+

satella/__init__.py

-__version__ = '2.9.15_a1'
+__version__ = '2.9.15_a2'

satella/opentracing/__init__.py

+from .trace import trace_future
+
+__all__ = ['trace_future']

satella/opentracing/trace.py

+import typing as tp
+from concurrent.futures import Future
+try:
+    from opentracing import Span
+except ImportError:
+    class Span:
+        pass
+
+try:
+    from cassandra.cluster import ResponseFuture
+except ImportError:
+    class ResponseFuture:
+        pass
+
+
+def trace_future(future: tp.Union[ResponseFuture, Future], span: Span):
+    """
+    Install a handler that will close a span upon a future completing, attaching the exception
+    contents if the future ends with an exception.
+
+    :param future: can be either a normal Future or a Cassandra's ResponseFuture
+    :param span: span to close
+    """
+    if isinstance(future, ResponseFuture):
+        def close_exception(exc):
+            Span._on_error(span, type(exc), exc, '<unavailable>')
+            span.finish()
+
+        future.add_callback(span.finish)
+        future.add_errback(close_exception)
+    else:
+        def close_future(fut):
+            exc = fut.exception()
+            if exc is not None:
+                Span._on_error(span, type(exc), exc, '<unavailable>')
+            span.finish()
+        future.add_done_callback(close_future)

setup.py

@@ -15,6 +15,7 @@ setup(keywords=['ha', 'high availability', 'scalable', 'scalability', 'server',
             'YAMLSource': ['pyyaml'],
             'TOMLSource': ['toml'],
             'FasterJSONSource': ['ujson'],
-            'cassandra': ['cassandra-driver']
+            'cassandra': ['cassandra-driver'],
+            'opentracing': ['opentracing']
       }
       )