Provided by: cfengine2_2.1.20-1_i386 bug

NAME

       cfetool check - Check a new value against the averages currently in the
       database

SYNOPSIS

       cfetool check name --value-V value [--path-p directory name]
       [--time-t seconds] [--daily-d] [--weekly-w] [--yearly-y]
       [--histograms-H] [--verbose-v] [--help-h]

DESCRIPTION

       Takes a new value and checks it against the averages currently in the
       database specified by name, located at the path specified by the -p
       argument, or the current working directory if the -p argument is
       ommitted.  The value will be associated with the current time, unless
       the -t option is given. The output indicates how much higher or lower
       the new value is compared to the averages in the database, in terms of
       the number of standard deviations.

       The -d, -w and -y options specify the databases to check the new value
       against. If all three options are omitted, only the weekly database
       will be accessed.

OPTIONS

       --value-v value
           Specifies the new value to check against the database averages.

       --path-p directory name
           The directory in which the database specified by name can be found.

       --time-t
           The time the value was collected, in seconds since epoch (January
           1st, 1970).  If this argument is omitted, the current time will be
           used.

       --daily-d
           Check the new value against the daily averages database.

       --weekly-w
           Check the new value against the weekly averages database.

       --yearly-y
           Check the new value against the yearly averages database.

       --histograms-H
           Check which histogram bucket the new value would fall into.  The
           histogram is divided into 64 buckets, which represent distances
           from the mean value. Bucket 64 represents two standard deviations
           above the expected value, and bucket 0 represents two standard
           deviations below the expected value.

       --verbose-v
           Print details of the command’s execution to the standard output
           stream.

       --help-h
           Print a short help message and then exit.

OUTPUT

       Before exiting, "cfetool check" will print one line to the standard
       output stream, in the following format:

       yrly=ynum,bkt=ybkt;wkly=wnum,bkt=wbkt;dly=dnum,bkt=dbkt

       ybkt, wbkt and dbkt represent the histogram bucket the given value
       falls into, and will be 0 for databases that are not being checked
       against, and if there is no histogram file or the -H option was not
       specified.

       ynum, wnum and dnum will be either the number 0 if the corresponding
       database was not updated, or a code indicating the state of the given
       statistic, as compared to an average of equivalent earlier times, as
       specified below:

        code    high│low│normal   meaning
        -------------------------------------------------------------
         -2     -                 no sigma variation
        -------------------------------------------------------------
         -4     low               within noise threshold, and within
         -5     normal              2 standard deviations from
         -6     high                expected value
        -------------------------------------------------------------
        -14     low               microanomaly: within noise
        -15     normal              threshold, but 2 or more standard
        -16     high                deviations from expected value
        -------------------------------------------------------------
        -24     low               normal; within 1 standard deviation
        -25     normal              from the expected value
        -26     high
        -------------------------------------------------------------
        -34     low               dev1; more than 1 standard
        -35     normal              deviation from the expected
        -36     high                value
        ------------------------------------------------------------
        -44     low               dev2; more than 2 standard
        -45     normal              deviations from the expected
        -46     high                value
        -------------------------------------------------------------
        -54     low               anomaly; more than 3 standard
        -55     normal              deviations from the expected
        -56     high                value

       Where "low" indicates that the current value is below both the expected
       value for the current time position, and the global average value.
       "high" indicates that the current value is above those values. "normal"
       indicates that the current value is within the range of expected
       values.

       "cfetool check" also exits with a code corresponding to the above
       table. If more than one database is being checked against, the most
       negative result from all checks is returned, and the individual results
       must be obtained from the standard output stream, as described above.

EXAMPLE

         % cfetool check temperature --path /my/path --value 20 --histograms
         yrly=0,bkt=0;wkly=-6,bkt=51;dly=0,bkt=0

       Checks the value 20 against the weekly temperature database and
       histogram files located in /my/path/ using the current time. The output
       indicates that the new value given was within cfetool’s noise
       threshold, and also within 2 standard deviations of the previous
       average stored in the weekly database.

AUTHORS

       The code and documentation were contributed by Stanford Linear
       Accelerator Center, a department of Stanford University.  This
       documentation was written by

       Elizabeth Cassell <e_a_c@mailsnare.net> and
       Alf Wachsmann <alfw@slac.stanford.edu>

COPYRIGHT AND DISCLAIMER

        Copyright 2004 Alf Wachsmann <alfw@slac.stanford.edu> and
                       Elizabeth Cassell <e_a_c@mailsnare.net>
        All rights reserved.