# cpanel - Cpanel/BandwidthDB.pod Copyright(c) 2009 cPanel, Inc. # All rights Reserved. # copyright@cpanel.net http://cpanel.net # This code is subject to the cPanel license. Unauthorized copying is prohibited =head1 NAME Cpanel::BandwidthDB - Encapsulate the files we use to store long-term bandwidth information. =head1 SYNOPSIS use Cpanel::BandwidthDB; my $bwdb = Cpanel::BandwidthDB->new({ name=>'example.com', dir=>'/var/cpanel/bandwidth' }); my %usage = $bwdb->get_month_usage_for_type( 2009, 1, 'http' ); print 'Total: ', $bwdb->total_month_usage_for_type( 2009, 1, 'http' ); foreach my $update ( $bwdb->get_updates_list( 'daily', 'all' ) ) { print scalar localtime $update->[0], ': ', $update->[1], "\n"; } $bwdb->update( 'http', time, 1024 ); $bwdb->write(); =head1 DESCRIPTION The Cpanel::BandwidthDB module serves as an interface to the bandwidth summary text files. This encapsulates all of the code needed to access or modify these files. This saves other code from needing to know how to parse the format of these files. There are three resolutions of data stored in the summary files: =over 4 =item daily This is consistent with the old summary file format. It is maintained to support reading the older format. It also supports keeping new data in this format for any programs that depend on the older format. For newer usages, the I file is more useful. =item hourly This file stores hourly data as far back as we have it. It contains a historical record that can be used to recreate the long-term RRD file if necessary. =item 5min This file stores high-resolution (5 minute) data for about a month. It is not expected to be kept indefinitely. However, it does serve as a backup for the most recent RRD database. =back This module keeps the files consistent and allows relatively easy access to the data in those files. =head1 INTERFACE =head2 CPanel::BandwidthDB->new( $args_hr ) Creates a new database object. The argument hash ref contains the following named parameters: =over 4 =item name Required argument specifying the base name of the bandwidth database files, normally a domain or user name. =item uid Optional argument specifying the owner id for the bandwidth files if they need to be created. Defaults to 0. =item gid Optional argument specifying the group id for the bandwidth files if they need to be created. Defaults to 0. =item dir Optional argument specifying the directory in which to find/create the bandwidth database files. It should exist and be read/writable by the current user. The default value is F. =item cachedir Optional argument specifying the directory in which to find/create the bandwidth cache files. It should exist and be read/writable by the current user. The default value is the C parameter with an appended I<.cache>. =back =head2 $bwdb->update( $type, $time, $bytes ) Add a time series entry to the database. The data will automatically be aggregated into the correct time buckets. The parameters are all required: =over 4 =item C<$type> The type of bandwidth we need to track: usually one of imap, http, ftp, pop3, or smtp. The I value is also updated accordingly. =item C<$time> The time in epoch seconds for the update. =item C<$bytes> The number of bytes for this update. =back =head2 $bwdb->write( $force ) Write the current data to disk. The data is not written if the in-memory copy has not been changed. The optional C<$force> parameter causes us to write even if the data is not marked as updated. =head2 $bwdb->write_as( $name, $dir ) Write the current data to disk in the files specified by supplied C<$name> and C<$dir>. Unlike the C method, the data is always written even if it has not changed. The C<$name> parameter is required. If the C<$dir> parameter is not supplied, it defaults to the directory supplied when the C was created. =head2 $bwdb->bw_add( $odb ) Add all of the bandwidth data from the supplied C (C<$odb>) object to this C object on a day-by-day basis. =head2 $bwdb->bw_equal( $odb ) Return a true value if the supplied C (C<$odb>) has exactly the same bandwidth data as this C object. All days are compared. Returns false if any day has different bandwidth, or if one C has data on a day that the other does not. =head2 $bwdb->bw_clear() Clear all data from the C object. =head2 $bwdb->bw_partial_clear( @types ) Clear all data from the C object relating to the specified types. The 'all' summary type is always corrected for whatever data is removed. =head2 $bwdb->get_month_usage( $year, $month ) Extract the monthly usage from the database. Returns a 2D hash containing the data for the month, indexed by day, then type. =head2 $bwdb->get_day_usage_for_type( $year, $month, $day, $type ) Extract the day usage from the database for the supplied C<$type>. Returns the total usage for that type for the spaecified day as an integer. =head2 $bwdb->get_month_usage_for_type( $year, $month, $type ) Extract the monthly usage from the database for the supplied C<$type>. Returns a hash containing the data for the month, indexed by day. =head2 $bwdb->get_gid() Retrieves the group id associated with the bandwidth db files. =head2 $bwdb->get_types() List the types that this database is aware of. =head2 $bwdb->get_updates_list( $key, $type ) Returns a list of arrayrefs with the updates for the specified C<$key> and C<$type>. Each arrayref has two items: epoch time, and value of the update. The C<$key> specifies the resolution and is one of: I, I, or I<5min>. The C<$type> specifies the type of bandwidth and is one of: I, I, I, I, I, or I. =head2 $bwdb->total_month_usage_for_type( $year, $month, $type ) Calculate the total usage for the specified $type in the $month and $year specified. =head2 $bwdb->has_flag( $flag_name ) Returns true if the named flag exists in the C. The flag name cannot be empty or start with a digit. =head2 $bwdb->set_flag( $flag_name ) Set the named flag on the C. The flag name cannot be empty or start with a digit. =head2 $bwdb->remove_flag( $flag_name ) Remove the named flag from the C. The flag name cannot be empty or start with a digit. =head1 DIAGNOSTICS =item C<< Parameter to new must be a hash ref. >> The C method expects named parameters in a hash reference. =item C<< Missing required name parameter >> The C method was called with no I parameter. =item C<< No name was specified for write_as. >> The C module requires a filename to write. =item C<< Unrecognized type '%s'. >> The update method was called with an unrecognized type parameter. Known types are http, ftp, imap, pop3, and smtp. =item C<< The 'all' type is handled automatically, no need to update it. >> Don't try to update the I type. =item C<< Missing required parameter '%s' >> The required parameter was missing in a call to the C method. =item C<< Unrecognized key type '%s' >> The required parameter was missing in a call to the C method. Known key types are 5min, hourly, and daily. =item C<< Unrecognized type '%s' >> The required parameter was missing in a call to the C method. Known types are http, ftp, imap, pop3, smtp, and all. =back =head1 CONFIGURATION AND ENVIRONMENT Cpanel::BandwidthDB requires no configuration files or environment variables. =head1 DEPENDENCIES L, L, and L. =head1 INCOMPATIBILITIES None reported. =head1 BUGS AND LIMITATIONS No bugs have been reported. =head1 AUTHOR G. Wade Johnson C<< wade@cpanel.net >> =head1 LICENCE AND COPYRIGHT Copyright (c) 2009, cPanel, Inc. All rights reserved. This code is subject to the cPanel license. Unauthorized copying is prohibited