NAME

OpenTelemetry::Baggage - Records and propagates baggage in a distributed trace

SYNOPSIS

    use OpenTelemetry::Baggage;

    # Set and get baggage in the context
    $context = OpenTelemetry::Baggage->set( $key => $value, $meta );
    $entry   = OpenTelemetry::Baggage->get( $key, $context );

    # Or if you are setting multiple entries
    my $builder = OpenTelemetry::Baggage->builder;
    $builder->set( $key => $value, $meta ); # As many times as you want
    $context = $builder->build;

DESCRIPTION

This package provides methods to read and store data using the W3C Baggage Specification, specifically for use in the context of OpenTelemetry data propagation.

Baggage Entries

Baggage values are stored (by "set") and returned (by "get") as instances of an internal entry object with the following two methods:

value

Returns the value of the entry

meta

Returns the metadata associated to the entry, if any. If no metadata was set, this method returns an undefined value

CLASS METHODS

get

    $entry = OpenTelemetry::Baggage->get(
        $key,
        $context // OpenTelemetry::Context->current,
    )

Retrieve a value from the context. Takes a string to be used as the key, and an optional OpenTelemetry::Context object whence the key will be fetched from. If no context is provided, the current context will be used.

If the key does not exist in the context, this method will return an undefined value.

set

    $new_context = OpenTelemetry::Baggage->set(
        $key => $value,
        $meta    // undef,
        $context // OpenTelemetry::Context->current,
    )

Takes a key / value pair and stores it in the context as baggage. An optional metadata string can be passed as a third parameter, in which case this will be stored together with the pair.

An optional OpenTelemetry::Context object can be passed as the fourth argument, in which case the value will be stored in that context. If none is provided, the current context will be used.

This method returns a new context object, which holds the new value.

delete

    $new_context = OpenTelemetry::Baggage->delete(
        $key,
        $context // OpenTelemetry::Context->current,
    )

Takes a string to be used as a key, and deletes the value stored under that key from the baggage stored in the context.

An optional OpenTelemetry::Context object can be passed as the second argument, in which case the value will be deleted from that context. If none is provided, the current context will be used.

This method returns a new context object, which will no longer have the deleted key.

all

    %baggage = OpenTelemetry::Baggage->all(
        $context // OpenTelemetry::Context->current,
    )

Reads the baggage stored in the context and returns it as a list of key / value pairs, where the values will be instances of the internal baggage entry object (see "Baggage Entries", above).

If an optional OpenTelemetry::Context object is provided, the baggage will be read from that context. Otherwise the current context will be used.

clear

    $new_context = OpenTelemetry::Baggage->clear(
        $context // OpenTelemetry::Context->current,
    )

Removes all baggage from the context and returns a new context with no baggage in it.

If an optional OpenTelemetry::Context object is provided, the baggage will be read from that context. Otherwise the current context will be used.

builder

    $builder = OpenTelemetry::Baggage->builder;
    $builder->set( ... )->set( ... );
    $context = $builder->build;

This method facilitates setting multiple entries in the baggage of a context. It returns an internal builder class that caches the entries internally and writes them to the desired context only once when needed.

The builder implements two methods:

set

    $builder = $builder->set( $key => $value, $meta );

Takes the same parameters as the "set" class method and returns the builder itself.

build

    $new_context = $builder->build($context);

Takes an optional OpenTelemetry::Context object and returns a new context with all the keys in the provided context, and the baggage that has been defined via calls to the builder's set method.

If no context is provided, the current context will be used.

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.

cpanm OpenTelemetry

perl -MCPAN -e shell
install OpenTelemetry