| 1 | package RRD::Query; | ||
| 2 | |||
| 3 | use strict; | ||
| 4 | use RRDs; | ||
| 5 | use Error qw(:try); | ||
| 6 | |||
| 7 | require Exporter; | ||
| 8 | @RRD::Query::ISA = qw(Exporter); | ||
| 9 | @RRD::Query::EXPORT_OK = qw(isNaN); | ||
| 10 | |||
| 11 | # $Id: Query.pm,v 1.15 2005/02/28 17:37:12 rs Exp $ | ||
| 12 | $RRD::Query::VERSION = sprintf "%d.%03d", q$Revision: 1.15 $ =~ /(\d+)/g; | ||
| 13 | |||
| 14 | =pod | ||
| 15 | |||
| 16 | =head1 NAME | ||
| 17 | |||
| 18 | RRD::Query - Perform queries on RRD file | ||
| 19 | |||
| 20 | =head1 DESCRIPTION | ||
| 21 | |||
| 22 | Simple wrapper around RRDs library to do some simple queries. It | ||
| 23 | implemented more advanced error handling by using the Error module. | ||
| 24 | |||
| 25 | =head1 CONSTRUCTOR | ||
| 26 | |||
| 27 | my $rq = new RRD::Query("/path/to/file.rrd"); | ||
| 28 | |||
| 29 | =cut | ||
| 30 | |||
| 31 | sub new | ||
| 32 | { | ||
| 33 | my $proto = shift; | ||
| 34 | my $class = ref($proto) || $proto; | ||
| 35 | my $self = bless({}, $class); | ||
| 36 | $self->{file} = shift; | ||
| 37 | return $self; | ||
| 38 | } | ||
| 39 | |||
| 40 | =pod | ||
| 41 | |||
| 42 | =head1 METHODS | ||
| 43 | |||
| 44 | |||
| 45 | =pod | ||
| 46 | |||
| 47 | =head2 list | ||
| 48 | |||
| 49 | @datasources = list(); | ||
| 50 | |||
| 51 | Return the list of all datasource of the given file | ||
| 52 | |||
| 53 | Throws: | ||
| 54 | |||
| 55 | Error::RRDs - on RRDs library error | ||
| 56 | |||
| 57 | =cut | ||
| 58 | |||
| 59 | sub list | ||
| 60 | { | ||
| 61 | my($self) = @_; | ||
| 62 | |||
| 63 | my $info = RRDs::info($self->{file}); | ||
| 64 | if(RRDs::error()) | ||
| 65 | { | ||
| 66 | throw Error::RRDs("Can't get RRD info: " . RRDs::error()); | ||
| 67 | } | ||
| 68 | |||
| 69 | my %ds; | ||
| 70 | for my $key (keys %$info) | ||
| 71 | { | ||
| 72 | if(index($key, 'ds[') == 0) | ||
| 73 | { | ||
| 74 | $ds{substr($key, 3, index($key, ']') - 3)} = undef; | ||
| 75 | } | ||
| 76 | } | ||
| 77 | |||
| 78 | return([sort keys %ds]); | ||
| 79 | } | ||
| 80 | |||
| 81 | =head2 fetch | ||
| 82 | |||
| 83 | ($value) = fetch($ds, cf => $cf, offset => $offset) | ||
| 84 | |||
| 85 | Fetch a single value from the datasource $ds of RRD file. If $offset | ||
| 86 | is omitted, the last inserted value is returned, otherwise the last | ||
| 87 | value - $offset is returned. If $cf (consolidation function) is | ||
| 88 | omited, AVERAGE is used. | ||
| 89 | |||
| 90 | =head3 Options | ||
| 91 | |||
| 92 | =over 4 | ||
| 93 | |||
| 94 | =item ds | ||
| 95 | |||
| 96 | Datasource you want to fetch. If the datasource contains comat (,), | ||
| 97 | your datasource will be interpreted as an RPN (Reverse Polish | ||
| 98 | Notation) expression (see L<Math::RPN>). If the C<Math::RPN> module | ||
| 99 | isn't loadable, an C<Error::RRD::Feature> exception is thrown. | ||
| 100 | |||
| 101 | Some valide examples of datasource would be: C<ifError>, | ||
| 102 | C<high_mem,low_mem,+>. | ||
| 103 | |||
| 104 | =item cf | ||
| 105 | |||
| 106 | Consolidation function name you want to fetch. If omited, the AVERAGE | ||
| 107 | consolidation function is used. | ||
| 108 | |||
| 109 | =item offset | ||
| 110 | |||
| 111 | Time offset to go back in the past from the last inserted value time. | ||
| 112 | |||
| 113 | =back | ||
| 114 | |||
| 115 | =head3 Throws | ||
| 116 | |||
| 117 | =over 4 | ||
| 118 | |||
| 119 | =item Error::RRDs | ||
| 120 | |||
| 121 | on RRDs library error | ||
| 122 | |||
| 123 | =item Error::RRD::NoSuchDS | ||
| 124 | |||
| 125 | if datasource can't be found in RRD file | ||
| 126 | |||
| 127 | =item Error::RPN::Feature | ||
| 128 | |||
| 129 | if you try to use an RPN DS without Math::RPN installed | ||
| 130 | |||
| 131 | =back | ||
| 132 | |||
| 133 | =cut | ||
| 134 | |||
| 135 | sub fetch | ||
| 136 | { | ||
| 137 | my($self, $ds, %args) = @_; | ||
| 138 | |||
| 139 | $args{offset} ||= 0; | ||
| 140 | $args{cf} ||= 'AVERAGE'; | ||
| 141 | |||
| 142 | # treat RPN DS (ie: ds1,ds2,-) | ||
| 143 | if(index($ds, ',') != -1) | ||
| 144 | { | ||
| 145 | $self->_needs_rpn(); | ||
| 146 | my @rpn = split(/,/, $ds); | ||
| 147 | my %ds; | ||
| 148 | @ds{@{$self->list()}} = undef; | ||
| 149 | for my $item (@rpn) | ||
| 150 | { | ||
| 151 | if(exists($ds{$item})) | ||
| 152 | { | ||
| 153 | # substitute variables by their value | ||
| 154 | $item = $self->fetch($item, %args); | ||
| 155 | if(isNaN($item)) | ||
| 156 | { | ||
| 157 | $item = 'NaN'; | ||
| 158 | } | ||
| 159 | } | ||
| 160 | } | ||
| 161 | return(scalar Math::RPN::rpn(join(',', @rpn))); | ||
| 162 | } | ||
| 163 | |||
| 164 | # compute the time of the last value | ||
| 165 | my $info = $self->info(); | ||
| 166 | my $rra_step = $info->{step} * $info->{'rra[0].pdp_per_row'}; | ||
| 167 | my $endtime = $info->{last_update} - ($info->{last_update} % $rra_step); | ||
| 168 | |||
| 169 | my($start, $step, $names, $data) = RRDs::fetch | ||
| 170 | ( | ||
| 171 | $self->{file}, | ||
| 172 | $args{cf}, | ||
| 173 | '--start' => 'end-'.$info->{step}, | ||
| 174 | '--end' => $endtime.'-'.$args{offset}, | ||
| 175 | ); | ||
| 176 | if(RRDs::error()) | ||
| 177 | { | ||
| 178 | throw Error::RRDs("Can't export data: " . RRDs::error(), | ||
| 179 | -object => 'RRDs'); | ||
| 180 | } | ||
| 181 | |||
| 182 | # get DS id | ||
| 183 | my $value; | ||
| 184 | my $found = 0; | ||
| 185 | for(my $i = 0; $i < @$names; $i++) | ||
| 186 | { | ||
| 187 | if($names->[$i] eq $ds) | ||
| 188 | { | ||
| 189 | $found = 1; | ||
| 190 | $value = $data->[-1]->[$i]; | ||
| 191 | last; | ||
| 192 | } | ||
| 193 | } | ||
| 194 | |||
| 195 | if(!$found) | ||
| 196 | { | ||
| 197 | throw Error::RRD::NoSuchDS("Can't find datasource in RRD: ".$ds); | ||
| 198 | } | ||
| 199 | |||
| 200 | return $value; | ||
| 201 | } | ||
| 202 | |||
| 203 | =pod | ||
| 204 | |||
| 205 | =head2 get_last | ||
| 206 | |||
| 207 | $timestamp = get_last() | ||
| 208 | |||
| 209 | Returns the timestamp of the inserted value of the RRD file. | ||
| 210 | |||
| 211 | =head3 Throws | ||
| 212 | |||
| 213 | =over 4 | ||
| 214 | |||
| 215 | =item Error::RRDs | ||
| 216 | |||
| 217 | on RRDs library error | ||
| 218 | |||
| 219 | =cut | ||
| 220 | |||
| 221 | sub last {get_last(@_)} | ||
| 222 | sub get_last | ||
| 223 | { | ||
| 224 | my($self) = @_; | ||
| 225 | |||
| 226 | return $self->info()->{last_update}; | ||
| 227 | } | ||
| 228 | |||
| 229 | sub info | ||
| 230 | { | ||
| 231 | my($self) = @_; | ||
| 232 | |||
| 233 | my $mtime = (stat($self->{file}))[9]; | ||
| 234 | if(!defined $self->{info_ts} || $self->{info_ts} != $mtime) | ||
| 235 | { | ||
| 236 | $self->{info} = RRDs::info($self->{file}); | ||
| 237 | if(RRDs::error()) | ||
| 238 | { | ||
| 239 | throw Error::RRDs("Can't get info: " . RRDs::error(), | ||
| 240 | -object => 'RRDs'); | ||
| 241 | } | ||
| 242 | $self->{info_ts} = $mtime; | ||
| 243 | } | ||
| 244 | |||
| 245 | return $self->{info}; | ||
| 246 | } | ||
| 247 | |||
| 248 | =pod | ||
| 249 | |||
| 250 | =head1 EXPORTS | ||
| 251 | |||
| 252 | =head2 isNaN | ||
| 253 | |||
| 254 | $bool = isNaN($value); | ||
| 255 | |||
| 256 | Returns true if the value is Not a Number. | ||
| 257 | |||
| 258 | =cut | ||
| 259 | |||
| 260 | sub isNaN | ||
| 261 | { | ||
| 262 | my($value) = @_; | ||
| 263 | return !defined $value || $value eq 'NaN'; | ||
| 264 | } | ||
| 265 | |||
| 266 | sub _needs_rpn | ||
| 267 | { | ||
| 268 | try | ||
| 269 | { | ||
| 270 | require Math::RPN; | ||
| 271 | } | ||
| 272 | otherwise | ||
| 273 | { | ||
| 274 | throw Error::RRD::Feature("Can't load Math::RPN", -object => 'Math::RPN'); | ||
| 275 | }; | ||
| 276 | } | ||
| 277 | |||
| 278 | =pod | ||
| 279 | |||
| 280 | =head1 EXCEPTION CLASSES | ||
| 281 | |||
| 282 | =head2 Error::RRDs | ||
| 283 | |||
| 284 | =cut | ||
| 285 | |||
| 286 | package Error::RRDs; | ||
| 287 | |||
| 288 | use base qw(Error::Simple); | ||
| 289 | |||
| 290 | =pod | ||
| 291 | |||
| 292 | =head2 Error::RRD::NoSuchDS | ||
| 293 | |||
| 294 | =cut | ||
| 295 | |||
| 296 | package Error::RRD::NoSuchDS; | ||
| 297 | |||
| 298 | use base qw(Error::Simple); | ||
| 299 | |||
| 300 | =pod | ||
| 301 | |||
| 302 | =head2 Error::RRD::isNaN | ||
| 303 | |||
| 304 | =cut | ||
| 305 | |||
| 306 | package Error::RRD::isNaN; | ||
| 307 | |||
| 308 | use base qw(Error::Simple); | ||
| 309 | |||
| 310 | =pod | ||
| 311 | |||
| 312 | =head2 Error::RRD::Feature | ||
| 313 | |||
| 314 | =cut | ||
| 315 | |||
| 316 | package Error::RRD::Feature; | ||
| 317 | |||
| 318 | use base qw(Error::Simple); | ||
| 319 | |||
| 320 | =pod | ||
| 321 | |||
| 322 | =head1 AUTHOR | ||
| 323 | |||
| 324 | Olivier Poitrey E<lt>rs@rhapsodyk.netE<gt> | ||
| 325 | |||
| 326 | =head1 LICENCE | ||
| 327 | |||
| 328 | RRD::Query, performs queries on RRD files. | ||
| 329 | Copyright (C) 2004 Olivier Poitrey | ||
| 330 | |||
| 331 | This library is free software; you can redistribute it and/or modify | ||
| 332 | it under the terms of the GNU Lesser General Public License as | ||
| 333 | published by the Free Software Foundation; either version 2.1 of the | ||
| 334 | License, or (at your option) any later version. | ||
| 335 | |||
| 336 | This library is distributed in the hope that it will be useful, but | ||
| 337 | WITHOUT ANY WARRANTY; without even the implied warranty of | ||
| 338 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
| 339 | Lesser General Public License for more details. | ||
| 340 | |||
| 341 | You should have received a copy of the GNU Lesser General Public | ||
| 342 | License along with this library; if not, write to the Free Software | ||
| 343 | Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 | ||
| 344 | USA | ||
| 345 | |||
| 346 | =head1 SEE ALSO | ||
| 347 | |||
| 348 | L<RRDs>, L<Error> | ||
| 349 | |||
| 350 | =cut | ||
| 351 | |||
| 352 | 1; |