diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 3abaf91..17e425b 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -27,7 +27,7 @@ History 1.2.1 (2016-09-22) ------------------ -- Make Span.log(self, **kwargs) smarter +- Make Span.log(self, \**kwargs) smarter 1.2.0 (2016-09-21) @@ -115,7 +115,7 @@ History ------------------ - Change inheritance to match api-go: TraceContextSource extends codecs, -Tracer extends TraceContextSource + Tracer extends TraceContextSource - Create API harness diff --git a/docs/conf.py b/docs/conf.py index ffd1887..206eacf 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -16,7 +16,7 @@ html_theme = 'sphinx_rtd_theme' html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] -html_static_path = ['_static'] +html_static_path = [] exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] intersphinx_mapping = { diff --git a/opentracing/ext/scope.py b/opentracing/ext/scope.py index 707a2dd..7731818 100644 --- a/opentracing/ext/scope.py +++ b/opentracing/ext/scope.py @@ -31,16 +31,16 @@ def __init__(self, manager, span, finish_on_close): """Initialize a `Scope` for the given `Span` object. :param span: the `Span` wrapped by this `Scope`. - :param finish_on_close: whether span should automatically be - finished when `Scope#close()` is called. + :param finish_on_close: whether :class:`Span` should automatically be + finished when :meth:`Scope.close()` is called. """ super(ThreadLocalScope, self).__init__(manager, span) self._finish_on_close = finish_on_close self._to_restore = manager.active def close(self): - """Mark the end of the active period for this {@link Scope}, - updating ScopeManager#active in the process. + """Mark the end of the active period for this :class:`Scope`, + updating :attr:`ScopeManager.active` in the process. """ if self.manager.active is not self: return diff --git a/opentracing/propagation.py b/opentracing/propagation.py index cb3257a..74b6888 100644 --- a/opentracing/propagation.py +++ b/opentracing/propagation.py @@ -23,9 +23,9 @@ class UnsupportedFormatException(Exception): """UnsupportedFormatException should be used when the provided format - value is unknown or disallowed by the Tracer. + value is unknown or disallowed by the :class:`Tracer`. - See Tracer.inject() and Tracer.extract(). + See :meth:`Tracer.inject()` and :meth:`Tracer.extract()`. """ pass @@ -34,16 +34,16 @@ class InvalidCarrierException(Exception): """InvalidCarrierException should be used when the provided carrier instance does not match what the `format` argument requires. - See Tracer.inject() and Tracer.extract(). + See :meth:`Tracer.inject()` and :meth:`Tracer.extract()`. """ pass class SpanContextCorruptedException(Exception): - """SpanContextCorruptedException should be used when the underlying span - context state is seemingly present but not well-formed. + """SpanContextCorruptedException should be used when the underlying + :class:`SpanContext` state is seemingly present but not well-formed. - See Tracer.inject() and Tracer.extract(). + See :meth:`Tracer.inject()` and :meth:`Tracer.extract()`. """ pass @@ -51,8 +51,8 @@ class SpanContextCorruptedException(Exception): class Format(object): """A namespace for builtin carrier formats. - These static constants are intended for use in the Tracer.inject() and - Tracer.extract() methods. E.g.:: + These static constants are intended for use in the :meth:`Tracer.inject()` + and :meth:`Tracer.extract()` methods. E.g.:: tracer.inject(span.context, Format.BINARY, binary_carrier) @@ -62,29 +62,29 @@ class Format(object): """ The BINARY format represents SpanContexts in an opaque bytearray carrier. - For both Tracer.inject() and Tracer.extract() the carrier should be a - bytearray instance. Tracer.inject() must append to the bytearray carrier - (rather than replace its contents). + For both :meth:`Tracer.inject()` and :meth:`Tracer.extract()` the carrier + should be a bytearray instance. :meth:`Tracer.inject()` must append to the + bytearray carrier (rather than replace its contents). """ TEXT_MAP = 'text_map' """ - The TEXT_MAP format represents SpanContexts in a python dict mapping from - strings to strings. + The TEXT_MAP format represents :class:`SpanContext`\ s in a python ``dict`` + mapping from strings to strings. Both the keys and the values have unrestricted character sets (unlike the HTTP_HEADERS format). - NOTE: The TEXT_MAP carrier dict may contain unrelated data (e.g., - arbitrary gRPC metadata). As such, the Tracer implementation should use a - prefix or other convention to distinguish Tracer-specific key:value - pairs. + NOTE: The TEXT_MAP carrier ``dict`` may contain unrelated data (e.g., + arbitrary gRPC metadata). As such, the :class:`Tracer` implementation + should use a prefix or other convention to distinguish tracer-specific + key:value pairs. """ HTTP_HEADERS = 'http_headers' """ - The HTTP_HEADERS format represents SpanContexts in a python dict mapping - from character-restricted strings to strings. + The HTTP_HEADERS format represents :class:`SpanContext`\ s in a python + ``dict`` mapping from character-restricted strings to strings. Keys and values in the HTTP_HEADERS carrier must be suitable for use as HTTP headers (without modification or further escaping). That is, the @@ -92,8 +92,8 @@ class Format(object): be preserved by various intermediaries, and the values should be URL-escaped. - NOTE: The HTTP_HEADERS carrier dict may contain unrelated data (e.g., - arbitrary gRPC metadata). As such, the Tracer implementation should use a - prefix or other convention to distinguish Tracer-specific key:value - pairs. + NOTE: The HTTP_HEADERS carrier ``dict`` may contain unrelated data (e.g., + arbitrary gRPC metadata). As such, the :class:`Tracer` implementation + should use a prefix or other convention to distinguish tracer-specific + key:value pairs. """ diff --git a/opentracing/scope.py b/opentracing/scope.py index 9aa321a..dc28583 100644 --- a/opentracing/scope.py +++ b/opentracing/scope.py @@ -22,38 +22,46 @@ class Scope(object): - """A `Scope` formalizes the activation and deactivation of a `Span`, - usually from a CPU standpoint. Many times a `Span` will be extant (in that - `Span#finish()` has not been called) despite being in a non-runnable state - from a CPU/scheduler standpoint. For instance, a `Span` representing the - client side of an RPC will be unfinished but blocked on IO while the RPC is - still outstanding. A `Scope` defines when a given `Span` is scheduled - and on the path. + """A scope formalizes the activation and deactivation of a :class:`Span`, + usually from a CPU standpoint. Many times a :class:`Span` will be extant + (in that :meth:`Span.finish()` has not been called) despite being in a + non-runnable state from a CPU/scheduler standpoint. For instance, a + :class:`Span` representing the client side of an RPC will be unfinished but + blocked on IO while the RPC is still outstanding. A scope defines when a + given :class:`Span` is scheduled and on the path. + + :param manager: the :class:`ScopeManager` that created this :class:`Scope`. + :type manager: ScopeManager + + :param span: the :class:`Span` used for this :class:`Scope`. + :type span: Span """ def __init__(self, manager, span): - """Initializes a `Scope` for the given `Span` object. - - :param manager: the `ScopeManager` that created this `Scope` - :param span: the `Span` used for this `Scope` - """ + """Initializes a scope for *span*.""" self._manager = manager self._span = span @property def span(self): - """Returns the `Span` wrapped by this `Scope`.""" + """Returns the :class:`Span` wrapped by this :class:`Scope`. + + :rtype: Span + """ return self._span @property def manager(self): - """Returns the `ScopeManager` that created this `Scope`.""" + """Returns the :class:`ScopeManager` that created this :class:`Scope`. + + :rtype: ScopeManager + """ return self._manager def close(self): - """Marks the end of the active period for this `Scope`, - updating `ScopeManager#active` in the process. + """Marks the end of the active period for this :class:`Scope`, updating + :attr:`ScopeManager.active` in the process. - NOTE: Calling `close()` more than once on a single `Scope` instance + NOTE: Calling this method more than once on a single :class:`Scope` leads to undefined behavior. """ pass @@ -63,7 +71,7 @@ def __enter__(self): return self def __exit__(self, exc_type, exc_val, exc_tb): - """Calls `close()` when the execution is outside the Python + """Calls :meth:`close()` when the execution is outside the Python Context Manager. """ self.close() diff --git a/opentracing/scope_manager.py b/opentracing/scope_manager.py index 72b0d10..eb6bb6c 100644 --- a/opentracing/scope_manager.py +++ b/opentracing/scope_manager.py @@ -25,9 +25,8 @@ class ScopeManager(object): - """The `ScopeManager` interface abstracts both the activation of `Span` - instances (via `ScopeManager#activate(span, finish_on_close)`) and - access to an active `Span` / `Scope` (via `ScopeManager#active`). + """The :class:`ScopeManager` interface abstracts both the activation of + a :class:`Span` and access to an active :class:`Span`/:class:`Scope`. """ def __init__(self): # TODO: `tracer` should not be None, but we don't have a reference; @@ -37,27 +36,30 @@ def __init__(self): self._noop_scope = Scope(self, self._noop_span) def activate(self, span, finish_on_close): - """Makes a `Span` instance active. + """Makes a :class:`Span` active. - :param span: the `Span` that should become active. - :param finish_on_close: whether span should be automatically - finished when `Scope#close()` is called. + :param span: the :class:`Span` that should become active. + :param finish_on_close: whether :class:`Span` should be automatically + finished when :meth:`Scope.close()` is called. - :return: a `Scope` instance to control the end of the active period for - the `Span`. It is a programming error to neglect to call - `Scope#close()` on the returned instance. + :rtype: Scope + :return: a :class:`Scope` to control the end of the active period for + *span*. It is a programming error to neglect to call + :meth:`Scope.close()` on the returned instance. """ return self._noop_scope @property def active(self): - """Returns the currently active `Scope` which can be used to access the - currently active `Scope#span`. + """Returns the currently active :class:`Scope` which can be used to access the + currently active :attr:`Scope.span`. - If there is a non-null `Scope`, its wrapped `Span` becomes an implicit - parent of any newly-created `Span` at `Tracer#start_active_span()` - time. + If there is a non-null :class:`Scope`, its wrapped :class:`Span` + becomes an implicit parent of any newly-created :class:`Span` at + :meth:`Tracer.start_active_span()` time. - :return: the `Scope` that is active, or `None` if not available. + :rtype: Scope + :return: the :class:`Scope` that is active, or ``None`` if not + available. """ return self._noop_scope diff --git a/opentracing/span.py b/opentracing/span.py index b5c87e7..a99bf61 100644 --- a/opentracing/span.py +++ b/opentracing/span.py @@ -24,14 +24,15 @@ class SpanContext(object): - """SpanContext represents Span state that must propagate to descendant - Spans and across process boundaries. + """SpanContext represents :class:`Span` state that must propagate to + descendant :class:`Span`\ s and across process boundaries. SpanContext is logically divided into two pieces: the user-level "Baggage" - (see set_baggage_item and get_baggage_item) that propagates across Span - boundaries and any Tracer-implementation-specific fields that are needed to - identify or otherwise contextualize the associated Span instance (e.g., a - tuple). + (see :meth:`Span.set_baggage_item` and :meth:`Span.get_baggage_item`) that + propagates across :class:`Span` boundaries and any + tracer-implementation-specific fields that are needed to identify or + otherwise contextualize the associated :class:`Span` (e.g., a ``(trace_id, + span_id, sampled)`` tuple). """ EMPTY_BAGGAGE = {} # TODO would be nice to make this immutable @@ -39,15 +40,17 @@ class SpanContext(object): @property def baggage(self): """ - Return baggage associated with this SpanContext. - If no baggage has been added to the span, returns an empty dict. + Return baggage associated with this :class:`SpanContext`. + If no baggage has been added to the :class:`Span`, returns an empty + dict. The caller must not modify the returned dictionary. - See also: Span.set_baggage_item() / Span.get_baggage_item() + See also: :meth:`Span.set_baggage_item()` / + :meth:`Span.get_baggage_item()` :rtype: dict - :return: returns baggage associated with this SpanContext or {}. + :return: baggage associated with this :class:`SpanContext` or ``{}``. """ return SpanContext.EMPTY_BAGGAGE @@ -60,14 +63,13 @@ class Span(object): and these relationships transitively form a DAG. It is common for spans to have at most one parent, and thus most traces are merely tree structures. - Span implements a Context Manager API that allows the following usage: - - .. code-block:: python + Span implements a context manager API that allows the following usage:: with tracer.start_span(operation_name='go_fishing') as span: call_some_service() - In the Context Manager syntax it's not necessary to call span.finish() + In the context manager syntax it's not necessary to call + :meth:`Span.finish()` """ def __init__(self, tracer, context): @@ -76,20 +78,24 @@ def __init__(self, tracer, context): @property def context(self): - """Provides access to the SpanContext associated with this Span. + """Provides access to the :class:`SpanContext` associated with this + :class:`Span`. - The SpanContext contains state that propagates from Span to Span in a - larger trace. + The :class:`SpanContext` contains state that propagates from + :class:`Span` to :class:`Span` in a larger trace. - :return: returns the SpanContext associated with this Span. + :rtype: SpanContext + :return: the :class:`SpanContext` associated with this :class:`Span`. """ return self._context @property def tracer(self): - """Provides access to the Tracer that created this Span. + """Provides access to the :class:`Tracer` that created this + :class:`Span`. - :return: returns the Tracer that created this Span. + :rtype: Tracer + :return: the :class:`Tracer` that created this :class:`Span`. """ return self._tracer @@ -97,42 +103,51 @@ def set_operation_name(self, operation_name): """Changes the operation name. :param operation_name: the new operation name - :return: Returns the Span itself, for call chaining. + :type operation_name: str + + :rtype: Span + :return: the :class:`Span` itself, for call chaining. """ return self def finish(self, finish_time=None): - """Indicates that the work represented by this span has completed or + """Indicates that the work represented by this :class:`Span` has completed or terminated. - With the exception of the `Span.context` property, the semantics of all - other Span methods are undefined after `finish()` has been invoked. + With the exception of the :attr:`Span.context` property, the semantics + of all other :class:`Span` methods are undefined after + :meth:`Span.finish()` has been invoked. - :param finish_time: an explicit Span finish timestamp as a unix - timestamp per time.time() + :param finish_time: an explicit :class:`Span` finish timestamp as a + unix timestamp per :meth:`time.time()` + :type finish_time: float """ pass def set_tag(self, key, value): - """Attaches a key/value pair to the span. + """Attaches a key/value pair to the :class:`Span`. The value must be a string, a bool, or a numeric type. If the user calls set_tag multiple times for the same key, - the behavior of the tracer is undefined, i.e. it is implementation - specific whether the tracer will retain the first value, or the last - value, or pick one randomly, or even keep all of them. + the behavior of the :class:`Tracer` is undefined, i.e. it is + implementation specific whether the :class:`Tracer` will retain the + first value, or the last value, or pick one randomly, or even keep all + of them. :param key: key or name of the tag. Must be a string. + :type key: str + :param value: value of the tag. + :type value: string or bool or int or float - :return: Returns the Span itself, for call chaining. :rtype: Span + :return: the :class:`Span` itself, for call chaining. """ return self def log_kv(self, key_values, timestamp=None): - """Adds a log record to the Span. + """Adds a log record to the :class:`Span`. For example:: @@ -145,24 +160,24 @@ def log_kv(self, key_values, timestamp=None): :param key_values: A dict of string keys and values of any type :type key_values: dict - :param timestamp: A unix timestamp per time.time(); current time if - None + :param timestamp: A unix timestamp per :meth:`time.time()`; current + time if ``None`` :type timestamp: float - :return: Returns the Span itself, for call chaining. :rtype: Span + :return: the :class:`Span` itself, for call chaining. """ return self def set_baggage_item(self, key, value): - """Stores a Baggage item in the span as a key/value pair. + """Stores a Baggage item in the :class:`Span` as a key/value pair. Enables powerful distributed context propagation functionality where arbitrary application data can be carried along the full path of request execution throughout the system. Note 1: Baggage is only propagated to the future (recursive) children - of this Span. + of this :class:`Span`. Note 2: Baggage is sent in-band with every subsequent local and remote calls, so this feature must be used with care. @@ -173,34 +188,35 @@ def set_baggage_item(self, key, value): :param value: Baggage item value :type value: str - :rtype : Span + :rtype: Span :return: itself, for chaining the calls. """ return self def get_baggage_item(self, key): - """Retrieves value of the Baggage item with the given key. + """Retrieves value of the baggage item with the given key. - :param key: key of the Baggage item + :param key: key of the baggage item :type key: str - :rtype : str - :return: value of the Baggage item with given key, or None. + :rtype: str + :return: value of the baggage item with given key, or ``None``. """ return None def __enter__(self): - """Invoked when span is used as a context manager. + """Invoked when :class:`Span` is used as a context manager. - :return: returns the Span itself + :rtype: Span + :return: the :class:`Span` itself """ return self def __exit__(self, exc_type, exc_val, exc_tb): - """Ends context manager and calls finish() on the span. + """Ends context manager and calls finish() on the :class:`Span`. If exception has occurred during execution, it is automatically added - as a tag to the span. + as a tag to the :class:`Span`. """ if exc_type: self.log_kv({ diff --git a/opentracing/tracer.py b/opentracing/tracer.py index 232ab58..478b560 100644 --- a/opentracing/tracer.py +++ b/opentracing/tracer.py @@ -53,11 +53,12 @@ def scope_manager(self): @property def active_span(self): - """Provides access to the the active Span. This is a shorthand for - Tracer.scope_manager.active.span, and None will be returned if - Scope.span is None. + """Provides access to the the active :class:`Span`. This is a shorthand for + :attr:`Tracer.scope_manager.active.span`, and ``None`` will be + returned if :attr:`Scope.span` is ``None``. - :return: returns the active Span. + :rtype: Span + :return: the active :class:`Span`. """ scope = self._scope_manager.active return None if scope is None else scope.span @@ -70,18 +71,19 @@ def start_active_span(self, start_time=None, ignore_active_span=False, finish_on_close=True): - """Returns a newly started and activated `Scope`. + """Returns a newly started and activated :class:`Scope`. - The returned `Scope` supports with-statement contexts. For example: + The returned :class:`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 + # 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: + It's also possible to not finish the :class:`Span` when the + :class:`Scope` context expires:: with tracer.start_active_span('...', finish_on_close=False) as scope: @@ -91,24 +93,39 @@ def start_active_span(self, # `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 - the parent in a REFERENCE_CHILD_OF Reference. If specified, the - `references` parameter must be omitted. - :param references: (optional) a list of Reference objects that identify - one or more parent SpanContexts. (See the Reference documentation + :class:`Span` from the perspective of the current service. + :type operation_name: str + + :param child_of: (optional) a :class:`Span` or :class:`SpanContext` + instance representing the parent in a REFERENCE_CHILD_OF reference. + If specified, the `references` parameter must be omitted. + :type child_of: Span or SpanContext + + :param references: (optional) references that identify one or more + parent :class:`SpanContext`\ s. (See the Reference documentation for detail). - :param tags: an optional dictionary of Span Tags. The caller gives up - ownership of that dictionary, because the Tracer may use it as-is - to avoid extra data copying. - :param start_time: an explicit Span start time as a unix timestamp per - time.time(). + :type references: :obj:`list` of :class:`Reference` + + :param tags: an optional dictionary of :class:`Span` tags. The caller + gives up ownership of that dictionary, because the :class:`Tracer` + may use it as-is to avoid extra data copying. + :type tags: dict + + :param start_time: an explicit :class:`Span` start time as a unix + timestamp per :meth:`time.time()`. + :type start_time: float + :param ignore_active_span: (optional) an explicit flag that ignores - the current active `Scope` and creates a root `Span`. - :param finish_on_close: whether span should automatically be finished - when `Scope#close()` is called. + the current active :class:`Scope` and creates a root :class:`Span`. + :type ignore_active_span: bool + + :param finish_on_close: whether :class:`Span` should automatically be + finished when :meth:`Scope.close()` is called. + :type finish_on_close: bool - :return: a `Scope`, already registered via the `ScopeManager`. + :rtype: Scope + :return: a :class:`Scope`, already registered via the + :class:`ScopeManager`. """ return self._noop_scope @@ -119,22 +136,23 @@ def start_span(self, tags=None, start_time=None, ignore_active_span=False): - """Starts and returns a new Span representing a unit of work. + """Starts and returns a new :class:`Span` representing a unit of work. - Starting a root Span (a Span with no causal references):: + Starting a root :class:`Span` (a :class:`Span` with no causal + references):: tracer.start_span('...') - Starting a child Span (see also start_child_span()):: + Starting a child :class:`Span` (see also :meth:`start_child_span()`):: tracer.start_span( '...', child_of=parent_span) - Starting a child Span in a more verbose way:: + Starting a child :class:`Span` in a more verbose way:: tracer.start_span( '...', @@ -142,22 +160,34 @@ def start_span(self, :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 - the parent in a REFERENCE_CHILD_OF Reference. If specified, the - `references` parameter must be omitted. - :param references: (optional) a list of Reference objects that identify - one or more parent SpanContexts. (See the Reference documentation - for detail) - :param tags: an optional dictionary of Span Tags. The caller gives up - ownership of that dictionary, because the Tracer may use it as-is - to avoid extra data copying. + :class:`Span` from the perspective of the current service. + :type operation_name: str + + :param child_of: (optional) a :class:`Span` or :class:`SpanContext` + representing the parent in a REFERENCE_CHILD_OF reference. If + specified, the `references` parameter must be omitted. + :type child_of: Span or SpanContext + + :param references: (optional) references that identify one or more + parent :class:`SpanContext`\ s. (See the Reference documentation + for detail). + :type references: :obj:`list` of :class:`Reference` + + :param tags: an optional dictionary of :class:`Span` tags. The caller + gives up ownership of that dictionary, because the :class:`Tracer` + may use it as-is to avoid extra data copying. + :type tags: dict + :param start_time: an explicit Span start time as a unix timestamp per - time.time() + :meth:`time.time()` + :type start_time: float + :param ignore_active_span: an explicit flag that ignores the current - active `Scope` and creates a root `Span`. + active :class:`Scope` and creates a root :class:`Span`. + :type ignore_active_span: bool - :return: Returns an already-started Span instance. + :rtype: Span + :return: an already-started :class:`Span` instance. """ return self._noop_span @@ -165,16 +195,18 @@ def inject(self, span_context, format, carrier): """Injects `span_context` into `carrier`. The type of `carrier` is determined by `format`. See the - opentracing.propagation.Format class/namespace for the built-in - OpenTracing formats. + :class:`Format` class/namespace for the built-in OpenTracing formats. - Implementations MUST raise opentracing.UnsupportedFormatException if + Implementations *must* raise :exc:`UnsupportedFormatException` if `format` is unknown or disallowed. - :param span_context: the SpanContext instance to inject + :param span_context: the :class:`SpanContext` instance to inject + :type span_context: SpanContext + :param format: a python object instance that represents a given carrier format. `format` may be of any type, and `format` equality - is defined by python `==` equality. + is defined by python ``==`` equality. + :type format: Format :param carrier: the format-specific carrier object to inject into """ if format in Tracer._supported_formats: @@ -182,27 +214,30 @@ def inject(self, span_context, format, carrier): raise UnsupportedFormatException(format) def extract(self, format, carrier): - """Returns a SpanContext instance extracted from a `carrier` of the - given `format`, or None if no such SpanContext could be found. + """Returns a :class:`SpanContext` instance extracted from a `carrier` of the + given `format`, or ``None`` if no such :class:`SpanContext` could be + found. The type of `carrier` is determined by `format`. See the - opentracing.propagation.Format class/namespace for the built-in - OpenTracing formats. + :class:`Format` class/namespace for the built-in OpenTracing formats. - Implementations MUST raise opentracing.UnsupportedFormatException if + Implementations *must* raise :exc:`UnsupportedFormatException` if `format` is unknown or disallowed. - Implementations may raise opentracing.InvalidCarrierException, - opentracing.SpanContextCorruptedException, or implementation-specific - errors if there are problems with `carrier`. + Implementations may raise :exc:`InvalidCarrierException`, + :exc:`SpanContextCorruptedException`, or implementation-specific errors + if there are problems with `carrier`. + :param format: a python object instance that represents a given carrier format. `format` may be of any type, and `format` equality - is defined by python `==` equality. + is defined by python ``==`` equality. + :param carrier: the format-specific carrier object to extract from - :return: a SpanContext instance extracted from `carrier` or None if no - such span context could be found. + :rtype: SpanContext + :return: a :class:`SpanContext` extracted from `carrier` or ``None`` if + no such :class:`SpanContext` could be found. """ if format in Tracer._supported_formats: return self._noop_span_context @@ -222,22 +257,23 @@ class ReferenceType(object): # We use namedtuple since references are meant to be immutable. # We subclass it to expose a standard docstring. class Reference(namedtuple('Reference', ['type', 'referenced_context'])): - """A Reference pairs a reference type with a referenced SpanContext. + """A Reference pairs a reference type with a referenced :class:`SpanContext`. - References are used by Tracer.start_span() to describe the relationships - between Spans. + References are used by :meth:`Tracer.start_span()` to describe the + relationships between :class:`Span`\ s. - Tracer implementations must ignore references where referenced_context is - None. This behavior allows for simpler code when an inbound RPC request - contains no tracing information and as a result tracer.extract() returns - None:: + :class:`Tracer` implementations must ignore references where + referenced_context is ``None``. This behavior allows for simpler code when + an inbound RPC request contains no tracing information and as a result + :meth:`Tracer.extract()` returns ``None``:: parent_ref = tracer.extract(opentracing.HTTP_HEADERS, request.headers) span = tracer.start_span( 'operation', references=child_of(parent_ref) ) - See `child_of` and `follows_from` helpers for creating these references. + See :meth:`child_of` and :meth:`follows_from` helpers for creating these + references. """ pass @@ -245,11 +281,14 @@ class Reference(namedtuple('Reference', ['type', 'referenced_context'])): def child_of(referenced_context=None): """child_of is a helper that creates CHILD_OF References. - :param referenced_context: the (causal parent) SpanContext to reference. - If None is passed, this reference must be ignored by the tracer. + :param referenced_context: the (causal parent) :class:`SpanContext` to + reference. If ``None`` is passed, this reference must be ignored by + the :class:`Tracer`. + :type referenced_context: SpanContext :rtype: Reference - :return: A Reference suitable for Tracer.start_span(..., references=...) + :return: A reference suitable for ``Tracer.start_span(..., + references=...)`` """ return Reference( type=ReferenceType.CHILD_OF, @@ -259,11 +298,14 @@ def child_of(referenced_context=None): def follows_from(referenced_context=None): """follows_from is a helper that creates FOLLOWS_FROM References. - :param referenced_context: the (causal parent) SpanContext to reference - If None is passed, this reference must be ignored by the tracer. + :param referenced_context: the (causal parent) :class:`SpanContext` to + reference. If ``None`` is passed, this reference must be ignored by the + :class:`Tracer`. + :type referenced_context: SpanContext :rtype: Reference - :return: A Reference suitable for Tracer.start_span(..., references=...) + :return: A Reference suitable for ``Tracer.start_span(..., + references=...)`` """ return Reference( type=ReferenceType.FOLLOWS_FROM, @@ -271,9 +313,10 @@ def follows_from(referenced_context=None): def start_child_span(parent_span, operation_name, tags=None, start_time=None): - """A shorthand method that starts a child_of span for a given parent span. + """A shorthand method that starts a `child_of` :class:`Span` for a given + parent :class:`Span`. - Equivalent to calling + Equivalent to calling:: parent_span.tracer().start_span( operation_name, @@ -281,16 +324,25 @@ def start_child_span(parent_span, operation_name, tags=None, start_time=None): tags=tags, start_time=start_time) - :param parent_span: the Span which will act as the parent in the returned - Span's child_of reference. - :param operation_name: the operation name for the child Span instance - :param tags: optional dict of Span Tags. The caller gives up ownership of - that dict, because the Tracer may use it as-is to avoid extra data - copying. - :param start_time: an explicit Span start time as a unix timestamp per - time.time(). + :param parent_span: the :class:`Span` which will act as the parent in the + returned :class:`Span`\ s child_of reference. + :type parent_span: Span + + :param operation_name: the operation name for the child :class:`Span` + instance + :type operation_name: str + + :param tags: optional dict of :class:`Span` tags. The caller gives up + ownership of that dict, because the :class:`Tracer` may use it as-is to + avoid extra data copying. + :type tags: dict + + :param start_time: an explicit :class:`Span` start time as a unix timestamp + per :meth:`time.time()`. + :type start_time: float - :return: Returns an already-started Span instance. + :rtype: Span + :return: an already-started :class:`Span` instance. """ return parent_span.tracer.start_span( operation_name=operation_name,