Merge pull request #3 from carlosalberto/final_refinements

Final refinements

Author: carlosalberto

Makefile

@@ -1,4 +1,4 @@
-.PHONY: test install clean clean-build clean-pyc build
+.PHONY: test publish install clean clean-build clean-pyc clean-test build
 
 install: 
 	python setup.py install
@@ -20,6 +20,27 @@ clean-pyc:
 	find . -name '*~' -exec rm -f {} +
 	find . -name '__pycache__' -exec rm -fr {} +
 
+clean-test:
+	rm -f .coverage
+
+test:
+	py.test -s --cov=sqlalchemy_opentracing
+
 build: 
 	python setup.py build
 
+publish: test build
+	@git diff-index --quiet HEAD || (echo "git has uncommitted changes. Refusing to publish." && false)
+	awk 'BEGIN { FS = "." }; { printf("%d.%d.%d", $$1, $$2, $$3+1) }' VERSION > VERSION.incr
+	mv VERSION.incr VERSION
+	git add VERSION
+	git commit -m "Update VERSION"
+	git tag `cat VERSION`
+	git push
+	git push --tags
+	python setup.py register -r pypi || (echo "Was unable to register to pypi, aborting publish." && false)
+	python setup.py sdist upload -r pypi || (echo "Was unable to upload to pypi, publish failed." && false)
+	@echo
+	@echo "\033[92mSUCCESS: published v`cat VERSION` \033[0m"
+	@echo
+

README.rst

@@ -21,7 +21,7 @@ Please see the examples directory. Overall, basic usage requires that a tracer g
     import sqlalchemy_opentracing
 
     sqlalchemy_opentracing.init_tracing(tracer) # A OpenTracing compatible tracer.
-    sqlalchemy_opentracing.register_connectable(engine) # A valid SQLAlchemy Engine object.
+    sqlalchemy_opentracing.register_engine(engine) # A valid SQLAlchemy Engine object.
 
     with engine.begin() as conn:
         sel = select([users])
@@ -40,6 +40,95 @@ By default, only statements marked to be traced are taken into account (explicit
         sel = select([users])
         conn.execute(sel)
 
+The resulting spans will have an operation name related to the sql statement (such as `create-table` or `insert`), and will include exception information (if any), the dialect/backend (such as sqlite), and a few other hints.
+
+Tracing under a Connection
+===========================
+
+It is possible to trace all statements being executed under a connection's transaction lifetime. For this, instead of marking a statement as traced, the connection is passed to set_traced() or set_parent_span():
+
+.. code-block:: python
+
+    parent_span = tracer.start_span('ParentSpan')
+    conn = engine.connect()
+
+    with conn.begin() as trans:
+        sqlalchemy_opentracing.set_parent_span(conn, parent_span)
+
+        # these three statements will be traced as children of
+        # parent_span
+        conn.execute(users.insert().values(name='John'))
+        conn.execute(users.insert().values(name='Jason'))
+        conn.execute(users.insert().values(name='Jackie'))
+
+Either a commit or a rollback on a connection's transaction will finish its tracing. If the same Connection object is used afterwards, no tracing will be done for it (unless registered for tracing again). When using (emulated) nested transactions, the tracing needs to be marked at top-level transaction time, and tracing will happen for all statements under the nested transactions:
+
+.. code-block:: python
+
+    with conn.begin() as trans:
+        sqlalchemy_opentracing.set_parent_span(conn, parent_span)
+        conn.execute(users.insert().values(name='John'))
+
+        with conn.begin() as nested_trans:
+            # This statement will also be traced as
+            # child of parent_span
+            conn.execute(users.insert().values(name='Jason'))
+
+
+Tracing under a Session (ORM)
+=============================
+
+It is also possible to trace all actual SQL statements happening during a Session's execution life time - that is, from being fresh to have its statements executed and committed (or rollbacked). For this, the Session object is passed to set_traced or set_parent_span():
+
+.. code-block:: python
+
+    parent_span = tracer.start_span('ParentSpan')
+    session = Session()
+
+    sqlalchemy_opentracing.set_parent_span(session, parent_span)
+    try:
+        session.add(User(name='Jackie'))
+        session.commit()
+    except IntegrityError:
+        session.rollback()
+
+Similar to what happens for Connection, either a commit or a rollback will finish its tracing, and further work on it will not be reported.
+
+Tracing raw SQL statements
+==========================
+
+Executing raw SQL statements can be done through either a Connection or a Session, through their execute() method. Since there's no way to mark each statement individually, tracing them can be done through either tracing all statements, or through tracing a Connection's transaction or Session:
+
+.. code-block:: python
+
+    sqlalchemy_opentracing.set_parent_span(session, parent_span)
+
+    # this statement will be traced as part of the session's execution
+    session.execute('INSERT INTO users VALUES (?, ?)', 1, 'John')
+
+
+Raw SQL statements will be traced having its operation name as `textclause`, to indicate their explicit text nature.
+
+Manually cancel tracing
+=======================
+
+Sometimes no commit nor rollback may happen for a Connection or Session (for example, when doing bulk insertion/update). In this case, manually canceling tracing for an object can be done through clear_traced():
+
+.. code-block:: python
+
+    parent_span = tracer.start_span('ParentSpan')
+    session = Session()
+
+    sqlalchemy_opentracing.set_parent_span(session, parent_span)
+
+    # this will generate tracing of a single INSERT statement.
+    users = [User(name = 'User-%s' % i) for i in xrange(100)]
+    session.bulk_save_objects(users)
+
+    sqlalchemy_opentracing.clear_traced(session)
+
+Manually canceling tracing will not clear any tracing already done - it will simply stop any further tracing for the current statement, Connection or Session object.
+
 Further information
 ===================
 

VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1

examples/README.md

@@ -0,0 +1,10 @@
+## Examples
+
+This directory contains examples of tracing applications using the sqlalchemy package. To run the examples, make sure you've installed the packages `opentracing` and `lightstep`. If you have a lightstep token and would like to view the created spans, then uncomment to proper lines under the given examples. If you would like to use a different OpenTracing implementation, you may also replace the lightstep tracer with the tracer of your choice.
+
+Then simply:
+
+```
+> python example-file.py
+```
+

examples/core-childspans.py

@@ -21,7 +21,7 @@
     conn = engine.connect()
 
     sqlalchemy_opentracing.init_tracing(tracer)
-    sqlalchemy_opentracing.register_connectable(engine)
+    sqlalchemy_opentracing.register_engine(engine)
 
     span = tracer.start_span('create sample')
 

examples/core-connection.py

@@ -0,0 +1,33 @@
+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-conn',
+    access_token='{your_lightstep_token}'
+)
+
+if __name__ == '__main__':
+    engine = create_engine('sqlite:///:memory:')
+
+    sqlalchemy_opentracing.init_tracing(tracer)
+    sqlalchemy_opentracing.register_engine(engine)
+
+    metadata = MetaData()
+    users = Table('users', metadata,
+        Column('id', Integer, primary_key=True),
+        Column('name', String),
+    )
+    creat = CreateTable(users)
+    ins = users.insert().values(name='John Doe')
+
+    # All statements during this transaction will be traced.
+    with engine.begin() as conn:
+        sqlalchemy_opentracing.set_traced(conn)
+        conn.execute(creat)
+        conn.execute(ins)
+
+    tracer.flush()
+

examples/core-simple.py

@@ -13,7 +13,7 @@
     engine = create_engine('sqlite:///:memory:')
 
     sqlalchemy_opentracing.init_tracing(tracer)
-    sqlalchemy_opentracing.register_connectable(engine)
+    sqlalchemy_opentracing.register_engine(engine)
 
     metadata = MetaData()
     users = Table('users', metadata,

examples/orm-bulk.py

@@ -0,0 +1,46 @@
+import os
+from sqlalchemy import MetaData, Table, Integer, String, Column, create_engine
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import sessionmaker
+
+import lightstep
+import sqlalchemy_opentracing
+
+DB_LOCATION = '/tmp/simple.db'
+
+tracer = lightstep.Tracer(
+    component_name='sqlalchemy-orm-bulk',
+    access_token='{your_lightstep_token}'
+)
+
+Base = declarative_base()
+
+class User(Base):
+    __tablename__ = 'users'
+
+    id = Column(Integer, primary_key=True)
+    name = Column(String)
+
+if __name__ == '__main__':
+    if os.path.exists(DB_LOCATION):
+        os.remove(DB_LOCATION) # cleanup
+
+    engine = create_engine('sqlite:///%s' % DB_LOCATION)
+    session = sessionmaker(bind=engine)()
+
+    sqlalchemy_opentracing.init_tracing(tracer)
+    sqlalchemy_opentracing.register_engine(engine)
+
+    User.metadata.create_all(engine)
+
+    # Register the session for the current transaction.
+    sqlalchemy_opentracing.set_traced(session)
+
+    # Insert a set of rows.
+    users = [User(name = 'User-%s' % i) for i in xrange(100)]
+    session.bulk_save_objects(users)
+
+    # Bulk saves objects without intermmediate steps,
+    # so explicitly stop tracing the session.
+    sqlalchemy_opentracing.clear_traced(session)
+

examples/orm-childspan.py

@@ -29,7 +29,7 @@ class User(Base):
     session = sessionmaker(bind=engine)()
 
     sqlalchemy_opentracing.init_tracing(tracer)
-    sqlalchemy_opentracing.register_connectable(engine)
+    sqlalchemy_opentracing.register_engine(engine)
 
     User.metadata.create_all(engine)
 

examples/orm-simple.py

@@ -29,7 +29,7 @@ class User(Base):
     session = sessionmaker(bind=engine)()
 
     sqlalchemy_opentracing.init_tracing(tracer)
-    sqlalchemy_opentracing.register_connectable(engine)
+    sqlalchemy_opentracing.register_engine(engine)
 
     User.metadata.create_all(engine)