def log_kv(self, key_values, timestamp=None):
"""Implements the ``log_kv()`` method from the base class.
Logs an :class:`opentelemetry.trace.Event` for the wrapped
OpenTelemetry span.
Note:
The OpenTracing API defines the values of *key_values* to be of any
type. However, the OpenTelemetry API requires that the values be
one of :obj:`str`, :obj:`bool`, :obj:`float`. Therefore, only these
types are supported as values.
Args:
key_values(:obj:`dict`): A dict with :obj:`str` keys and values of
type :obj:`str`, :obj:`bool` or :obj:`float`.
Returns:
Returns this :class:`SpanShim` instance to allow call chaining.
"""
if timestamp is not None:
event_timestamp = util.time_seconds_to_ns(timestamp)
else:
event_timestamp = None
event_name = util.event_name_from_kv(key_values)
self._otel_span.add_event(event_name, key_values, event_timestamp)
return self
def log_kv(self, key_values, timestamp=None):
if timestamp is not None:
event_timestamp = util.time_seconds_to_ns(timestamp)
else:
event_timestamp = None
event_name = util.event_name_from_kv(key_values)
self._otel_span.add_event(event_name, event_timestamp, key_values)
return self
def finish(self, finish_time=None):
"""Implements the ``finish()`` method from the base class.
Ends the OpenTelemetry span wrapped by this :class:`SpanShim`.
If *finish_time* is provided, the time value is converted to the
OpenTelemetry time format (number of nanoseconds since the epoch,
expressed as an integer) and passed on to the OpenTelemetry tracer when
ending the OpenTelemetry span. If *finish_time* isn't provided, it is
up to the OpenTelemetry tracer implementation to generate a timestamp
when ending the span.
Args:
finish_time(:obj:`float`, optional): An explicit finish time
expressed as the number of seconds since the epoch as returned
by :func:`time.time()`. Defaults to `None`.
"""
end_time = finish_time
if end_time is not None:
end_time = util.time_seconds_to_ns(finish_time)
self._otel_span.end(end_time=end_time)
def start_span(
self,
operation_name=None,
child_of=None,
references=None,
tags=None,
start_time=None,
ignore_active_span=False,
):
# Use active span as parent when no explicit parent is specified.
if not ignore_active_span and not child_of:
child_of = self.active_span
# Use the specified parent or the active span if possible. Otherwise,
# use a `None` parent, which triggers the creation of a new trace.
parent = child_of.unwrap() if child_of else None
span = self._otel_tracer.create_span(operation_name, parent)
if references:
for ref in references:
span.add_link(ref.referenced_context.unwrap())
if tags:
for key, value in tags.items():
span.set_attribute(key, value)
# The OpenTracing API expects time values to be `float` values which
# represent the number of seconds since the epoch. OpenTelemetry
# represents time values as nanoseconds since the epoch.
start_time_ns = start_time
if start_time_ns is not None:
start_time_ns = util.time_seconds_to_ns(start_time)
span.start(start_time=start_time_ns)
context = SpanContextShim(span.get_context())
return SpanShim(self, context, span)
def finish(self, finish_time=None):
end_time = finish_time
if end_time is not None:
end_time = util.time_seconds_to_ns(finish_time)
self._otel_span.end(end_time=end_time)
def start_span(
self,
operation_name=None,
child_of=None,
references=None,
tags=None,
start_time=None,
ignore_active_span=False,
):
"""Implements the ``start_span()`` method from the base class.
Starts a span. In terms of functionality, this method behaves exactly
like the same method on a "regular" OpenTracing tracer. See
:meth:`opentracing.Tracer.start_span` for more details.
Args:
operation_name(:obj:`str`): Name of the operation represented by
the new span from the perspective of the current service.
child_of(:class:`SpanShim` or :class:`SpanContextShim`, optional):
A :class:`SpanShim` or :class:`SpanContextShim` representing
the parent in a "child of" reference. If specified, the
*references* parameter must be omitted. Defaults to `None`.
references(:obj:`list`, optional): A list of
:class:`opentracing.Reference` objects that identify one or
more parents of type :class:`SpanContextShim`. Defaults to
`None`.
tags(:obj:`dict`, optional): A dictionary of tags. The keys must be
of type :obj:`str`. The values may be one of :obj:`str`,
:obj:`bool`, :obj:`int`, :obj:`float`. Defaults to `None`.
start_time(:obj:`float`, optional): An explicit start time
expressed as the number of seconds since the epoch as returned
by :func:`time.time()`. Defaults to `None`.
ignore_active_span(:obj:`bool`, optional): Ignore the
currently-active span in the OpenTelemetry tracer and make the
created span the root span of a new trace. Defaults to `False`.
Returns:
An already-started :class:`SpanShim` instance.
"""
# Use active span as parent when no explicit parent is specified.
if not ignore_active_span and not child_of:
child_of = self.active_span
# Use the specified parent or the active span if possible. Otherwise,
# use a `None` parent, which triggers the creation of a new trace.
parent = child_of.unwrap() if child_of else None
links = []
if references:
for ref in references:
links.append(trace_api.Link(ref.referenced_context.unwrap()))
# The OpenTracing API expects time values to be `float` values which
# represent the number of seconds since the epoch. OpenTelemetry
# represents time values as nanoseconds since the epoch.
start_time_ns = start_time
if start_time_ns is not None:
start_time_ns = util.time_seconds_to_ns(start_time)
span = self._otel_tracer.start_span(
operation_name,
parent,
links=links,
attributes=tags,
start_time=start_time_ns,
)
context = SpanContextShim(span.get_context())
return SpanShim(self, context, span)
