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

NAME

6       Log::Any::Adapter - Tell Log::Any where to send its logs
7

VERSION

9       version 1.714
10

SYNOPSIS

12           # Log to a file, or stdout, or stderr for all categories
13           #
14           use Log::Any::Adapter ('File', '/path/to/file.log');
15           use Log::Any::Adapter ('Stdout');
16           use Log::Any::Adapter ('Stderr');
17
18           # Use Log::Log4perl for all categories
19           #
20           Log::Log4perl::init('/etc/log4perl.conf');
21           Log::Any::Adapter->set('Log4perl');
22
23           # Use Log::Dispatch for Foo::Baz
24           #
25           use Log::Dispatch;
26           my $log = Log::Dispatch->new(outputs => [[ ... ]]);
27           Log::Any::Adapter->set( { category => 'Foo::Baz' },
28               'Dispatch', dispatcher => $log );
29
30           # Use Log::Dispatch::Config for Foo::Baz and its subcategories
31           #
32           use Log::Dispatch::Config;
33           Log::Dispatch::Config->configure('/path/to/log.conf');
34           Log::Any::Adapter->set(
35               { category => qr/^Foo::Baz/ },
36               'Dispatch', dispatcher => Log::Dispatch::Config->instance() );
37
38           # Use your own adapter for all categories
39           #
40           Log::Any::Adapter->set('+My::Log::Any::Adapter', ...);
41

DESCRIPTION

43       Log::Any::Adapter connects log producers and log consumers.  Its
44       methods instantiate a logging adapter (a subclass of
45       Log::Any::Adapter::Base) and route log messages from one or more
46       categories to it.
47

ADAPTERS

49       In order to use a logging mechanism with "Log::Any", there needs to be
50       an adapter class for it. Typically this is named
51       Log::Any::Adapter::something.
52
53   Adapters in this distribution
54       Three basic adapters come with this distribution --
55       Log::Any::Adapter::File, Log::Any::Adapter::Stdout and
56       Log::Any::Adapter::Stderr:
57
58           use Log::Any::Adapter ('File', '/path/to/file.log');
59           use Log::Any::Adapter ('Stdout');
60           use Log::Any::Adapter ('Stderr');
61
62           # or
63
64           use Log::Any::Adapter;
65           Log::Any::Adapter->set('File', '/path/to/file.log');
66           Log::Any::Adapter->set('Stdout');
67           Log::Any::Adapter->set('Stderr');
68
69       All of them simply output the message and newline to the specified
70       destination; a datestamp prefix is added in the "File" case. For
71       anything more complex you'll want to use a more robust adapter from
72       CPAN.
73
74   Adapters on CPAN
75       A sampling of adapters available on CPAN as of this writing:
76
77       •   Log::Any::Adapter::Log4perl
78
79       •   Log::Any::Adapter::Dispatch
80
81       •   Log::Any::Adapter::FileHandle
82
83       •   Log::Any::Adapter::Syslog
84
85       You may find other adapters on CPAN by searching for
86       "Log::Any::Adapter", or create your own adapter. See
87       Log::Any::Adapter::Development for more information on the latter.
88

SETTING AND REMOVING ADAPTERS

90       Log::Any::Adapter->set ([options, ]adapter_name, adapter_params...)
91           This method sets the adapter to use for all log categories, or for
92           a particular set of categories.
93
94           adapter_name is the name of an adapter. It is automatically
95           prepended with "Log::Any::Adapter::". If instead you want to pass
96           the full name of an adapter, prefix it with a "+". e.g.
97
98               # Use My::Adapter class
99               Log::Any::Adapter->set('+My::Adapter', arg => $value);
100
101           adapter_params are passed along to the adapter constructor. See the
102           documentation for the individual adapter classes for more
103           information.
104
105           An optional hash of options may be passed as the first argument.
106           Options are:
107
108           category
109               A string containing a category name, or a regex (created with
110               "qr//") matching multiple categories.  If not specified, all
111               categories will be routed to the adapter.
112
113           lexically
114               A reference to a lexical variable. When the variable goes out
115               of scope, the adapter setting will be removed. e.g.
116
117                   {
118                       Log::Any::Adapter->set({lexically => \my $lex}, ...);
119
120                       # in effect here
121                       ...
122                   }
123                   # no longer in effect here
124
125           "set" returns an entry object, which can be passed to "remove".  If
126           you call "set" repeatedly without calling "remove" you will leak
127           memory.  For most programs that set an adapter once until the end
128           of the program, this shouldn't matter.
129
130       use Log::Any::Adapter (...)
131           If you pass arguments to "use Log::Any::Adapter", it calls
132           "Log::Any::Adapter->set" with those arguments.
133
134       Log::Any::Adapter->remove (entry)
135           Remove an entry previously returned by "set".
136

USING MORE THAN ONE ADAPTER

138       "Log::Any" maintains a stack of entries created via "set".  If you call
139       "set" repeatedly, you will leak memory unless you do one of the
140       following:
141
142       When getting a logger for a particular category, "Log::Any" will work
143       its way down the stack and use the first matching entry.
144
145       Whenever the stack changes, any "Log::Any" loggers that have previously
146       been created will automatically adjust to the new stack. For example:
147
148           my $log = Log::Any->get_logger();
149           $log->error("aiggh!");   # this goes nowhere
150           ...
151           {
152               Log::Any::Adapter->set({ lexically => \my $lex }, 'Log4perl');
153               $log->error("aiggh!");   # this goes to log4perl
154               ...
155           }
156           $log->error("aiggh!");   # this goes nowhere again
157

BUILDING ON THE Log::Any BACKEND

159       get
160             my $adapter= Log::Any::Adapter->get($category);
161
162           The primary intended way to extend the producing-side of Log::Any
163           is with a custom Log::Any::Proxy class.  However, for special
164           logging scenarios you might also just want access to the adapter
165           for a given category.  The API of an adapter object is described in
166           Log::Any::Adapter::Development.  Beware that adapter objects can be
167           "rewritten" on the fly, so any conditional behavior you write
168           depending on the capabilities of an adapter must be re-checked
169           every time you access the adapter.
170

SEE ALSO

172       Log::Any
173

AUTHORS

175       •   Jonathan Swartz <swartz@pobox.com>
176
177       •   David Golden <dagolden@cpan.org>
178
179       •   Doug Bell <preaction@cpan.org>
180
181       •   Daniel Pittman <daniel@rimspace.net>
182
183       •   Stephen Thirlwall <sdt@cpan.org>
184
186       This software is copyright (c) 2017 by Jonathan Swartz, David Golden,
187       and Doug Bell.
188
189       This is free software; you can redistribute it and/or modify it under
190       the same terms as the Perl 5 programming language system itself.
191
192
193
194perl v5.36.0                      2023-03-22              Log::Any::Adapter(3)
Impressum