Provided by: hobbit_4.2.0.dfsg-10_i386 bug

NAME

       hobbitd_rrd - hobbitd worker module for updating Hobbit RRD files

SYNOPSIS

       hobbitd_channel --channel=status hobbitd_rrd [options]
       hobbitd_channel --channel=data hobbitd_rrd [options]

DESCRIPTION

       hobbitd_rrd  is a worker module for hobbitd, and as such it is normally
       run via the hobbitd_channel(8) program. It receives "status" and "data"
       messages  from hobbitd via stdin, and updates the RRD databases used to
       generate trend-graphs.

       Clients can send data to Hobbit using both status- and data-  messages.
       So  you  will  normally  run two instances of this module, once for the
       "status" channel and once for the "data" channel.

       hobbitd_rrd understands  data  sent  by  the  LARRD  0.43c  client-side
       scripts  (the  so-called "bottom-feeder" scripts). So you still want to
       install the LARRD bottom-feeders on the clients you monitor.

       Note: For certain types of data, the  RRD  files  used  by  Hobbit  are
       imcompatible with those generated by the Big Brother LARRD add-on.  See
       the COMPATIBILITY section below.

OPTIONS

       --debug
              Enable debugging output.

       --rrddir=DIRECTORY
              Defines  the  directory  where   the   RRD-files   are   stored.
              hobbitd_rrd  will  use  the  location  pointed  to by the BBRRDS
              environment if this option is not present.

       --extra-script=FILENAME
              Defines the script that is run to get the  RRD  data  for  tests
              that are not built into hobbitd_rrd. You must also specify which
              tests are handled by the external script  in  the  --extra-tests
              option.  This  option can only be given once, so the script must
              handle all of the external test-data. See the  CUSTOM  RRD  DATA
              section  below.  Note  that  this  is  NOT needed if your custom
              graphs are generated  by  the  NCV  (Name  Colon  Value)  module
              described  below,  it is only required for data where you have a
              custom script to parse the status message and extract  the  data
              that is put into the graph.

       --extra-tests=TEST[,TEST]
              List  of  testnames that are handled by the external script. See
              the CUSTOM RRD DATA section below. Note that NCV  graphs  should
              NOT  be  listed here, but in the TEST2RRD environment variable -
              see below.

ENVIRONMENT

       TEST2RRD
              Defines the mapping between  a  status-log  columnname  and  the
              corresponding  RRD  database format. This is normally defined in
              the hobbitserver.cfg(5) file.

       BBRRDS Default directory where RRD files are stored.

       NCV_testname
              Defines the types of data  collected  by  the  "ncv"  module  in
              hobbitd_rrd.  See below for more information.

       SPLITNCV_testname
              The  same  as  NCV_testname,  but  keeps  the data into separate
              files. That is, it creates one rrd file per "NAME : value"  line
              found  in  the status message. It is useful when the list of NCV
              lines is varying.

       TRACKMAX
              Comma-separated list of columnname for which you  want  to  keep
              the  maximum  values along with the default average values. This
              only works
               for the NCV backend.

COLLECTED DATA

       The following RRD-file datasets are generated by hobbitd_rrd:

       la     Records the CPU load average. Data is collected from  the  "cpu"
              status  report.  Requires that a Hobbit client is running on the
              monitored server.

       disk   Records the disk utilization. Data is collected from the  "disk"
              status  report.  Requires  that  a  Hobbit-compatible  client is
              running on the monitored server.

       memory Records memory- and swap-utilization. Data is collected from the
              "memory"  status  report.  If no "memory" status is reported, it
              will use the data from the Win32 client "cpu" status  report  to
              generate  this dataset. Requires that a Hobbit-compatible client
              is running on the monitored server.

       netstat
              Records TCP and UDP  statistics.  Data  is  collected  from  the
              "netstat"  status  report;  however, this data is often sent via
              the Hobbit "data" protocol, so there need  not  be  a  "netstat"
              column  visible  on  the  Hobbit display. To get these data, the
              LARRD netstat  bottom-feeder  script  must  be  running  on  the
              monitored server.

       vmstat Records  system  performance  metrics from the "vmstat" command.
              Data is collected from the "vmstat" status report; however, this
              data is often sent via the Hobbit "data" protocol, so there need
              not be a "vmstat" column visible on the Hobbit display.  To  get
              these  data,  the  LARRD  vmstat  bottom-feeder  script  must be
              running on the monitored server.

       tcp    Response-time metrics from all of the Hobbit network  tests  are
              recorded in the "tcp" RRD.

       apache Apache  server performance metrics, taken from the "apache" data
              report. See the description of the apache keyword in bb-hosts(5)
              for details.

       sendmail
              Sendmail  server performance metrics, taken from the "mailstats"
              output. To get these  data,  the  LARRD  sendmail  bottom-feeder
              script must be running on the monitored server.

       mailq  Mail  queue  size.  To  get these data, the LARRD nmailq bottom-
              feeder script must be running on the monitored server.

       bea    BEA Weblogic performance data. This is an  experimental  set  of
              data  collected  from  BEA  Weblogic  servers  via  SNMP, by the
              "beastats" tool included with Hobbit.

       iishealth
              IIS webserver performance data,  collected  by  the  "iishealth"
              script.   This script is a client-side add-on available from the
              www.deadcat.net archive.

       temperature
              Temperature data, collected with  the  temperature  script  from
              www.deadcat.net.  To get these data, the temperature script must
              be running on the monitored server.

       ntpstat
              Tracks the deviation between the local system time  and  an  NTP
              server,  using  the  output  from  the  "ntpq -c rv" command.  A
              simple script to collect these data is included  in  the  Hobbit
              contrib/ directory.

       citrix Tracks  the  number  of active sessions on a Citrix server using
              the "query session" command. An extension for  the  BBNT  client
              that  generates  data  for  this graph is in the Hobbit contrib/
              directory.

CUSTOM RRD DATA IN NAME-COLON-VALUE (NCV) FORMAT

       Many data-collection scripts report data in the form "NAME : value"  or
       "NAME  =  value".  So  a  generic module in hobbitd_rrd allows for easy
       tracking of this type of data.

       The "ncv" module will automatically detect all occurrences of a "NAME :
       value"  or  "NAME  = value" string in a status message, and generate an
       RRD file holding all of  the  name/value  data  found  in  the  message
       (unless  you use SPLITNCV, see above). The colon- or equal-sign must be
       present - if there is only whitespace, this module will fail.

       Only the valid letters (A-Z, a-z) and digits  (0-9)  are  used  in  the
       dataset  names;  whitespace  and  other  characters  are  stripped  off
       automatically. Only the first 19 characters of a dataset name are  used
       (this is an RRD limitation). Underscore ’_’ is not allowed, even though
       RRDtool permits this, and will be stripped from the name.

       When using the alternative SPLITNCV_testname, the dataset name  is  not
       limited  in length, and non-valid characters are changed to underscores
       instead of being stripped off. The dataset  inside  the  resulting  rrd
       file is always "lambda".

       Note  that each "NAME : value" must be on a line by itself. If you have
       a custom script generating the status- or data-message that is fed into
       the  NCV  handler,  make  sure  it inserts a newline before each of the
       data-items you want to track.

       To enable the ncv module for a status, add a  "COLUMNNAME=ncv"  to  the
       TEST2RRD   setting   and  the  COLUMNNAME  to  the  GRAPHS  setting  in
       hobbitserver.cfg(5) , then restart Hobbit. Hobbit  will  now  send  all
       status-messages  for the column COLUMNNAME through the hobbitd_rrd ncv-
       handler.

       The name of the RRD file will be COLUMNNAME.rrd. When  using  SPLITNCV,
       the name of the RRD file will be COLUMNAME,DATASETNAME.rrd.

       By  default, all of the datasets are generated as the RRD type "DERIVE"
       which works for all types of monotonically increasing counters. If  you
       have  data that are of the type GAUGE, you can override the default via
       an environment variable NCV_COLUMNNAME (or SPLITNCV_COLUMNAME).

       E.g. if you are using the bb-mysqlstatus script from www.deadcat.net to
       collect  data  about  your  MySQL  server, it generates a report in the
       column  called  "mysql".  One  data  item  is  the  average  number  of
       queries/second,  which  must be logged in the RRD file as type "GAUGE".
       To do that, add the following to hobbitserver.cfg:
           NCV_mysql="Queriespersecondavg:GAUGE"
       If you have multiple datasets that you myst define,  add  them  to  the
       environment variable separated by commas, e.g.
           NCV_mysql="Uptime:NONE,Queriespersecondavg:GAUGE"

       The  dataset  type  "NONE" used above causes hobbitd_rrd to ignore this
       data, it is not included in the RRD file.

       You can use "*" as the dataset name to match all datasets  not  listed.
       E.g.
           NCV_weather="Rain:DERIVE,*:GAUGE"
       will  cause the "Rainfall" dataset to be of type DERIVE, and all others
       of type GAUGE. If you want to track only a few of the variables in your
       data, you can use "*:NONE" to drop any dataset not explicitly listed.

       For  a  more  detailed  "how  to"  description,  see  the  on-line HTML
       documentation of "How to create graph custom  data"  available  in  the
       Help menu section on your Hobbit server.

CUSTOM RRD DATA VIA SCRIPTS

       hobbitd_rrd provides a simple mechanism for adding custom graphs to the
       set of data collected on your Hobbit server. By  adding  the  "--extra-
       script"  and  "--extra-tests"  options,  data  reported  to Hobbit from
       selected tests are passed to an external script, which can  define  the
       RRD data-sets to store in an RRD file.

       NOTE:  For  performance  reasons, you should not use this mechanism for
       large amounts of data. The overhead involved in  storing  the  received
       message  to  disk and launching the script is significantly larger than
       the normal hobbitd_rrd overhead. So if  you  have  a  large  number  of
       reports  for a given test, you should consider implementing it in C and
       including it in the hobbitd_rrd tool.

       Apart from  writing  the  script,  You  must  also  add  a  section  to
       hobbitgraph.cfg(5) so that hobbitgraph.cgi(1) knows how to generate the
       graph from the data stored  in  the  RRD  file.   To  make  the  graphs
       actually  show  up on the status-page and/or the "trends" page, add the
       name of the  new  graph  to  the  TEST2RRD  and/or  GRAPHS  setting  in
       hobbitserver.cfg(5).

       The  script  is  invoked for each message that arrives, where the test-
       name matches one of the testnames given in the "--extra-tests"  option.
       The script receives three commandline parameters:

       Hostname
              The name of the host reporting the data.

       Testname
              The name of the test being reported.

       Filename
              File  containing  the  data  that  was  reported.  This  file is
              generated  for  you  by  hobbitd_rrd,  and   is   also   deleted
              automatically after your script is finished with it.

       The  script  must  process  the data that is reported, and generate the
       following output:

       RRD data-set definitions
              For each dataset that the RRD file holds, a line beginning  with
              "DS:" must be output.  If multiple data-sets are used, print one
              line for each dataset.
              Data-set  definitions  are   described   in   the   rrdcreate(1)
              documentation,  but  a  common  definition for e.g. tracking the
              number of users logged  on  would  be  "DS:users:GAUGE:600:0:U".
              "users"  is  the  name  of the dataset, "GAUGE" is the datatype,
              "600" is the longest time allowed between updates for  the  data
              to  be  valid,  "0" is the minimum value, and "U" is the maximum
              value (a "U" means "unknown").

       RRD filename
              The name of the RRD file where the data  is  stored.  Note  that
              Hobbit  stores  all  RRD  files in host-specific directories, so
              unlike LARRD you should not include the hostname in the name  of
              the RRD file.

       RRD values
              One  line,  with all of the data values collected by the script.
              Data-items are colon-delimited  and  must  appear  in  the  same
              sequence  as your data-set definitions, e.g. if your RRD has two
              datasets with the values "5" and "0.4"  respectively,  then  the
              script must output "5:0.4" as the RRD values.
              In  some  cases it may be useful to define a dataset even though
              you will not always have data for it.  In  that  case,  use  "U"
              (unknown) for the value.

              If  you want to store the data in multiple RRD files, the script
              can just print out more sequences of data-set  definitions,  RRD
              filenames  and  RRD  values.  If  the  data-set  definitions are
              identical to the previous definition, you  need  not  print  the
              data-set  definitions  again - just print a new RRD filename and
              value.

       The following sample script for tracking weather data shows how to  use
       this mechanism. It assumes the status message include lines like these:

              green Weather in Copenhagen is FAIR

              Temperature: 21 degrees Celsius
              Wind: 4 m/s
              Humidity: 72 %
              Rainfall: 5 mm since 6:00 AM

       A shell-script to track all of these variables could  be  written  like
       this:

              #!/bin/sh

              # Input parameters: Hostname, testname (column), and messagefile
              HOSTNAME="$1"
              TESTNAME="$2"
              FNAME="$3"

              if [ "$TESTNAME" = "weather" ]
              then
                   # Analyze the message we got
                   TEMP=‘grep "^Temperature:" $FNAME | awk ’{print $2}’‘
                   WIND=‘grep "^Wind:" $FNAME | awk ’{print $2}’‘
                   HMTY=‘grep "^Humidity:" $FNAME | awk ’{print $2}’‘
                   RAIN=‘grep "^Rainfall:" $FNAME | awk ’{print $2}’‘

                   # The RRD dataset definitions
                   echo "DS:temperature:GAUGE:600:-30:50"
                   echo "DS:wind:GAUGE:600:0:U"
                   echo "DS:humidity:GAUGE:600:0:100"
                   echo "DS:rainfall:DERIVE:600:0:100"

                   # The filename
                   echo "weather.rrd"

                   # The data
                   echo "$TEMP:$WIND:$HMTY:$RAIN"
              fi

              exit 0

COMPATIBILITY

       Some  of  the  RRD files generated by hobbitd_rrd are incompatible with
       the files generated by the Big Brother LARRD add-on:

       vmstat The  vmstat  files  with  data  from  Linux  based  systems  are
              incompatible  due  to the addition of a number of new data-items
              that LARRD 0.43 do not collect, but hobbitd_rrd  does.  This  is
              due  to changes in the output from the Linux vmstat command, and
              changes in the way e.g.  system load metrics are reported.

       netstat
              All  netstat  files  from  LARRD  0.43  are  incompatible   with
              hobbitd_rrd.   The  netstat  data  collected  by  LARRD is quite
              confusing: For some types  of  systems  LARRD  collects  packet-
              counts,  for others it collects byte- counts. hobbitd_rrd uses a
              different RRD file-format with separate counters for packets and
              bytes and tracks whatever data the system is reporting.

SEE ALSO

       hobbitd_channel(8), hobbitd(8), hobbitserver.cfg(5), hobbit(7)