Add OpenTracing shim example (open-telemetry#282)

Co-authored-by: Diego Hurtado <[email protected]>
Co-authored-by: Christian Neumüller <[email protected]>
Co-authored-by: Mauricio Vásquez <[email protected]>

examples/opentracing/README.md

@@ -0,0 +1,90 @@
+# Overview
+
+This example shows how to use the [`opentelemetry-ext-opentracing-shim`
+package](https://github.com/open-telemetry/opentelemetry-python/tree/master/ext/opentelemetry-ext-opentracing-shim)
+to interact with libraries instrumented with
+[`opentracing-python`](https://github.com/opentracing/opentracing-python).
+
+The included `rediscache` library creates spans via the OpenTracing Redis
+integration,
+[`redis_opentracing`](https://github.com/opentracing-contrib/python-redis).
+Spans are exported via the Jaeger exporter, which is attached to the
+OpenTelemetry tracer.
+
+## Installation
+
+### Jaeger
+
+Install and run
+[Jaeger](https://www.jaegertracing.io/docs/latest/getting-started/#all-in-one).
+See the [basic tracer
+example](https://github.com/open-telemetry/opentelemetry-python/tree/master/examples/basic-tracer)
+for more detail.
+
+### Redis
+
+Install Redis following the [instructions](https://redis.io/topics/quickstart).
+
+Make sure that the Redis server is running by executing this:
+
+```sh
+$ redis-server
+```
+
+### Python Dependencies
+
+Install the Python dependencies in [`requirements.txt`](requirements.txt):
+
+```sh
+$ pip install -r requirements.txt
+```
+
+Alternatively, you can install the Python dependencies separately:
+
+```sh
+$ pip install \
+  opentelemetry-api \
+  opentelemetry-sdk \
+  opentelemetry-ext-jaeger \
+  opentelemetry-opentracing-shim \
+  redis \
+  redis_opentracing
+```
+
+## Run the Application
+
+The example script calculates a few Fibonacci numbers and stores the results in
+Redis. The script, the `rediscache` library, and the OpenTracing Redis
+integration all contribute spans to the trace.
+
+To run the script:
+
+```sh
+$ python main.py
+```
+
+After running, you can view the generated trace in the Jaeger UI.
+
+#### Jaeger UI
+
+Open the Jaeger UI in your browser at
+<http://localhost:16686> and view traces for the
+"OpenTracing Shim Example" service.
+
+Each `main.py` run should generate a trace, and each trace should include
+multiple spans that represent calls to Redis.
+
+<p align="center"><img src="./images/jaeger-trace-full.png?raw=true"/></p>
+
+Note that tags and logs (OpenTracing) and attributes and events (OpenTelemetry)
+from both tracing systems appear in the exported trace.
+
+<p align="center"><img src="./images/jaeger-span-expanded.png?raw=true"/></p>
+
+## Useful links
+- For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
+- For more information on tracing in Python, visit: <https://github.com/open-telemetry/opentelemetry-python>
+
+## LICENSE
+
+Apache License 2.0

examples/opentracing/main.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python
+
+from opentelemetry import trace
+from opentelemetry.ext import opentracing_shim
+from opentelemetry.ext.jaeger import JaegerSpanExporter
+from opentelemetry.sdk.trace import TracerSource
+from opentelemetry.sdk.trace.export import SimpleExportSpanProcessor
+from rediscache import RedisCache
+
+# Configure the tracer using the default implementation
+trace.set_preferred_tracer_source_implementation(lambda T: TracerSource())
+tracer_source = trace.tracer_source()
+
+# Configure the tracer to export traces to Jaeger
+jaeger_exporter = JaegerSpanExporter(
+    service_name="OpenTracing Shim Example",
+    agent_host_name="localhost",
+    agent_port=6831,
+)
+span_processor = SimpleExportSpanProcessor(jaeger_exporter)
+tracer_source.add_span_processor(span_processor)
+
+# Create an OpenTracing shim. This implements the OpenTracing tracer API, but
+# forwards calls to the underlying OpenTelemetry tracer.
+opentracing_tracer = opentracing_shim.create_tracer(tracer_source)
+
+# Our example caching library expects an OpenTracing-compliant tracer.
+redis_cache = RedisCache(opentracing_tracer)
+
+# Appication code uses an OpenTelemetry Tracer as usual.
+tracer = trace.tracer_source().get_tracer(__name__)
+
+
+@redis_cache
+def fib(number):
+    """Get the Nth Fibonacci number, cache intermediate results in Redis."""
+    if number < 0:
+        raise ValueError
+    if number in (0, 1):
+        return number
+    return fib(number - 1) + fib(number - 2)
+
+
+with tracer.start_as_current_span("Fibonacci") as span:
+    span.set_attribute("is_example", "yes :)")
+    fib(4)

examples/opentracing/rediscache.py

@@ -0,0 +1,61 @@
+"""
+This is an example of a library written to work with opentracing-python. It
+provides a simple caching decorator backed by Redis, and uses the OpenTracing
+Redis integration to automatically generate spans for each call to Redis.
+"""
+
+import pickle
+from functools import wraps
+
+# FIXME The pylint disablings are needed here because the code of this
+# example is being executed against the tox.ini of the main
+# opentelemetry-python project. Find a way to separate the two.
+import redis  # pylint: disable=import-error
+import redis_opentracing  # pylint: disable=import-error
+
+
+class RedisCache:
+    """Redis-backed caching decorator, using OpenTracing!
+
+    Args:
+        tracer: an opentracing.tracer.Tracer
+    """
+
+    def __init__(self, tracer):
+        redis_opentracing.init_tracing(tracer)
+        self.tracer = tracer
+        self.client = redis.StrictRedis()
+
+    def __call__(self, func):
+        @wraps(func)
+        def inner(*args, **kwargs):
+            with self.tracer.start_active_span("Caching decorator") as scope1:
+
+                # Pickle the call args to get a canonical key. Don't do this in
+                # prod!
+                key = pickle.dumps((func.__qualname__, args, kwargs))
+
+                pval = self.client.get(key)
+                if pval is not None:
+                    val = pickle.loads(pval)
+                    scope1.span.log_kv(
+                        {"msg": "Found cached value", "val": val}
+                    )
+                    return val
+
+                scope1.span.log_kv({"msg": "Cache miss, calling function"})
+                with self.tracer.start_active_span(
+                    'Call "{}"'.format(func.__name__)
+                ) as scope2:
+                    scope2.span.set_tag("func", func.__name__)
+                    scope2.span.set_tag("args", str(args))
+                    scope2.span.set_tag("kwargs", str(kwargs))
+
+                    val = func(*args, **kwargs)
+                    scope2.span.set_tag("val", str(val))
+
+                # Let keys expire after 10 seconds
+                self.client.setex(key, 10, pickle.dumps(val))
+                return val
+
+        return inner

examples/opentracing/requirements.txt

@@ -0,0 +1,6 @@
+opentelemetry-api
+opentelemetry-sdk
+opentelemetry-ext-jaeger
+opentelemetry-opentracing-shim
+redis
+redis_opentracing

ext/opentelemetry-ext-opentracing-shim/tests/test_shim.py

@@ -489,7 +489,6 @@ def test_inject_text_map(self):
 
         # Verify Format.TEXT_MAP
         text_map = {}
-
         self.shim.inject(context, opentracing.Format.TEXT_MAP, text_map)
         self.assertEqual(text_map[MockHTTPTextFormat.TRACE_ID_KEY], str(1220))
         self.assertEqual(text_map[MockHTTPTextFormat.SPAN_ID_KEY], str(7478))