| 1 | package Acme::Crux::Plugin::Log; | ||
| 2 | use warnings; | ||
| 3 | use strict; | ||
| 4 | use utf8; | ||
| 5 | |||
| 6 | =encoding utf-8 | ||
| 7 | |||
| 8 | =head1 NAME | ||
| 9 | |||
| 10 | Acme::Crux::Plugin::Log - The Acme::Crux plugin for logging in your application | ||
| 11 | |||
| 12 | =head1 SYNOPSIS | ||
| 13 | |||
| 14 | # In startup | ||
| 15 | $app->plugin('Log'); | ||
| 16 | $app->plugin('Log', undef, { ... options ... }); | ||
| 17 | |||
| 18 | # In application | ||
| 19 | $app->log->trace('Whatever'); | ||
| 20 | $app->log->debug('You screwed up, but that is ok'); | ||
| 21 | $app->log->info('You are bad, but you prolly know already'); | ||
| 22 | $app->log->notice('Normal, but significant, condition...'); | ||
| 23 | $app->log->warn('Dont do that Dave...'); | ||
| 24 | $app->log->error('You really screwed up this time'); | ||
| 25 | $app->log->fatal('Its over...'); | ||
| 26 | $app->log->crit('Its over...'); | ||
| 27 | $app->log->alert('Action must be taken immediately'); | ||
| 28 | $app->log->emerg('System is unusable'); | ||
| 29 | |||
| 30 | =head1 DESCRIPTION | ||
| 31 | |||
| 32 | The Acme::Crux plugin for logging in your application | ||
| 33 | |||
| 34 | =head1 OPTIONS | ||
| 35 | |||
| 36 | This plugin supports the following options | ||
| 37 | |||
| 38 | =head2 autoclean | ||
| 39 | |||
| 40 | $app->plugin(Log => undef, {autoclean => 1}); | ||
| 41 | |||
| 42 | This option enables cleaning (closing handler or syslog) on DESTROY | ||
| 43 | |||
| 44 | Default: C<logautoclean> command line option or C<logautoclean> application argument | ||
| 45 | or C<LogAutoclean> configuration value or C<0> otherwise | ||
| 46 | |||
| 47 | =head2 color | ||
| 48 | |||
| 49 | $app->plugin(Log => undef, {color => 1}); | ||
| 50 | |||
| 51 | This option enables colorize log messages with the available levels using L<Term::ANSIColor> | ||
| 52 | |||
| 53 | Default: C<logcolorize> command line option or C<logcolorize> application argument | ||
| 54 | or C<LogColorize> configuration value or C<0> otherwise | ||
| 55 | |||
| 56 | =head2 facility | ||
| 57 | |||
| 58 | $app->plugin(Log => undef, {facility => 'user'}); | ||
| 59 | |||
| 60 | This option sets facility for logging | ||
| 61 | |||
| 62 | Available standard facilities: C<auth>, C<authpriv>, C<cron>, C<daemon>, C<ftp>, | ||
| 63 | C<kern>, C<local0>, C<local1>, C<local2>, C<local3>, C<local4>, C<local5>, C<local6>, | ||
| 64 | C<local7>, C<lpr>, C<mail>, C<news>, C<syslog>, C<user> and C<uucp> | ||
| 65 | |||
| 66 | Default: C<logfacility> command line option or C<logfacility> application argument | ||
| 67 | or C<LogFacility> configuration value or C<user> otherwise | ||
| 68 | |||
| 69 | =head2 file | ||
| 70 | |||
| 71 | $app->plugin(Log => undef, {file => '/var/log/myapp.log'}); | ||
| 72 | |||
| 73 | Log file path used by "handle" | ||
| 74 | |||
| 75 | Default: C<logfile> command line option or C<LogFile> configuration value | ||
| 76 | or C<logfile> application argument or C</var/log/$moniker/$moniker.log> otherwise | ||
| 77 | |||
| 78 | =head2 format | ||
| 79 | |||
| 80 | $app->plugin(Log => undef, {format => sub {...}}); | ||
| 81 | |||
| 82 | A callback function for formatting log messages. See L<Acrux::Log/format> | ||
| 83 | |||
| 84 | Default: C<logformat> application argument or C<undef> otherwise | ||
| 85 | |||
| 86 | =head2 handle | ||
| 87 | |||
| 88 | $app->plugin(Log => undef, { | ||
| 89 | handle => IO::Handle->new_from_fd(fileno(STDOUT), "w") | ||
| 90 | }); | ||
| 91 | |||
| 92 | Log filehandle, defaults to opening "file" or uses syslog if file not specified | ||
| 93 | |||
| 94 | Default: C<loghandle> application argument or C<undef> otherwise | ||
| 95 | |||
| 96 | =head2 ident | ||
| 97 | |||
| 98 | $app->plugin(Log => undef, {ident => 'myapp'}); | ||
| 99 | |||
| 100 | The B<ident> is prepended to every B<syslog> message | ||
| 101 | |||
| 102 | Default: C<logident> command line option or C<logident> application argument | ||
| 103 | or C<LogIdent> configuration value or script name C<basename($0)> otherwise | ||
| 104 | |||
| 105 | =head2 level | ||
| 106 | |||
| 107 | $app->plugin(Log => undef, {level => 'debug'}); | ||
| 108 | |||
| 109 | This option sets log level | ||
| 110 | |||
| 111 | Predefined log levels: C<fatal>, C<error>, C<warn>, C<info>, C<debug>, and C<trace> (in descending priority). | ||
| 112 | The syslog supports followed additional log levels: C<emerg>, C<alert>, C<crit'> and C<notice> (in descending priority). | ||
| 113 | But we recommend not using them to maintain compatibility. | ||
| 114 | |||
| 115 | See also L<Acrux::Log/level> | ||
| 116 | |||
| 117 | Default: C<loglevel> command line option or C<loglevel> application argument | ||
| 118 | or C<LogLevel> configuration value or C<debug> otherwise | ||
| 119 | |||
| 120 | =head2 logger | ||
| 121 | |||
| 122 | $app->plugin(Log => undef, {logger => Mojo::Log->new()}); | ||
| 123 | |||
| 124 | This option sets predefined logger, eg. Mojo::Log | ||
| 125 | |||
| 126 | Default: C<logger> application argument or C<undef> otherwise | ||
| 127 | |||
| 128 | =head2 logopt | ||
| 129 | |||
| 130 | $app->plugin(Log => undef, {logopt => 'ndelay,pid'}); | ||
| 131 | |||
| 132 | This option contains zero or more of the options detailed in L<Sys::Syslog/openlog> | ||
| 133 | |||
| 134 | Default: C<logopt> command line option or C<logopt> application argument | ||
| 135 | or C<LogOpt> configuration value or C<'ndelay,pid'> otherwise | ||
| 136 | |||
| 137 | =head2 prefix | ||
| 138 | |||
| 139 | $app->plugin(Log => undef, {prefix => '>>>'}); | ||
| 140 | |||
| 141 | The B<prefix> is prepended to every C<handled> log message | ||
| 142 | |||
| 143 | Default: C<logprefix> command line option or C<logprefix> application argument | ||
| 144 | or C<LogPrefix> configuration value or C<null> otherwise | ||
| 145 | |||
| 146 | =head2 provider | ||
| 147 | |||
| 148 | $app->plugin(Log => undef, {provider => 'syslog'}); | ||
| 149 | |||
| 150 | This option select the provider of logging. Avalabled providers: | ||
| 151 | C<logger>, C<handler>, C<file> and C<syslog>. | ||
| 152 | |||
| 153 | Default: C<logprovider> command line option or C<logprovider> application argument | ||
| 154 | or C<LogProvider> configuration value or C<file> otherwise | ||
| 155 | |||
| 156 | =head2 short | ||
| 157 | |||
| 158 | $app->plugin(Log => undef, {short => 1}); | ||
| 159 | |||
| 160 | Generate short log messages without a timestamp but with log level prefix | ||
| 161 | |||
| 162 | Default: C<logshort> command line option or C<logshort> application argument | ||
| 163 | or C<LogShort> configuration value or C<0> otherwise | ||
| 164 | |||
| 165 | =head1 METHODS | ||
| 166 | |||
| 167 | This class inherits all methods from L<Acme::Crux::Plugin> and implements the following new ones | ||
| 168 | |||
| 169 | =head2 register | ||
| 170 | |||
| 171 | $plugin->register($app, {file => '/var/log/app.log'}); | ||
| 172 | |||
| 173 | Register plugin in Acme::Crux application | ||
| 174 | |||
| 175 | =head1 HELPERS | ||
| 176 | |||
| 177 | All helpers of this plugin are allows get access to logger object. | ||
| 178 | See L<Acrux::Log> for details | ||
| 179 | |||
| 180 | =head2 log | ||
| 181 | |||
| 182 | Returns L<Acrux::Log> object | ||
| 183 | |||
| 184 | =head1 TO DO | ||
| 185 | |||
| 186 | See C<TODO> file | ||
| 187 | |||
| 188 | =head1 SEE ALSO | ||
| 189 | |||
| 190 | L<Acme::Crux::Plugin>, L<Acrux::Log> | ||
| 191 | |||
| 192 | =head1 AUTHOR | ||
| 193 | |||
| 194 | Serż Minus (Sergey Lepenkov) L<https://www.serzik.com> E<lt>abalama@cpan.orgE<gt> | ||
| 195 | |||
| 196 | =head1 COPYRIGHT | ||
| 197 | |||
| 198 | Copyright (C) 1998-2026 D&D Corporation | ||
| 199 | |||
| 200 | =head1 LICENSE | ||
| 201 | |||
| 202 | This program is distributed under the terms of the Artistic License Version 2.0 | ||
| 203 | |||
| 204 | See the C<LICENSE> file or L<https://opensource.org/license/artistic-2-0> for details | ||
| 205 | |||
| 206 | =cut | ||
| 207 | |||
| 208 | use parent 'Acme::Crux::Plugin'; | ||
| 209 | |||
| 210 | use Acrux::Log; | ||
| 211 | |||
| 212 | use Carp qw/croak/; | ||
| 213 | use Acrux::RefUtil qw/is_code_ref is_true_flag is_ref/; | ||
| 214 | |||
| 215 | sub register { | ||
| 216 | my ($self, $app, $args) = @_; | ||
| 217 | my $has_config = $app->can('config') ? 1 : 0; | ||
| 218 | |||
| 219 | # Autoclean flag: PLGARGS || OPTS || ORIG || CONF || DEFS | ||
| 220 | my $autoclean = is_true_flag($args->{autoclean}) # From plugin arguments first | ||
| 221 | || $app->getopt("logautoclean") # From command line options | ||
| 222 | || $app->orig->{"logautoclean"} # From App arguments | ||
| 223 | || ($has_config ? $app->config->latest("/logautoclean") : 0); # From config file | ||
| 224 | |||
| 225 | # Colorize flag: PLGARGS || OPTS || ORIG || CONF || DEFS | ||
| 226 | my $colorize = is_true_flag($args->{color}) # From plugin arguments first | ||
| 227 | || $app->getopt("logcolorize") # From command line options | ||
| 228 | || $app->orig->{"logcolorize"} # From App arguments | ||
| 229 | || ($has_config ? $app->config->latest("/logcolorize") : 0); # From config file | ||
| 230 | |||
| 231 | # Log facility: PLGARGS || OPTS || ORIG || CONF || DEFS | ||
| 232 | my $facility = $args->{facility} # From plugin arguments first | ||
| 233 | || $app->getopt("logfacility") # From command line options | ||
| 234 | || $app->orig->{"logfacility"} # From App arguments | ||
| 235 | || ($has_config ? $app->config->latest("/logfacility") : ''); # From config file | ||
| 236 | croak(qq{Invalid log facility}) if defined($facility) && is_ref($facility); | ||
| 237 | |||
| 238 | # Log file: PLGARGS || OPTS || CONF || ORIG || DEFS | ||
| 239 | my $file = $args->{file} # From plugin arguments first | ||
| 240 | || $app->getopt("logfile") # From command line options | ||
| 241 | || ($has_config ? $app->config->latest("/logfile") : '') # From config file | ||
| 242 | || $app->logfile; # From App arguments | ||
| 243 | croak(qq{Invalid log file}) if defined($file) && is_ref($file); | ||
| 244 | |||
| 245 | # Format: PLGARGS || DEFS | ||
| 246 | my $frmt = $args->{format} || $app->orig->{"logformat"}; | ||
| 247 | if (defined($frmt) && length($frmt)) { | ||
| 248 | croak(qq{Invalid log format coderef}) unless is_code_ref($frmt); | ||
| 249 | } | ||
| 250 | |||
| 251 | # Handle: PLGARGS || DEFS | ||
| 252 | my $handle = $args->{handle} || $app->orig->{"loghandle"}; | ||
| 253 | if (defined $handle) { | ||
| 254 | croak(qq{Invalid log handle}) unless is_ref($handle); | ||
| 255 | } | ||
| 256 | |||
| 257 | # Log ident: PLGARGS || OPTS || ORIG || CONF || DEFS | ||
| 258 | my $ident = $args->{ident} # From plugin arguments first | ||
| 259 | || $app->getopt("logident") # From command line options | ||
| 260 | || $app->orig->{"logident"} # From App arguments | ||
| 261 | || ($has_config ? $app->config->latest("/logident") : ''); # From config file | ||
| 262 | croak(qq{Invalid log ident}) if defined($ident) && is_ref($ident); | ||
| 263 | |||
| 264 | # Log level: PLGARGS || OPTS || ORIG || CONF || DEFS | ||
| 265 | my $level = $args->{level} # From plugin arguments first | ||
| 266 | || $app->getopt("loglevel") # From command line options | ||
| 267 | || $app->orig->{"loglevel"} # From App arguments | ||
| 268 | || ($has_config ? $app->config->latest("/loglevel") : ''); # From config file | ||
| 269 | croak(qq{Invalid log level}) if defined($level) && is_ref($level); | ||
| 270 | |||
| 271 | # Logger: PLGARGS || DEFS | ||
| 272 | my $logger = $args->{logger} || $app->orig->{"logger"}; | ||
| 273 | if (defined $logger) { | ||
| 274 | croak(qq{Invalid logger object}) unless is_ref($logger); | ||
| 275 | } | ||
| 276 | |||
| 277 | # Log options: PLGARGS || OPTS || ORIG || CONF || DEFS | ||
| 278 | my $logopt = $args->{logopt} # From plugin arguments first | ||
| 279 | || $app->getopt("logopt") # From command line options | ||
| 280 | || $app->orig->{"logopt"} # From App arguments | ||
| 281 | || ($has_config ? $app->config->latest("/logopt") : ''); # From config file | ||
| 282 | |||
| 283 | # Short flag: PLGARGS || OPTS || ORIG || CONF || DEFS | ||
| 284 | my $short = is_true_flag($args->{short}) # From plugin arguments first | ||
| 285 | || $app->getopt("logshort") # From command line options | ||
| 286 | || $app->orig->{"logshort"} # From App arguments | ||
| 287 | || ($has_config ? $app->config->latest("/logshort") : 0); # From config file | ||
| 288 | |||
| 289 | # Log prefix: PLGARGS || OPTS || ORIG || CONF || DEFS | ||
| 290 | my $prefix = $args->{prefix} # From plugin arguments first | ||
| 291 | || $app->getopt("logprefix") # From command line options | ||
| 292 | || $app->orig->{"logprefix"} # From App arguments | ||
| 293 | || ($has_config ? $app->config->latest("/logprefix") : ''); # From config file | ||
| 294 | croak(qq{Invalid log prefix}) if defined($prefix) && is_ref($prefix); | ||
| 295 | |||
| 296 | # Correct provider rules | ||
| 297 | my $provider = $args->{provider} # From plugin arguments first | ||
| 298 | || $app->getopt("logprovider") # From command line options | ||
| 299 | || $app->orig->{"logprovider"} # From App arguments | ||
| 300 | || ($has_config ? $app->config->latest("/logprovider") : '') || ''; # From config file | ||
| 301 | if ($provider eq 'syslog') { $file = 'syslog'; $handle = $logger = undef } | ||
| 302 | elsif ($provider eq 'file') { $logger = $handle = undef } | ||
| 303 | elsif ($provider eq 'handle') { $logger = undef } | ||
| 304 | |||
| 305 | # Create instance | ||
| 306 | my $log = Acrux::Log->new( | ||
| 307 | autoclean => $autoclean, | ||
| 308 | color => $colorize, | ||
| 309 | facility => $facility, | ||
| 310 | file => $file, | ||
| 311 | format => $frmt, | ||
| 312 | handle => $handle, | ||
| 313 | ident => $ident, | ||
| 314 | level => $level, | ||
| 315 | logger => $logger, | ||
| 316 | logopt => $logopt, | ||
| 317 | short => $short, | ||
| 318 | prefix => $prefix, | ||
| 319 | ); | ||
| 320 | |||
| 321 | # Set log helper (method) | ||
| 322 | $app->register_method(log => sub { $log }); | ||
| 323 | |||
| 324 | return $log; | ||
| 325 | } | ||
| 326 | |||
| 327 | 1; | ||
| 328 | |||
| 329 | __END__ |