NAME

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

SYNOPSIS

    class My::Class :does(OpenTelemetry::Attributes) { }
    my $class = My::Class->new(
        attributes => \%attributes,
    );
    my $read_only = $class->attributes;
    say $class->dropped_attributes;

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

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

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 "dropped_attributes" method described below.

METHODS

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 "attributes" parameter will be used as the initial set of attributes.

The "attribute_count_limit" and "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.

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.

dropped_attributes

    $count = $class->dropped_attributes;

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

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.