NAME

OpenTelemetry::TraceContext::W3C - W3C Trace Context implementation

VERSION

version 0.02

SYNOPSIS

    # traceparent
    $traceparent = parse_traceparent($header_in_string);
    $traceparent->{parent_id} = <generate new id>;
    $header_out_string = format_traceparent($traceparent);

    # tracestate
    $tracestate = parse_tracestate($header_in_string);
    update_tracestate($tracestate, $key, $value);
    $header_out_string = format_tracestate($tracestate);

DESCRIPTION

This module provides a set of low-level functions to parse and format traceparent and tracestate headers as specified by Trace Context W3C recommendation.

It supports parsing/formatting of headers with version 00 format.

FUNCTIONS

parse_traceparent

    $parsed = parse_traceparent($header_string);

Takes a traceparent header value as input. Returns undef on failure. On success it returns a hash with the following keys:

version

numeric version (e.g. version f0 would be returned as the number 240)

trace_id

hexadecimal trace id (a 32 character string)

parent_id

hexadecimal parent id (a 16 character string)

trace_flags

numeric trace flags (e.g. flags 11 would be returned as the number 17)

format_traceparent

    $header_string = format_traceparent($parsed);

Takes a value with the same structure as returned by parse_traceparent. Returns a formatted traceparent value on success, undef on failure.

parse_tracestate

    $parsed = parse_tracestate($header_string);

Takes a traceparent header value as input. Returns undef on failure. On success it returns a hash with the following key:

list_members

An array with one item for each valid key/value pair found in the header.

Each item is an hash with the following keys:

key, value

the key/value pair. For multi-tenant systems, key has the form <tenant-id>@<system-id>.

system_id

Only present for multi-tenant systems.

tenant_id

Only present for multi-tenant systems.

update_tracestate

    $ok = update_tracestate($parsed, $key, $value);

Takes a value with the same structure as returned by parse_tracestate. On success, it adds/updates the given key/value pair and returns a true value, returns a false value on failure.

format_tracestate

    $header_string = format_tracestate($parsed);
    $header_string = format_tracestate($parsed, $options);

Takes a value with the same structure as returned by parse_tracestate. Returns a formatted tracestate value on success, undef on failure.

$options is an hash. The only supported option is

max_length

Maximum permitted lenght for the formatted header (defaults to 512). If the formatted value is longer, entries are pruned as per the Trace Context specification.

AUTHOR

Mattia Barbon <mattia@barbon.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2022 by Mattia Barbon.

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::TraceContext::W3C

perl -MCPAN -e shell
install OpenTelemetry::TraceContext::W3C