hotsanic

Subversion Repositories:
[/] [branches/] [HotSaNIC-0.5.0-pre6/] [Documentation/] [module-howto/] [howto-diagrams.pl] - Rev 20 Go to most recent revision
Compare with Previous - Blame - Download
The "diagrams.pl" file will be called to build all diagrams of this module. It imports some of HotSaNICs libraries to save some nasty fiddling with the settings files and rrdtool's "graph" function. The skeleton would always look like this:

---------- BEGIN CODE ----------
#!/usr/bin/env perl

# include PERL libraries
use strict;
use warnings;
use diagnostics;

# include HotSaNIC libraries
use lib "../../lib";
use HotSaNICparser;
use HotSaNICdiagram;

# If you're going to check the file into CVS, please use this construct.
# It makes sure that the CVS version numberes will be set correctly.
#
(my $VERSION = '$Revision: 1.2 $') =~ s/.*(\d+\.\d+).*/$1/;
(my $IDENTIFIER = '$Id: howto-diagrams.pl,v 1.2 2004/05/23 12:11:33 bernisys Exp $') =~ s/.*,v (.*) \$/$1/;

# read all settings
#
my $MODNAME=HotSaNICparser::get_module_name();
my %CONFIG=HotSaNICparser::get_config("../..");
my %MODULECONFIG=HotSaNICparser::get_moduleconfig(".", %CONFIGURATION_HASH );
#
# %CONFIGURATION_HASH has to contain the names and types of each settings item used in this script.
# It can be a static hash of the form:  (ITEM=>"type", ...)
# type may be:  array, var, bool
#
# Example:
#   my %MODULECONFIG=HotSaNICparser::get_moduleconfig(".",(FOO=>"var",BAR=>"bool",HOST=>"array");
#
my $OUTDIR=$CONFIG{"WEBDIR"}."/".lc $MODNAME;
if ( ! -e $OUTDIR ) { mkdir $OUTDIR,0755; }
my $IMGFMT=lc $CONFIG{"IMAGEFORMAT"};

my ($FORCE,$DEBUGLEVEL,%PLOT)=HotSaNICdiagram::check_args(@ARGV);
my @OPTIONS=HotSaNICdiagram::get_common_options(%MODULECONFIG,%CONFIG);

#
#  Now add all graph options which are common in EVERY DIAGRAM! to the @OPTIONS array
#

# create diagrams
#
foreach ( <<array with diagram names>> ) {
  my $name = ....
  my $description = ....
  my $DB_FILE="./rrd/<<filename>>.rrd";
  if (%PLOT) { next if ! defined $PLOT{$name}; }

  print "creating images for $dev ($description) ...\n";

# if database exists, create images...
  if ( -e $DB_FILE) {

    foreach my $range ("1h","6h","1day","1week","1month","1year") {
      my ($range_plaintext,$file,$build,$fullrange,$DATESTRING)=HotSaNICdiagram::get_diagram_properties($range);

      my @EXTOPTIONS=("-s","-$fullrange", "--title", "TITLE_STRING - last $range_plaintext ($DATESTRING)");
      my @COMMANDS;

#
# now fill @COMMANDS array with valid rrdtool::graph commands
#
# HotSaNICdiagram.pm holds some functions that makes it easy to fill your diagram with graphs and legends.
# These are documented in the library itself, as well as in the "howto-diagrams.pl" documentation file.
#

      my %CONF=(RANGE=>$descr,
                FILENAME=>"$OUTDIR/$name-$file",
                FORMAT=>lc $MODULECONFIG{IMAGEFORMAT},
                INTERVAL=>$build,
                FORCE=>$FORCE,
                OPTIONS=>[@OPTIONS,@EXTOPTIONS,@COMMANDS],
                DEBUGLEVEL=>$DEBUGLEVEL,
                MODNAME=>$MODNAME);
      HotSaNICdiagram::graph(%CONF);
      }
    }
  }

---------- END CODE ----------





---------- FUNCTION DESCRIPTIONS ----------


---------- HotSaNICdiagram::get_diagram_properties ----------

USAGE:
  ($range_plaintext,$file,$build,$fullrange,$DATESTRING)=HotSaNICdiagram::get_diagram_properties($range);

PARAMETERS:
  $range              the range of the desired diagram: "1h" "6h" "1day" "1week" "1month" "1year"

RETURN VALUES:
  $range_plaintext    will be  "hour" "6 hours" "day" "week" "month" or "year"  in dependency of $range

  $file               filename-extension (same as $range_plaintext, except "6 hours" will be "6h")

  $build              number of seconds after which a rebuild of the diagram should be done

  $fullrange          number of seconds covered by the current diagram
                      This can be used to calculate for example the number of events over the diagram's timespan

  $DATESTRING         the current time in human-readable format:  "Day YYYY-MM-DD hh:mm"




---------- HotSaNICdiagram::insert_data ----------

USAGE:
  @array = HotSaNICdiagram::insert_data($type,$vars,$color,$name,$legends,$unit,$use_SI);

PARAMETERS:
  $type     one of the graph types defined in rrdtool:  LINE[123] AREA STACK

  $vars     string that contains one to five RRD-variables to be used for plotting and for the legend elements
            if it contains less than five entries, the last entry will be copied to the remaining ones

              "var_plot var_min var_avg var_max var_current"

                 var_plot     variable that will be plotted as graph
                              this may be set to "0" to supporess the graph and only add the legend.
                 var_min      variable to be used in legend as minimum
                 var_avg      variable to be used in legend as average
                 var_max      variable to be used in legend as maximum
                 var_current  variable to be used in legend as current

  $name     name of the graph

  $color    valid color definition, hexadecimal:  "RRGGBB"

  $legends  string that contains a space separated list of legends to be built.
            If the string is empty, no legend will be added.
            Valid entries are:

              "min"            minimum value of the 2nd item in $vars
              "avg"            average value of the 3rd item in $vars
              "max"            maximum value of the 4th item in $vars
              "now" or "cur"   last value of the 5th item in $vars

  $unit     unit of the graph, a string that contains something like "bytes/s" or "sec." etc.

  $use_SI   1 => use SI units (... m for milli, k for kilo, M for mega ...) in legend
            0 => don't use SI units
RETURN VALUES:
  @array    array that contains valid graph commands

EXAMPLE:
  push @array,HotSaNICdiagram::insert_data("LINE1","var1 var2 var3","FF0000","test graph","min cur","bytes/s",1),

    plots a red line and adds a legend that looks like this:

      [#] test graph  (min: 1.234 k  current: 2.345 k  bytes/s)

    ([#] is the red square that marks the legend)



---------- HotSaNICdiagram::insert_minmax ----------

USAGE:
  @array = HotSaNICdiagram::insert_minmax($vars,$areacolor,$bordercolor,$name,$unit,$use_SI);

PARAMETERS:
  $vars         string that contains two RRD-variables to be used for plotting and for the legend elements.
                the first element is the variable to be used for plotting the minimum, the second for the maximum.
                this string may be prepended with a "0" to suppress the graph:  "0 min max"

  $areacolor    valid color definition for the area, hexadecimal:  "RRGGBB"

  $bordercolor  valid color definition for the area borders (thin lines), hexadecimal:  "RRGGBB"

  $name         name of the graph

  $unit         unit of the graph, a string that contains something like "bytes/s" or "sec." etc.

  $use_SI       1 => use SI units (... m for milli, k for kilo, M for mega ...) in legend
                0 => don't use SI units


---------- HotSaNICdiagram::insert_unknown_area ----------

USAGE:
  @array = HotSaNICdiagram::insert_unknown_area($vars,$color,$description);

PARAMETERS:

  $vars        space separated list of all variables to be taken into account.
               If one of them is unknown, the area will be marked.
 
  $color       valid color definition, hexadecimal:  "RRGGBB"

  $description some additional legend that will (if defined) show up in brackets after the string "data unknown".