sqlalchemy_opentracing 0.1.6

安装

运行以下命令：

$ pip install sqlalchemy_opentracing

开始

请参阅示例目录。总的来说，基本用法要求设置一个跟踪器，并为语句分配其父跨距（如果有的话）：

importsqlalchemy_opentracingsqlalchemy_opentracing.init_tracing(tracer)# A OpenTracing compatible tracer.withengine.begin()asconn:sel=select([users])sqlalchemy_opentracing.set_parent_span(sel,main_span)conn.execute(sel)

默认情况下，跟踪所有引擎中的所有语句。或者，您可以通过指定并非所有引擎都已注册来启用对特定引擎下所有查询的跟踪，并自己注册引擎：

sqlalchemy_opentracing.init_tracing(tracer,trace_all_engines=False)sqlalchemy_opentracing.register_engine(engine)# Only queries under `engine` will be traced.withengine.begin()asconn:sel=select([users])conn.execute(sel)

还可以防止自动跟踪所有查询（与是否跟踪所有引擎无关），并显式标记它们（带或不带父范围）：

sqlalchemy_opentracing.init_tracing(tracer,trace_all_queries=False)withengine.begin()asconn:sel=select([users])sqlalchemy_opentracing.set_traced(sel)sqlalchemy_opentracing.set_parent_span(sel,main_span)# Optional

生成的跨距将具有与sql语句相关的操作名（例如create table或insert），并将包括异常信息（如果有）、方言/后端（例如sqlite）和一些其他提示。

在连接下跟踪

可以跟踪在连接事务生存期内执行的所有语句。为此，不将语句标记为traced，而是将连接传递给set_traced（）或set_parent_span（）：

parent_span=tracer.start_span('ParentSpan')conn=engine.connect()withconn.begin()astrans:sqlalchemy_opentracing.set_parent_span(conn,parent_span)# these three statements will be traced as children of# parent_spanconn.execute(users.insert().values(name='John'))conn.execute(users.insert().values(name='Jason'))conn.execute(users.insert().values(name='Jackie'))

连接事务的提交或回滚将完成其跟踪。如果之后使用相同的连接对象，则不会对其进行跟踪（除非再次注册进行跟踪）。使用（模拟）嵌套事务时，需要在顶级事务时间标记跟踪，并且将对嵌套事务下的所有语句进行跟踪：

withconn.begin()astrans:sqlalchemy_opentracing.set_parent_span(conn,parent_span)conn.execute(users.insert().values(name='John'))withconn.begin()asnested_trans:# This statement will also be traced as# child of parent_spanconn.execute(users.insert().values(name='Jason'))

会话下的跟踪（ORM）

还可以跟踪会话执行生命周期中发生的所有实际SQL语句，也就是说，从刷新到执行和提交（或回滚）语句。为此，会话对象被传递给set_traced或set_parent_span（）：

parent_span=tracer.start_span('ParentSpan')session=Session()sqlalchemy_opentracing.set_parent_span(session,parent_span)try:session.add(User(name='Jackie'))session.commit()exceptIntegrityError:session.rollback()

与连接的情况类似，提交或回滚都将完成其跟踪，并且不会报告有关它的进一步工作。

跟踪原始SQL语句

执行原始SQL语句可以通过连接或会话，通过它们的execute（）方法来完成。由于无法单独标记每个语句，因此可以通过跟踪所有语句或通过跟踪连接的事务或会话来跟踪它们：

sqlalchemy_opentracing.set_parent_span(session,parent_span)# this statement will be traced as part of the session's executionsession.execute('INSERT INTO users VALUES (?, ?)',1,'John')

将跟踪操作名为textclessue的原始sql语句，以指示它们的显式文本性质。

手动取消跟踪

有时，连接或会话可能不会发生提交或回滚（例如，在执行大容量插入/更新时）。在这种情况下，可以通过clear_traced（）来手动取消对象的跟踪：

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)foriinxrange(100)]session.bulk_save_objects(users)sqlalchemy_opentracing.clear_traced(session)

手动取消跟踪不会清除任何已完成的跟踪-它只会停止对当前语句、连接或会话对象的任何进一步跟踪。

更多信息

如果您有兴趣进一步了解opentracing标准，请访问opentracing.io或join the mailing list。如果您想在您的项目中实现opentracing并需要帮助，请随时在community@opentracing.io向我们发送一条消息。