=encoding UTF-8

=head1 NAME

OpenTelemetry::Attributes - A common role for OpenTelemetry classes with attributes

=head1 SYNOPSIS

    class My::Class :does(OpenTelemetry::Attributes) { }

    my $class = My::Class->new(
        attributes => \%attributes,
    );

    my $read_only = $class->attributes;

    say $class->dropped_attributes;

=head1 DESCRIPTION

A number of OpenTelemetry classes allow for arbitrary attributes to be stored
on them. Since the rules for these attributes are shared by all of them, this
module provides a role that can be consumed by any class that should have
attributes, and makes it possible to have a consistent behaviour in all of
them.

See the
L<OpenTelemetry specification|https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/common/README.md#attribute>
for more details on these behaviours.

=head2 Allowed values

The values stored in an OpenTelemetry attribute hash can be any defined scalar
that is not a reference. The only exceptions to this rule are array references,
which are allowed as values as long as they do not contain any values that are
themselves undefined or references (of any kind).

=head2 Limits

This role can optionally be configured to limit the number of attributes
it will store, and the length of the stored values. If configured in this way,
information about how many attributes were dropped will be made available
via the L</dropped_attributes> method described below.

=head1 METHODS

=head2 new

    $instance = Class::Consuming::Role->new(
        attributes             => \%attributes // {},
        attribute_count_limit  => $count       // undef,
        attribute_length_limit => $length      // undef,
    );

Creates a new instance of the class that consumes this role. A hash reference
passed as the value for the C<attributes> parameter will be used as the
initial set of attributes.

The C<attribute_count_limit> and C<attribute_length_limit> parameters passed
to the constructor can optionally be used to limit the number of fields the
attribute store will hold, and the length of the stored values. If not set,
the store will have no limit.

If the length limit is set, fields set to plain scalar values will be
truncated at that limit when set. In the case of values that are array
references, the length limit will apply to each individual value.

=head2 attributes

    $hash = $class->attributes;

Returns a hash reference with a copy of the stored attributes. Because this
is a copy, the returned hash reference is read-only.

=head2 dropped_attributes

    $count = $class->dropped_attributes;

Return the number of attributes that were dropped if attribute count limits
have been configured (see L</new>, described above).

=head1 SEE ALSO

=over

=item L<OpenTelemetry specification|https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/common/README.md#attribute>

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