OpenTracing Python Tutorial - Lesson 02 | opentracing

OpenTracing Python Tutorial - Lesson 02

Step 1 of 3

Trace Individual Functions

Let's begin from where we left in lesson01. Let's rewrite our simple hello world
program from lesson01. Click the link below to open
hello.py in the editor:
exercise/hello.py

Once the file is opened in the editor, you can then copy the content
below into the file (or use the Copy to Editor button):

## hello.py
## simple hello world program

import sys
# modify path variable to search for lib.tracing module
sys.path.append("/root/opentracing-tutorial/python")
import time
from lib.tracing import init_tracer


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

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

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

assert len(sys.argv) == 2

tracer = init_tracer('hello-world')

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

# yield to IOLoop to flush the spans
time.sleep(2)
tracer.close()

Note :Observe that init_tracer function is moved to a separate library directory.

Let's move the two operations - formatting and printing a string - to
standalone functions and wrap each function into its own span. We observe
that the functions format_string and print_hello are introduced in
the program, respectively, to format and print strings.

We copy the code below into hello.py file (or use the Copy to Editor
button):

## hello.py
## simple hello world program

import sys
# modify path variable to search for lib.tracing module
sys.path.append("/root/opentracing-tutorial/python")
import time
from lib.tracing import init_tracer

def say_hello(hello_to):
  with tracer.start_span('say-hello') as span:
    span.set_tag('hello-to', hello_to)
    hello_str = format_string(span, hello_to)
    print_hello(span, hello_str)

# format given string
def format_string(root_span, hello_to):
  with tracer.start_span('format') as span:
      hello_str = 'Hello, %s!' % hello_to
      span.log_kv({'event': 'string-format', 'value': hello_str})
      return hello_str

# display given string
def print_hello(root_span, hello_str):
  with tracer.start_span('println') as span:
      print(hello_str)
      span.log_kv({'event': 'println'})

assert len(sys.argv) == 2

tracer = init_tracer('hello-world')

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

# yield to IOLoop to flush the spans
time.sleep(2)
tracer.close()

Let's run the above python program with a command line argument,
say, Alice:

python2.7 -m hello Alice

We find three spans if we observe the output carefully, each with a unique
Jaeger trace ID (the first hexadecimal segment). If we search the IDs
in the Jaeger UI's dashboard, each ID will represent a separate trace
with a single span. Instead, we would want to set up a relationship
between the two new spans - format and println - and the main span
say_hello.

Note :To see a trace in Jaeger UI dashboard, select service name as hello-world
and operation name as either say-hello, format or println accordingly.

Aggregate Spans into Single Trace

Since we want to establish a causal relationship between the two new spans
format; println and the root span say-hello, we pass an additional
argument to the start_span method.

def format_string(root_span, hello_to):
  with tracer.start_span('format', child_of=root_span) as span:
      hello_str = 'Hello, %s!' % hello_to
      span.log_kv({'event': 'string-format', 'value': hello_str})
      return hello_str

def print_hello(root_span, hello_str):
  with tracer.start_span('println', child_of=root_span) as span:
      print(hello_str)
      span.log_kv({'event': 'println'})

A trace is a directed acyclic graph where the nodes represent spans
and the edges represent causal relationships or references between spans.
In the OpenTracing Specification, the edges are abstracted as SpanReference
type that consists of SpanContext and ReferenceType label.

The SpanContext is an immutable thread safe portion of the span that can
be used to establish references between spans or to propagate spans over the
wire.

The ReferenceType describes the nature of the relationship between spans.
There are two kinds of references:

ChildOf reference: A span maybe a ChildOf parent span. In this example,
root_span is the parent span of format and println spans. In this
reference, the parent span logically depends on its child span(s) before it
can complete its operation.
FollowsFrom reference: A child span FollowsFrom its parent span. For
example, root_span maybe the ancestor of the DAG and it does not depend
on completion of its child span(s).

Copy the code below into hello.py file (or use the Copy to Editor
button):

## hello.py
## simple hello world program

import sys
# modify path variable to search for lib.tracing module
sys.path.append("/root/opentracing-tutorial/python")
import time
from lib.tracing import init_tracer

def say_hello(hello_to):
  with tracer.start_span('say-hello') as span:
    span.set_tag('hello-to', hello_to)
    hello_str = format_string(span, hello_to)
    print_hello(span, hello_str)

def format_string(root_span, hello_to):
  with tracer.start_span('format', child_of=root_span) as span:
      hello_str = 'Hello, %s!' % hello_to
      span.log_kv({'event': 'string-format', 'value': hello_str})
      return hello_str

def print_hello(root_span, hello_str):
  with tracer.start_span('println', child_of=root_span) as span:
      print(hello_str)
      span.log_kv({'event': 'println'})

assert len(sys.argv) == 2

tracer = init_tracer('hello-world')

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

# yield to IOLoop to flush the spans
time.sleep(2)
tracer.close()

Let's run the modified python program:
python2.7 -m hello Alice

The reported spans in the output now belong to the same trace. We observe
that the third hexadecimal segment in both the new spans is no longer 0
but is the value of the root_span Jaeger trace ID.

Let's find out how the trace would look in the Jaeger UI.
We can observe that the spans format and println are causally related to
the root span say-hello.

Note :To see a trace in Jaeger UI dashboard, select service name as hello-world
and operation name as either say-hello.

Propagate In-process Context

You might have noticed an unpleasant side effect of our recent changes,
i.e. passing a span object as the first parameter to the functions,
format_string and print_hello.

Unlike Go, programming languages like Python support thread-local storage,
which is a convenient way to store such request-scoped data like the current
span. However, since the OpenTracing API for Python does not support a standard
mechanism for accessing such thread-local storage, we will use an alternative
API called opentracing_instrumentation that provides an in-memory context
propagation facility suitable for multiple thread apps and Tornado apps via
its request_context submodule.

To store top level root_span in the context,

from opentracing_instrumentation.request_context import get_current_span, span_in_context

def say_hello(hello_to):
  with tracer.start_span('say-hello') as span:
    span.set_tag('hello-to', hello_to)
    with span_in_context(span):
      hello_str = format_string(hello_to)
      print_hello(hello_str)

def format_string(hello_to):
  root_span = get_current_span()
  with tracer.start_span('format', child_of=root_span) as span:
      hello_str = 'Hello, %s!' % hello_to
      span.log_kv({'event': 'string-format', 'value': hello_str})
      return hello_str

Accordingly, we modify print_hello function to save the main root_span in context.

def print_hello(root_span, hello_str):
  root_span = get_current_span()
  with tracer.start_span('println', child_of=root_span) as span:
      print(hello_str)
      span.log_kv({'event': 'println'})

Observe that we are no longer passing an instance of Span as an argument
to the functions, format_string and print_hello, because they can now
retrieve the root_span with the get_current_span method.

Let's copy the code below into the file hello.py (or use the Copy to Editor button):

## hello.py
## simple hello world program

import sys
# modify path variable to search for lib.tracing module
sys.path.append("/root/opentracing-tutorial/python")
import time
from lib.tracing import init_tracer
from opentracing_instrumentation.request_context import get_current_span, span_in_context

def say_hello(hello_to):
  with tracer.start_span('say-hello') as span:
    span.set_tag('hello-to', hello_to)
    with span_in_context(span):
      hello_str = format_string(hello_to)
      print_hello(hello_str)

def format_string(hello_to):
  root_span = get_current_span()
  with tracer.start_span('format', child_of=root_span) as span:
      hello_str = 'Hello, %s!' % hello_to
      span.log_kv({'event': 'string-format', 'value': hello_str})
      return hello_str

def print_hello(hello_str):
  root_span = get_current_span()
  with tracer.start_span('println', child_of=root_span) as span:
      print(hello_str)
      span.log_kv({'event': 'println'})

assert len(sys.argv) == 2

tracer = init_tracer('hello-world')

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

# yield to IOLoop to flush the spans
time.sleep(2)
tracer.close()

Let's run the program and find out its trace in Jaeger UI:
python2.7 -m hello Alice

This particular change is helpful in larger programs with many functions
calling each other. By using request_context mechanism, we can access
the current span from any place in the program without passing the Span
object as an argument to all the function calls.

Note :To see a trace in Jaeger UI dashboard, select service name as hello-world
and operation name as either say-hello.

cd <directory>	Change directory
ls	List directory
echo 'contents' > <file>	Write contents to a file
cat <file>	Output contents of file

i	In Command Mode	Change into Insert Mode, you can now insert and edit text in the file
esc	In Insert Mode	Change into Command Mode, you can now execute commands
:wq	In Command Mode	Save and Exit

Welcome!

OpenTracing Python Tutorial - Lesson 02

Congratulations!

You've completed the scenario!

Scenario Rating

Additional Resources

Steps