Merge pull request #1 from carlosalberto/initial_code_import

Initial code import

Author: carlosalberto

MANIFEST

@@ -0,0 +1 @@
+include VERSION LICENSE

Makefile

@@ -0,0 +1,25 @@
+.PHONY: test install clean clean-build clean-pyc build
+
+install: 
+	python setup.py install
+
+clean: clean-build clean-pyc
+
+clean-build:
+	python setup.py clean
+	rm -fr build/
+	rm -fr dist/
+	rm -fr .eggs/
+	rm -fr .cache/
+	find . -name '*.egg-info' -exec rm -fr {} +
+	find . -name '*.egg' -exec rm -rf {} +
+
+clean-pyc:
+	find . -name '*.pyc' -exec rm -f {} +
+	find . -name '*.pyo' -exec rm -f {} +
+	find . -name '*~' -exec rm -f {} +
+	find . -name '__pycache__' -exec rm -fr {} +
+
+build: 
+	python setup.py build
+

README.rst

@@ -1,3 +1,51 @@
 ######################
 SQLAlchemy Opentracing
 ######################
+
+This package enables OpenTracing support for SQLAlchemy.
+
+Installation
+============
+
+Run the following command::
+
+    $ pip install sqlalchemy_opentracing
+
+Getting started
+===============
+
+Please see the examples directory. Overall, basic usage requires that a tracer gets set, an Engine (or Connection) is registered, and statements get their parent spans assigned (if any):
+
+.. code-block:: python
+
+    import sqlalchemy_opentracing
+
+    sqlalchemy_opentracing.init_tracing(tracer) # A OpenTracing compatible tracer.
+    sqlalchemy_opentracing.register_connectable(engine) # A valid SQLAlchemy Engine object.
+
+    with engine.begin() as conn:
+        sel = select([users])
+        sqlalchemy_opentracing.set_traced(sel)
+        conn.execute(sel)
+
+By default, only statements marked to be traced are taken into account (explicitly through set_traced() or implicitly when registering its parent span through set_parent_span()). Alternatively, you can enable tracing of all queries under the registered Engine/Connection:
+
+.. code-block:: python
+
+    sqlalchemy_opentracing.init_tracing(tracer, trace_all=True)
+    sqlalchemy_opentracing.register_connectable(engine)
+
+    # this statement will be traced too (without a parent span, though)
+    with engine.begin() as conn:
+        sel = select([users])
+        conn.execute(sel)
+
+Further information
+===================
+
+If you’re interested in learning more about the OpenTracing standard, please visit `opentracing.io`_ or `join the mailing list`_. If you would like to implement OpenTracing in your project and need help, feel free to send us a note at `community@opentracing.io`_.
+
+.. _opentracing.io: http://opentracing.io/
+.. _join the mailing list: http://opentracing.us13.list-manage.com/subscribe?u=180afe03860541dae59e84153&id=19117aa6cd
+.. _community@opentracing.io: community@opentracing.io
+

VERSION

@@ -0,0 +1 @@
+0.1.0

examples/child-spans.py

@@ -0,0 +1,50 @@
+import os
+from sqlalchemy import MetaData, Table, Integer, String, Column, create_engine
+from sqlalchemy import select
+from sqlalchemy.schema import CreateTable
+
+import lightstep
+import sqlalchemy_opentracing
+
+DB_LOCATION = '/tmp/simple.db'
+
+tracer = lightstep.Tracer(
+    component_name='sqlalchemy-childspans',
+    access_token='{your_lightstep_token}'
+)
+
+
+if __name__ == '__main__':
+    os.remove(DB_LOCATION) # cleanup
+
+    engine = create_engine('sqlite:///%s' % DB_LOCATION)
+    conn = engine.connect()
+
+    sqlalchemy_opentracing.init_tracing(tracer)
+    sqlalchemy_opentracing.register_connectable(engine)
+
+    span = tracer.start_span('create sample')
+
+    # 1. Create a table
+    metadata = MetaData()
+    users = Table('users', metadata,
+        Column('id', Integer, primary_key=True),
+        Column('name', String),
+    )
+    creat = CreateTable(users)
+    sqlalchemy_opentracing.set_parent_span(creat, span)
+    conn.execute(creat)
+
+    # 2. Insert a single value.
+    ins = users.insert().values(name='John Doe', id=1)
+    sqlalchemy_opentracing.set_parent_span(ins, span)
+    conn.execute(ins)
+
+    # 3. Select the new value.
+    sel = select([users])
+    sqlalchemy_opentracing.set_parent_span(sel, span)
+    print conn.execute(sel).fetchone()
+
+    span.finish()
+    tracer.flush()
+

examples/simple.py

@@ -0,0 +1,30 @@
+from sqlalchemy import MetaData, Table, Integer, String, Column, create_engine
+from sqlalchemy.schema import CreateTable
+
+import lightstep
+import sqlalchemy_opentracing
+
+tracer = lightstep.Tracer(
+    component_name='sqlalchemy-simple',
+    access_token='{your_lightstep_token}'
+)
+
+if __name__ == '__main__':
+    engine = create_engine('sqlite:///:memory:')
+
+    sqlalchemy_opentracing.init_tracing(tracer)
+    sqlalchemy_opentracing.register_connectable(engine)
+
+    metadata = MetaData()
+    users = Table('users', metadata,
+        Column('id', Integer, primary_key=True),
+        Column('name', String),
+    )
+    creat = CreateTable(users)
+    sqlalchemy_opentracing.set_traced(creat)
+
+    with engine.begin() as conn:
+        conn.execute(creat)
+
+    tracer.flush()
+

setup.cfg

@@ -0,0 +1,2 @@
+[metadata]
+description-file = README.rst

setup.py

@@ -0,0 +1,27 @@
+from setuptools import setup
+
+version = open('VERSION').read()
+setup(
+    name='sqlalchemy_opentracing',
+    version=version,
+    url='https://github.com/carlosalberto/python-sqlalchemy/',
+    download_url='https://github.com/carlosalberto/python-sqlalchemy/tarball/'+version,
+    license='BSD',
+    author='Carlos Alberto Cortez',
+    author_email='calberto.cortez@gmail.com',
+    description='OpenTracing support for SQLAlchemy',
+    long_description=open('README.rst').read(),
+    packages=['sqlalchemy_opentracing'],
+    platforms='any',
+    install_requires=[
+        'sqlalchemy',
+        'opentracing>=1.1,<1.2'
+    ],
+    classifiers=[
+        'Intended Audience :: Developers',
+        'License :: OSI Approved :: BSD License',
+        'Operating System :: OS Independent',
+        'Programming Language :: Python',
+        'Topic :: Software Development :: Libraries :: Python Modules',
+    ]
+)

sqlalchemy_opentracing/__init__.py

@@ -0,0 +1,125 @@
+from sqlalchemy.event import listen, remove
+
+g_tracer = None
+g_trace_all = True
+
+def init_tracing(tracer, trace_all=False):
+    '''
+    Set our global tracer.
+    Tracer objects from our pyramid/flask/django libraries
+    can be passed as well.
+    '''
+    global g_tracer, g_trace_all
+    if hasattr(tracer, '_tracer'):
+        g_tracer = tracer._tracer
+    else:
+        g_tracer = tracer
+
+    g_trace_all = trace_all
+
+def get_traced(stmt_obj):
+    '''
+    Gets a bool indicating whether or not this
+    statement is marked for tracing.
+    '''
+    return getattr(stmt_obj, '_traced', False)
+
+def set_traced(stmt_obj):
+    '''
+    Mark a statement to be traced.
+    '''
+    stmt_obj._traced = True
+
+def get_parent_span(stmt_obj):
+    '''
+    Gets a parent span for this statement, if any.
+    '''
+    return getattr(stmt_obj, '_parent_span', None)
+
+def set_parent_span(stmt_obj, parent_span):
+    '''
+    Marks a statement as a child of a span.
+    It gets marked to be traced if it wasn't before.
+    '''
+    stmt_obj._parent_span = parent_span
+    stmt_obj._traced = True
+
+def has_parent_span(stmt_obj):
+    '''
+    Get whether or not the statement has
+    a parent span.
+    '''
+    return hasattr(stmt_obj, '_parent_span')
+
+def get_span(stmt_obj):
+    '''
+    Get the span of a statement object, if any.
+    '''
+    return getattr(stmt_obj, '_span', None)
+
+def register_connectable(obj):
+    '''
+    Register an object to have its events be traced.
+    Any Connectable object is accepted, which
+    includes Connection and Engine.
+    '''
+    listen(obj, 'before_cursor_execute', _before_cursor_handler)
+    listen(obj, 'after_cursor_execute', _after_cursor_handler)
+    listen(obj, 'handle_error', _error_handler)
+
+def unregister_connectable(obj):
+    '''
+    Remove a connectable from having its events being
+    traced.
+    '''
+    remove(obj, 'before_cursor_execute', _before_cursor_handler)
+    remove(obj, 'after_cursor_execute', _after_cursor_handler)
+    remove(obj, 'handle_error', _error_handler)
+
+def _get_operation_name(stmt_obj):
+    return stmt_obj.__visit_name__
+
+def _normalize_stmt(statement):
+    return statement.strip().replace('\n', '').replace('\t', '')
+
+def _before_cursor_handler(conn, cursor, statement, parameters, context, executemany):
+    if context.compiled is None: # PRAGMA
+        return
+
+    # Don't trace if trace_all is disabled and the statement wasn't marked
+    stmt_obj = context.compiled.statement
+    if not (g_trace_all or get_traced(stmt_obj)):
+        return
+
+    parent_span = get_parent_span(stmt_obj)
+    operation_name = _get_operation_name(stmt_obj)
+
+    # Start a new span for this query.
+    span = g_tracer.start_span(operation_name=operation_name, child_of=parent_span)
+    span.set_tag('component', 'sqlalchemy')
+    span.set_tag('db.type', 'sql')
+    span.set_tag('db.statement', _normalize_stmt(statement))
+
+    stmt_obj._span = span
+
+def _after_cursor_handler(conn, cursor, statement, parameters, context, executemany):
+    if context.compiled is None: # PRAGMA
+        return
+
+    stmt_obj = context.compiled.statement
+    span = get_span(stmt_obj)
+    if span is None:
+        return
+
+    span.finish()
+
+def _error_handler(exception_context):
+    execution_context = exception_context.execution_context
+    stmt_obj = execution_context.compiled.statement
+    span = get_span(stmt_obj)
+    if span is None:
+        return
+
+    span.set_tag('error', 'true')
+    span.finish()
+