Span

class opencensus.trace.span.BoundedDict(maxlen)

Bases: collections.abc.MutableMapping

A dict with a fixed max capacity.

class opencensus.trace.span.BoundedList(maxlen)

Bases: collections.abc.Sequence

An append only list with a fixed max size.

class opencensus.trace.span.Span(name, parent_span=None, attributes=None, start_time=None, end_time=None, span_id=None, stack_trace=None, annotations=None, message_events=None, links=None, status=None, same_process_as_parent_span=None, context_tracer=None, span_kind=0)

Bases: opencensus.trace.base_span.BaseSpan

A span is an individual timed event which forms a node of the trace tree. Each span has its name, span id and parent id. The parent id indicates the causal relationships between the individual spans in a single distributed trace. Span that does not have a parent id is called root span. All spans associated with a specific trace also share a common trace id. Spans do not need to be continuous, there can be gaps between two spans.

Parameters

• name (str) -- The name of the span.

• parent_span (Span) -- (Optional) Parent span.

• attributes (dict) -- Collection of attributes associated with the span. Attribute keys must be less than 128 bytes. Attribute values must be less than 16 kilobytes.

• start_time (str) -- (Optional) Start of the time interval (inclusive) during which the trace data was collected from the application.

• end_time (str) -- (Optional) End of the time interval (inclusive) during which the trace data was collected from the application.

• span_id (int) -- Identifier for the span, unique within a trace.

• stack_trace -- (Optional) A call stack appearing in a trace

• annotations (list(opencensus.trace.time_event.Annotation)) -- (Optional) The list of span annotations.

• message_events (list(opencensus.trace.time_event.MessageEvent)) -- (Optional) The list of span message events.

• links (list) -- (Optional) Links associated with the span. You can have up to 128 links per Span.

• status -- (Optional) An optional final status for this span.

• same_process_as_parent_span (bool) -- (Optional) A highly recommended but not required flag that identifies when a trace crosses a process boundary. True when the parent_span belongs to the same process as the current span.

• context_tracer ( ContextTracer) -- The tracer that holds a stack of spans. If this is not None, then when exiting a span, use the end_span method in the tracer class to finish a span. If no tracer is passed in, then just finish the span using the finish method in the Span class.

• span_kind (int) -- (Optional) Highly recommended flag that denotes the type of span (valid values defined by :class: opencensus.trace.span.SpanKind)

add_annotation(description, **attrs)

Add an annotation to span.

Parameters

• description (str) -- A user-supplied message describing the event. The maximum length for the description is 256 bytes.

• attrs (kwargs) -- keyworded arguments e.g. failed=True, name='Caching'

add_attribute(attribute_key, attribute_value)

Add attribute to span.

Parameters

attribute_key (str) -- Attribute key.

:type attribute_value:str :param attribute_value: Attribute value.

add_link(link)

Add a Link.

Parameters

link -- A Link object.

add_message_event(message_event)

Add a message event to this span.

Parameters

message_event (opencensus.trace.time_event.MessageEvent) -- The message event to attach to this span.

children

The child spans of the current span.

finish()

Set the end time for a span.

span(name='child_span')

Create a child span for the current span and append it to the child spans list.

Parameters

name (str) -- (Optional) The name of the child span.

Return type

class

~opencensus.trace.span.Span

Returns

A child Span to be added to the current span.

start()

Set the start time for a span.

opencensus.trace.span.format_span_json(span)

Helper to format a Span in JSON format.

Parameters

span (Span) -- A Span to be transferred to JSON format.

Return type

dict

Returns

Formatted Span.