NAME

OpenTelemetry::Common - Utility package with shared functions for OpenTelemetry

SYNOPSIS

    use OpenTelemetry::Common;

    # Read a config value from the environment for the FOO and BAR keys
    # or undefined if they are not set
    my $value = config(qw( FOO BAR )) // $default;

    my $timeout = 10; # seconds
    my $start   = timeout_timestamp;

    for (@tasks) {
        last unless maybe_timeout $timeout, $start;

        ...
    }

DESCRIPTION

This module contains functions that are useful throughout the OpenTelemetry codebase, and help provide a consistent way to handle certain processes.

They will most likely only be of interest to authors of OpenTelemetry libraries and integrations.

FUNCTIONS

config

    $value = config(@keys);

This function takes a list of keys and tries to read values from those keys in the environment, and return the first value it finds, or undefined if no value is found.

Keys will be read from the environment in order, after prepending first the OTEL_PERL_ prefix (which should be specific to this Perl implementation), and then the OTEL_ prefix (which are the ones defined by the standard) if no value has been found.

Values will be parsed as described in the OpenTelemetry specification, which in the context of Perl means the following:

• Empty values are the same as undefined

• If the variable is set to the string "true" or "false" (case-insensitively), it will be returned as a true or false value respectively

• Any other value will be returned as is

maybe_timeout

    $time_remaining = maybe_timeout(
        $timeout // undef,
        $start   // 0,
    );

Takes a timeout value and an optional starting timestamp, and returns how much of the provided timeout is still available. This is useful for timed operations that span over several steps, and need to propagate this timeout to additional calls.

If the timeout argument was undefined, this function returns undefined, to indicate the absence of a timeout (rather than the fact that time has run out).

timeout_timestamp

    $timestamp = timeout_timestamp;

Returns a monotonic timestamp value. This is used internally in "maybe_timeout", described above.

generate_span_id

    $id = generate_span_id;

Generates a new random span ID. Do not use this function directly. Use it instead through the interface provided in OpenTelemetry::Trace.

generate_trace_id

    $id = generate_trace_id;

Generates a new random trace ID. Do not use this function directly. Use it instead through the interface provided in OpenTelemetry::Trace.

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.