NAME

OpenTelemetry::SDK::Resource - Represents the entity producing OpenTelemetry data

SYNOPSIS

    use OpenTelemetry::SDK::Resource;

    # Read default attributes, or pass them to the constructor
    my $resource = OpenTelemetry::SDK::Resource->new(
        attributes => \%attributes,
    );

    # Merge resources into new ones
    my $new = $resource->merge($other);

DESCRIPTION

This module provides an immutable resource class that represents the entity that produces the telemetry data. The entity is represented as a set of attributes with specific meanings as described in the "Semantic Conventions" OpenTelemetry section of the OpenTelemetry specification.

When loading the OpenTelemetry::SDK, it will install a global OpenTelemetry::SDK::Trace::TracerProvider that will be linked to an instance of this resource class. This link cannot be modified after the tracer provider has been created, and it will be propagated to any OpenTelemetry::SDK::Trace::Tracer it provides, and any OpenTelemetry::SDK::Trace::Span objects created by those tracers.

CONFIGURATION

As with the OpenTelemetry::SDK more generally, the resource will capture data about the environment it is running in. This will include aspects like the version of Perl it is running under, as well as the version of the SDK that is in use.

Apart from this automatic detection, resource attributes will be read from those provided to the constructor (see below) and from the "OTEL_RESOURCE_ATTRIBUTES" environment variable. Attributes provided via this variable take precedence over those automatically detected, and those provided to the constructor take precedence over any other.

The value of this environment variable will consist of a list of key/value pairs which are expected to be represented in a format matching that of the W3C Baggage, but without the semicolon-delimited metadata: key1=value1,key2=value2.

Values outside the "baggage-octet" range (ASCII except control characters, whitespace, double-quote, comma, semicolon and backslash) must be percent-encoded. Any that are not will be ignored, and a warning will be logged.

METHODS

This class implements the OpenTelemetry::Attributes role. Please consult that module's documentation for details on the behaviours it provides.

new

    $resource = OpenTelemetry::SDK::Resource->new(
        attributes => \%attributes, # optional
        schema_url => $schema_url,  # optional
    );

Construct a new resource instance. Takes a schema URL and a list of user-provided attributes. If no schema URL is provided, the resource's schema URL will be left empty.

In addition to the attributes provided by the user, and those read from the OTEL_RESOURCE_ATTRIBUTES environment variable, the constructed resource will automatically detect the following standard attributes, and set them to the values described:

telemetry.sdk.name

Hard-coded to opentelemetry.

telemetry.sdk.language

Hard-coded to perl.

telemetry.sdk.version

The $VERSION string for OpenTelemetry::SDK.

process.pid

The value of $$.

process.command

The value of $0.

process.executable.path

The value of $^X.

process.command_args

An array reference with a copy of @ARGV.

process.executable.name

The basename of $^X.

process.runtime.name

Hard-coded to perl.

process.runtime.version

The stringified value of $^V.

As explained in the "CONFIGURATION" section above, user-provided attributes will take precedence over those that are automatically detected, and those that are read from the environment.

empty

    $resource = OpenTelemetry::SDK::Resource->empty(
        attributes => \%attributes, # optional
        schema_url => $schema_url,  # optional
    );

Accepts the same parameters as "new", but returns a resource with no additional automatic attribute detection.

merge

    $new = $resource->merge($another_resource);

Create a new resource that is the result of merging the original one with the attributes in the one provided. This is useful when merging resources that come from different sources.

The newly created merged resource will have all the attributes that exist on any of the two resources. If an attribute exists on both, then the values in the updating resource will take precedence, even if that value is empty.

The schema URL will be determined following the rules below:

• If it was originally empty, the new one will be used

• If it was empty on the new one, the original will be kept

• If both have the same URL, that one will be used

• If they are both set but differ, the original will be kept

SEE ALSO

OpenTelemetry::Attributes

OpenTelemetry::SDK

OpenTelemetry::SDK::Trace::Span

OpenTelemetry::SDK::Trace::TracerProvider

OpenTelemetry::SDK::Trace::Tracer

W3C Baggage

OpenTelemetry Resource Semantic Conventions

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::SDK

perl -MCPAN -e shell
install OpenTelemetry::SDK