1Log::Any::Proxy(3) User Contributed Perl Documentation Log::Any::Proxy(3)
2
6 Log::Any::Proxy - Log::Any generator proxy object
7
9 version 1.710
10
12 # prefix log messages
13 use Log::Any '$log', prefix => 'MyApp: ';
14 # transform log messages
16 use Log::Any '$log', filter => \&myfilter;
17 # format with String::Flogger instead of the default
19 use String::Flogger;
20 use Log::Any '$log', formatter => sub {
21 my ($cat, $lvl, @args) = @_;
22 String::Flogger::flog( @args );
23 };
24 # create a clone with different attributes
26 my $bar_log = $log->clone( prefix => 'bar: ' );
27
29 Log::Any::Proxy objects are what modules use to produce log messages.
30 They construct messages and pass them along to a configured adapter.
31
33 adapter
34 A Log::Any::Adapter object to receive any messages logged. This is
35 generated by Log::Any and can not be overridden.
36 category
38 The category name of the proxy. If not provided, Log::Any will set it
39 equal to the calling when the proxy is constructed.
40 filter
42 A code reference to transform messages before passing them to a
43 Log::Any::Adapter. It gets three arguments: a category, a numeric
44 level and a string. It should return a string to be logged.
45 sub {
47 my ($cat, $lvl, $msg) = @_;
48 return "[$lvl] $msg";
49 }
50 If the return value is undef or the empty string, no message will be
52 logged. Otherwise, the return value is passed to the logging adapter.
53 Numeric levels range from 0 (emergency) to 8 (trace). Constant
55 functions for these levels are available from Log::Any::Adapter::Util.
56 Configuring a filter disables structured logging, even if the
58 configured adapter supports it.
59 formatter
61 A code reference to format messages given to the *f methods ("tracef",
62 "debugf", "infof", etc..)
63 It get three or more arguments: a category, a numeric level and the
65 list of arguments passsed to the *f method. It should return a string
66 to be logged.
67 sub {
69 my ($cat, $lvl, $format, @args) = @_;
70 return sprintf($format, @args);
71 }
72 The default formatter does the following:
74 prefix
76 If defined, this string will be prepended to all messages. It will not
77 include a trailing space, so add that yourself if you want. This is
78 less flexible/powerful than "filter", but avoids an extra function
79 call.
80
82 Simple logging
83 Your library can do simple logging using logging methods corresponding
84 to the log levels (or aliases):
85 Pass a string to be logged. Do not include a newline.
87 $log->info("Got some new for you.");
89 The log string will be transformed via the "filter" attribute (if any)
91 and the "prefix" (if any) will be prepended. Returns the transformed
92 log string.
93 NOTE: While you are encouraged to pass a single string to be logged, if
95 multiple arguments are passed, they are concatenated with a space
96 character into a single string before processing. This ensures
97 consistency across adapters, some of which may support multiple
98 arguments to their logging functions (and which concatenate in
99 different ways) and some of which do not.
100 Advanced logging
102 Your library can do advanced logging using logging methods
103 corresponding to the log levels (or aliases), but with an "f" appended:
104 When these methods are called, the adapter is first checked to see if
106 it is logging at that level. If not, the method returns without
107 logging.
108 Next, arguments are transformed to a message string via the "formatter"
110 attribute.
111 The default formatter first checks if the first log argument is a code
113 reference. If so, it will executed and the result used as the
114 formatted message. Otherwise, the formatter acts like "sprintf" with
115 some helpful formatting.
116 Finally, the message string is logged via the simple logging functions,
118 which can transform or prefix as described above. The transformed log
119 string is then returned.
120 Numeric levels range from 0 (emergency) to 8 (trace). Constant
122 functions for these levels are available from Log::Any::Adapter::Util.
123 Logging Structured Data
125 If you have data in addition to the text you want to log, you can
126 specify a hashref after your string. If the configured adapter supports
127 structured data, it will receive the hashref as-is, otherwise it will
128 be converted to a string using Data::Dumper and will be appended to
129 your text.
130
132 UTF-8 in Data Structures
133 If you have high-bit characters in a data structure being passed to a
134 log method, Log::Any will output that data structure with the high-bit
135 characters encoded as "\x{###}", Perl's escape sequence for high-bit
136 characters. This is because the Data::Dumper module escapes those
137 characters.
138 use utf8;
140 use Log::Any qw( $log );
141 my @data = ( "Привет мир" ); # Hello, World!
142 $log->infof("Got: %s", \@data);
143 # Got: ["\x{41f}\x{440}\x{438}\x{432}\x{435}\x{442} \x{43c}\x{438}\x{440}"]
144 If you want to instead display the actual characters in your log file
146 or terminal, you can use the Data::Dumper::AutoEncode module. To wire
147 this up into Log::Any, you must pass a custom "formatter" sub:
148 use utf8;
150 use Data::Dumper::AutoEncode;
151 sub log_formatter {
153 my ( $category, $level, $format, @params ) = @_;
154 # Run references through Data::Dumper::AutoEncode
155 @params = map { ref $_ ? eDumper( $_ ) : $_ } @params;
156 return sprintf $format, @params;
157 }
158 use Log::Any '$log', formatter => \&log_formatter;
160 This formatter changes the output to:
162 Got: $VAR1 = [
164 'Привет мир'
165 ];
166 Thanks to @denis-it <https://github.com/denis-it> for this tip!
168
170 • Jonathan Swartz <swartz@pobox.com>
171 • David Golden <dagolden@cpan.org>
173 • Doug Bell <preaction@cpan.org>
175 • Daniel Pittman <daniel@rimspace.net>
177 • Stephen Thirlwall <sdt@cpan.org>
179
181 This software is copyright (c) 2017 by Jonathan Swartz, David Golden,
182 and Doug Bell.
183 This is free software; you can redistribute it and/or modify it under
185 the same terms as the Perl 5 programming language system itself.
186perl v5.34.0 2021-08-04 Log::Any::Proxy(3)