=encoding UTF-8

=head1 NAME

OpenTelemetry::X - An exception factory for OpenTelemetry

=head1 SYNOPSIS

    use OpenTelemetry::X;

    die OpenTelemetry::X->create( $type => $message );

=head1 DESCRIPTION

Because of the nature of OpenTelemetry, the vast majority of its operations
will attempt to recover from unexpected circumstances that might otherwise
be considered errors: one would not want an application crashing because of
the monitoring framework it uses. In these cases, OpenTelemetry prefers to
log that these events took place, and carry on.

Some errors, however, are the result of incorrectly using the framework's
API, or are otherwise unrecoverable. This package is there to make it easier
to handle and identify these cases.

The created exceptions overload stringification, so they should be usable
in most contexts where regular errors are used elsewhere in Perl.

=head1 CLASS METHODS

=head2 create

    $exception = OpenTelemetry::X->create( $type => $message )

Takes a string identifying an exception class and a message, and returns an
instance of an exception object of that type, with that message. The type will
be used as a sub-namespace under 'OpenTelemetry::X' to generate the class of
the exception to be constructed.

Constructed exceptions will be subclasses of OpenTelemetry::X, but this method
should only be called from this package.

=head1 SEE ALSO

=over

=item L<OpenTelemetry::X::Invalid>

=item L<OpenTelemetry::X::Parsing>

=item L<OpenTelemetry::X::Unsupported>

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