package Log::ger::Manual::Tutorial::500_Category;

# DATE
# VERSION

1;
# ABSTRACT: Categories

__END__

=pod

=encoding UTF-8

=head1 NAME

Log::ger::Manual::Tutorial::500_Category - Categories

=head1 VERSION

version 0.033.000

=head1 DESCRIPTION

=over

=back

=head1 WHAT ARE CATEGORIES?

Aside from filtering log messages by level, you can also filter by category.
Category normally maps to Perl packages (but they can also be something else).
For example:

 # in My/App/Module1.pm
 package My::App::Module1;
 use Log::ger;
 sub foo {
     log_warn("foo!");
 }
 1;

 # in My/App/Module2.pm
 package My::App::Module2;
 use Log::ger;
 sub bar {
     log_warn("bar!");
 }
 1;

Logger subroutines in C<My::App::Module1> will log messages under the category
C<My::App::Module1>, while logger subroutines in C<My::App::Module2> will log
messages under the category C<My::App::Module2>. In your application, you can do
something like:

 use Log::ger::Output Composite => (
     outputs => { ... },
     category_level => {
         'My::App' => 'info',
         'My::App::Module1' => 'debug',
         'My::App::Module2' => 'error',
     },
 );

Categories work hierarchically. The above means, other modules under C<My::App>,
like C<My::App::Module3> or C<My::App::Module4::Submodule> is set to level
C<info>.

=head1 LOGGING UNDER A DIFFERENT CATEGORY

 package My::App::Module4;
 use Log::ger ();
 my $log     = Log::ger->get_logger(); # by default will use the caller's package
 my $log_foo = Log::ger->get_logger(category => "Foo");

 $log->warn("This message will be logged under the category 'My::App::Module4'");
 $log_foo->warn("This message will be logged under the category 'Foo'");

=head2 PER-CATEGORY OUTPUT

To direct log messages under a certain category to its own output, for example
category C<Foo> to a separate file C</path/foo.log> while the rest go to
C</path/app.log>, you can do something like this:

 use Log::ger::Output Composite => (
     outputs => {
         File => [
             {
                 conf => {path=>'/path/app.log'},
                 category_level => { Foo => 'off' },
             },
             {
                 conf => {path=>'/path/foo.log'},
                 level => 'off',
                 category_level => { Foo => 'trace' },
             },
         ],
     },
 );

So basically for C</path/app.log> you turn off the category C<Foo>, while for
C</path/foo.log> you turn off for all category except for C<Foo>.

=head1 AUTHOR

perlancar <perlancar@cpan.org>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2020, 2019, 2018, 2017 by 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.

=cut