NAME

C<Log::Dispatch::Destination> - role implementing destination end-point interface


DESCRIPTION

This role must be consumed by any class, implementing log destination.


ATTRIBUTES

head

Defines the maximum log level this destination would record. Any message with a level higher than this gets dropped.


METHODS

C<method report(>L<C<Log::Dispatch::Msg>|Msg.md>C<:D $msg)>


The only method to be implemented by a destination end-point class. Must take the C<$msg> object and translate it into
a format, acceptable by the destination. Normally it would be as simple, as producing one or few lines using the helper
method C<fmt-lines>, provided by L<C<Log::Dispatch::Msg>|Msg.md> class. But a destination more complicated may require more
complicated data structure to be submitted.


Don't override unless there is a B<really> good reason.


L<C<Log::Dispatch>|../Dispatch.md>, L<C<Log::Dispatch::Source>|Source.md>, L<C<Log::Dispatch::Msg>|Msg.md>


AUTHOR

root

para

L<Examples| file:../examples/index.podlite>


L<Download |file:../download/index.podlite>


React

=begin React :component<HeaderCol> :id<menu> 
=para L<Documentation|/doc/introduction>
=para L<Modules| /mods>
=para L<Examples| file:../examples/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


HEADER

FOOTER

Destination

C<Log::Dispatch::File> - destination end point for logging into a text file


This log destination sends lines of log into a text file. The lines are formatted using standard means of
L<C<Log::Dispatch::Msg>|Msg.md>.


If the destination file doesn't exists it will be created.


This destination can operate in two modes: streaming or discrete. In the streaming mode the log file is opened on start
and closed when the dispatcher shuts down. In the discrete mode the log file is opened and closed on per-message basis.
The latter is recommended for daemons for which it is undesirable to stop them to perform log rotation as moving away
the old log file before archiving is all the rotator tool has to do.


A flag requesting the destination to operate in safe mode, i.e. with no write buffers. Defaults to I<False>.


The flag which turns on the discrete mode of operation. Defaults to I<False>.


L<C<Log::Dispatch>|../Dispatch.md>,
L<C<Log::Dispatch::Source>|Source.md>,
L<C<Log::Dispatch::Destination>|Destination.md>,
L<C<Log::Dispatch::Msg>|Msg.md>


File

C<Log::Dispatch> - Dispatching multi-source, multi-destination logging


SYNOPSIS

code

=begin code :lang<raku>
use Log::Dispatch;
use Log::Dispatch::Destination;
use Log::Dispatch::Source;

class DBDestination does Log::Ddispatch::Destination {
    method report(Log::Dispatch::Msg:D $message) {
        ... # Implement writing log messages to a database table
    }
}

class MyApp does Log::Dispatch::Source {
    has Log::Dispatch:D $!logger .= new;
    has Str:D $.log-file is required;
    submethod TWEAK {
        $!logger.add: Log::Dispatch::TTY, :max-level(LOG-LEVEL::DEBUG);
        $!logger.add: 'File', file => $!log-file;
        $!logger.add: DBDestination;
    }
    method do-an-action {
        my Bool $success;
        my $diagnostics;

        self.log: :debug, "Trying an action...";

        ... # Do something

        if $success {
            self.log: "All done";
        }
        else {
            self.log: :critical, "Something is wrong! Cause: ", $diagnostics;
        }
    }
}
=end code


This module provide a means to have multiple log destinations withing single application with extra hassle
but with easy support for concurrency.


The model this module is based upon is built around a single dispatcher, which can be considered as a minimalistic
wrapper around a L<C<Supplier>|https://docs.raku.org/type/Supplier>. The dispatcher accepts message objects from sources and dispatches them into
destinations.


A source here is any instance of a class consuming L<C<Log::Dispatch::Source>|Dispatch/Source.md> role.


A destination is an instance of a class consuming L<C<Log::Dispatch::Destination>|Dispatch/Destination.md> role. It represented an endpoint
where messages are to be submitted to.


For example, one may have an application and wants to log its messages into a file and on the console. This is as simple
as adding C<does Log::Dispatch::Source> to the declaration of our application class. And by having something like the
following example anywhere in application code:


=begin code :lang<raku>
my $logger = Log::Dispatch.new;
$logger.add: 'File', :max-level(LOG-LEVEL::DEBUG), $log-file-name;
$logger.add: Log::Dispatch::TTY;
=end code


Note that the application would then log all messages into a log file, but only the essential ones to the console.


It worth to mention that each destination code is by default gets its own thread. For a source it is normally sufficient
just to use `log` method provided by L<C<Log::Dispatch::Source>|Dispatch/Source.md> role.


A I<processor> is an end-point attached to the dispatcher. The module provides two kinds of processors: source and
destination implemented, correspondingly, by L<C<Log::Dispatch::Source>|Dispatch/Source.md> and L<C<Log::Dispatch::Destination>|Dispatch/Destination.md> roles.


C<Log::Dispatch::Processor> role is just an interface requiring C<attach> method to be implemented.


Currently the module only provides two destination end-points: L<C<Log::Dispatch::TTY>|Dispatch/TTY.md> and
L<C<Log::Dispatch::File>|Dispatch/File.md>. Syslog support may be added later.


The multi-destination concept with per-destination maximum log-level support implies that there is no way to optimize
away some possibly unused calls to the method C<log> because any message, no matter what log-level it is assigned with,
must be accepted and emitted into dispatcher's L<C<Supply>|https://docs.raku.org/type/Supply>.


The number and names of log levels are taken from I<syslog> standard exactly for the reason it is the most common
logging standard existing around.


Levels are provided as C<LOG-LEVEL> enum values declared by L<C<Log::Dispatch::Types>|Dispatch/Types.md> module. Here is the list in the
ascending order:


item

This module tries to reduce namespace pollution to the absolute minimum. The only symbol exported is C<LOG-LEVEL>
enumeration type for comparatively simple registration of a destination, as in the above example from the
L<Model|#Model> section.


C<multi method add(Log::Dispatch::Processor:D $processor --> Nil)>


Adds an end-point object C<$processor> to the dispatcher.


Note that the C<attach> method of a custom processor is expected to return a L<C<Promise>|https://docs.raku.org/type/Promise> which is to be kept only and
only when the processor is ready. The meaning of being ready would then depend on the end-point type only.


C<multi method add(Log::Dispatch::Processor:U $processor, *%params)>


This method creates an instance of the C<$processor> type using C<%params> as constructor parameters. The resulting
instance is then gets registered with the dispatcher.


C<multi method add(>L<C<Str>|https://docs.raku.org/type/Str>C<:D $processor, *%params)>


This method determines processor type based on the name provided in C<$processor> parameter and then instantiates it
as described for the previous method candidate.


The following rules are used to resolve the type:


See the example in the L<Model|#Model> section above.


Can only be issued once on a dispatcher. Any subsequent call to the method is ignored.


Closes the dispatching supply by invoking method C<done> on the L<C<Supplier>|https://docs.raku.org/type/Supplier>.


The method can be invoked manually when absolutely necessary. But normally is it called inside an C<END> phaser to
ensure that the logging capabilities are available up until the complete stop of the application.


C<dispatch-msg(>L<C<Log::Dispatch::Msg>|Dispatch/Msg.md>C<:D $msg)>


Emits L<C<Log::Dispatch::Msg>|Dispatch/Msg.md> object into the dispatching supply.


LICENSE

Dispatch

The Raku Knowledge Base


=begin React :component<HeaderCol> :id<footer>  
=begin nested :!nested
=item1 B<Language>
    =item2 L<Get started|file:../getting-started/getting-started.podlite>
    =item2 L<Why Raku?|/doc/language/faq#Why-should-I-learn-Raku-What's-so-great-about-it>
    =item2 L<Try Raku|https://glot.io/new/raku>
    =item2 L<Raku cheat sheet|https://github.com/Raku/mu/blob/master/docs/Perl6/Cheatsheet/cheatsheet.txt>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<Raku on Exercism|https://exercism.org/tracks/raku>
    =item2 L<Wikipedia|https://en.wikipedia.org/wiki/Raku_(programming_language)>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=begin nested :!nested

=item1 B<L<Documentation|/doc>>
    =item2 L<Getting started, Migration guides from other languages, & Tutorials | file:../doc/introduction.podlite>
    =item2 L<Language References|file:../doc/reference.podlite>
    =item2 L<Type Reference| file:../doc/types.podlite>
    =item2 L<Miscellaneous| file:../doc/miscellaneous.podlite>
    =item2 L<FAQs (Frequently Asked Questions)|/doc/language/faq>
    =item2 L<Community|/doc/language/community>
    =item2 L<The list of all documents|file:../doc/index.podlite>

=item1 B<Resources>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>

=end nested
=begin nested :!nested

=item1 B<Resoures>
    =item2 L<Download | file:../download/index.podlite>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=item1 B<Learning>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Wikibook |https://en.wikibooks.org/wiki/Raku_Programming>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>
    =item2 L<Learn Raku in Y minutes|https://learnxinyminutes.com/docs/raku/>
    =item2 L<Golfing |https://github.com/AlexDaniel/raku-golf-cheatsheet>
=end nested
=begin nested :!nested

=item1 B<Explore>
    =item2 L<Raku Blog Aggregator|https://planet.raku.org/>
    =item2 L<Rakudo Weekly|https://rakudoweekly.blog/>
    =item2 L<The Weekly Challenge |https://perlweeklychallenge.org/>
    =item2 L<Raku Advent Calendar|https://raku-advent.blog/>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=end React


=begin React :component<CookieConsent> :id<CookieConsent> :buttonCaption("Got it!")
=para
This website uses cookies for analytics.
=end React


Destination

NAME

ATTRIBUTES

`LOG-LEVEL:D $.max-level`

METHODS

`method report(`Log::Dispatch::Msg`:D $msg)`

`method attach($dispatcher)`

SEE ALSO

AUTHOR

Log::Dispatch v0.0.1

Authors

License

Dependencies

Test Dependencies

Provides

Documentation

NAME

ATTRIBUTES

LOG-LEVEL:D $.max-level

METHODS

method report(Log::Dispatch::Msg:D $msg)

method attach($dispatcher)

SEE ALSO

AUTHOR

Log::Dispatch v0.0.1

Authors

License

Dependencies

Test Dependencies

Provides

Documentation

`LOG-LEVEL:D $.max-level`

`method report(`Log::Dispatch::Msg`:D $msg)`

`method attach($dispatcher)`