gluetool.action module

Actions are pieces of workflow. Actions have a name and start/end time, and actions can be traced.

This module provides simple instrumentation to enable logging of actions, and - when client libraries are installed - submission of actions to storages compatible with <https://opentracing.io/docs/overview/>`_.

Actions - which are wrapping Open Tracing’s _span_ objects - can form an acyclic graph - actions can have a single parent, it is then possible to start with a “root” action (e.g. “running the pipeline”) from which are children actions spawned (e.g. “executing module”) and these actions can become parents to actions spawned deeper in modules, end so on and on, forming a nice overview of what the code did, how long did it took, and what are the dependencies between actions, i.e. what subactions were necessary to perform a particular action.

Each execution of Gluetool pipeline forms a _trace_, which consists of multiple _spans_. Each action represents a single span, wrapping its properties and dependencies.

with Action('some label', parent=parent_action, tags={'foo': 'bar'}) as action:
   # do some work

   with Action('some subtask', parent=action):
       # e.g. fetching a webpage

   with Action('another subtask', parent=action):
       # e.g. validating page's source code

For the example above, you get a trace capturing dependencies between a prent task and its two children, how long they spent doing their job, how it affected the parent. Instrument interesting pieces of your code, e.g. interaction with remote services, and get an overview of your workflow on a level of “symbolical” actions.

When a supported tracing client is installed, spans created by actions actions are reported to the remote storage.

Supported clients:

• https://github.com/jaegertracing/jaeger-client-python

To control behavior of tracing subsystem, you can use following environment variables:

• GLUETOOL_TRACING_DISABLE - when set to anything, tracing won’t be enabled even when a client is available.
• GLUETOOL_TRACING_SERVICE_NAME - given string is used to name the trace produced by gluetool execution.

• GLUETOOL_TRACING_REPORTING_HOST - given string represents a hostname where service, capturing

  traces, listens.

• GLUETOOL_TRACING_REPORTING_PORT - given integer represents a port number where service, capturing

  traces, listens.

class gluetool.action.Action(label, parent=None, tags=None, logger=None)

Bases: object

A piece of a workflow: it has a name, and starts and ends at some point of time. Represents an individual unit of work.

Parameters:

• label (str) – a human-readable string which concisely represents the work done by the Action. The name should be the most general string that describes an interesting class of Action instances. I.e. fetch-url` is better than ``fetch-url-https://foo.com`.
• parent (Action) – parent Action - one action can spawn multiple additional “children” actions to achieve its goal, either explicitly or by using instrumented library code.
• tags (dict) – additional key/value tags of this action, e.g. url=https://foo.com.
• logger (ContextAdapter) – logger to use for logging purposes.

static _action_stack()

Return current - or create an empty new one - list of unfinished actions of the current thread.

static _add_action(action)

Add action on top of the list of unfinished actions of the current thread.

static _drop_action(action)

Drop action from the list of unfinished actions of the current thread.

_thread_actions = <thread._local object>

static current_action()

Return the top-most - “current” - unfinished action of the current thread.

finish()

Complete the action.

set_tag(name, value)

set_tags(tags)

static set_thread_root(action)

Initialize list of unfinished action of the current thread with a given transaction.

When thread starts, its list is obviously empty, therefore current_action() cannot return anything reasonable. But there probably was an action, e.g. the one in the main thread, which could serve as “current action” for this thread. This method inserts it into the threads list, as the first action.

This is a combination of resetting the action stack followed by _add_action(). Cannot be replaced by _add_action though - _add_action adds action to the existing stack, but this method promises to reset the stack: imagine re-using thread as a worker for multiple workflows, each workflow should start with a clean slate, with a different root - when work starts in the thread, it should call set_thread_root to initialize its actions stack with an action, given by whoever started the work from the main thread.

class gluetool.action.Tracer(service_name=None, logger=None, reporting_host=None, reporting_port=None)

Bases: object

Wrap tracking tracer instance.

Parameters:

• service_name (str) – name to apply to all traces produced by this tracer.
• logger (ContextAdapter) – logger to use for logging.
• reporting_host (str) – address to which tracer should submit traces.
• reporting_port (int) – port to which tracer should submit tracers.

TRACER = None

close(flush_timeout=None, logger=None)