---
name: "Log::ger"
section: "3pm"
platform: "linux"
package: "liblog-ger-perl"
version: "0.042-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Log::ger"
---

# Log::ger(3pm)

A lightweight, flexible logging framework

## NAME

Log::ger - A lightweight, flexible logging framework

## VERSION

version 0.042

## SYNOPSIS

### Producing logs

In your module (producer):

```
 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;
```

### Consuming logs

*Choosing an output*

In your application (consumer/listener):

```
 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 output to multiple outputs (including multiple files):

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

See Log::ger::Manual::Tutorial::481\_Output\_Composite for more examples.

There is also Log::ger::App that wraps this in a simple interface so you just need to do:

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

*Choosing level*

One way to set 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
```

There are better ways, e.g. letting users configure log level via configuration file or command-line option. See Log::ger::Manual::Tutorial::300\_Level for more details.

## DESCRIPTION

Log::ger is yet another logging framework with the following features:

- •

  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.