A trace is a directed acyclic graph of spans. A span is a logical
representation of some work done in your application. Each span has
three essential attributes: an operation name, a start time, and a finish time.

Let's create an instance of a real tracer, such as Jaeger.

A Configuration class is used to initialize the Jaeger Tracer so that
we can easily parameterize the Tracer.

We define a function that returns the Tracer and call that function
explicitly after all imports are done.

import logging
from jaeger_client import Config

def init_jaeger_tracer(service):
  logging.getLogger('').handlers = []
  logging.basicConfig(format='%(message)s', level=logging.DEBUG)

  # Config class constructor
  config = Config(
      config={
          'sampler':{
              'type':'const',
              'param':1
          },
          'logging':True
      },
      service_name=service
  )

  return config.initialize_tracer()

# Initialize Jaeger Tracer
tracer = init_jaeger_tracer('hello-world')

We create a tracer instance with the sevice name hello-world, which
is passed as an argument to init_jaeger_tracer function. Thus, all spans emitted from the tracer are marked as originating from
the service hello-world.

We have successfully initialized an instance of Jaeger tracer.

We use the Jaeger tracer instance initialized in the previous step
in our simple hello world program as follows:

def say_hello(hello_to):
    ## Create trace
    span = tracer.start_span('say-hello')
    hello_str = 'Hello, %s!' % hello_to
    print hello_str
    span.finish()

We use the following basic features of the OpenTracing API:

• a tracer instance is used to start new spans via start_span method
• each span is given an operation name, say-hello in this example
• each span must be finished by explicitly calling its finish() method
• start and finish timestamps of a span are automatically captured by
  the tracer implementation, in this case, the Jaeger Tracer captures
  the start and finish timestamps of each span

It's tedious to call finish() manually on each given span. Instead, we
can use span as context manager as shown below:

def say_hello(hello_to):
    ## span as context manager
    with tracer.start_span('say-hello') as span:
        hello_str = 'Hello, %s!' % hello_to
        print hello_str

Since the program is short-lived and it exits immediately, we can flush
the span to Jaeger backend by adding the following to hello-world.py:

import time

def say_hello(hello_to):
    ## span as context manager
    ## Create trace
    with tracer.start_span('say-hello') as span:
        hello_str = 'Hello, %s!' % hello_to
        print hello_str

# Flush span to Jaeger backend
time.sleep(2)
tracer.close()

We instrument the simple hello world program in hello.py.

Copy the below content into the file (or click Copy to Editor button):

# a simple hello world program
# to demonstrate instrumenting a
# simple Python program using OpenTracing API
# and JaegerTracing system

import sys
import time
import logging
from jaeger_client import Config

def init_jaeger_tracer(service):
    logging.getLogger('').handlers=[]
    logging.basicConfig(format='%(message)s', level=logging.DEBUG)

    config=Config(
        config={
            'sampler':{
                'type':'const',
                'param':1
            },
            'logging':True
        },
        service_name=service
    )

    return config.initialize_tracer()

tracer = init_jaeger_tracer('hello-world')

def say_hello(hello_to):
    with tracer.start_span('say-hello') as span:
        hello_str = "Hello, %s!" % hello_to
        print hello_str

assert len(sys.argv) == 2

hello_to = sys.argv[1]
say_hello(hello_to)

time.sleep(20)
tracer.close()

We run the above program with the command line argument, Alice, and should
be able to see a span logged:
python2.7 hello.py Alice

A visual representation of the trace in the form of a timing diagram is
available through Jaeger UI.
To view the corresponding timing diagram, follow these steps:

1. Click the service name drop-down list, select hello-world
2. Click the operation name drop-down list, select say-hello

What if we call our program with a different command line argument,
say Bob instead of Alice? Both the resulting traces will be identical.
We can capture command line arguments in the traces to distinguish them
by annotating traces with tags and logs.

However, we cannot use a span's operation name to distinguish traces,
because the operation name represents a class of spans, rather than a
unique span. Moreover, a general operation name allows a tracing system
to do aggregations.

A tag is a key:value pair that provides certain metadata about the span.

A log is similar to a regular log statement, it contains a timestamp and
some data, but it is associated with the span from which it is logged.

If a span represents an HTTP request, the URL of the request should be
made a tag because the URL is relevant for the entire duration of the
span. On the other hand, if the server responds with an indirect URL,
logging it would make more sense since there is a clear timestamp
associated with such event.

Using Tags

Consider Hello, Bob. The string Bob is a good candidate for a span
tag, since it applies to the whole span and not to a particular moment
in time.

with tracer.start_span('say-hello') as span:
  span.set_tag('hello_to', hello_to)

Using Logs

The two operations in our hello world program - formatting hello_str,
and then printing it - take certain time, so we can log their completion.

# log string formatting
hello_str = 'Hello, %s!' % hello_to
span.log_kv({'event':'string-format', 'value':hello_str})

# log string printing
print(hello_str)
span.log_kv({'event':'println'})

The OpenTracing API for Python exposes structured logging API method log_kv
that takes a dictionary of key:value pairs.

The OpenTracing Specification also recommends all log statements to always
contain an event field that describes the overall event being logged, with
other attributes of the event provided as additional fields.

The complete instrumented code is shown below (copy it into hello.py by
clicking on Copy to Editor button) :

# a simple hello world program
# to demonstrate annotating a
# trace with tags and logs
# using JaegerTracing system

import sys
import time
import logging
from jaeger_client import Config

def init_jaeger_tracer(service):
    logging.getLogger('').handlers=[]
    logging.basicConfig(format='%(message)s', level=logging.DEBUG)

    config=Config(
        config={
            'sampler':{
                'type':'const',
                'param':1
            },
            'logging':True
        },
        service_name=service
    )

    return config.initialize_tracer()

tracer = init_jaeger_tracer('hello-world')

def say_hello(hello_to):
    with tracer.start_span('say-hello') as span:
        hello_str = "Hello, %s!" % hello_to
        span.log_kv({'event':'string-format', 'value':hello_to})

        print hello_str
        span.log_kv({'event':'printlin'})

assert len(sys.argv) == 2

hello_to = sys.argv[1]
say_hello(hello_to)

time.sleep(20)
tracer.close()

Let's run the above program with Bryan as the command line argument:
python2.7 hello.py Bryan

A visual representation of the trace in the form of a timing diagram is
available through Jaeger UI.
To view the corresponding timing diagram, follow these steps:

1. Click the service name drop-down list, select hello-world
2. Click the operation name drop-down list, select say-hello