NAME

OpenTelemetry::Logs::Logger - A log record factory for OpenTelemetry

SYNOPSIS

    use OpenTelemetry;
    my $provider = OpenTelemetry->logger_provider;
    my $logger   = $provider->logger;
    # Emit a log record
    $logger->emit_record(%args);

DESCRIPTION

A logger is responsible for emitting log records. The class provided by this module does nothing, but is suitable to be sub-classed to emit specific kinds of logs. See OpenTelemetry::SDK::Logs::Logger for one such example which emits OpenTelemetry::SDK::Logs::LogRecord objects.

METHODS

emit_record

    $logger->emit_record(
        attributes         => %attributes // {},
        body               => $body,
        context            => $context    // undef,
        observed_timestamp => $timestamp  // time,
        severity_number    => $number     // undef,
        severity_text      => $text       // undef,
        timestamp          => $timestamp  // undef,
    )

Emits a log record.

Takes a list of key / value pairs. Of these, the only one that callers are always expected to provide is the log record body: not doing so may result in a warning being logged. All other keys are optional and can be used to further specify the record. The value of the "body" parameter is not required to be a string, in order to support structured loggers.

If provided, the value of the "context" parameter should be an instance of OpenTelemetry::Context. Otherwise, the current context will be used. In either case, this will be used to access the span context this log record should be associated to, if any.

The value of the "timestamp" parameter represents the time at which the event the log record is associated with took place. This can be left unset if no such time is known. This is different from the "observed_timestamp", which is the time at which the record was seen by the collection platform. If this is not provided, it will be given a default value by the platform.

The value of the "severity_text" parameter should be set to the name of the level of the logged event (eg. "error", "warning", etc) as known at the source. The value of the "severity_number", on the other hand, should be a number between 1 and 24, with numbers mapping to the following levels:

TRACE: Levels 1-4. A fine-grained debugging event. Typically disabled in default configurations.
DEBUG: Levels 5-8. A debugging event.
INFO: Levels 9-12. An informational event. Indicates that an event happened.
WARN: Levels 13-16. A warning event. Not an error but is likely more important than an informational event.
ERROR: Levels 17-20. An error event. Something went wrong.
FATAL: Levels 21-24. A fatal error such as application or system crash.

Values in "Log Severity Values" in OpenTelemetry::Constants are suitable to be used as values for "severity_number". They will be evaluated in numeric context internally.

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.