NAME

OpenTelemetry::Trace - Generic methods for the OpenTelemetry Tracing API

SYNOPSIS

    use OpenTelemetry::Trace;

    # Retrieve a span from context
    my $span = OpenTelemetry::Trace->span_from_context;

    # Store a span in the context
    my $context = OpenTelemetry::Trace->context_with_span($span);

    # This is a no-op, since we are retrieving the span we stored
    $span = OpenTelemetry::Trace->span_from_context($context);

DESCRIPTION

This package provides some methods for injecting Span objects into, and extracting them from, a given context.

For the meat and bones of the OpenTelemetry Tracing API, please see the following packages:

OpenTelemetry::Trace::TracerProvider, which provides access to tracers.

OpenTelemetry::Trace::Tracer, which can create spans.

OpenTelemetry::Trace::Span, which allows the trace of a single operation.

METHODS

span_from_context

    $span = OpenTelemetry::Trace->span_from_context($context);

Takes an optional OpenTelemetry::Context object, and returns the OpenTelemetry::Trace::Span object that has been stored within, if any. If no context was provided, the span will be read from the current context.

If no span was found in the context, this method returns an invalid span (see "INVALID_SPAN_ID" below).

context_with_span

    $context = OpenTelemetry::Trace->context_with_span( $span, $context );

Takes an OpenTelemetry::Trace::Span and returns a context that contains it (such that passing that context to eg. "span_from_context" would return the provided span).

An optional OpenTelemetry::Context instance can be passed as a second argument, in which case it will be used as the base for the new context. If no context is provided, the current context will be used.

non_recording_span

    $span = OpenTelemetry::Trace->non_recording_span($span_context)

Returns an instance of OpenTelemetry::Trace::Span that records no trace data. Operations on this span are effectively a no-op.

Takes an instance of OpenTelemetry::Trace::SpanContext to use as the context of the span. If none is provided, it will default to a new instance.

generate_trace_id

    $id = OpenTelemetry::Trace->generate_trace_id;

Generate a new random trace ID. This ID is guaranteed to be valid.

generate_span_id

    $id = OpenTelemetry::Trace->generate_span_id;

Generate a new random span ID. This ID is guaranteed to be valid.

untraced_context

    $new_context = OpenTelemetry::Trace->untraced_context($context);

Returns a new OpenTelemetry::Context instance which is marked as untraced. This can be used together with the "is_untraced_context" method below to locally disable tracing for internal operations:

    dynamically OpenTelemetry::Context->current
        = OpenTelemetry::Trace->untraced_context;

This method takes an optional OpenTelemetry::Context to use as the base context. If none is provided, the current context will be used.

is_untraced_context

    $bool = OpenTelemetry::Trace->is_untraced_context($context);

Takes an OpenTelemetry::Context instance and checks if it is marked as an untraced context (see the "untraced_context" method above). If no context is provided, the current context will be used.

Returns true if this is an untraced context, or false otherwise.

SEE ALSO

OpenTelemetry::Trace::TracerProvider

OpenTelemetry::Trace::Tracer

OpenTelemetry::Trace::Span

COPYRIGHT AND LICENSE

This software is copyright (c) 2023 by José Joaquín Atria.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm OpenTelemetry

perl -MCPAN -e shell
install OpenTelemetry