contrib/collection3/lib/Collectd/Graph/Type.pm

   1 package Collectd::Graph::Type;
   2
   3 =head1 NAME
   4
   5 Collectd::Graph::Type - Base class for the collectd graphing infrastructure
   6
   7 =cut
   8
   9 # Copyright (C) 2008  Florian octo Forster <octo at verplant.org>
  10 #
  11 # This program is free software; you can redistribute it and/or modify it under
  12 # the terms of the GNU General Public License as published by the Free Software
  13 # Foundation; only version 2 of the License is applicable.
  14 #
  15 # This program is distributed in the hope that it will be useful, but WITHOUT
  16 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  17 # FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
  18 # details.
  19 #
  20 # You should have received a copy of the GNU General Public License along with
  21 # this program; if not, write to the Free Software Foundation, Inc.,
  22 # 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  23
  24 use strict;
  25 use warnings;
  26
  27 use Carp (qw(confess cluck));
  28 use RRDs ();
  29 use URI::Escape (qw(uri_escape));
  30
  31 use Collectd::Graph::Common (qw($ColorCanvas $ColorFullBlue $ColorHalfBlue
  32   ident_to_filename
  33   ident_to_string
  34   get_faded_color));
  35
  36 return (1);
  37
  38 =head1 DESCRIPTION
  39
  40 This module serves as base class for more specialized classes realizing
  41 specific "types".
  42
  43 =head1 MEMBER VARIABLES
  44
  45 As typical in Perl, a Collectd::Graph::Type object is a blessed hash reference.
  46 Member variables are entries in that hash. Inheriting classes are free to add
  47 additional entries. To set the member variable B<foo> to B<42>, do:
  48
  49  $obj->{'foo'} = 42;
  50
  51 The following members control the behavior of Collectd::Graph::Type.
  52
  53 =over 4
  54
  55 =item B<files> (array reference)
  56
  57 List of RRD files. Each file is passed as "ident", i.E<nbsp>e. broken up into
  58 "hostname", "plugin", "type" and optionally "plugin_instance" and
  59 "type_instance". Use the B<addFiles> method rather than setting this directly.
  60
  61 =item B<data_sources> (array reference)
  62
  63 List of data sources in the RRD files. If this is not given, the default
  64 implementation of B<getDataSources> will use B<RRDs::info> to find out which
  65 data sources are contained in the files.
  66
  67 =item B<ds_names> (array reference)
  68
  69 Names of the data sources as printed in the graph. Should be in the same order
  70 as the data sources are returned by B<getDataSources>.
  71
  72 =item B<rrd_title> (string)
  73
  74 Title of the RRD graph. The title can contain "{hostname}", "{plugin}" and so
  75 on which are replaced with their actual value. See the B<getTitle> method
  76 below.
  77
  78 =item B<rrd_opts> (array reference)
  79
  80 List of options directly passed to B<RRDs::graph>.
  81
  82 =item B<rrd_format> (string)
  83
  84 Format to use with B<GPRINT>. Defaults to C<%5.1lf>.
  85
  86 =item B<rrd_colors> (hash reference)
  87
  88 Mapping of data source names to colors, used when graphing the different data
  89 sources.  Colors are given in the typical hexadecimal RGB form, but without
  90 leading "#", e.E<nbsp>g.:
  91
  92  $obj->{'rrd_colors'} = {foo => 'ff0000', bar => '00ff00'};
  93
  94 =back
  95
  96 =head1 METHODS
  97
  98 The following methods are used by the graphing front end and may be overwritten
  99 to customize their behavior.
 100
 101 =over 4
 102
 103 =cut
 104
 105 sub _get_ds_from_file
 106 {
 107   my $file = shift;
 108   my $info = RRDs::info ($file);
 109   my %ds = ();
 110   my @ds = ();
 111
 112   if (!$info || (ref ($info) ne 'HASH'))
 113   {
 114     return;
 115   }
 116
 117   for (keys %$info)
 118   {
 119     if (m/^ds\[([^\]]+)\]/)
 120     {
 121       $ds{$1} = 1;
 122     }
 123   }
 124
 125   @ds = (keys %ds);
 126   if (wantarray ())
 127   {
 128     return (@ds);
 129   }
 130   elsif (@ds)
 131   {
 132     return (\@ds);
 133   }
 134   else
 135   {
 136     return;
 137   }
 138 } # _get_ds_from_file
 139
 140 sub new
 141 {
 142   my $pkg = shift;
 143   my $obj = bless ({files => []}, $pkg);
 144
 145   if (@_)
 146   {
 147     $obj->addFiles (@_);
 148   }
 149
 150   return ($obj);
 151 }
 152
 153 =item B<addFiles> ({ I<ident> }, [...])
 154
 155 Adds the given idents (which are hash references) to the B<files> member
 156 variable, see above.
 157
 158 =cut
 159
 160 sub addFiles
 161 {
 162   my $obj = shift;
 163   push (@{$obj->{'files'}}, @_);
 164 }
 165
 166 =item B<getGraphsNum> ()
 167
 168 Returns the number of graphs that can be generated from the added files. By
 169 default this number equals the number of files.
 170
 171 =cut
 172
 173 sub getGraphsNum
 174 {
 175   my $obj = shift;
 176   return (scalar @{$obj->{'files'}});
 177 }
 178
 179 =item B<getDataSources> ()
 180
 181 Returns the names of the data sources. If the B<data_sources> member variable
 182 is unset B<RRDs::info> is used to read that information from the first file.
 183 Set the B<data_sources> member variable instead of overloading this method!
 184
 185 =cut
 186
 187 sub getDataSources
 188 {
 189   my $obj = shift;
 190
 191   if (!defined $obj->{'data_sources'})
 192   {
 193     my $ident;
 194     my $filename;
 195
 196     if (!@{$obj->{'files'}})
 197     {
 198       return;
 199     }
 200
 201     $ident = $obj->{'files'}[0];
 202     $filename = ident_to_filename ($ident);
 203
 204     $obj->{'data_sources'} = _get_ds_from_file ($filename);
 205     if (!$obj->{'data_sources'})
 206     {
 207       cluck ("_get_ds_from_file ($filename) failed.");
 208     }
 209   }
 210
 211   if (!defined $obj->{'data_sources'})
 212   {
 213     return;
 214   }
 215   elsif (wantarray ())
 216   {
 217     return (@{$obj->{'data_sources'}})
 218   }
 219   else
 220   {
 221     $obj->{'data_sources'};
 222   }
 223 } # getDataSources
 224
 225
 226 =item B<getTitle> (I<$index>)
 227
 228 Returns the title of the I<$index>th B<graph> (not necessarily file!). If the
 229 B<rrd_title> member variable is unset, a generic title is generated from the
 230 ident. Otherwise the substrings "{hostname}", "{plugin}", "{plugin_instance}",
 231 "{type}", and "{type_instance}" are replaced by their respective values.
 232
 233 =cut
 234
 235 sub getTitle
 236 {
 237   my $obj = shift;
 238   my $ident = shift;
 239   my $title = $obj->{'rrd_title'};
 240
 241   if (!$title)
 242   {
 243     return (ident_to_string ($ident));
 244   }
 245
 246   my $hostname = $ident->{'hostname'};
 247   my $plugin = $ident->{'plugin'};
 248   my $plugin_instance = $ident->{'plugin_instance'};
 249   my $type = $ident->{'type'};
 250   my $type_instance = $ident->{'type_instance'};
 251   my $instance;
 252
 253   if ((defined $type_instance) && (defined $plugin_instance))
 254   {
 255     $instance = "$plugin_instance/$type_instance";
 256   }
 257   elsif (defined $type_instance)
 258   {
 259     $instance = $type_instance;
 260   }
 261   elsif (defined $plugin_instance)
 262   {
 263     $instance = $plugin_instance;
 264   }
 265   else
 266   {
 267     $instance = 'no instance';
 268   }
 269
 270   if (!defined $plugin_instance)
 271   {
 272     $plugin_instance = 'no instance';
 273   }
 274
 275   if (!defined $type_instance)
 276   {
 277     $type_instance = 'no instance';
 278   }
 279
 280   $title =~ s#{hostname}#$hostname#g;
 281   $title =~ s#{plugin}#$plugin#g;
 282   $title =~ s#{plugin_instance}#$plugin_instance#g;
 283   $title =~ s#{type}#$type#g;
 284   $title =~ s#{type_instance}#$type_instance#g;
 285   $title =~ s#{instance}#$instance#g;
 286
 287   return ($title);
 288 }
 289
 290 =item B<getRRDArgs> (I<$index>)
 291
 292 Return the arguments needed to generate the graph from the RRD file(s). If the
 293 file has only one data source, this default implementation will generate that
 294 typical min, average, max graph you probably know from temperatures and such.
 295 If the RRD files have multiple data sources, the average of each data source is
 296 printes as simple line.
 297
 298 =cut
 299
 300 sub getRRDArgs
 301 {
 302   my $obj = shift;
 303   my $index = shift;
 304
 305   my $ident = $obj->{'files'}[$index];
 306   if (!$ident)
 307   {
 308     cluck ("Invalid index: $index");
 309     return;
 310   }
 311   my $filename = ident_to_filename ($ident);
 312
 313   my $rrd_opts = $obj->{'rrd_opts'} || [];
 314   my $rrd_title = $obj->getTitle ($ident);
 315   my $format = $obj->{'rrd_format'} || '%5.1lf';
 316
 317   my $rrd_colors = $obj->{'rrd_colors'};
 318   my @ret = ('-t', $rrd_title, @$rrd_opts);
 319
 320   if (defined $obj->{'rrd_vertical'})
 321   {
 322     push (@ret, '-v', $obj->{'rrd_vertical'});
 323   }
 324
 325   my $ds_names = $obj->{'ds_names'};
 326   if (!$ds_names)
 327   {
 328     $ds_names = {};
 329   }
 330
 331   my $ds = $obj->getDataSources ();
 332   if (!$ds)
 333   {
 334     confess ("obj->getDataSources failed.");
 335   }
 336
 337   if (!$rrd_colors)
 338   {
 339     my @tmp = ('0000ff', 'ff0000', '00ff00', 'ff00ff', '00ffff', 'ffff00');
 340
 341     for (my $i = 0; $i < @$ds; $i++)
 342     {
 343       $rrd_colors->{$ds->[$i]} = $tmp[$i % @tmp];
 344     }
 345   }
 346
 347   for (my $i = 0; $i < @$ds; $i++)
 348   {
 349     my $f = $filename;
 350     my $ds_name = $ds->[$i];
 351
 352     # We need to escape colons for RRDTool..
 353     $f =~ s#:#\\:#g;
 354     $ds_name =~ s#:#\\:#g;
 355
 356     if (exists ($obj->{'scale'}))
 357     {
 358       my $scale = 0.0 + $obj->{'scale'};
 359       push (@ret,
 360         "DEF:min${i}_raw=${f}:${ds_name}:MIN",
 361         "DEF:avg${i}_raw=${f}:${ds_name}:AVERAGE",
 362         "DEF:max${i}_raw=${f}:${ds_name}:MAX",
 363         "CDEF:max${i}=max${i}_raw,$scale,*",
 364         "CDEF:avg${i}=avg${i}_raw,$scale,*",
 365         "CDEF:min${i}=min${i}_raw,$scale,*");
 366     }
 367     else
 368     {
 369       push (@ret,
 370         "DEF:min${i}=${f}:${ds_name}:MIN",
 371         "DEF:avg${i}=${f}:${ds_name}:AVERAGE",
 372         "DEF:max${i}=${f}:${ds_name}:MAX");
 373     }
 374   }
 375
 376   if (@$ds == 1)
 377   {
 378     my $ds_name = $ds->[0];
 379     my $color_fg = $rrd_colors->{$ds_name} || '000000';
 380     my $color_bg = get_faded_color ($color_fg);
 381
 382     if ($ds_names->{$ds_name})
 383     {
 384       $ds_name = $ds_names->{$ds_name};
 385     }
 386     $ds_name =~ s#:#\\:#g;
 387
 388     push (@ret,
 389       "AREA:max0#${color_bg}",
 390       "AREA:min0#${ColorCanvas}",
 391       "LINE1:avg0#${color_fg}:${ds_name}",
 392       "GPRINT:min0:MIN:${format} Min,",
 393       "GPRINT:avg0:AVERAGE:${format} Avg,",
 394       "GPRINT:max0:MAX:${format} Max,",
 395       "GPRINT:avg0:LAST:${format} Last\\l");
 396   }
 397   else
 398   {
 399     for (my $i = 0; $i < @$ds; $i++)
 400     {
 401       my $ds_name = $ds->[$i];
 402       my $color = $rrd_colors->{$ds_name} || '000000';
 403
 404       if ($ds_names->{$ds_name})
 405       {
 406         $ds_name = $ds_names->{$ds_name};
 407       }
 408
 409       push (@ret,
 410         "LINE1:avg${i}#${color}:${ds_name}",
 411         "GPRINT:min${i}:MIN:${format} Min,",
 412         "GPRINT:avg${i}:AVERAGE:${format} Avg,",
 413         "GPRINT:max${i}:MAX:${format} Max,",
 414         "GPRINT:avg${i}:LAST:${format} Last\\l");
 415     }
 416   }
 417
 418   return (\@ret);
 419 } # getRRDArgs
 420
 421 =item B<getGraphArgs> (I<$index>)
 422
 423 Returns the parameters that should be passed to the CGI script to generate the
 424 I<$index>th graph. The returned string is already URI-encoded and will possibly
 425 set the "hostname", "plugin", "plugin_instance", "type", and "type_instance"
 426 parameters.
 427
 428 The default implementation simply uses the ident of the I<$index>th file to
 429 fill this.
 430
 431 =cut
 432
 433 sub getGraphArgs
 434 {
 435   my $obj = shift;
 436   my $index = shift;
 437   my $ident = $obj->{'files'}[$index];
 438
 439   my @args = ();
 440   for (qw(hostname plugin plugin_instance type type_instance))
 441   {
 442     if (defined ($ident->{$_}))
 443     {
 444       push (@args, uri_escape ($_) . '=' . uri_escape ($ident->{$_}));
 445     }
 446   }
 447
 448   return (join (';', @args));
 449 }
 450
 451 =item B<getLastModified> ([I<$index>])
 452
 453 If I<$index> is not given, the modification time of all files is scanned and the most recent modification is returned. If I<$index> is given, only the files belonging to the I<$index>th graph will be considered.
 454
 455 =cut
 456
 457 sub getLastModified
 458 {
 459   my $obj = shift;
 460   my $index = @_ ? shift : -1;
 461
 462   my $mtime = 0;
 463
 464   if ($index == -1)
 465   {
 466     for (@{$obj->{'files'}})
 467     {
 468       my $ident = $_;
 469       my $filename = ident_to_filename ($ident);
 470       my @statbuf = stat ($filename);
 471
 472       if (!@statbuf)
 473       {
 474         next;
 475       }
 476
 477       if ($mtime < $statbuf[9])
 478       {
 479         $mtime = $statbuf[9];
 480       }
 481     }
 482   }
 483   else
 484   {
 485     my $ident = $obj->{'files'}[$index];
 486     my $filename = ident_to_filename ($ident);
 487     my @statbuf = stat ($filename);
 488
 489     $mtime = $statbuf[9];
 490   }
 491
 492   if (!$mtime)
 493   {
 494     return;
 495   }
 496   return ($mtime);
 497 } # getLastModified
 498
 499 =back
 500
 501 =head1 SEE ALSO
 502
 503 L<Collectd::Graph::Type::GenericStacked>
 504
 505 =head1 AUTHOR AND LICENSE
 506
 507 Copyright (c) 2008 by Florian Forster
 508 E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt>. Licensed under the terms of the GNU
 509 General Public License, VersionE<nbsp>2 (GPLv2).
 510
 511 =cut
 512
 513 # vim: set shiftwidth=2 softtabstop=2 tabstop=8 :