.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "File::Write::Rotate 3pm" .TH File::Write::Rotate 3pm "2022-10-15" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" File::Write::Rotate \- Write to files that archive/rotate themselves .SH "VERSION" .IX Header "VERSION" This document describes version 0.321 of File::Write::Rotate (from Perl distribution File-Write-Rotate), released on 2019\-06\-27. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use File::Write::Rotate; \& \& my $fwr = File::Write::Rotate\->new( \& dir => \*(Aq/var/log\*(Aq, # required \& prefix => \*(Aqmyapp\*(Aq, # required \& #suffix => \*(Aq.log\*(Aq, # default is \*(Aq\*(Aq \& size => 25*1024*1024, # default is 10MB, unless period is set \& histories => 12, # default is 10 \& #buffer_size => 100, # default is none \& ); \& \& # write, will write to /var/log/myapp.log, automatically rotate old log files \& # to myapp.log.1 when myapp.log reaches 25MB. will keep old log files up to \& # myapp.log.12. \& $fwr\->write("This is a line\en"); \& $fwr\->write("This is", " another line\en"); .Ve .PP To compressing old log files: .PP .Vb 1 \& $fwr\->compress; .Ve .PP This is usually done in a separate process, because it potentially takes a long time if the files to compress are large; we are rotating automatically in \&\fBwrite()\fR so doing automatic compression too would annoyingly block writer for a potentially long time. .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module can be used to write to file, usually for logging, that can rotate itself. File will be opened in append mode. By default, locking will be done to avoid conflict when there are multiple writers. Rotation can be done by size (after a certain size is reached), by time (daily/monthly/yearly), or both. .PP I first wrote this module for logging script \s-1STDERR\s0 output to files (see Tie::Handle::FileWriteRotate). .SH "ATTRIBUTES" .IX Header "ATTRIBUTES" .SS "buffer_size => int" .IX Subsection "buffer_size => int" Get or set buffer size. If set to a value larger than 0, then when a \fBwrite()\fR failed, instead of dying, the message will be stored in an internal buffer first (a regular Perl array). When the number of items in the buffer exceeds this size, then \fBwrite()\fR will die upon failure. Otherwise, every \fBwrite()\fR will try to flush the buffer. .PP Can be used for example when a program runs as superuser/root then temporarily drops privilege to a normal user. During this period, logging can fail because the program cannot lock the lock file or write to the logging directory. Before dropping privilege, the program can set buffer_size to some larger-than-zero value to hold the messages emitted during dropping privilege. The next \fBwrite()\fR as the superuser/root will succeed and flush the buffer to disk (provided there is no other error condition, of course). .SS "path => str (ro)" .IX Subsection "path => str (ro)" Current file's path. .SS "handle => (ro)" .IX Subsection "handle => (ro)" Current file handle. You should not use this directly, but use \fBwrite()\fR instead. This attribute is provided for special circumstances (e.g. in hooks, see example in the hook section). .SS "hook_before_write => code" .IX Subsection "hook_before_write => code" Will be called by \fBwrite()\fR before actually writing to filehandle (but after locking is done). Code will be passed ($self, \e@msgs, \f(CW$fh\fR) where \f(CW@msgs\fR is an array of strings to be written (the contents of buffer, if any, plus arguments passed to \fBwrite()\fR) and \f(CW$fh\fR is the filehandle. .SS "hook_before_rotate => code" .IX Subsection "hook_before_rotate => code" Will be called by the rotating routine before actually doing rotating. Code will be passed ($self). .PP This can be used to write a footer to the end of each file, e.g.: .PP .Vb 4 \& # hook_before_rotate \& my ($self) = @_; \& my $fh = $self\->handle; \& print $fh "Some footer\en"; .Ve .PP Since this hook is indirectly called by \fBwrite()\fR, locking is already done. .SS "hook_after_rotate => code" .IX Subsection "hook_after_rotate => code" Will be called by the rotating routine after the rotating process. Code will be passed ($self, \e@renamed, \e@deleted) where \f(CW@renamed\fR is array of new filenames that have been renamed, \f(CW@deleted\fR is array of new filenames that have been deleted. .SS "hook_after_create => code" .IX Subsection "hook_after_create => code" Will be called by after a new file is created. Code will be passed ($self). .PP This hook can be used to write a header to each file, e.g.: .PP .Vb 4 \& # hook_after_create \& my ($self) = @_; \& my $fh $self\->handle; \& print $fh "header\en"; .Ve .PP Since this is called indirectly by \fBwrite()\fR, locking is also already done. .SS "binmode => str" .IX Subsection "binmode => str" If set to \*(L"1\*(R", will cause the file handle to be set: .PP .Vb 1 \& binmode $fh; .Ve .PP which might be necessary on some \s-1OS,\s0 e.g. Windows when writing binary data. Otherwise, other defined values will cause the file handle to be set: .PP .Vb 1 \& binmode $fh, $value .Ve .PP which can be used to set PerlIO layer(s). .SH "METHODS" .IX Header "METHODS" .ie n .SS "$obj = File::Write::Rotate\->new(%args)" .el .SS "\f(CW$obj\fP = File::Write::Rotate\->new(%args)" .IX Subsection "$obj = File::Write::Rotate->new(%args)" Create new object. Known arguments: .IP "\(bu" 4 dir => \s-1STR\s0 (required) .Sp Directory to put the files in. .IP "\(bu" 4 prefix => \s-1STR\s0 (required) .Sp Name of files. The files will be named like the following: .Sp .Vb 1 \& .Ve .Sp \&\f(CW\*(C`\*(C'\fR will only be given if the \f(CW\*(C`period\*(C'\fR argument is set. If \&\f(CW\*(C`period\*(C'\fR is set to \f(CW\*(C`yearly\*(C'\fR, \f(CW\*(C`\*(C'\fR will be \f(CW\*(C`YYYY\*(C'\fR (4\-digit year). If \f(CW\*(C`period\*(C'\fR is \f(CW\*(C`monthly\*(C'\fR, \f(CW\*(C`\*(C'\fR will be \f(CW\*(C`YYYY\-MM\*(C'\fR (4\-digit year and 2\-digit month). If \f(CW\*(C`period\*(C'\fR is \f(CW\*(C`daily\*(C'\fR, \f(CW\*(C`\*(C'\fR will be \f(CW\*(C`YYYY\-MM\-DD\*(C'\fR (4\-digit year, 2\-digit month, and 2\-digit day). .Sp \&\f(CW\*(C`\*(C'\fR is either empty string for current file; or \f(CW.1\fR, \f(CW.2\fR and so on for rotated files. \f(CW.1\fR is the most recent rotated file, \f(CW.2\fR is the next most recent, and so on. .Sp An example, with \f(CW\*(C`prefix\*(C'\fR set to \f(CW\*(C`myapp\*(C'\fR: .Sp .Vb 3 \& myapp # current file \& myapp.1 # most recently rotated \& myapp.2 # the next most recently rotated .Ve .Sp With \f(CW\*(C`prefix\*(C'\fR set to \f(CW\*(C`myapp\*(C'\fR, \f(CW\*(C`period\*(C'\fR set to \f(CW\*(C`monthly\*(C'\fR, \f(CW\*(C`suffix\*(C'\fR set to \&\f(CW\*(C`.log\*(C'\fR: .Sp .Vb 2 \& myapp.2012\-12.log # file name for december 2012 \& myapp.2013\-01.log # file name for january 2013 .Ve .Sp Like previous, but additionally with \f(CW\*(C`size\*(C'\fR also set (which will also rotate each period file if it exceeds specified size): .Sp .Vb 4 \& myapp.2012\-12.log # file(s) for december 2012 \& myapp.2012\-12.log.1 \& myapp.2012\-12.log.2 \& myapp.2013\-01.log # file(s) for january 2013 .Ve .Sp All times will use local time, so you probably want to set \f(CW\*(C`TZ\*(C'\fR environment variable or equivalent methods to set time zone. .IP "\(bu" 4 suffix => \s-1STR\s0 (default: '') .Sp Suffix to give to file names, usually file extension like \f(CW\*(C`.log\*(C'\fR. See \f(CW\*(C`prefix\*(C'\fR for more details. .Sp If you use a yearly period, setting suffix is advised to avoid ambiguity with rotate suffix (for example, is \f(CW\*(C`myapp.2012\*(C'\fR the current file for year 2012 or file with \f(CW2012\fR rotate suffix?) .IP "\(bu" 4 size => \s-1INT\s0 (default: 10*1024*1024) .Sp Maximum file size, in bytes, before rotation is triggered. The default is 10MB (10*1024*1024) \fIif\fR \f(CW\*(C`period\*(C'\fR is not set. If \f(CW\*(C`period\*(C'\fR is set, no default for \&\f(CW\*(C`size\*(C'\fR is provided, which means files will not be rotated for size (only for period). .IP "\(bu" 4 period => \s-1STR\s0 .Sp Can be set to either \f(CW\*(C`daily\*(C'\fR, \f(CW\*(C`monthly\*(C'\fR, or \f(CW\*(C`yearly\*(C'\fR. If set, will automatically rotate after period change. See \f(CW\*(C`prefix\*(C'\fR for more details. .IP "\(bu" 4 histories => \s-1INT\s0 (default: 10) .Sp Number of rotated files to keep. After the number of files exceeds this, the oldest one will be deleted. 0 means not to keep any history, 1 means to only keep \f(CW.1\fR file, and so on. .IP "\(bu" 4 buffer_size => \s-1INT\s0 (default: 0) .Sp Set initial value of buffer. See the \f(CW\*(C`buffer_size\*(C'\fR attribute for more information. .IP "\(bu" 4 lock_mode => \s-1STR\s0 (default: 'write') .Sp Can be set to either \f(CW\*(C`none\*(C'\fR, \f(CW\*(C`write\*(C'\fR, or \f(CW\*(C`exclusive\*(C'\fR. \f(CW\*(C`none\*(C'\fR disables locking and increases write performance, but should only be used when there is only one writer. \f(CW\*(C`write\*(C'\fR acquires and holds the lock for each write. \&\f(CW\*(C`exclusive\*(C'\fR acquires the lock at object creation and holds it until the the object is destroyed. .Sp Lock file is named \f(CW\*(C`\*(C'\fR\f(CW\*(C`.lck\*(C'\fR. Will wait for up to 1 minute to acquire lock, will die if failed to acquire lock. .IP "\(bu" 4 hook_before_write => \s-1CODE\s0 .IP "\(bu" 4 hook_before_rotate => \s-1CODE\s0 .IP "\(bu" 4 hook_after_rotate => \s-1CODE\s0 .IP "\(bu" 4 hook_after_create => \s-1CODE\s0 .Sp See \*(L"\s-1ATTRIBUTES\*(R"\s0. .IP "\(bu" 4 buffer_size => int .IP "\(bu" 4 rotate_probability => float (between 0 < x < 1) .Sp If set, instruct to only check for rotation under a certain probability, for example if value is set to 0.1 then will only check for rotation 10% of the time. .SS "lock_file_path => \s-1STR\s0" .IX Subsection "lock_file_path => STR" Returns a string representing the complete pathname to the lock file, based on \f(CW\*(C`dir\*(C'\fR and \f(CW\*(C`prefix\*(C'\fR attributes. .ie n .SS "$fwr\->write(@args)" .el .SS "\f(CW$fwr\fP\->write(@args)" .IX Subsection "$fwr->write(@args)" Write to file. Will automatically rotate file if period changes or file size exceeds specified limit. When rotating, will only keep a specified number of histories and delete the older ones. .PP Does not append newline so you'll have to do it yourself. .ie n .SS "$fwr\->compress" .el .SS "\f(CW$fwr\fP\->compress" .IX Subsection "$fwr->compress" Compress old rotated files and remove the uncompressed originals. Currently uses IO::Compress::Gzip to do the compression. Extension given to compressed file is \f(CW\*(C`.gz\*(C'\fR. .PP Will not lock writers, but will create \f(CW\*(C`\*(C'\fR\f(CW\*(C`\-compress.pid\*(C'\fR \s-1PID\s0 file to prevent multiple compression processes running and to signal the writers to postpone rotation. .PP After compression is finished, will remove the \s-1PID\s0 file, so rotation can be done again on the next \f(CW\*(C`write()\*(C'\fR if necessary. .SH "FAQ" .IX Header "FAQ" .SS "Why use autorotating file?" .IX Subsection "Why use autorotating file?" Mainly convenience and low maintenance. You no longer need a separate rotator process like the Unix \fBlogrotate\fR utility (which when accidentally disabled or misconfigured will cause your logs to stop being rotated and grow indefinitely). .SS "What is the downside of using \s-1FWR\s0 (and \s-1LDFR\s0)?" .IX Subsection "What is the downside of using FWR (and LDFR)?" Mainly (significant) performance overhead. At (almost) every \f(CW\*(C`write()\*(C'\fR, \s-1FWR\s0 needs to check file sizes and/or dates for rotation. Under default configuration (where \f(CW\*(C`lock_mode\*(C'\fR is \f(CW\*(C`write\*(C'\fR), it also performs locking on each \f(CW\*(C`write()\*(C'\fR to make it safe to use with multiple processes. Below is a casual benchmark to give a sense of the overhead, tested on my Core i5\-2400 3.1GHz desktop: .PP Writing lines in the size of ~ 200 bytes, raw writing to disk (\s-1SSD\s0) has the speed of around 3.4mil/s, while using \s-1FWR\s0 it goes down to around ~13k/s. Using \&\f(CW\*(C`lock_mode\*(C'\fR \f(CW\*(C`none\*(C'\fR or \f(CW\*(C`exclusive\*(C'\fR, the speed is ~52k/s. .PP However, this is not something you'll notice or need to worry about unless you're writing near that speed. .PP If you need more speed, you can try setting \f(CW\*(C`rotate_probability\*(C'\fR which will cause \s-1FWR\s0 to only check for rotation probabilistically, e.g. if you set this to 0.1 then checks will only be done in about 1 of 10 writes. This can significantly reduce the overhead and increase write speed several times (e.g. 5\-8 times), but understand that this will make the writes \*(L"overflow\*(R" a bit, e.g. file sizes will exceed for a bit if you do size-based rotation. More suitable if you only do size-based rotation since it is usually okay to exceed sizes for a bit. .SS "I want a filehandle instead of a File::Write::Rotate object!" .IX Subsection "I want a filehandle instead of a File::Write::Rotate object!" Use Tie::Handle::FileWriteRotate. .SH "HOMEPAGE" .IX Header "HOMEPAGE" Please visit the project's homepage at . .SH "SOURCE" .IX Header "SOURCE" Source repository is at . .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests on the bugtracker website .PP When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature. .SH "SEE ALSO" .IX Header "SEE ALSO" Log::Dispatch::FileRotate, which inspires this module. Differences between File::Write::Rotate (\s-1FWR\s0) and Log::Dispatch::FileRotate (\s-1LDFR\s0) are as follows: .IP "\(bu" 4 \&\s-1FWR\s0 is not part of the Log::Dispatch family. .Sp This makes \s-1FWR\s0 more general to use. .Sp For using together with Log::Dispatch/Log4perl, I have also written Log::Dispatch::FileWriteRotate which is a direct (although not a perfect drop-in) replacement for Log::Dispatch::FileRotate. .IP "\(bu" 4 Secondly, \s-1FWR\s0 does not use Date::Manip. .Sp Date::Manip is relatively large (loading Date::Manip 6.37 equals to loading 34 files and ~ 22k lines; while \s-1FWR\s0 itself is only < 1k lines!) .Sp As a consequence of this, \s-1FWR\s0 does not support DatePattern; instead, \s-1FWR\s0 replaces it with a simple daily/monthly/yearly period. .IP "\(bu" 4 And lastly, \s-1FWR\s0 supports compressing and rotating compressed old files. .Sp Using separate processes like the Unix \fBlogrotate\fR utility means having to deal with yet another race condition. \s-1FWR\s0 takes care of that for you (see the \&\fBcompress()\fR method). You also have the option to do file compression in the same script/process if you want, which is convenient. .PP There is no significant overhead difference between \s-1FWR\s0 and \s-1LDFR\s0 (\s-1FWR\s0 is slightly faster than \s-1LDFR\s0 on my testing). .PP Tie::Handle::FileWriteRotate and Log::Dispatch::FileWriteRotate, which use this module. .SH "AUTHOR" .IX Header "AUTHOR" perlancar .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2019, 2016, 2015, 2014, 2013, 2012 by perlancar@cpan.org. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.