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)
 254   {
 255     $instance = $type_instance;
 256   }
 257   elsif (defined $plugin_instance)
 258   {
 259     $instance = $plugin_instance;
 260   }
 261   else
 262   {
 263     $instance = 'no instance';
 264   }
 265
 266   if (!defined $plugin_instance)
 267   {
 268     $plugin_instance = 'no instance';
 269   }
 270
 271   if (!defined $type_instance)
 272   {
 273     $type_instance = 'no instance';
 274   }
 275
 276   $title =~ s#{hostname}#$hostname#g;
 277   $title =~ s#{plugin}#$plugin#g;
 278   $title =~ s#{plugin_instance}#$plugin_instance#g;
 279   $title =~ s#{type}#$type#g;
 280   $title =~ s#{type_instance}#$type_instance#g;
 281   $title =~ s#{instance}#$instance#g;
 282
 283   return ($title);
 284 }
 285
 286 =item B<getRRDArgs> (I<$index>)
 287
 288 Return the arguments needed to generate the graph from the RRD file(s). If the
 289 file has only one data source, this default implementation will generate that
 290 typical min, average, max graph you probably know from temperatures and such.
 291 If the RRD files have multiple data sources, the average of each data source is
 292 printes as simple line.
 293
 294 =cut
 295
 296 sub getRRDArgs
 297 {
 298   my $obj = shift;
 299   my $index = shift;
 300
 301   my $ident = $obj->{'files'}[$index];
 302   if (!$ident)
 303   {
 304     cluck ("Invalid index: $index");
 305     return;
 306   }
 307   my $filename = ident_to_filename ($ident);
 308
 309   my $rrd_opts = $obj->{'rrd_opts'} || [];
 310   my $rrd_title = $obj->getTitle ($ident);
 311   my $format = $obj->{'rrd_format'} || '%5.1lf';
 312
 313   my $rrd_colors = $obj->{'rrd_colors'};
 314   my @ret = ('-t', $rrd_title, @$rrd_opts);
 315
 316   if (defined $obj->{'rrd_vertical'})
 317   {
 318     push (@ret, '-v', $obj->{'rrd_vertical'});
 319   }
 320
 321   my $ds_names = $obj->{'ds_names'};
 322   if (!$ds_names)
 323   {
 324     $ds_names = {};
 325   }
 326
 327   my $ds = $obj->getDataSources ();
 328   if (!$ds)
 329   {
 330     confess ("obj->getDataSources failed.");
 331   }
 332
 333   if (!$rrd_colors)
 334   {
 335     my @tmp = ('0000ff', 'ff0000', '00ff00', 'ff00ff', '00ffff', 'ffff00');
 336
 337     for (my $i = 0; $i < @$ds; $i++)
 338     {
 339       $rrd_colors->{$ds->[$i]} = $tmp[$i % @tmp];
 340     }
 341   }
 342
 343   for (my $i = 0; $i < @$ds; $i++)
 344   {
 345     my $f = $filename;
 346     my $ds_name = $ds->[$i];
 347
 348     # We need to escape colons for RRDTool..
 349     $f =~ s#:#\\:#g;
 350     $ds_name =~ s#:#\\:#g;
 351
 352     push (@ret,
 353       "DEF:min${i}=${f}:${ds_name}:MIN",
 354       "DEF:avg${i}=${f}:${ds_name}:AVERAGE",
 355       "DEF:max${i}=${f}:${ds_name}:MAX");
 356   }
 357
 358   if (@$ds == 1)
 359   {
 360     my $ds_name = $ds->[0];
 361     my $color_fg = $rrd_colors->{$ds_name} || '000000';
 362     my $color_bg = get_faded_color ($color_fg);
 363
 364     if ($ds_names->{$ds_name})
 365     {
 366       $ds_name = $ds_names->{$ds_name};
 367     }
 368     $ds_name =~ s#:#\\:#g;
 369
 370     push (@ret,
 371       "AREA:max0#${color_bg}",
 372       "AREA:min0#${ColorCanvas}",
 373       "LINE1:avg0#${color_fg}:${ds_name}",
 374       "GPRINT:min0:MIN:${format} Min,",
 375       "GPRINT:avg0:AVERAGE:${format} Avg,",
 376       "GPRINT:max0:MAX:${format} Max,",
 377       "GPRINT:avg0:LAST:${format} Last\\l");
 378   }
 379   else
 380   {
 381     for (my $i = 0; $i < @$ds; $i++)
 382     {
 383       my $ds_name = $ds->[$i];
 384       my $color = $rrd_colors->{$ds_name} || '000000';
 385
 386       if ($ds_names->{$ds_name})
 387       {
 388         $ds_name = $ds_names->{$ds_name};
 389       }
 390
 391       push (@ret,
 392         "LINE1:avg${i}#${color}:${ds_name}",
 393         "GPRINT:min${i}:MIN:${format} Min,",
 394         "GPRINT:avg${i}:AVERAGE:${format} Avg,",
 395         "GPRINT:max${i}:MAX:${format} Max,",
 396         "GPRINT:avg${i}:LAST:${format} Last\\l");
 397     }
 398   }
 399
 400   return (\@ret);
 401 } # getRRDArgs
 402
 403 =item B<getGraphArgs> (I<$index>)
 404
 405 Returns the parameters that should be passed to the CGI script to generate the
 406 I<$index>th graph. The returned string is already URI-encoded and will possibly
 407 set the "hostname", "plugin", "plugin_instance", "type", and "type_instance"
 408 parameters.
 409
 410 The default implementation simply uses the ident of the I<$index>th file to
 411 fill this.
 412
 413 =cut
 414
 415 sub getGraphArgs
 416 {
 417   my $obj = shift;
 418   my $index = shift;
 419   my $ident = $obj->{'files'}[$index];
 420
 421   my @args = ();
 422   for (qw(hostname plugin plugin_instance type type_instance))
 423   {
 424     if (defined ($ident->{$_}))
 425     {
 426       push (@args, uri_escape ($_) . '=' . uri_escape ($ident->{$_}));
 427     }
 428   }
 429
 430   return (join (';', @args));
 431 }
 432
 433 =item B<getLastModified> ([I<$index>])
 434
 435 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.
 436
 437 =cut
 438
 439 sub getLastModified
 440 {
 441   my $obj = shift;
 442   my $index = @_ ? shift : -1;
 443
 444   my $mtime = 0;
 445
 446   if ($index == -1)
 447   {
 448     for (@{$obj->{'files'}})
 449     {
 450       my $ident = $_;
 451       my $filename = ident_to_filename ($ident);
 452       my @statbuf = stat ($filename);
 453
 454       if (!@statbuf)
 455       {
 456         next;
 457       }
 458
 459       if ($mtime < $statbuf[9])
 460       {
 461         $mtime = $statbuf[9];
 462       }
 463     }
 464   }
 465   else
 466   {
 467     my $ident = $obj->{'files'}[$index];
 468     my $filename = ident_to_filename ($ident);
 469     my @statbuf = stat ($filename);
 470
 471     $mtime = $statbuf[9];
 472   }
 473
 474   if (!$mtime)
 475   {
 476     return;
 477   }
 478   return ($mtime);
 479 } # getLastModified
 480
 481 =back
 482
 483 =head1 SEE ALSO
 484
 485 L<Collectd::Graph::Type::GenericStacked>
 486
 487 =head1 AUTHOR AND LICENSE
 488
 489 Copyright (c) 2008 by Florian Forster
 490 E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt>. Licensed under the terms of the GNU
 491 General Public License, VersionE<nbsp>2 (GPLv2).
 492
 493 =cut
 494
 495 # vim: set shiftwidth=2 softtabstop=2 tabstop=8 :