praval.observability.tracing.tracer

Official OpenTelemetry tracer compatibility facade.

Functions

generate_span_id()

Generate a valid non-zero OpenTelemetry span identifier.

generate_trace_id()

Generate a valid non-zero OpenTelemetry trace identifier.

reset_tracer()

Retain the old test hook; tracer ownership now lives in lifecycle.
class praval.observability.tracing.tracer.Tracer[source]

Bases: ABC

Handles span creation and in-process context propagation.

This class provides methods for manipulating the context, creating spans, and controlling spans’ lifecycles.

abstractmethod start_span(name, context=None, kind=SpanKind.INTERNAL, attributes=None, links=None, start_time=None, record_exception=True, set_status_on_exception=True)[source]

Starts a span.

Create a new span. Start the span without setting it as the current span in the context. To start the span and use the context in a single method, see start_as_current_span().

By default the current span in the context will be used as parent, but an explicit context can also be specified, by passing in a Context containing a current Span. If there is no current span in the global Context or in the specified context, the created span will be a root span.

The span can be used as a context manager. On exiting the context manager, the span’s end() method will be called.

Example:

# trace.get_current_span() will be used as the implicit parent.
# If none is found, the created span will be a root instance.
with tracer.start_span("one") as child:
    child.add_event("child's event")
Parameters:

  • name (str) – The name of the span to be created.

  • context (Context | None) – An optional Context containing the span’s parent. Defaults to the global context.

  • kind (SpanKind) – The span’s kind (relationship to parent). Note that is meaningful even if there is no parent.

  • attributes (Mapping[str, str | bool | int | float | Sequence[str] | Sequence[bool] | Sequence[int] | Sequence[float]] | None) – The span’s attributes.

  • links (Sequence[Link] | None) – Links span to other spans

  • start_time (int | None) – Sets the start time of a span

  • record_exception (bool) – Whether to record any exceptions raised within the context as error event on the span.

  • set_status_on_exception (bool) – Only relevant if the returned span is used in a with/context manager. Defines whether the span status will be automatically set to ERROR when an uncaught exception is raised in the span with block. The span status won’t be set by this mechanism if it was previously set manually.

Return type:

Span

Returns:

The newly-created span.

abstractmethod start_as_current_span(name, context=None, kind=SpanKind.INTERNAL, attributes=None, links=None, start_time=None, record_exception=True, set_status_on_exception=True, end_on_exit=True)[source]

Context manager for creating a new span and set it as the current span in this tracer’s context.

Exiting the context manager will call the span’s end method, as well as return the current span to its previous value by returning to the previous context.

Example:

with tracer.start_as_current_span("one") as parent:
    parent.add_event("parent's event")
    with tracer.start_as_current_span("two") as child:
        child.add_event("child's event")
        trace.get_current_span()  # returns child
    trace.get_current_span()      # returns parent
trace.get_current_span()          # returns previously active span

This is a convenience method for creating spans attached to the tracer’s context. Applications that need more control over the span lifetime should use start_span() instead. For example:

with tracer.start_as_current_span(name) as span:
    do_work()

is equivalent to:

span = tracer.start_span(name)
with opentelemetry.trace.use_span(span, end_on_exit=True):
    do_work()

This can also be used as a decorator:

@tracer.start_as_current_span("name")
def function():
    ...

function()
Parameters:

  • name (str) – The name of the span to be created.

  • context (Context | None) – An optional Context containing the span’s parent. Defaults to the global context.

  • kind (SpanKind) – The span’s kind (relationship to parent). Note that is meaningful even if there is no parent.

  • attributes (Mapping[str, str | bool | int | float | Sequence[str] | Sequence[bool] | Sequence[int] | Sequence[float]] | None) – The span’s attributes.

  • links (Sequence[Link] | None) – Links span to other spans

  • start_time (int | None) – Sets the start time of a span

  • record_exception (bool) – Whether to record any exceptions raised within the context as error event on the span.

  • set_status_on_exception (bool) – Only relevant if the returned span is used in a with/context manager. Defines whether the span status will be automatically set to ERROR when an uncaught exception is raised in the span with block. The span status won’t be set by this mechanism if it was previously set manually.

  • end_on_exit (bool) – Whether to end the span automatically when leaving the context manager.

Yields:

The newly-created span.

Return type:

Iterator[Span]

praval.observability.tracing.tracer.generate_span_id()[source]

Generate a valid non-zero OpenTelemetry span identifier.

Return type:

str

praval.observability.tracing.tracer.generate_trace_id()[source]

Generate a valid non-zero OpenTelemetry trace identifier.

Return type:

str

praval.observability.tracing.tracer.get_tracer(name='praval')[source]

Return an official OpenTelemetry tracer from the active provider.

Return type:

Tracer

Parameters:

name (str)

praval.observability.tracing.tracer.reset_tracer()[source]

Retain the old test hook; tracer ownership now lives in lifecycle.

Return type:

None