NAME

OpenTelemetry::Context - A context class for OpenTelemetry

SYNOPSIS

    use OpenTelemetry::Context;
    my $key = OpenTelemetry::Context->key('something');
    my $ctx = OpenTelemetry::Context->current;
    # You can store and delete values in a context
    my $new = $ctx->set( $key => 'VALUE' );
    say $new->get($key); # Prints VALUE
    $new = $new->delete($key);
    say $new->get($key); # Warns because value is undefined
    # But the original context is immutable
    say defined $ctx->get($key) ? 1 : 0; # Prints 0

DESCRIPTION

This package provides an implementation of the OpenTelemetry Context <https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/README.md> class.

It contains methods to both construct new instances, and to store and retrieve instances in a global context stack.

OpenTelemetry uses the context class for propagation of values within a process across API boundaries. A key aspect of this context class is that it is immutable, such that write operations always result in a new context being created, which holds the values from the original context plus whatever new values have been provided.

For more details, please refer to the OpenTelemetry specification.

Key objects

Values in a context are stored using a key object rather than a plain string. See the "key" class method below for details on how to construct these objects.

METHODS

new

    $context = OpenTelemetry::Context->new

Create a new context object.

As of version 0.028 this method takes no arguments. To set values on the context, use the "set" method described below.

get

    $value = $context->get($key)

Retrieve a value from the context. Takes an object representing a context key (see the key class method below) and returns the value stored in the context object under that key. If no value is stored under that key, this method will return an undefined value.

set

    $new_context = $context->set( $key => $value )
    $new_context = $context->set( @pairs )

Takes one or more key / value pairs to set in the context. All keys must be key objects (see the "key" class method). The method returns a new context object with all the values of the calling context, as well as any provided values stored under the corresponding provided keys.

As is normal in Perl, when passing multiple pairs later ones will take precedence.

delete

    $new_context = $context->delete($key)
    $new_context = $context->delete(@keys)

Takes one or more key objects (see the "key" class method) and returns a new context object with all the values of the calling context, except those stored under the provided keys.

CLASS METHODS

key

    $key = OpenTelemetry::Context->key($string)
    $key = $context->key($string)

Takes a string and creates a key object with that string as its name. The key object can be used to store and retrieve values from a context object (see the "get" and "set" methods above).

Two key objects with the same name are not interchangeable. They are unique to ensure that multiple libraries that use the same context to store values under the same name. See more details in the OpenTelemetry specification <https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/README.md#create-a-key>.

current

    $context = OpenTelemetry::Context->current
    $new     = OpenTelemetry::Context->current = $new

Retrieve the context associated to the current execution unit.

This is an lvalue method, so it can also be used to set the current context. This is probably most useful when used together with a localisation method like the one provided by Syntax::Keyword::Dynamically, to ensure that once this execution unit is finished, the previous context is restored:

    use Syntax::Keyword::Dynamically;
    {
        my $context = ...;
        # This assignment will only be active in this scope
        dynamically OpenTelemetry::Context->current = $context;
        # ... do other things that rely on this context ...
    }

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.