[opentracer] Documentation (#517)

* add opentracing documentation basics

Author: Kyle-Verhoog

ddtrace/opentracer/README.rst

@@ -34,6 +34,20 @@ class Tracer(opentracing.Tracer):
     """A wrapper providing an OpenTracing API for the Datadog tracer."""
 
     def __init__(self, service_name=None, config=None, scope_manager=None):
+        """Initialize a new Datadog opentracer.
+
+        :param service_name: (optional) the name of the service that this
+            tracer will be used with. Note if not provided, a service name will
+            try to be determined based off of ``sys.argv``. If this fails a
+            :class:`ddtrace.settings.ConfigException` will be raised.
+        :param config: (optional) a configuration object to specify additional
+            options. See the documentation for further information.
+        :param scope_manager: (optional) the scope manager for this tracer to
+            use. The available managers are listed in the Python OpenTracing repo
+            here: https://github.com/opentracing/opentracing-python#scope-managers.
+            If ``None`` is provided, defaults to
+            :class:`opentracing.scope_managers.ThreadLocalScopeManager`.
+        """
         # Merge the given config with the default into a new dict
         config = config or {}
         self._config = merge_dicts(DEFAULT_CONFIG, config)
@@ -80,20 +94,24 @@ def start_active_span(self, operation_name, child_of=None, references=None,
                           tags=None, start_time=None, ignore_active_span=False,
                           finish_on_close=True):
         """Returns a newly started and activated `Scope`.
-        The returned `Scope` supports with-statement contexts. For example:
+        The returned `Scope` supports with-statement contexts. For example::
+
             with tracer.start_active_span('...') as scope:
                 scope.span.set_tag('http.method', 'GET')
                 do_some_work()
             # Span.finish() is called as part of Scope deactivation through
             # the with statement.
+
         It's also possible to not finish the `Span` when the `Scope` context
-        expires:
+        expires::
+
             with tracer.start_active_span('...',
                                           finish_on_close=False) as scope:
                 scope.span.set_tag('http.method', 'GET')
                 do_some_work()
             # Span.finish() is not called as part of Scope deactivation as
             # `finish_on_close` is `False`.
+
         :param operation_name: name of the operation represented by the new
             span from the perspective of the current service.
         :param child_of: (optional) a Span or SpanContext instance representing
@@ -111,7 +129,7 @@ def start_active_span(self, operation_name, child_of=None, references=None,
             the current active `Scope` and creates a root `Span`.
         :param finish_on_close: whether span should automatically be finished
             when `Scope.close()` is called.
-         :return: a `Scope`, already registered via the `ScopeManager`.
+        :return: a `Scope`, already registered via the `ScopeManager`.
         """
         otspan = self.start_span(
             operation_name=operation_name,
@@ -131,13 +149,17 @@ def start_span(self, operation_name=None, child_of=None, references=None,
         """Starts and returns a new Span representing a unit of work.
 
         Starting a root Span (a Span with no causal references)::
+
             tracer.start_span('...')
 
         Starting a child Span (see also start_child_span())::
+
             tracer.start_span(
                 '...',
                 child_of=parent_span)
+
         Starting a child Span in a more verbose way::
+
             tracer.start_span(
                 '...',
                 references=[opentracing.child_of(parent_span)])

ddtrace/opentracer/tracer.py

@@ -54,7 +54,8 @@ def __init__(
         """
         Create a new span. Call `finish` once the traced operation is over.
 
-        :param Tracer tracer: the tracer that will submit this span when finished.
+        :param ddtrace.Tracer tracer: the tracer that will submit this span when
+            finished.
         :param str name: the name of the traced operation.
 
         :param str service: the service name

ddtrace/span.py

@@ -449,6 +449,147 @@ following flag or environment variable::
 
     $ PYTHONWARNINGS=all python app.py
 
+.. _opentracing:
+
+OpenTracing
+-----------
+
+Datadog OpenTracing Tracer
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Datadog opentracer provides an OpenTracing-compatible API to the Datadog
+tracer so that you can use the Datadog tracer in your OpenTracing-compatible
+applications.
+
+Installation
+~~~~~~~~~~~~
+
+To include OpenTracing dependencies in your project with `ddtrace`, ensure you
+have the following in `setup.py`::
+
+    install_requires=[
+        "ddtrace[opentracing]",
+    ],
+
+Configuration
+~~~~~~~~~~~~~
+
+The OpenTracing convention for initializing a tracer is to define an
+initiliazation method that will configure and instantiate a new tracer and
+overwrite the global `opentracing.tracer` reference.
+
+Typically this method looks something like::
+
+    from ddtrace.opentracer import Tracer, set_global_tracer
+
+    def init_tracer(service_name):
+        """
+        Initialize a new Datadog opentracer and set it as the
+        global tracer.
+
+        This overwrites the opentracing.tracer reference.
+        """
+        config = {
+          'agent_hostname': 'localhost',
+          'agent_port': 8126,
+        }
+        tracer = Tracer(service_name, config=config)
+        set_global_tracer(tracer)
+        return tracer
+
+**Opentracer API**
+
+.. autoclass:: ddtrace.opentracer.Tracer
+    :members:
+    :special-members: __init__
+
+
+The Datadog opentracer can be configured via the `config` dictionary parameter
+which accepts the following described fields.
+
++---------------------+---------------------------------------------------------+---------------+
+| Configuration Key   |  Description                                            | Default Value |
++=====================+=========================================================+===============+
+| `enabled`           | enable or disable the tracer                            | `True`        |
++---------------------+---------------------------------------------------------+---------------+
+| `debug`             | enable debug logging                                    | `False`       |
++---------------------+---------------------------------------------------------+---------------+
+| `agent_hostname`    | hostname of the Datadog agent to use                    | `localhost`   |
++---------------------+---------------------------------------------------------+---------------+
+| `agent_port`        | port the Datadog agent is listening on                  | `8126`        |
++---------------------+---------------------------------------------------------+---------------+
+| `global_tags`       | tags that will be applied to each span                  | `{}`          |
++---------------------+---------------------------------------------------------+---------------+
+| `sampler`           | see `Sampling`_                                         | `AllSampler`  |
++---------------------+---------------------------------------------------------+---------------+
+| `priority_sampling` | see `Priority Sampling`_                                | `False`       |
++---------------------+---------------------------------------------------------+---------------+
+| `settings`          | see `Advanced Usage`_                                   | `{}`          |
++---------------------+---------------------------------------------------------+---------------+
+
+
+Usage
+~~~~~
+
+**Manual tracing**
+
+To explicitly trace::
+
+  import time
+  import opentracing
+  from ddtrace.opentracer import Tracer, set_global_tracer
+
+  def init_tracer(service_name):
+      config = {
+        'agent_hostname': 'localhost',
+        'agent_port': 8126,
+      }
+      tracer = Tracer(service_name, config=config)
+      set_global_tracer(tracer)
+      return tracer
+
+  def my_operation():
+    span = opentracing.tracer.start_span('my_operation_name')
+    span.set_tag('my_interesting_tag', 'my_interesting_value')
+    time.sleep(0.05)
+    span.finish()
+
+  init_tracer('my_service_name')
+  my_operation()
+
+**Context Manager Tracing**
+
+To trace a function using the span context manager::
+
+  import time
+  import opentracing
+  from ddtrace.opentracer import Tracer, set_global_tracer
+
+  def init_tracer(service_name):
+      config = {
+        'agent_hostname': 'localhost',
+        'agent_port': 8126,
+      }
+      tracer = Tracer(service_name, config=config)
+      set_global_tracer(tracer)
+      return tracer
+
+  def my_operation():
+    with opentracing.tracer.start_span('my_operation_name') as span:
+      span.set_tag('my_interesting_tag', 'my_interesting_value')
+      time.sleep(0.05)
+
+  init_tracer('my_service_name')
+  my_operation()
+
+See our tracing trace-examples_ repository for concrete, runnable examples of
+the Datadog opentracer.
+
+.. _trace-examples: https://github.com/DataDog/trace-examples/tree/master/python
+
+See also the `Python OpenTracing`_ repository for usage of the tracer.
+
+.. _Python OpenTracing: https://github.com/opentracing/opentracing-python
 
 Advanced Usage
 --------------