Changeset 115

Show
Ignore:
Timestamp:
04/12/10 19:40:54 (9 years ago)
Author:
depesz
Message:

add and reformat existing docs

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved
  • trunk/omnipitr/lib/OmniPITR/Log.pm

    r87 r115  
    1414} 
    1515 
     16=head1 new() 
     17 
     18Constructor for logger class. 
     19 
     20Takes one argument: template (using %*, strftime variables). 
     21 
     22=cut 
     23 
    1624sub new { 
    1725    my $class = shift; 
     
    2937} 
    3038 
     39=head1 _log() 
     40 
     41Internal function, shouldn't be called from client code. 
     42 
     43Gets loglevel (assumed to be string), format, and list of values to 
     44fill-in in the format, using standard sprintf semantics. 
     45 
     46Each line (even in multiline log messages) is prefixed with 
     47metainformation (timestamp, pid, program name). 
     48 
     49In case reference is passed as one of args - it is dumped using 
     50Data::Dumper. 
     51 
     52Thanks to this this: 
     53 
     54    $object->_log('loglevel', '%s', $object); 
     55 
     56Will print dump of $object and not stuff like 'HASH(0xdeadbeef)'. 
     57 
     58For client-code open methods check L<log()>, L<error()> and L<fatal()>. 
     59 
     60=cut 
     61 
    3162sub _log { 
    3263    my $self = shift; 
    3364    my ( $level, $format, @args ) = @_; 
    3465 
    35     my $log_line_prefix = $self->get_log_line_prefix(); 
    36     my $fh              = $self->get_log_fh(); 
     66    my $log_line_prefix = $self->_get_log_line_prefix(); 
     67    my $fh              = $self->_get_log_fh(); 
    3768 
    3869    @args = map { ref $_ ? Dumper( $_ ) : $_ } @args; 
     
    5182} 
    5283 
     84=head1 log() 
     85 
     86Client code facing method, which calls internal L<_log()> method, giving 
     87'LOG' as loglevel, and passing rest of arguments without modifications. 
     88 
     89Example: 
     90 
     91    $logger->log( 'i = %u', $i ); 
     92 
     93=cut 
     94 
    5395sub log { 
    5496    my $self = shift; 
     
    5698} 
    5799 
     100=head1 error() 
     101 
     102Client code facing method, which calls internal L<_log()> method, giving 
     103'ERROR' as loglevel, and passing rest of arguments without 
     104modifications. 
     105 
     106Example: 
     107 
     108    $logger->error( 'File creation failed: %s', $OS_ERROR ); 
     109 
     110=cut 
     111 
    58112sub error { 
    59113    my $self = shift; 
    60114    return $self->_log( 'ERROR', @_ ); 
    61115} 
     116 
     117=head1 fatal() 
     118 
     119Client code facing method, which calls internal L<_log()> method, giving 
     120'FATAL' as loglevel, and passing rest of arguments without 
     121modifications. 
     122 
     123Additionally, after logging the message, it exits main program, setting 
     124error status 1. 
     125 
     126Example: 
     127 
     128    $logger->fatal( 'Called from user with uid = %u, and not 0!', $user_uid ); 
     129 
     130=cut 
    62131 
    63132sub fatal { 
     
    66135    exit( 1 ); 
    67136} 
     137 
     138=head1 time_start() 
     139 
     140Starts timer. 
     141 
     142Should be used together with time_finish, for example like this: 
     143 
     144    $logger->time_start( 'zipping' ); 
     145    $zip->run(); 
     146    $logger->time_finish( 'zipping' ); 
     147 
     148Arguments to time_start and time_finish should be the same to allow 
     149matching of events. 
     150 
     151=cut 
    68152 
    69153sub time_start { 
     
    73157    return; 
    74158} 
     159 
     160=head1 time_finish() 
     161 
     162Finished calculation of time for given block of code. 
     163 
     164Calling: 
     165 
     166    $logger->time_finish( 'Compressing with gzip' ); 
     167 
     168Will log line like this: 
     169 
     170    2010-04-09 00:08:35.148118 +0200 : 19713 : omnipitr-archive : LOG : Timer [Compressing with gzip] took: 0.351s 
     171 
     172Assuming related time_start() was called 0.351s earlier. 
     173 
     174=cut 
    75175 
    76176sub time_finish { 
     
    82182} 
    83183 
    84 sub get_log_line_prefix { 
     184=head1 _get_log_line_prefix() 
     185 
     186Internal method generating line prefix, which is prepended to every 
     187logged line of text. 
     188 
     189Prefix contains ( " : " separated ): 
     190 
     191=over 
     192 
     193=item * Timestamp, with microsecond precision 
     194 
     195=item * Process ID (PID) of logging program 
     196 
     197=item * Name of program that logged the message 
     198 
     199=back 
     200 
     201=cut 
     202 
     203sub _get_log_line_prefix { 
    85204    my $self         = shift; 
    86205    my $time         = time(); 
     
    93212} 
    94213 
    95 sub get_log_fh { 
     214=head1 _get_log_fh() 
     215 
     216Internal method handling logic to close and open logfiles when 
     217necessary, based of given logfile template, current time, and when 
     218previous logline was logged. 
     219 
     220At any given moment only 1 filehandle will be opened, and it will be 
     221closed, and reopened, when time changes in such way that it would 
     222require another filename. 
     223 
     224=cut 
     225 
     226sub _get_log_fh { 
    96227    my $self = shift; 
    97228 
  • trunk/omnipitr/lib/OmniPITR/Program.pm

    r114 r115  
    66use Proc::Pidfile; 
    77use Carp; 
     8 
     9=head1 new() 
     10 
     11Object contstructor. 
     12 
     13Since all OmniPITR programs are based on object, and they start with 
     14doing the same things (namely reading and validating command line 
     15arguments) - this is wrapped in here, to avoid code duplication. 
     16 
     17Constructor also handles pid file creation, in case it was requested. 
     18 
     19=cut 
    820 
    921sub new { 
     
    1729} 
    1830 
     31=head1 run() 
     32 
     33Just a stub method, that has to be overriden in subclasses. 
     34 
     35=cut 
     36 
    1937sub run { 
    2038    my $self = shift; 
     
    2240} 
    2341 
    24 # Shortcuts 
     42=head1 verbose() 
     43 
     44Shortcut to make code a bit nicer. 
     45 
     46Returns values of (command line given) verbose switch. 
     47 
     48=cut 
     49 
    2550sub verbose { return shift->{ 'verbose' }; } 
    26 sub log     { return shift->{ 'log' }; } 
     51 
     52=head1 log() 
     53 
     54Shortcut to make code a bit nicer. 
     55 
     56Returns logger object. 
     57 
     58=cut 
     59 
     60sub log { return shift->{ 'log' }; } 
    2761 
    28621; 
  • trunk/omnipitr/lib/OmniPITR/Program/Restore.pm

    r113 r115  
    1919=head1 run() 
    2020 
    21 Main function, called by actual script in bin/, wraps all work done by script with the sole exception of reading and validating command line arguments. 
    22  
    23 These tasks (reading and validating arguments) are in this module, but they are called from L<OmniPITR::Program::new()> 
    24  
    25 Name of called method should be self explanatory, and if you need further information - simply check doc for the method you have questions about. 
     21Main function, called by actual script in bin/, wraps all work done by 
     22script with the sole exception of reading and validating command line 
     23arguments. 
     24 
     25These tasks (reading and validating arguments) are in this module, but 
     26they are called from L<OmniPITR::Program::new()> 
     27 
     28Name of called method should be self explanatory, and if you need 
     29further information - simply check doc for the method you have questions 
     30about. 
    2631 
    2732=cut 
     
    4449    } 
    4550} 
     51 
     52=head1 do_some_removal() 
     53 
     54Wraps all work necessary to remove obsolete WAL segments from archive. 
     55 
     56Contains actual I<unlink> calls, but all other work (checking 
     57pg_controldata, extracting last REDO segment, getting list of files to 
     58remove, calling pre-removal hook) is delegated to dedicated methods. 
     59 
     60=cut 
    4661 
    4762sub do_some_removal { 
     
    8297} 
    8398 
     99=head1 handle_pre_removal_processing() 
     100 
     101Before removing obsolete WAL segment, I<omnipitr-restore> can call 
     102arbitrary program to do whatever is necessary - for example - to send 
     103the WAL segment to backup server. 
     104 
     105This is done in here. Each segment is first uncompressed to temporary 
     106directory, and then given program is called. 
     107 
     108Temporary directory is always made so that it "looks" like it was called 
     109by archive-command from PostgreSQL, i.e.: 
     110 
     111=over 
     112 
     113=item * Current directory contains pg_xlog directory 
     114 
     115=item * Segment is unpacked 
     116 
     117=item * Segment is in pg_xlog directory 
     118 
     119=item * Handler program is called with segment name like 
     120'pg_xlog/000000010000000500000073' 
     121 
     122=back 
     123 
     124=cut 
     125 
    84126sub handle_pre_removal_processing { 
    85127    my $self         = shift; 
     
    122164    return; 
    123165} 
     166 
     167=head1 get_list_of_segments_to_remove() 
     168 
     169Scans source directory, and returns names of all files, which are 
     170"older" than last required segment (REDO segment from pg_controldata). 
     171 
     172Older - is defined as alphabetically smaller than REDO segment. 
     173 
     174Returns at most X files, where X is defined by --remove-at-a-time 
     175command line option. 
     176 
     177=cut 
    124178 
    125179sub get_list_of_segments_to_remove { 
     
    154208} 
    155209 
     210=head1 get_last_redo_segment() 
     211 
     212Based on information from pg_controldata, returns name of file that 
     213contains oldest file required in case recovery would have to be 
     214restarted. 
     215 
     216This is required to be able to tell which files can be safely removed 
     217from archive. 
     218 
     219=cut 
     220 
    156221sub get_last_redo_segment { 
    157222    my $self = shift; 
     
    169234    return $segment_filename; 
    170235} 
     236 
     237=head1 get_control_data() 
     238 
     239Calls pg_controldata, and parses its output. 
     240 
     241Verifies that output contains 2 critical pieces of information: 
     242 
     243=over 
     244 
     245=item * Latest checkpoint's REDO location 
     246 
     247=item * Latest checkpoint's TimeLineID 
     248 
     249=back 
     250 
     251=cut 
    171252 
    172253sub get_control_data { 
     
    203284    return $control_data; 
    204285} 
     286 
     287=head1 try_to_restore_and_exit() 
     288 
     289Checks if requested wal segment exists, and is ready to be restored ( 
     290vide --recovery-delay option). 
     291 
     292Handles also situations where there is finish request (both immediate 
     293and smart). 
     294 
     295If recovery worked - finished with status 0. 
     296 
     297If no file can be returned yet - goes back to main loop in L<run()> 
     298method. 
     299 
     300=cut 
    205301 
    206302sub try_to_restore_and_exit { 
     
    256352} 
    257353 
     354=head1 copy_segment_to() 
     355 
     356Helper function which deals with copying segment from archive to given 
     357destination, handling compression when necessary. 
     358 
     359=cut 
     360 
    258361sub copy_segment_to { 
    259362    my $self = shift; 
     
    280383    return; 
    281384} 
     385 
     386=head1 check_for_trigger_file() 
     387 
     388Checks existence and possibly content of finish-trigger file, setting 
     389appropriate flags. 
     390 
     391=cut 
    282392 
    283393sub check_for_trigger_file { 
     
    337447=head1 read_args() 
    338448 
    339 Function which does all the parsing, and transformation of command line arguments. 
    340  
    341 It also verified base facts about passed WAL segment name, but all other validations, are being done in separate function: L<validate_args()>. 
     449Function which does all the parsing, and transformation of command line 
     450arguments. 
     451 
     452It also verified base facts about passed WAL segment name, but all other 
     453validations, are being done in separate function: L<validate_args()>. 
     454 
     455=cut 
     456 
     457=head1 read_args() 
    342458 
    343459=cut 
     
    415531Does all necessary validation of given command line arguments. 
    416532 
    417 One exception is for compression programs paths - technically, it could be validated in here, but benefit would be pretty limited, and code to do so relatively complex, as compression program path 
    418 might, but doesn't have to be actual file path - it might be just program name (without path), which is the default. 
     533One exception is for compression programs paths - technically, it could 
     534be validated in here, but benefit would be pretty limited, and code to 
     535do so relatively complex, as compression program path might, but doesn't 
     536have to be actual file path - it might be just program name (without 
     537path), which is the default. 
    419538 
    420539=cut 
  • trunk/omnipitr/lib/OmniPITR/Tools.pm

    r87 r115  
    1111our %EXPORT_TAGS = ( 'all' => \@EXPORT_OK ); 
    1212 
     13=head1 ext_for_compression() 
     14 
     15Simple function returning file extension for given compression schema. 
     16 
     17It could be easily handled with hash, but I decided to use function, to 
     18have explicit die/croak in case of bad compression type. 
     19 
     20=cut 
     21 
    1322sub ext_for_compression { 
    1423    my $compression = lc shift; 
     
    1827    croak 'Unknown compression type: ' . $compression; 
    1928} 
     29 
     30=head1 file_md5sum() 
     31 
     32Wrapper around Digest::MD5 to calculate md5 sum of file. 
     33 
     34Returned checksum is hex encoded - like output of I<md5sum> program. 
     35 
     36=cut 
    2037 
    2138sub file_md5sum { 
     
    3148    return $md5; 
    3249} 
     50 
     51=head1 run_command() 
     52 
     53Runs given program, adding proper escapes of values, and gets stdout and 
     54stderr of it. 
     55 
     56Returns hashref which contains: 
     57 
     58=over 
     59 
     60=item * stderr - stringified stderr output from program 
     61 
     62=item * stdout - stringified stdout output from program 
     63 
     64=item * status - return value of system() call 
     65 
     66=item * error_code - undef in case there was no error, or stringified 
     67error information 
     68 
     69=back 
     70 
     71=cut 
    3372 
    3473sub run_command {