=encoding UTF-8

=head1 NAME

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

=head1 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;

=head1 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 L</add_event> and L</set_attribute> methods
below for some ways in which this can be achieved).

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

The only supported way to create a span is through the
L<OpenTelemetry::Trace::Tracer/create_span>. Please refer to that
documentation for details.

=head1 METHODS

=head2 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:

=over

=item 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
L<Semantic Conventions for Event Attributes|https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md>
specification for more details.

=item 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
L<Semantic Conventions|https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md>
specification for more details.

If not set, the string C<undef> will be used.

=item timestamp

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

=back

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

=head2 context

    $span_context = $span->context

Returns the L<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.

=head2 end

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

Marks the span as ended. This will most commonly mean that the span is no
longer recording (see L</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.

=head2 recording

    $bool = $span->recording

Returns a true value if the span is recording information like
L<events|/add_event>, L<attributes|/set_attribute>, L<status|/set_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.

=head2 record_exception

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

Calls L</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.

=head2 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
L<the OpenTelementry specification|https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md>
for details on some of the standard attribute names and their meanings.

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

=head2 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.

=head2 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.

=head1 CONSTANTS

=head2 INVALID

Stores a span with an invalid L<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.

=head1 SEE ALSO

=over

=item L<OpenTelemetry::Context>

=item L<OpenTelemetry::Trace::SpanContext>

=item L<OpenTelemetry::Trace::Tracer>

=back

=head1 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.
