Add OpenTracing shim example

examples/opentracing/README.md

@@ -0,0 +1,88 @@
+# 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-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](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,47 @@
+#!/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 BatchExportSpanProcessor
+from rediscache import RedisCache
+
+# Configure the tracer using the default implementation
+trace.set_preferred_tracer_source_implementation(lambda T: TracerSource())
+tracer = trace.tracer_source().get_tracer(__name__)
+
+# 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 = BatchExportSpanProcessor(jaeger_exporter)
+trace.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)
+
+# Our example caching library expects an OpenTracing-compliant tracer.
+redis_cache = RedisCache(opentracing_tracer)
+
+
+@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)
+
+
+# Export the remaining span before exiting
+span_processor.shutdown()

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 integartion 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/src/opentelemetry/ext/opentracing_shim/__init__.py

@@ -82,8 +82,16 @@
 
 import logging
 
-import opentracing
 from deprecated import deprecated
+from opentracing import (  # pylint: disable=no-name-in-module
+    Format,
+    Scope,
+    ScopeManager,
+    Span,
+    SpanContext,
+    Tracer,
+    UnsupportedFormatException,
+)
 
 import opentelemetry.trace as trace_api
 from opentelemetry import propagators
@@ -101,10 +109,10 @@ def create_tracer(otel_tracer_source):
     :class:`opentracing.Tracer` using OpenTelemetry under the hood.
 
     Args:
-        otel_tracer_source: A :class:`opentelemetry.trace.TracerSource` to be used for
-            constructing the :class:`TracerShim`. A tracer from this source will be used
-            to perform the actual tracing when user code is instrumented using
-            the OpenTracing API.
+        otel_tracer_source: A :class:`opentelemetry.trace.TracerSource` to be
+            used for constructing the :class:`TracerShim`. A tracer from this
+            source will be used to perform the actual tracing when user code is
+            instrumented using the OpenTracing API.
 
     Returns:
         The created :class:`TracerShim`.
@@ -113,7 +121,7 @@ def create_tracer(otel_tracer_source):
     return TracerShim(otel_tracer_source.get_tracer(__name__, __version__))
 
 
-class SpanContextShim(opentracing.SpanContext):
+class SpanContextShim(SpanContext):
     """Implements :class:`opentracing.SpanContext` by wrapping a
     :class:`opentelemetry.trace.SpanContext` object.
 
@@ -151,7 +159,7 @@ def baggage(self):
         # TODO: Implement.
 
 
-class SpanShim(opentracing.Span):
+class SpanShim(Span):
     """Implements :class:`opentracing.Span` by wrapping a
     :class:`opentelemetry.trace.Span` object.
 
@@ -265,7 +273,7 @@ def log(self, **kwargs):
     def log_event(self, event, payload=None):
         super().log_event(event, payload=payload)
 
-    def set_baggage_item(self, key, value):
+    def set_baggage_item(self, key, value):  # pylint: disable=W0613
         """Implements the ``set_baggage_item()`` method from the base class.
 
         Warning:
@@ -278,7 +286,7 @@ def set_baggage_item(self, key, value):
         )
         # TODO: Implement.
 
-    def get_baggage_item(self, key):
+    def get_baggage_item(self, key):  # pylint: disable=W0613
         """Implements the ``get_baggage_item()`` method from the base class.
 
         Warning:
@@ -292,7 +300,7 @@ def get_baggage_item(self, key):
         # TODO: Implement.
 
 
-class ScopeShim(opentracing.Scope):
+class ScopeShim(Scope):
     """A `ScopeShim` wraps the OpenTelemetry functionality related to span
     activation/deactivation while using OpenTracing :class:`opentracing.Scope`
     objects for presentation.
@@ -401,7 +409,7 @@ def close(self):
             self._span.unwrap().end()
 
 
-class ScopeManagerShim(opentracing.ScopeManager):
+class ScopeManagerShim(ScopeManager):
     """Implements :class:`opentracing.ScopeManager` by setting and getting the
     active `opentelemetry.trace.Span` in the OpenTelemetry tracer.
 
@@ -496,7 +504,7 @@ def tracer(self):
         return self._tracer
 
 
-class TracerShim(opentracing.Tracer):
+class TracerShim(Tracer):
     """Implements :class:`opentracing.Tracer` by wrapping a
     :class:`opentelemetry.trace.Tracer` object.
 
@@ -518,8 +526,8 @@ def __init__(self, tracer):
         super().__init__(scope_manager=ScopeManagerShim(self))
         self._otel_tracer = tracer
         self._supported_formats = (
-            opentracing.Format.TEXT_MAP,
-            opentracing.Format.HTTP_HEADERS,
+            Format.TEXT_MAP,
+            Format.HTTP_HEADERS,
         )
 
     def unwrap(self):
@@ -668,7 +676,7 @@ def inject(self, span_context, format, carrier):
         # TODO: Support Format.BINARY once it is supported in
         # opentelemetry-python.
         if format not in self._supported_formats:
-            raise opentracing.UnsupportedFormatException
+            raise UnsupportedFormatException
 
         propagator = propagators.get_global_httptextformat()
         propagator.inject(
@@ -685,7 +693,7 @@ def extract(self, format, carrier):
         # TODO: Support Format.BINARY once it is supported in
         # opentelemetry-python.
         if format not in self._supported_formats:
-            raise opentracing.UnsupportedFormatException
+            raise UnsupportedFormatException
 
         def get_as_list(dict_object, key):
             value = dict_object.get(key)