1Log::Any::Proxy(3)    User Contributed Perl Documentation   Log::Any::Proxy(3)
2
3
4

NAME

6       Log::Any::Proxy - Log::Any generator proxy object
7

VERSION

9       version 1.708
10

SYNOPSIS

12           # prefix log messages
13           use Log::Any '$log', prefix => 'MyApp: ';
14
15           # transform log messages
16           use Log::Any '$log', filter => \&myfilter;
17
18           # 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
25           # create a clone with different attributes
26           my $bar_log = $log->clone( prefix => 'bar: ' );
27

DESCRIPTION

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

ATTRIBUTES

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
37   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
41   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
46           sub {
47               my ($cat, $lvl, $msg) = @_;
48               return "[$lvl] $msg";
49           }
50
51       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
54       Numeric levels range from 0 (emergency) to 8 (trace).  Constant
55       functions for these levels are available from Log::Any::Adapter::Util.
56
57       Configuring a filter disables structured logging, even if the
58       configured adapter supports it.
59
60   formatter
61       A code reference to format messages given to the *f methods ("tracef",
62       "debugf", "infof", etc..)
63
64       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
68           sub {
69               my ($cat, $lvl, $format, @args) = @_;
70               return sprintf($format, @args);
71           }
72
73       The default formatter does the following:
74
75   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

USAGE

82   Simple logging
83       Your library can do simple logging using logging methods corresponding
84       to the log levels (or aliases):
85
86       Pass a string to be logged.  Do not include a newline.
87
88           $log->info("Got some new for you.");
89
90       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
94       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
101   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
105       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
109       Next, arguments are transformed to a message string via the "formatter"
110       attribute.
111
112       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
117       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
121       Numeric levels range from 0 (emergency) to 8 (trace).  Constant
122       functions for these levels are available from Log::Any::Adapter::Util.
123
124   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

TIPS

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
139           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
145       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
149           use utf8;
150           use Data::Dumper::AutoEncode;
151
152           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
159           use Log::Any '$log', formatter => \&log_formatter;
160
161       This formatter changes the output to:
162
163               Got: $VAR1 = [
164                                 'Привет мир'
165                               ];
166
167       Thanks to @denis-it <https://github.com/denis-it> for this tip!
168

AUTHORS

170       ·   Jonathan Swartz <swartz@pobox.com>
171
172       ·   David Golden <dagolden@cpan.org>
173
174       ·   Doug Bell <preaction@cpan.org>
175
176       ·   Daniel Pittman <daniel@rimspace.net>
177
178       ·   Stephen Thirlwall <sdt@cpan.org>
179
181       This software is copyright (c) 2017 by Jonathan Swartz, David Golden,
182       and Doug Bell.
183
184       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.
186
187
188
189perl v5.32.0                      2020-07-28                Log::Any::Proxy(3)
Impressum