1Log::Any::Adapter::DeveUlsoeprmeCnotn(t3r)ibuted Perl DoLcougm:e:nAtnayt:i:oAndapter::Development(3)
2
3
4

NAME

6       Log::Any::Adapter::Development - Manual for developing new Log::Any
7       adapters
8

VERSION

10       version 1.717
11

SYNOPSIS

13       The adapter module:
14
15          package Log::Any::Adapter::YAL;
16          use strict;
17          use warnings;
18          use Log::Any::Adapter::Util ();
19          use base qw(Log::Any::Adapter::Base);
20
21          # Optionally initialize object, e.g. for delegation
22          #
23          sub init {
24              my ($self) = @_;
25
26              $self->{attr} = ...;
27          }
28
29          # Create logging methods: debug, info, etc.
30          #
31          foreach my $method ( Log::Any::Adapter::Util::logging_methods() ) {
32              no strict 'refs';
33              *$method = sub { ... };
34          }
35
36          # or, support structured logging instead
37          sub structured {
38              my ($self, $level, $category, @args) = @_;
39              # ... process and log all @args
40          }
41
42
43          # Create detection methods: is_debug, is_info, etc.
44          #
45          foreach my $method ( Log::Any::Adapter::Util::detection_methods() ) {
46              no strict 'refs';
47              *$method = sub { ... };
48          }
49
50       and the application:
51
52          Log::Any->set_adapter('YAL');
53

DESCRIPTION

55       This document describes how to implement a new Log::Any adapter.
56
57       The easiest way to start is to look at the source of existing adapters,
58       such as Log::Any::Adapter::Log4perl and Log::Any::Adapter::Dispatch.
59

NAMING

61       If you are going to publicly release your adapter, call it
62       'Log::Any::Adapter::something' so that users can use it with
63
64           Log::Any->set_adapter(I<something>);
65
66       If it's an internal driver, you can call it whatever you like and use
67       it like
68
69           Log::Any->set_adapter('+My::Log::Adapter');
70

BASE CLASS

72       All adapters must directly or indirectly inherit from
73       Log::Any::Adapter::Base.
74

LOG LEVELS

76       Log::Any supports the following log levels:
77
78       If the logging mechanism used by your adapter supports different
79       levels, it's your responsibility to map them appropriately when you
80       implement the logging and detection methods described below.  For
81       example, if your mechanism only supports "debug", "normal" and "fatal"
82       levels, you might map the levels like this:
83

METHODS

85   Constructor
86       The constructor ("new") is provided by Log::Any::Adapter::Base. It
87       will:
88
89       At this point, overriding the default constructor is not supported.
90       Hopefully it will not be needed.
91
92       The constructor is called whenever a log object is requested. e.g. If
93       the application initializes Log::Any like so:
94
95           Log::Any->set_adapter('Log::YAL', yal_object => $yal, depth => 3);
96
97       and then a class requests a logger like so:
98
99           package Foo;
100           use Log::Any qw($log);
101
102       Then $log will be populated with the return value of:
103
104           Log::Any::Adapter::Yal->new(yal_object => $yal, depth => 3, category => 'Foo');
105
106       This is memoized, so if the same category should be requested again
107       (e.g.  through a separate "get_logger" call, the same object will be
108       returned.  Therefore, you should try to avoid anything non-
109       deterministic in your "init" function.
110
111   Logging methods
112       The following methods have no default implementation, and MUST be
113       defined by your subclass, unless your adapter supports "Structured
114       logging":
115
116       These methods must log a message at the specified level.
117
118       To help generate these methods programmatically, you can get a list of
119       the sub names with the Log::Any::Adapter::Util::logging_methods
120       function.
121
122   Log-level detection methods (required)
123       The following methods have no default implementation, and MUST be
124       defined by your subclass:
125
126       These methods must return a boolean indicating whether the specified
127       level is active, i.e. whether the adapter is listening for messages of
128       that level.
129
130       To help generate these methods programmatically, you can get a list of
131       the sub names with the Log::Any::Adapter::Util::detection_methods
132       function.
133
134   Structured logging
135       Your adapter can choose to receive structured data instead of a string.
136       In this case, instead of implementing all the "Logging methods", you
137       define a single method called "structured". The method receives the log
138       level, the category, and all arguments that were passed to the logging
139       function, so be prepared to not only handle strings, but also hashrefs,
140       arrayrefs, coderefs, etc.
141
142   Aliases
143       Aliases (e.g. "err" for "error") are handled by Log::Any::Proxy and
144       will call the corresponding real name in your adapter class.  You do
145       not need to implement them in your adapter.
146
147   Optional methods
148       The following methods have no default implementation but MAY be
149       provided by your subclass:
150
151       init
152           This is called after the adapter object is created and blessed into
153           your class.  Perform any necessary validation or initialization
154           here.  For example, you would use "init" to create a logging object
155           for delegation, or open a file or socket, etc.
156
157   Support methods
158       The following Log::Any::Adapter::Base method may be useful for defining
159       adapters via delegation:
160
161       delegate_method_to_slot ($slot, $method, $adapter_method)
162           Handle the specified $method by calling $adapter_method on the
163           object contained in "$self->{$slot}".
164
165           See Log::Any::Adapter::Dispatch and Log::Any::Adapter::Log4perl for
166           examples of usage.
167
168       The following Log::Any::Adapter::Util functions give you a list of
169       methods that you need to implement.  You can get logging methods,
170       detection methods or both:
171

AUTHORS

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