diff options
-rw-r--r-- | lib/Log.rakumod | 84 | ||||
-rw-r--r-- | lib/Log/Level.rakumod | 15 |
2 files changed, 99 insertions, 0 deletions
diff --git a/lib/Log.rakumod b/lib/Log.rakumod index e0ecb8d..d6e5b4d 100644 --- a/lib/Log.rakumod +++ b/lib/Log.rakumod @@ -35,6 +35,90 @@ multi method add-output (IO::Handle:D $, Int() $ where Log::Level::Emergency ≤ =VERSION 0.0.0 =AUTHOR Patrick Spek <p.spek@tyil.nl> +=head1 Description + +The C<Log> module provides a role which I<should> be implemented by a logging +system. It presents a standardized interface for use around the Raku ecosystem. +This would allow module developers to add logging statements throughout their +libraries, and these logs being in the same format as the application using the +libraries. + +=head1 Usage + +Usage of the C<Log> module goes through implementations of it, such as +C<Log::Simple>, C<Log::Colored>, or C<Log::JSON>. The C<Log> role itself only +helps in ensuring the interfaces are the same, allowing easy replacement of the +implementation if ever needed in the future. + +Whatever imlementation of C<Log> you use, it C<must> be set in the C<$*LOG> +dynamic variable. This makes it available to all the libraries that are used in +the program. You C<should> set it as early as possible. + +Because it must be using the C<$*LOG> variable, module developers around the +ecosystem can rely on it for their logging needs. However, not every +application will implement this, and that needs to be accounted for, too. For +this, make use of Raku's C<with> flow control statement. + +=begin code :lang<raku> +.notice('This is a log message') with $*LOG; +=end code + +This can be used freely and safely, throughout all modules. Any application +using that module and implementing C<Log> will immediately be able to reap the +benefits. + +=head2 Implementing a Log class + +=begin code :lang<raku> +use Log; + +unit class Log::Custom is Log; + +# Implement all required methods +=end code + +=head3 Methods + +There are 8 log levels, each with two method calls to invoke them. All of these +I<must> be implemented. + +=item C<multi method emergency (Str:D $) { * }> +=item C<multi method emergency (Str:D $, *@) { * }> +=item C<multi method alert (Str:D $) { * }> +=item C<multi method alert (Str:D $, *@) { * }> +=item C<multi method critical (Str:D $) { * }> +=item C<multi method critical (Str:D $, *@) { * }> +=item C<multi method error (Str:D $) { * }> +=item C<multi method error (Str:D $, *@) { * }> +=item C<multi method warning (Str:D $) { * }> +=item C<multi method warning (Str:D $, *@) { * }> +=item C<multi method notice (Str:D $) { * }> +=item C<multi method info (Str:D $) { * }> +=item C<multi method info (Str:D $, *@) { * }> +=item C<multi method notice (Str:D $, *@) { * }> +=item C<multi method debug (Str:D $0 { * }> +=item C<multi method debug (Str:D $, *@) { * }> + +Additionally, the following configuration method I<must> be implemented. + +=item C<multi method add-output (IO::Handle:D $, Int() $ where Log::Level::Emergency ≤ * ≤ Log::Level::Debug, Callable $?) { * }> + +=head2 Environment variables + +This logging standard defines two environment variables to respect. + +=defn RAKU_LOG_CLASS +The C<RAKU_LOG_CLASS> allows a user to override the logging class used by the +application. This allows programs ran interactively to show more human friendly +logs, and the same program ran in a cluster to provide formatted logs for +ingestion into a central logging system, without any code changes required. + +=defn RAKU_LOG_LEVEL +This allows a user to override the log level used by the application. This way, +by default, a program won't be too spammy with low-level details, but a user +I<can> enable it if they want to figure out why something isn't working the way +they expected. + =begin LICENSE Copyright © 2020 diff --git a/lib/Log/Level.rakumod b/lib/Log/Level.rakumod index 3c57adf..baeae10 100644 --- a/lib/Log/Level.rakumod +++ b/lib/Log/Level.rakumod @@ -19,6 +19,21 @@ enum Log::Level < =VERSION 0.0.0 =AUTHOR Patrick Spek <p.spek@tyil.nl> +=head1 Description + +C<Log::Level> is an C<Enum> to allow for human-readable log levels in your +code, as opposed to magic numbers that give little insight to people not +familiar with the levels. The allowed values are: + +=item C<Log::Level::Emergency> +=item C<Log::Level::Alert> +=item C<Log::Level::Critical> +=item C<Log::Level::Error> +=item C<Log::Level::Warning> +=item C<Log::Level::Notice> +=item C<Log::Level::Info> +=item C<Log::Level::Debug> + =begin LICENSE Copyright © 2020 |