=encoding UTF-8

=head1 NAME

OpenTelemetry::Exporter - Abstract interface of an OpenTelemetry exporter

=head1 SYNOPSIS

    use Object::Pad;
    use OpenTelemetry::SDK::Trace::Span::Processor::Batch;
    use Future::AsyncAwait;

    class My::Exporter :does(OpenTelemetry::Exporter) {
        method export ( $spans, $timeout // undef ) { ... }

        async method shutdown    ( $timeout // undef ) { ... }
        async method force_flush ( $timeout // undef ) { ... }
    }

    # Use it with a span processor
    my $processor = OpenTelemetry::SDK::Trace::Span::Processor::Batch->new(
        exporter => My::Exporter->new,
    );

    # Register it with the OpenTelemetry tracer provider
    OpenTelemetry->tracer_provider->add_span_processor($processor);

=head1 DESCRIPTION

This module provides an abstract role that can be used by classes implementing
OpenTelemetry exporters. Exporters are objects that can take telemetry data
generated by traces, and send it to whoever needs to process that data.

Exporters receive the data they export from a span processor, which must
implement the interface defined in L<OpenTelemetry::Trace::Span::Processor>.

Although this cannot be enforced in the code, the methods described in this
role are all expected to return one of the values from
L<OpenTelemetry::Constants/Trace Export Results>.

=head1 METHODS

=head2 export

    $result = $exporter->export( \@spans, $timeout // undef );

Takes an array reference with readable spans (such as those provided by
L<OpenTelemetry::SDK::Trace::Span::Readable>) and an optional timeout value
and returns the outcome of exporting the span data.

The return value will be one of the
L<OpenTelemetry::Constants/Trace Export Results>.

=head2 shutdown

    $result = await $exporter->shutdown( $timeout // undef );

Takes an optional timeout value and returns a L<Future> that will be done
when this exporter has completed shutting down. The shutdown process must
include the effects of L<force_flush>, described below. After shutting down,
the exporter is not expected to do any further work, and should ignore any
subsequent calls.

The value of the future will be one of the
L<OpenTelemetry::Constants/Trace Export Results>.

=head2 force_flush

    $result = await $exporter->force_flush( $timeout // undef );

Takes an optional timeout value and returns a L<Future> that will be done
when this exporter has finished flushing. Flushing signals to the exporter
that it should export the data for any unprocessed spans as soon as possible.
This could be due to an imminent shutdown, but does not have to be.

The value of the future will be one of the
L<OpenTelemetry::Constants/Trace Export Results>.

=head1 SEE ALSO

=over

=item L<Future>

=item L<OpenTelemetry::Constants>

=item L<OpenTelemetry::Trace::Span::Processor>

=item L<OpenTelemetry::SDK>

=item L<OpenTelemetry::SDK::Trace::Span::Readable>

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