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.714
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 context
82 Logging context data hashref. All the key/value pairs added to this
83 hash will be printed with every log message.
84
86 Simple logging
87 Your library can do simple logging using logging methods corresponding
88 to the log levels (or aliases):
89 Pass a string to be logged. Do not include a newline.
91 $log->info("Got some new for you.");
93 The log string will be transformed via the "filter" attribute (if any)
95 and the "prefix" (if any) will be prepended. Returns the transformed
96 log string.
97 NOTE: While you are encouraged to pass a single string to be logged, if
99 multiple arguments are passed, they are concatenated with a space
100 character into a single string before processing. This ensures
101 consistency across adapters, some of which may support multiple
102 arguments to their logging functions (and which concatenate in
103 different ways) and some of which do not.
104 Advanced logging
106 Your library can do advanced logging using logging methods
107 corresponding to the log levels (or aliases), but with an "f" appended:
108 When these methods are called, the adapter is first checked to see if
110 it is logging at that level. If not, the method returns without
111 logging.
112 Next, arguments are transformed to a message string via the "formatter"
114 attribute.
115 The default formatter first checks if the first log argument is a code
117 reference. If so, it will executed and the result used as the
118 formatted message. Otherwise, the formatter acts like "sprintf" with
119 some helpful formatting.
120 Finally, the message string is logged via the simple logging functions,
122 which can transform or prefix as described above. The transformed log
123 string is then returned.
124 Numeric levels range from 0 (emergency) to 8 (trace). Constant
126 functions for these levels are available from Log::Any::Adapter::Util.
127 Logging Structured Data
129 If you have data in addition to the text you want to log, you can
130 specify a hashref after your string. If the configured adapter supports
131 structured data, it will receive the hashref as-is, otherwise it will
132 be converted to a string using Data::Dumper and will be appended to
133 your text.
134
136 UTF-8 in Data Structures
137 If you have high-bit characters in a data structure being passed to a
138 log method, Log::Any will output that data structure with the high-bit
139 characters encoded as "\x{###}", Perl's escape sequence for high-bit
140 characters. This is because the Data::Dumper module escapes those
141 characters.
142 use utf8;
144 use Log::Any qw( $log );
145 my @data = ( "Привет мир" ); # Hello, World!
146 $log->infof("Got: %s", \@data);
147 # Got: ["\x{41f}\x{440}\x{438}\x{432}\x{435}\x{442} \x{43c}\x{438}\x{440}"]
148 If you want to instead display the actual characters in your log file
150 or terminal, you can use the Data::Dumper::AutoEncode module. To wire
151 this up into Log::Any, you must pass a custom "formatter" sub:
152 use utf8;
154 use Data::Dumper::AutoEncode;
155 sub log_formatter {
157 my ( $category, $level, $format, @params ) = @_;
158 # Run references through Data::Dumper::AutoEncode
159 @params = map { ref $_ ? eDumper( $_ ) : $_ } @params;
160 return sprintf $format, @params;
161 }
162 use Log::Any '$log', formatter => \&log_formatter;
164 This formatter changes the output to:
166 Got: $VAR1 = [
168 'Привет мир'
169 ];
170 Thanks to @denis-it <https://github.com/denis-it> for this tip!
172
174 • Jonathan Swartz <swartz@pobox.com>
175 • David Golden <dagolden@cpan.org>
177 • Doug Bell <preaction@cpan.org>
179 • Daniel Pittman <daniel@rimspace.net>
181 • Stephen Thirlwall <sdt@cpan.org>
183
185 This software is copyright (c) 2017 by Jonathan Swartz, David Golden,
186 and Doug Bell.
187 This is free software; you can redistribute it and/or modify it under
189 the same terms as the Perl 5 programming language system itself.
190perl v5.36.0 2023-03-22 Log::Any::Proxy(3)