1Appender::Synchronized(U3s)er Contributed Perl DocumentatAipopnender::Synchronized(3)
2
6 Log::Log4perl::Appender::Synchronized - Synchronizing other appenders
7
9 use Log::Log4perl qw(:easy);
10 my $conf = qq(
12 log4perl.category = WARN, Syncer
13 # File appender (unsynchronized)
15 log4perl.appender.Logfile = Log::Log4perl::Appender::File
16 log4perl.appender.Logfile.autoflush = 1
17 log4perl.appender.Logfile.filename = test.log
18 log4perl.appender.Logfile.mode = truncate
19 log4perl.appender.Logfile.layout = SimpleLayout
20 # Synchronizing appender, using the file appender above
22 log4perl.appender.Syncer = Log::Log4perl::Appender::Synchronized
23 log4perl.appender.Syncer.appender = Logfile
24 );
25 Log::Log4perl->init(\$conf);
27 WARN("This message is guaranteed to be complete.");
28
30 If multiple processes are using the same "Log::Log4perl" appender
31 without synchronization, overwrites might happen. A typical scenario
32 for this would be a process spawning children, each of which inherits
33 the parent's Log::Log4perl configuration.
34 In most cases, you won't need an external synchronisation tool like
36 Log::Log4perl::Appender::Synchronized at all. Log4perl's file appender,
37 Log::Log4perl::Appender::File, for example, provides the "syswrite"
38 mechanism for making sure that even long log lines won't interleave.
39 Short log lines won't interleave anyway, because the operating system
40 makes sure the line gets written before a task switch occurs.
41 In cases where you need additional synchronization, however, you can
43 use "Log::Log4perl::Appender::Synchronized" as a gateway between your
44 loggers and your appenders. An appender itself,
45 "Log::Log4perl::Appender::Synchronized" just takes two additional
46 arguments:
47 "appender"
49 Specifies the name of the appender it synchronizes access to. The
50 appender specified must be defined somewhere in the configuration
51 file, not necessarily before the definition of
52 "Log::Log4perl::Appender::Synchronized".
53 "key"
55 This optional argument specifies the key for the semaphore that
56 "Log::Log4perl::Appender::Synchronized" uses internally to ensure
57 atomic operations. It defaults to "_l4p". If you define more than
58 one "Log::Log4perl::Appender::Synchronized" appender, it is
59 important to specify different keys for them, as otherwise every
60 new "Log::Log4perl::Appender::Synchronized" appender will nuke
61 previously defined semaphores. The maximum key length is four
62 characters, longer keys will be truncated to 4 characters --
63 "mylongkey1" and "mylongkey2" are interpreted to be the same:
64 "mylo" (thanks to David Viner <dviner@yahoo-inc.com> for pointing
65 this out).
66 "Log::Log4perl::Appender::Synchronized" uses
68 Log::Log4perl::Util::Semaphore internally to perform locking with
69 semaphores provided by the operating system used.
70 Performance tips
72 The "Log::Log4perl::Appender::Synchronized" serializes access to a
73 protected resource globally, slowing down actions otherwise performed
74 in parallel.
75 Unless specified otherwise, all instances of
77 "Log::Log4perl::Appender::Synchronized" objects in the system will use
78 the same global IPC key "_l4p".
79 To control access to different appender instances, it often makes sense
81 to define different keys for different synchronizing appenders. In this
82 way, Log::Log4perl serializes access to each appender instance
83 separately:
84 log4perl.category = WARN, Syncer1, Syncer2
86 # File appender 1 (unsynchronized)
88 log4perl.appender.Logfile1 = Log::Log4perl::Appender::File
89 log4perl.appender.Logfile1.filename = test1.log
90 log4perl.appender.Logfile1.layout = SimpleLayout
91 # File appender 2 (unsynchronized)
93 log4perl.appender.Logfile2 = Log::Log4perl::Appender::File
94 log4perl.appender.Logfile2.filename = test2.log
95 log4perl.appender.Logfile2.layout = SimpleLayout
96 # Synchronizing appender, using the file appender above
98 log4perl.appender.Syncer1 = Log::Log4perl::Appender::Synchronized
99 log4perl.appender.Syncer1.appender = Logfile1
100 log4perl.appender.Syncer1.key = l4p1
101 # Synchronizing appender, using the file appender above
103 log4perl.appender.Syncer2 = Log::Log4perl::Appender::Synchronized
104 log4perl.appender.Syncer2.appender = Logfile2
105 log4perl.appender.Syncer2.key = l4p2
106 Without the ".key = l4p1" and ".key = l4p2" lines, both Synchronized
108 appenders would be using the default "_l4p" key, causing unnecessary
109 serialization of output written to different files.
110 Advanced configuration
112 To configure the underlying Log::Log4perl::Util::Semaphore module in a
113 different way than with the default settings provided by
114 Log::Log4perl::Appender::Synchronized, use the following parameters:
115 log4perl.appender.Syncer1.destroy = 1
117 log4perl.appender.Syncer1.mode = sub { 0775 }
118 log4perl.appender.Syncer1.uid = hugo
119 log4perl.appender.Syncer1.gid = 100
120 Valid options are "destroy" (Remove the semaphore on exit), "mode"
122 (permissions on the semaphore), "uid" (uid or user name the semaphore
123 is owned by), and "gid" (group id the semaphore is owned by),
124 Note that "mode" is usually given in octal and therefore needs to be
126 specified as a perl sub {}, unless you want to calculate what 0755
127 means in decimal.
128 Changing ownership or group settings for a semaphore will obviously
130 only work if the current user ID owns the semaphore already or if the
131 current user is "root". The "destroy" option causes the current process
132 to destroy the semaphore on exit. Spawned children of the process won't
133 inherit this behavior.
134 Semaphore user and group IDs with mod_perl
136 Setting user and group IDs is especially important when the
137 Synchronized appender is used with mod_perl. If Log4perl gets
138 initialized by a startup handler, which runs as root, and not as the
139 user who will later use the semaphore, the settings for uid, gid, and
140 mode can help establish matching semaphore ownership and access rights.
141
143 "Log::Log4perl::Appender::Synchronized" is a composite appender.
144 Unlike other appenders, it doesn't log any messages, it just passes
145 them on to its attached sub-appender. For this reason, it doesn't need
146 a layout (contrary to regular appenders). If it defines none, messages
147 are passed on unaltered.
148 Custom filters are also applied to the composite appender only. They
150 are not applied to the sub-appender. Same applies to appender
151 thresholds. This behaviour might change in the future.
152
154 Copyright 2002-2013 by Mike Schilli <m@perlmeister.com> and Kevin Goess
155 <cpan@goess.org>.
156 This library is free software; you can redistribute it and/or modify it
158 under the same terms as Perl itself.
159
161 Please contribute patches to the project on Github:
162 http://github.com/mschilli/log4perl
164 Send bug reports or requests for enhancements to the authors via our
166 MAILING LIST (questions, bug reports, suggestions/patches):
168 log4perl-devel@lists.sourceforge.net
169 Authors (please contact them via the list above, not directly): Mike
171 Schilli <m@perlmeister.com>, Kevin Goess <cpan@goess.org>
172 Contributors (in alphabetical order): Ateeq Altaf, Cory Bennett, Jens
174 Berthold, Jeremy Bopp, Hutton Davidson, Chris R. Donnelly, Matisse
175 Enzer, Hugh Esco, Anthony Foiani, James FitzGibbon, Carl Franks, Dennis
176 Gregorovic, Andy Grundman, Paul Harrington, Alexander Hartmaier David
177 Hull, Robert Jacobson, Jason Kohles, Jeff Macdonald, Markus Peter,
178 Brett Rann, Peter Rabbitson, Erik Selberg, Aaron Straup Cope, Lars
179 Thegler, David Viner, Mac Yang.
180perl v5.36.0 2023-01-20 Appender::Synchronized(3)