NAME

OpenTelemetry::Trace::Span - A single operation within a trace

SYNOPSIS

    use OpenTelemetry;
    use Syntax::Keyword::Dynamically;

    my $span = OpenTelemetry->tracer_provider->tracer->create_span(
        ...
    );

    # Attach this span to the current context
    # Doing this dynamically means this is only applied to this scope
    my $context = OpenTelemetry->context_with_span($span);
    dynamically OpenTelemetry->current_context = $context;

DESCRIPTION

An instance of this class represents a single operation within a trace.

Spans have a name that identifies them, and can store additional data related to the operation they represent, including start and end timestamps as well as other metadata (see the "add_event" and "set_attribute" methods below for some ways in which this can be achieved).

Spans can also link to a parent OpenTelemetry::Context, which allows them to form a tree structure within a trace.

The only supported way to create a span is through the "create_span" in OpenTelemetry::Trace::Tracer. Please refer to that documentation for details.

METHODS

add_event

    $span = $span->add_event(
        name       => $name       // 'undef',
        timestamp  => $timestamp  // time,
        attributes => $attributes // {},
    )

Add an event to this span. It accepts the following parameters:

attributes

A hash reference with the attributes of this event. If not set, no attributes will be set. Note that the OpenTelementry specification details standard event attribute names and values to be used with specific meanings. Please refer to the Semantic Conventions for Event Attributes specification for more details.

name

The name of this event. Note that the OpenTelementry specification details standard event names to be used with specific meanings. Please refer to the Semantic Conventions specification for more details.

If not set, the string undef will be used.

timestamp

A timestamp for this event in (possibly fractional) seconds. If not provided, the current time will be used.

This method returns the calling span, which means it can be chained.

context

    $span_context = $span->context

Returns the OpenTelemetry::Trace::SpanContext object associated with this span. This value can continue to be used even after the span is finished, and is guaranteed to be the same throughout the entire lifetime of the span.

end

    $span = $span->end( $timestamp // time )

Marks the span as ended. This will most commonly mean that the span is no longer recording (see "recording", above).

It takes an optional timestamp to use as the end timestamp of the span. If not provided, the current time will be used.

Note that ending a span does not, by itself, affect any of the span's child spans. It also does not render the span invalid or limit its capacity to be used to create new child spans.

This method returns the calling span, which means it can be chained.

recording

    $bool = $span->recording

Returns a true value if the span is recording information like events, attributes, status, etc. This might be the case if eg. the span has been ended.

Note that the recording state of a span does not extend to any of its children.

Note also that this method may return true even if the entire span has been sampled out.

record_exception

    $span = $span->record_exception(
        $exception,
        %attributes, # optional
    );

Calls "add_event" to add an "exception" event. This is a convenience method to make it easier to stick to existing event semantic conventions.

It takes a mandatory scalar to use as the exception, and list of key/value pairs that will be added as attributes to the event.

This method returns the calling span, which means it can be chained.

set_attribute

    $span = $span->set_attribute( $key => $value )
    $span = $span->set_attribute( %pairs )

Set one or more attributes in this span.

Setting an attribute will overwrite any attribute of the same name.

Refer to the OpenTelementry specification for details on some of the standard attribute names and their meanings.

This method returns the calling span, which means it can be chained.

set_name

    $span = $span->set_name( $name )

Sets the name a span. This name will override whatever name was used during creation.

This method returns the calling span, which means it can be chained.

set_status

    $span = $span->set_status( $status, $description // '' )

Sets the status of a span.

Every span starts with an "unset" status. This can be changed to either an "Ok" status, which indicates the operation represented by this span is deemed to have completed successfully; or "Error", in which case the operation did not.

A span's status can only be set: any attempt to unset it will be ignored. Likewise, an "Ok" status is final, and any attempts to alter it will also be ignored.

This method returns the calling span, which means it can be chained.

CONSTANTS

INVALID

Stores a span with an invalid OpenTelemetry::Trace::SpanContext. This will be sometimes returned to mark the lack of a valid span, while still providing an instance on which methods can be called.

SEE ALSO

OpenTelemetry::Context

OpenTelemetry::Trace::SpanContext

OpenTelemetry::Trace::Tracer

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