Log::ger(3pm)

🌸 NAME 🌸

okay so bestie, welcome to the manual page for Log::ger(3pm) — straight out of the User Contributed Perl Documentation collection, no cap 💅. And what is it? It's Log::ger — a lightweight, flexible logging framework. that's the whole vibe. iconic, honestly.

---

✨ VERSION ✨

version 0.042 🎀

---

🦋 SYNOPSIS 🦋

💖 Producing logs

so like, in your module (you're the producer here, main character energy):

package MyModule;

# this will install some logger routines. by default: log_trace, log_debug,
# log_info, log_warn, log_error, and log_fatal. level checker routines are also
# installed: log_is_trace, log_is_debug, and so on.
use Log::ger;

sub foo {
    ...
    # produce some logs. no need to configure output or level. by default
    # output goes nowhere.
    log_error "an error occured: %03d - %s", $errcode, $errmsg;
    ...

    # the logging routines (log_*) can automatically dump data structures
    log_debug "http response: %s", $http;

    # log_fatal does not die by default, if you want to then die() explicitly.
    # but there are plugins that let you do this or provide log_die etc.
    if (blah) { log_fatal "..."; die }

    # use the level checker routines (log_is_*) to avoid doing unnecessary
    # heavy calculation
    if (log_is_trace) {
        my $res = some_heavy_calculation();
        log_trace "The result is %s", $res;
    }

}
1;

literally just drop use Log::ger; in there and you're logging. no config, no drama.

🌈 Consuming logs

🎀 Choosing an output

and now, in your application — you're the consumer/listener bestie:

use MyModule;
use Log::ger::Output 'Screen'; # configure output
# level is by default 'warn'
foo(); # the error message is shown, but debug/trace messages are not.

🫶 Choosing multiple outputs

instead of Screen you can go multiple outputs, including multiple files, because why choose:

use Log::ger::Output 'Composite' => (
    outputs => {
        Screen => {},
        File   => [
            {conf=>{path=>'/path/to/app.log'}},
            ...
        ],
        ...
    },
);

peep Log::ger::Manual::Tutorial::481_Output_Composite for more examples, bestie.

there's also Log::ger::App which wraps all this in a super simple interface so literally all you gotta do is:

# In your application or script:
use Log::ger::App;
use MyModule;

💅 Choosing level

one way to set the level:

use Log::ger::Util;
Log::ger::Util::set_level('debug'); # be more verbose
foo(); # the error message as well as debug message are now shown, but the trace is not

but ngl there are better ways — like letting your users configure the log level via a configuration file or a command-line option. go read Log::ger::Manual::Tutorial::300_Level for the whole tea ☕.

---

👑 DESCRIPTION 👑

Log::ger is yet another logging framework — and here's the feature list, because she's got range:

• Separation of producers and consumers/listeners

Like Log::Any, this offers a very easy way for modules to produce some logs without having to configure anything. Configuring output, level, etc can be done in the application as log consumers/listeners. To read more about this, see the documentation of Log::Any or Log::ger::Manual (but nevertheless see Log::ger::Manual on why you might prefer Log::ger to Log::Any).

• Lightweight and fast

Slim distribution. No non-core dependencies, extra functionalities are provided in separate distributions to be pulled as needed.

Low startup overhead. Only ~0.5-1ms. For comparison, strict ~0.2-0.5ms, warnings ~2ms, Log::Any (v0.15) ~2-3ms, Log::Any (v1.049) ~8-10ms, Log::Log4perl ~35ms. This is measured on a 2014-2015 PC and before doing any output configuration. I strive to make use Log::ger; statement to be roughly as light as use strict; or use warnings; so the impact of adding the statement is really minimal and you can just add logging without much thought to most of your modules. This is important to me because I want logging to be pervasive.

To test for yourself, try e.g. with bencher-code:

% bencher-code 'use Log::ger' 'use Log::Any' --startup

Fast. Low null-/stealth-logging overhead, about 1.5x faster than Log::Any, 3x faster than Log4perl, 5x faster than Log::Fast, ~40x faster than Log::Contextual, and ~100x faster than Log::Dispatch.

For more benchmarks, see Bencher::Scenarios::Log::ger.

Conditional compilation. There is a plugin to optimize away unneeded logging statements, like assertion/conditional compilation, so they have zero runtime performance cost. See Log::ger::Plugin::OptAway.

Being lightweight means the module can be used more universally, from CLI to long-running daemons to inside routines with tight loops.

• Flexible

Customizable levels and routine/method names. Can be used in a procedural or OO style. Log::ger can mimic the interface of Log::Any, Log::Contextual, Log::Log4perl, or some other popular logging frameworks, to ease migration or adjust with your personal style.

Per-package settings. Each importer package can use its own format/layout, output. For example, a module that is migrated from Log::Any uses Log::Any-style logging, while another uses native Log::ger style, and yet some other uses block formatting like Log::Contextual. This eases code migration and teamwork. Each module author can preserve her own logging style, if wanted, and all the modules still use the same framework.

Dynamic. Outputs and levels can be changed anytime during run-time and logger routines will be updated automatically. This is useful in situation like a long-running server application: you can turn on tracing logs temporarily to debug problems, then turn them off again, without restarting your server.

Interoperability. There are modules to interop with Log::Any, either consume Log::Any logs (see Log::Any::Adapter::LogGer) or produce logs to be consumed by Log::Any (see Log::ger::Output::LogAny).

Many output modules and plugins. See Log::ger::Output::*, Log::ger::Format::*, Log::ger::Layout::*, Log::ger::Plugin::*. Writing an output module in Log::ger is easier than writing a Log::Any::Adapter::*.

For more documentation, start with Log::ger::Manual. 🫶

---

🌟 SEE ALSO 🌟

Some other popular logging frameworks: Log::Any, Log::Contextual, Log::Log4perl, Log::Dispatch, Log::Dispatchouli.

If you still prefer debugging using the good old print(), there's Debug::Print.

---

💜 AUTHOR 💜

perlancar <perlancar@cpan.org>

---

🎀 COPYRIGHT AND LICENSE 🎀

This software is copyright (c) 2023, 2022, 2020, 2019, 2018, 2017 by perlancar <perlancar@cpan.org>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

okay that's the whole page bestie, go forth and log ✨

this lil page came to you via perl v5.38.2, dated 2024-05-25, and it's the Log::ger(3pm) manual — slay, periodt 💅💖