OpenTelemetry::SDK - An implementation of the OpenTelemetry SDK for Perl
# Read configuration from the environment at compile time use OpenTelemetry::SDK; # Or do that at runtime require OpenTelemetry::SDK; OpenTelemetry::SDK->import; # Load any integrations you may want use OpenTelemetry::Integration qw( HTTP::Tiny ); # You can also configure some parts of the SDK manually OpenTelemetry->tracer_provider->add_span_processor( OpenTelemetry::SDK::Trace::Span::Processor::Simple->new( exporter => OpenTelemetry::SDK::Exporter::Console->new, ), );
The OpenTelemetry standard keeps a strict separation between an API layer that implements an interface that is backend-agnostic, and an SDK layer that can be connected to the API to do the actual work.
For a Perl implementation of the API layer, please refer to the OpenTelemetry distribution.
The OpenTelemetry::SDK distribution provides the other half of that picture: it implements the OpenTelemetry SDK. While the API allows library authors to instrument their code so it produces telemetry data, the SDK allows application authors who use those libraries to process that data and make use of it how they see fit.
In most cases, simply importing this module will be enough. This can happen at compile time if the module is loaded via "use", or at runtime if the module is loaded with "require" and "import" is manually called.
When the SDK is loaded, it will install an instance of OpenTelemetry::SDK::Trace::TracerProvider as the global tracer provider, and configure the span exporters and processors that have been configured in the environment.
When loaded, the SDK will read its configuration from the environment and automatically apply those settings. This section lists the environment variables that are supported by the SDK and the way they are interpreted.
The OpenTelemetry specification has a full list of variables, and this SDK aims to support all the required ones.
When the variable controls aspects of the SDK that have not been fully implemented, those parts will be marked with the "(NYI)" label. When the variables are not defined by the official specification, this will be stated in their description.
All of the variables below are listed using their standard names. As they are read using "config" in OpenTelemetry::Common, Perl-specific versions of all of these can also be used by replacing the OTEL prefix with the OTEL_PERL string: eg. OTEL_PERL_SDK_DISABLED can be set instead of OTEL_SDK_DISABLED to disable the Perl SDK specifically. In all cases, the Perl-specific versions are preferred over the standard ones if both are set.
OTEL
OTEL_PERL
OTEL_PERL_SDK_DISABLED
OTEL_SDK_DISABLED
Maximum allowed attribute count. Default: 128.
This is used as the default value for "OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT", "OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT", and "OTEL_LINK_ATTRIBUTE_COUNT_LIMIT".
See OpenTelemetry::SDK::Trace::SpanLimits for more details.
Maximum allowed attribute value size. Default is to have no limit. If set, this will apply to span, event, and link attributes, unless a more specific limit is set for these with the "OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT", "OTEL_EVENT_ATTRIBUTE_VALUE_LENGTH_LIMIT", or "OTEL_LINK_ATTRIBUTE_VALUE_LENGTH_LIMIT" variables described below. Note that, of these, only the one for spans is defined by the OpenTelemetry standard specification.
Maximum allowed time (in milliseconds) for the batch span processor to wait before aborting the export process. Default: 30000.
See OpenTelemetry::SDK::Trace::Span::Processor::Batch for more details.
Maximum batch size for the batch exporter. Default: 512. Must be less than or equal to "OTEL_BSP_MAX_QUEUE_SIZE".
Maximum queue size for the batch exporter. Default: 2048.
Delay interval (in milliseconds) between two consecutive exports of the batch exporter. Default: 5000.
Maximum allowed attribute per span event count. Default: the value of "OTEL_ATTRIBUTE_COUNT_LIMIT".
Maximum allowed size for event attribute values. Default is to have no limit. If not set, but "OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT" is, the latter will apply to event attributes as well.
This variable is non-standard.
Set to the path to a PEM file with the certificate used to verify a server's TLS credentials. Default: empty.
See OpenTelemetry::Exporter::OTLP for more details.
Set to the path to a PEM file with the client certificate/chain trust for the client's private key to use in mTLS communication. Default: empty.
Set to the path to a PEM file with the client's private key to use in mTLS communication. Default: empty.
Controls the compression used by the OTLP exporter. Default: depends on availability.
Possible values are:
none
No compression will be used.
gzip
Compressed using zlib.
The base URL to be used when sending exported data. Default: http://localhost with port 4318 for HTTP traffic, and port 4317 for gRPC traffic.
http://localhost
Set to a string with key/value pairs to be sent along with requests exporting trace data. Default: empty.
Controls the protocol used by the OTLP exporter. Default: depends on availability.
http/json
Sends data as JSON over HTTP.
http/protobuf
Sends data as a Protobuf-encoded blob over HTTP.
grpc
Sends data using gRPC.
The maximum amount of time the OTLP exporter will wait for a response when exporting data. Default: 10.
Set to the path to a PEM file with the certificate used to verify a server's TLS credentials when exporting trace data. Default: the value of "OTEL_EXPORTER_OTLP_CERTIFICATE".
Set to the path to a PEM file with the client certificate/chain trust for the client's private key to use in mTLS communication when exporting trace data. Default: the value of "OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE".
Set to the path to a PEM file with the client's private key to use in mTLS communication when exporting trace data. Default: the value of "OTEL_EXPORTER_OTLP_CLIENT_KEY".
Controls the compression used by the OTLP exporter for trace data. Default: the value of "OTEL_EXPORTER_OTLP_COMPRESSION",
The URL to send exported trace data. Default: the value of "OTEL_EXPORTER_OTLP_ENDPOINT" with /v1/traces appended to it.
/v1/traces
Set to a string with key/value pairs to be sent along with requests exporting trace data. Default: the value of "OTEL_EXPORTER_OTLP_HEADERS".
The maximum amount of time the OTLP exporter will wait for a response when exporting trace data. Default: the value of "OTEL_EXPORTER_OTLP_TIMEOUT".
Maximum allowed attribute per span link count. Default: the value of "OTEL_ATTRIBUTE_COUNT_LIMIT".
Maximum allowed size for link attribute values. Default is to have no limit. If not set, but "OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT" is, the latter will apply to link attributes as well.
Key-value pairs to be used as resource attributes. Default: empty, for no attributes.
See OpenTelemetry::SDK::Resource for more details.
Propagators to be used as a comma-separated list. Values are deduplicated before use. Default: tracecontext,baggage.
tracecontext,baggage
Possible values, and the propagators that they refer to, are listed below:
b3
OpenTelemetry::Propagator::B3 (NYI)
b3multi
OpenTelemetry::Propagator::B3::Multi (NYI)
baggage
OpenTelemetry::Propagator::Baggage
jaeger
OpenTelemetry::Propagator::Jaeger (NYI)
OpenTelemetry::Propagator::None
ottrace
OpenTelemetry::Propagator::OTTrace (NYI)
tracecontext
OpenTelemetry::Propagator::TraceContext
xray
OpenTelemetry::Propagator::XRay (NYI)
Disable the SDK for all signals. Default: false
false
Sets the value of the service.name resource attribute. If service.name is also provided in "OTEL_RESOURCE_ATTRIBUTES", that value will be overridden by the one provided in this variable. Default: empty.
service.name
Maximum allowed span attribute count. Default: the value of "OTEL_ATTRIBUTE_COUNT_LIMIT".
Maximum allowed size for span attribute values. Default is to have no limit. If not set, but "OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT" is, the latter will apply to span attributes as well.
Maximum allowed span event count. Default: 128.
Maximum allowed span link count. Default: 128.
Trace exporter to be used. Default: otlp.
otlp
This can be set to a comma-separated list of values, to set multiple exporters. They will be deduplicated before configuration takes place.
Possible values (and the classes that represent them) are listed below:
OpenTelemetry::Exporter::OTLP
zipkin
OpenTelemetry::Exporter::Zipkin (NYI)
console
OpenTelemetry::SDK::Exporter::Console
This value is non-standard.
Sampler to be used for traces. Default: parentbased_always_on. See "Sampling" for more details.
parentbased_always_on
Possible values, and the classes that represent them, are listed below:
always_on
OpenTelemetry::SDK::Trace::Sampler::AlwaysOn
always_off
OpenTelemetry::SDK::Trace::Sampler::AlwaysOff
jaeger_remote
OpenTelemetry::SDK::Trace::Sampler::Jaeger::Remote (NYI)
traceidratio
OpenTelemetry::SDK::Trace::Sampler::TraceIDRatioBased
OpenTelemetry::SDK::Trace::Sampler::ParentBased with an always_on parent
parentbased_always_off
OpenTelemetry::SDK::Trace::Sampler::ParentBased with an always_off parent
parentbased_traceidratio
OpenTelemetry::SDK::Trace::Sampler::ParentBased with a traceidratio parent
parentbased_jaeger_remote
OpenTelemetry::SDK::Trace::Sampler::ParentBased with a jaeger_remote parent (NYI)
String value to be used as the sampler argument. Each sampler can decide whether to use this or not, and they get to define what the meaning of the argument is. Defaults to empty.
This will only be used if "OTEL_TRACES_SAMPLER" is set, and if the sampler requires it. Invalid or unrecognised input will be logged and will be ignored.
Special thanks to CV-Library Ltd. for their support in the development of this library.
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.
To install OpenTelemetry::SDK, copy and paste the appropriate command in to your terminal.
cpanm
cpanm OpenTelemetry::SDK
CPAN shell
perl -MCPAN -e shell install OpenTelemetry::SDK
For more information on module installation, please visit the detailed CPAN module installation guide.