This section is the definitive reference for each and every tag that
Cricket knows about. Use this section as a reference when you need to
know the exact format for something, or the exact behavior of a
certain tag.
File Format
Cricket config files are simple text files arranged into a tree-shaped
set of files called a Config Tree. They are processed by a Perl
module called ConfigTree.pm. This setup would make it possible to use
one config tree for Cricket and other clients of ConfigTree.pm. At
this time, there are no other programs that use the config tree
design, but there may be in the future. It was set up this way because
the config tree will grow to contain an accurate picture of your
network; it makes sense to try to leverage that information to other
network administration tools. The overriding philosophy here is
duplicated information is bad: it is hard to maintain, and it invites
silly mistakes.
The Cricket config tree is 100% incompatible with MRTG configuration
files. There are not even any plans to write a converter, though one
could probably be written. When you choose to use Cricket, it's a very
good idea to approach your config from a fresh perspective, to take
maximum advantage of Cricket's features.
The comment character for Cricket is "#". If a "#"
is found at the beginning of the line (or is preceded only by
whitespace) then the "#" and everything after it will be
deleted. Completely blank lines are discarded from the input too.
The fundamental unit of a config file is a chunk. A chunk is made up
of one line which begins in column one, and one or more lines which
have whitespace before them. In this way, you can continue a long line
to another line by simply inserting a newline and some
whitespace. When it is glued back together internally, the newline and
whitespace are replaced by a space. A chunk should have at least one
word (a group of characters that are not whitespace) at the
beginning. This word (called the "token" by the code) tells
ConfigTree.pm what kind of chunk it is dealing with, and what kind of
parser to use. If it is an unknown token, ConfigTree.pm can be told
to ignore it. By default, unknown chunks cause a warning, but not a
fatal error. Clients of ConfigTree.pm can control this; Cricket
chooses to ignore unknown chunks.
Text Parser
This parser is used in cases where free-text is useful, for
instance in the HTML dictionary. The first two tokens are parsed out,
and they serve as the chunk type, and the key. Everything after these
first two tokens is considered the value.
Simple Parser
This parser is used for simple mappings, like the OID mapping. An
example of a valid OID line is:
oid ifInOctets 1.3.6.1.2.1.2.2.1.10
The format is a token, another token (called the key;
ifInOctets in this case), and finally the value. The value
can have whitespace in it, but only if it is surrounded by double
quotes ("). Embedded quotes are not yet supported.
Tag/Value Parser
This is the most useful, and most commonly used parser. Here's an
example of a Tag/Value chunk:
graph ifInOctets
color = dark-green
draw-as = AREA
legend = "Average bits in"
y-axis = "bits per second"
scale = 8,*
Like the others, it parses out two tokens, the chunk type and the
key. After this, it parses a series of tag/value pairs separated by
whitespace and the equals sign ("="). The values must be
surrounded by quotes to embed whitespace, like the Simple
Parser. If you repeat a tag, only the second occurrence will be used.
Miscellaneous
All tokens and keys are case-insensitive. The tags in a tag/value
chunk are also case insensitive. The values will have their case
preserved when they are used by the system.
Tag names can have numbers, letters, the period symbol, the dash, and
the underscore. Avoid using other punctuation, since those symbols are
used by Cricket internally.
OID tags are more limited, to conform with the SNMP spec. A tag in an
OID dictionary can be made up of numbers and letters. Dashes are not
allowed.
Target names should consist of letters, numbers, dashes and
underscores. Do not put slashes in them, since they end up being used
as parts of filenames.
Inside of double quotes, on the right side of an equals sign, anything goes, with the exception of the double quote itself. There is currently no way to include the double quote in a string.
Avoid choosing names that begin and end with two dashes (like
--default--). Cricket uses some names like this internally,
and future additions will make use of these names.
The following table shows which tokens are parsed with which parsers:
Token
Parser
target
Tag/Value
datasource
Tag/Value
targetType
Tag/Value
graph
Tag/Value
color
Simple
oid
Simple
html
Text
event
Tag/Value
rra
Simple
For some tags, you can put Perl expressions into the value.
(inst-names is one such tag) However, double quotes are often
useful in Perl expressions. That's problematic, since at present there
is no way to put quotes into values. Instead, you should use single
quotes. Thus it might look something like this:
For each target known to Cricket, there is a target dictionary. The
target dictionary holds all the information needed by Cricket to collect
and store variables from a component. The target dictionary is
expanded with respect to itself immediately before it is
used to collect or display data.
collect
Default value: not set
If this tag exists, and it is set to false, then
this target will be skipped when the collector comes
across it. This is useful if you no longer want to collect
an obsolete target, but you still want it in the config tree
so that you can look at it with the grapher.
copy-to
Default value: not set
If this item is set, it tells Cricket to send the
data it collects somewhere else after it is added to
the RRD file. The value of this tag is interpreted
as a colon separated list of two things. The first
is where to send the data. The second item is used on
a case-by-case basis.
To send SNMP traps, set copy-to to a string like this:
trap:public@traphost.company.com.
The traps Cricket sends are marked with an enterprise number
of "1.3.6.1.4.1.2595.1.1" (which is enterprises.webtv.wtvOps.wtvOpsTraps).
Their generic type is 6, and their specific type is 3.
The first varbind is the full path to the target, including
the target name. The other varbinds are the actual data.
The OID's for these varbinds can be ignored. They are not
significant.
To send SQL updates to a database (see SQL HOWTO),
use a string like this:
sql:driver,user,password
driver is a string like: dbi:Sybase:NMSDB.
This is a new extension to copy-to and while it is designed to work with as
many platforms as possible, it may not work with all types of databases. It
has only been tested against SQLServer.
New copy-to types can only be added by editing the
source to the collector. Please send any patches
to the Cricket maintainer, so others can use your nifty
copy-to method.
directory-desc
Default value: unset
This string is displayed in the description column of the
directory selection list, if it is set. If not, the column
is simply left blank.
disable-short-desc
Default value: unset
Hold on tight, this is a weird one. If this is set in the
dictionary of the first target displayed in the "Targets
that are available" table, then the table will have only one
column. This is useful when you have lots of views and
don't want to lose the space used by the description
column.
display-name
Default value: same as target name
You can use this tag to use a more user friendly name for a target
for display purposes. If you do not set it, the target name itself
will be displayed.
events
Default value: none
This tag is interpreted by the grapher as a comma-separated list
of events to fetch from the events dictionary, and add
to the graph in the form of a vertical rule.
inst
Default value: none
This is the SNMP instance number. Cricket only really needs this value
to be set correctly if %inst% shows up in the ds-source tag
of the datasources you are collecting. If inst
is set, Cricket will attempt to evaluate it as a Perl expression.
Note: there's no protection against
side-effects from this expression, so to avoid a security problem from
an inst like unlink('/etc/motd'); you should make certain
your config tree is only writable by you.
The result of evaluating the instance is examined to see whether it is
a mapped instance, a scalar, or a vector. If it starts with "map(", it
is a mapped instance. The instance mapping algorithm is used to
derive an instance number from the rest of the data in the target (see
Instance Mapping for more information on
this), then the target is processed as though the instance number had
been a scalar all along.
If it is a scalar (i.e. inst=1) then it is processed
normally. If the instance is a vector (i.e. inst="(0..12)",
or inst="(1, 3, 5)") then the target is processed once for
each value in the list. The target dictionary is expanded with respect
to itself for each instance, so it's possible to embed %inst%
into the rrd-datafile tag. In fact, it's critical to add
%inst% to some part of the rrd-datafile tag, or else the data
will all be stored on top of one another in the same datafile.
inst-names
Default value: none
When making the instance selector table, Cricket will use names
from this tag instead of the instances themselves. If it will be
needed, inst-names is eval'ed (just like inst).
For each instance in the inst tag, Cricket looks for a
corresponding entry in the inst-name vector. If it
finds one, it uses that as the instance name, otherwise it defaults
to the instance it fetched from the inst tag.
long-desc
Default-value: unset
This description shows up at the top of a page of graphs, in the
"Summary" section. There is more room on this page for a longer
description. You can include your own HTML as long as you close all
tags that you open. If you don't feel like setting this for every
target, set it to %short-desc% in the "--default--" target,
and the short description will show up on each graph page for every
target which does not have an explicit long description. (Such is the
power of the config tree.)
If this tag exists, then this target is considered by Cricket to be a
multi-target. To the collector, this means that it simply doesn't need to
collect anything, and can skip the target. To the grapher, it means this
target will aggregate the data from several different targets all onto
one set of graphs. It will plot the data from each of the different targets
all on the same graph. It assumes that the target-type of each of the
specified targets is the same. It works best if the graph dictionary for
each datasource does not specify a color (otherwise you'll end up with more
than one line with the same color). It enforces only one AREA graph--it
will convert the others into LINE2 in order to ensure they can be seen.
It does not currently support vector instances. Other than that, the syntax
matches that for "targets". This tag can also be used in connection with
the mtargets-ops flag to perform arithmetic operations.
Note: This tag will not work with vector instances at this
time. If you absolutely need it to work, you'll need to use multiple
separate scalar targets to poll the device's ports, and then use
the mtargets tag to graph each of the scalar targets.
mtargets-ops
Default-value: none
This tag is used in connection with the "mtargets" tag. This tag lets
you perform arithmetic operations on multiple targets. For example,
this lets you add multiple targets together and graph the results.
This tag must either be set to an RPN notation, or to a short-hand
form, like "sum()".
If set to an RPN expression, it should be defined as a
comma separated list of operations, such
as "+","-","*","/". This is used as a RPN calculator, operating on the
targets listed in the mtargets definition.
So, if you list three targets
in your mtargets definition, you could define
mtargets-ops="+,+", and the
result would be a graph of the three targets added together.
If this tag is set to "sum()", the correct number of pluses
will be substituted to make a valid RPN expression to sum each
of the targets in the mtargets tag.
If this tag is set to "avg()", it will be replaced by
the correct RPN expression to
calculate the average of the targets in the mtargets tag.
The HTML
summary section also has the same set of operations done to the values
there. The operations are done to each datasource defined for that
target-type. If you have defined a scale for the individual datasource,
these operations are done on the scaled values.
order
Default value: 0
The order tag is used to control the order that targets are
displayed. It has nothing to do with the order that they are
polled. (Though it might work like that someday.) When the
display is laid out by the CGI application, it sorts the targets from
the highest order to the lowest order. Targets which have the same
order are sorted alpha-numerically within their order.
persistent-alarms
Default value: false
This tag tells the Monitor agent that if it receives an alarm to send traps
every time it detects an alarm condition. The default behavior is to only send
an Alarm/Clear trap. This can be useful for sending many SNMP traps into an
application which can tally the amount of failures, or to have it execute a
program multiple times. Setting this tag to 'true' turns persistent alarming
on.
rrd-datafile
Default value: none
This tag tells Cricket where to put the data it collects, and where to
find the data it will graph. Since there are no guarantees about where
Cricket will be running from, you should use a full path here. The
sample-config ships with a one-size-fits all definition for
rrd-datafile in the root Defaults file. Except for special cases, you
can probably use it and it will generate the filenames for you
automatically.
rrd-poll-interval
Default value: none
This tag is used to set the step size (in seconds) for the RRD file
when it is first created. This value cannot be changed once the RRD
file is created, so if you need to change it in the config tree, then
you must remove the RRD file, forcing Cricket to re-create it, to make
the change stick. You will, of course, lose all the data you have
collected so far. It is critical that the collector runs on each
target at least as often as the rrd-polling-interval, otherwise RRD
may mark the intervening polling periods as unknown.
RRA's are defined in terms of the fundamental polling-interval of the
RRD. Thus, if you chose to adjust the rrd-polling-interval (and then
run the collector at a non-standard rate) then you should re-visit the
RRA definitions and probably make adjustments to them. A particular
example of adjusting rrd-polling-interval would be using Cricket to
monitor a 155 Mbit OC3 link. Because an SNMP Counter32 can wrap in
under 5 minutes at bandwidths above 100 Mbits, it's critical to fetch
the data more often, or else RRD will not be able to correctly detect
and process the counter wrap.
Hopefully in the next few versions, we will have an
example of a part of the config tree optimized for very fast
interfaces.
rrd-max
Default value: unset
If this tag is present, it will override the same tag in the
datasource dictionary. See the entry on rrd-max there for
more information.
rrd-min
Default value: unset
If this tag is present, it will override the same tag in the
datasource dictionary. See the entry on rrd-min there for
more information.
short-desc
Default value: unset
This description shows up in the target selection table which the CGI
program displays. It is a good idea to keep this description to one
line. You can include your own HTML in it as long as you close all
tags that you open.
snmp
Default value: none
This tag is not directly used by Cricket except when it is doing
instance mapping. However, it is convention (as exemplified by the
sample-config tree) that this tag should hold the SNMP community
string, the hostname, and the port number in the exact form that is
required by the snmp:// ds-source specification. Thus, ds-sources can
simply start with snmp://%snmp%/, and they will incorporate
the current host, port, and community string into the ds-source tag as
soon as they are expanded with respect to the current target.
When using instance mapping, the snmp tag is used directly,
so it must be present, even if you are using another convention to get
the data into the ds-source tags.
snmp-uptime
Default value: none
If an snmp-uptime tag is specified, collector will
retrieve the specified SNMP object and interpret it as the remote
device uptime. If the uptime is less than the rrd-poll-interval,
Cricket will assume the device has been rebooted and will ignore the
previous value of any COUNTERs on the device (effectively
instructing RRD to just store the value as a baseline for the next sample).
This tag should only be used if you must use COUNTER
rather than DERIVE as the datatype for your data, because
checking the uptime will not protect you against a host of other
causes for spurious counter wraps. Use at your own risk, most users
should just use the DERIVE datatype for counters.
Example: snmp-uptime = 1.3.6.1.2.1.1.3.0
This example shows how to use the system.sysUptime object to
determine the device uptime. This tag only makes sense in the
target --default-- stanza, because specifying it will affect
all collected counters.
If not specified, Cricket will not monitor device uptime for reboots.
summary-loc
Default value: top
This tag controls where the "Summary" box appears on the page. There
may be instances where you want it on the bottom instead of the top.
This could be useful for aggregate pages where you only care about the graphs
and not so much the content. To have it display on the bottom, change the tag
to 'bottom'.
targets
Default value: none
If this tag exists, then this target is considered by Cricket to be a
multi-target. To the collector, this means that it simply doesn't need
to collect anything, and can skip the target. To the grapher, it means
this target will aggregate the data from several different targets all
onto one report. The syntax is a semi-colon delimited list of targets.
The target definition can either by fully-qualified, which would look
like "/router-interfaces/Datacenter1/ds3-1", or unqualified, in which case
they are assumed to be in the current directory.
For targets with vector instance definitions, it may also be useful to
specify which instance you wish to display. You can do that by putting
a colon after the target definition. So, it would look something like
this: targets="/switch-ports/switch-1:3;/switch-ports/switch-2:5..7". This
would put up instance #3 from switch-1, and instance #5, #6, and #7 from
switch-2. Variable expansion is handled in the instance definition
section as well.
This functionality assumes that the target-type of each of the specified
targets is the same. You also must set a target-type for the multi-target
itself. There are some variables which control the presentation of this
data, which are also listed in this reference.
targets-long-desc
Default value: none
This tag sets the text which is displayed above each graph in a "targets"
multi-target. It should be an array of the same length as the "targets" array.
This value overrides the default presentation, and also overrides the tag
targets-short-desc. Syntax would look like:
targets-long-desc="('Target1','Target2')"
targets-short-desc
Default value: none
By default above each graph in a targets multi-target page, the short-desc
of each target being displayed is printed above that graph (as well as
some other text). This replaces that text with this. It should be an
array which matches the "targets" array. The syntax would look the same as
for targets-long-desc.
target-type
Default value: none
This tag sets the target type for this target. It must be one of the
target type names from the targetType dictionary. Cricket uses the
targetType to decide which variables to fetch, and how much data to
store in the RRD.
trap-address
Default value: unset
This tag is used to tell Monitor.pm where to send SNMP traps when
it needs to send one. The format should be community@hostname:port.
You can safely leave off community and port. The defaults are "public",
and "162", respectively.
unknown-is-zero
Default value: unset
When this tag is set and the target is part of a multitarget
which has mtargets-ops set, then data which is unknown
will be treated as a 0, unless all targets of the multitarget are
unknown (in which case the value is still unknown).
This is very useful when trying to create
aggregate graphs that sum a set of targets that span different time
ranges. By default, places where one target is
unknown and the others are known
will show on the graph as unknown (blank). In some cases, this
can result in no graph appearing at all (when the set of known
datapoints are completely disjoint). Set this flag to "true" to
avoid this problem.
In addition, the following tags are set automatically by Cricket for
your use in other tags in the target dictionary:
auto-target-name
Default value: automatically set
The short name of the current target. This does not include the entire
path from the config tree root to the target.
auto-target-path
Default value: automatically set
The path leading from the base of the config tree to the current
target.
auto-base
Default value: automatically set
The config tree root directory. This is especially useful for creating
paths which you want to be relative to the config tree root. For
instance, setting rrd-datafile to
%auto-base%/../cricket-data/foo.rrd would put the datafile in a
directory named cricket-data, next to the base of the config tree.
auto-view
Default value: automatically set
The name of the current view, as selected using the user interface.
This is sometimes useful to incorporate into strings used in the user
interface via the HTML dictionary.
This dictionary tells Cricket everything it needs to know about
individual datasources. A datasource is a single variable about a
target which is polled and logged. For instance, a datasource for a
router interface would be "inbound bandwidth". A separate datasource
definition is needed for each of the other variables that you might
want to measure ("outbound bandwidth", for instance).
desc
Default value: unset
If this tag is set, the value is incorporated into a key at the bottom
of the page of graphs. This is a very good place to put notes about
how the value is measured, what uncertainty there is in the
measurement, etc. You can put arbitrary HTML into it, as long as you
close any tags that you open. If there are no datasources with a
description, then no key will be printed. Only datasources with
descriptions will be present in the key.
ds-source
Default value: none
This tag is used to tell Cricket where to fetch the data from. There
is a scheme identifier from the beginning until the first
colon. Everything after the first colon is defined on a per-scheme
basis. The scheme identifier is case-insensitive.
The per-scheme part is expanded with respect to the target dictionary
immediately before it is resolved into measurements, making it
possible to plug values from the target dictionary into the ds-source
at runtime. Likely candidates for this substitution include the SNMP
hostname and community string, the instance number (which is appended
to table-base OID's), and some or all of the command line for EXEC
datasources.
Here's a detailed description of each scheme.
SNMP
These ds-sources look like this:
snmp://community@hostname:port/oid. The hostname part
can be either an IP address or a domain name. It will be resolved
with gethostbyname() in the latter case. The oid part can
include a text label which will be expanded from the OID
dictionary.
EXEC
This ds-source is used to tell Cricket to run a shell
command in order to fetch the value or values required for a
target. After the exec: scheme identifier comes
an integer followed by a colon, followed by a command (including
whatever arguments are required for the command). The number
chooses a line of output from the command (starting from line
0). For example, say the "vmstat" program on your system prints
this when given the "-s" argument:
350 swap ins
2982 swap outs
239 pages swapped in
3298 pages swapped out
(etc...)
Then the following datasource would fetch the number of pages
swapped out:
exec:3:vmstat -s
Note that we allow the text output from the command
(i.e. "pages swapped out")
to go in to Cricket. As of version 0.64, Cricket ignores everything
after the first space or tab. It will attempt to interpret the
first sequence of non-space characters on the line as a floating
point number. Since an integer is a degenerate form of a floating
point number, they are acceptable. This behavior holds for all
ds-sources, actually, but it is most useful for the EXEC type.
If the initial integer is omitted (and there are no colons in the
command line to confuse Cricket) then the line number will be
assumed to be 0, and the first line of output will be used as
the measurement.
FILE
This ds-source tells Cricket to read a file and find the
results on a certain line of that file. The line is specified
using the same syntax as EXEC. For example, say the file /tmp/data
has two lines in it, like this:
100
235
Then this datasource would always fetch "235" from the file:
file:1:/tmp/data
Presumably, there would be some other process updating the data
file with interesting data from someplace, or else the graph
would be a flat line at 235.
FIELD
This datasource is based on the FILE library. It is used to extract
specific fields from a file. It is analog to a cricket version of cut(1).
FIELD ds-source look like:
field:filename:key:valuef:keyf:delim
key is the field to grab. valuef is which key section from to grab (defaults to 2). keyfis which key to grab based on the delimiter (defaults to 1). delimis the delimiter (defaults to :).
FUNC
This ds-source uses a Perl function to fetch the result. It
is not enabled by default, since it requires extra code
to be useful, and could be a security vulnerability, if the
config tree were not properly protected. To enable it,
uncomment the line use func; in collector.
This ds-source uses Perl's eval keyword to evaluate
some Perl code at runtime. Usually, this will be a function
call to a function you have written yourself and added into
collector. A good way to add the code portably is to
keep it in its own file and incorporate it with the
require keyword. You will need to be careful to avoid
stomping on any data that collector uses, since it will be
running your code in its namespace. This should be fixed
someday, if many extensions to Cricket use this interface.
PERFMON (warning: still in development)
This ds-source is used to extract perflib information from Win32 hosts
which don't use SNMP (or where counters aren't available through SNMP).
Setting up perflib counters in Cricket is not a trivial process, and requires
the following: RRDtool 1.1.x, comfort with RPN, and ActiveState perl. This
module will not under any circumstances work with any non-Windows OS.
Perflib counter procedures are documented more in depth in the
Perfmon reference document.
Instance is optional, and only required for instance counters. Unlike
the perfmon.exe application in NT. Special is optional as well and is
documented in the perfmon reference document.
If you're collecting an "instant" perfmon counter, collection is much like
getting something from SNMP. Here is an example.
perfmon:%auto-host-name%:System:Processes
Many perfmon counters return averages which need to be computed against a
timebase. This makes collection challenging because you need to first collect
several DERIVE-based datasources, and then tie them together with a COMPUTE
datasource. The sample-config directory has a large amount of examples with
common counters to help, and there is the perfmon
reference document.
Please note that this piece of Cricket is still not complete and hasn't been
tested very well. Please let the developers know if you find any major bugs
or have any enhancement suggestions.
SQL (warning: still in development)
This ds-source is used to for extracting counters from a database
server. It's still in development and not very robust.
Here is the syntax:
sql:login:password:query:col:DRIVER
col is used to get a particular column of data returned from the
first returned row. Currently any other rows returned get discarded.
DRIVER can have colons in it. Cricket's parser will not treat it
like separate arguments to the ds itself.
Here is an example:
sql:anonymous::select top 1 samplevalue from samplednumericdata where idsamplednumericdatasource = 'C04E3055-B282-4EE9-9F5D-CB46DC45C988' order by timesampled desc:1:dbi:Sybase:NMSDB
WBEM (warning: still in development)
This ds-source is used to extract WBem information from Win32 hosts.
Currently this requires ActiveState Perl and will not run under any non-
Windows OS. It has not been tested for compatibility against a UNIX WBem
data provider.
Datasources are batched together and executed with as few network
transactions or shell executions are possible. For instance, if you
are fetching six datasources from the same hostname, all six
datasources will be rolled into one SNMP request. Likewise, if you
are fetching 3 different lines from the results of the same command,
that command will be run only once.
Schemes are expected to return their data as an array of numbers.
If the values are of the form "XXX@YYY", then the measurement XXX
will be recorded as being taken at time YYY. The time must be in the
form of a Unix time_t, i.e. number of seconds since 1970.
Currently, this feature is only supported by the EXEC and FILE schemes.
RRD imposes the restriction that data can only be added in
strictly ascending time order. Each datasource which has a time in it
should have a matching
time. If this is not the case, Cricket will log a warning, but use
the first time it found in the array.
You might use this
feature if you are fetching the data from another data collection
system which is operating on a different polling cycle than Cricket.
You could use a shell script to fetch the data from the other
system, along with the time the data was sampled. Then you
could format the result into the "XXX@YYY" format, and print it to
standard out for Cricket to read.
New schemes can be added to Cricket with minimal effort. Use the file
lib/exec.pm as your guide, then add a use statement
for your new .pm file to collector.
rrd-ds-type
Default value: GAUGE
The DS type is used by RRD to know how to interpret the numbers
fetched from this datasource. There are three possibilities:
GAUGE
The measurement will be directly copied into the RRD
datafile without any extra processing. Examples of this
type of measurement include readings from thermometers,
percent disk space free, etc.
COUNTER
The measurements from COUNTER datasources will be treated
like SNMP counters. An SNMP counter increases monotonically
until a fixed wrap-around point (usually either 2^31-2 or 2^63-2,
depending on the size of the data type). To convert a COUNTER
measurement into a rate (for instance, "count of octets" to
"octets per second") RRD subtracts the previous value from the
current one, and adjusts for any wraparound conditions. Any
SNMP variable which is marked with the SNMP "COUNTER" data type
would normally have its rrd-ds-type set to COUNTER,
but unless your datasource guarantees a monotonous increase,
it is better to use DERIVE with an rrd-min of zero.
DERIVE
DERIVE is like COUNTER, but there is no overflow check, so
negative rates are possible. This datasource type would be
useful when you have a count of something (which may increase
and decrease), and you want to graph the rate of change.
With an rrd-min of zero, the DERIVE datasource type acts like
COUNTER, except that negative samples are treated as unknown.
Handling SNMP COUNTERs in this fashion helps reduce the occurrence
of spikes in the graphs. Negative values can result from
restarting the device or implementation errors in its SNMP agent,
and are common enough to really recommend using DERIVE rather than
COUNTER.
ABSOLUTE
ABSOLUTE is for COUNTERs which get reset upon reading. Some
SNMP variables have this property. Using ABSOLUTE instead of COUNTER
tells RRD to compute the rate assuming the value is an absolute
count of octets (or whatever) during the last polling period.
The datasource type names are case-insensitive. They are passed
directly through to RRD when the RRD file is created. If the
datasource type is changed later, you must use rrd-tune to
apply the change to the underlying RRD file. For more information
about them, consult the RRD documentation for the create
command.
rrd-heartbeat
Default value: 1800 (value is in seconds)
The heartbeat for a datasource is the number of seconds that can pass
between updates before the datasource is marked unknown. If this tag
is changed after the RRD file has been created, then the rrd-tune tool must be used to apply the changes
to the existing RRD's.
rrd-max
Default value: U
This tag is used to set the RRD maximum value parameter. If RRD gets a
value higher than this number, it will throw the data away, instead of
adding it to the RRA. This can be used to filter bad data, though it
could be argued it would be better to simply avoid fetching bad data
in the first place. When it is set to "U" (for unknown), RRD does not
attempt to check incoming data against an upper bound.
If the tag rrd-max is present in the target dictionary,
it will override the value found in the datasource dictionary.
This makes is possible to assign different maxima to different
targets.
If this value is changed after the underlying RRD file has been
created, the rrd-tune script must be used to apply the
changes.
rrd-min
Default value: U
Like rrd-max, this tag is passed through to RRD
unchanged. It can be used to apply an upper bound to data
submitted to RRD.
Also like rrd-max, if rrd-min appears in the target
dictionary, it will override the rrd-min in the datasource
dictionary.
The TargetType dictionary tells Cricket which datasources
to gather together for a certain kind of target. Unlike
other dictionaries, keys in this one can occur multiple
times.
ds
Default value: none
Each ds tag tells Cricket about a variable it will be
fetching. The value of the tag must be comma-separated list
of known datasource names.
view
Default value: none
A view is a subset of the datasources that you'd like to display
together, apart from the rest of the datasources. The syntax
for the value is "view-name: ds ds ...". The view name you choose
shows up in the CGI grapher, so you should try to make it
descriptive. The space-separated list of datasources after the colon
must be datasources that are part of the target type. You can specify
several views by separating them by commas.
The graph dictionary controls how individual variables are displayed
when it comes time to graph them. The graph dictionary is structured
exactly the same as the datasource dictionary, and in some ways they
could be merged. For historical reasons, or architectural reasons (I
haven't decided yet...) they remain separate dictionaries.
There are actually two "flavors" of graph dictionary tags;
per-datasource and generic. The generic tags relate to the graphs
themselves, as opposed to the individual datasources drawn onto the
graphs. For instance, the width and height of a graph are configured
by generic tags, whereas the color of a datasource is configured by a
per-datasource tag. Per-datasource tags are stored in the graph
dictionary just as all the tags in the datasource dictionary are
stored. Generic tags are stored only in the --default--
dictionary.
Below, the generic tags are listed.
height
Default value: 200
This tag defines the requested height of the data area of the
graph. This value is passed into RRD, which then draws the actual
image
somewhat bigger, in order to leave room for the margin, the scales, and
the legend.
height-hint
Default value: none
HTML defines image sizing tags that allow the browser to layout the
page more efficiently. Using the Cricket's size hints,
you can control what image
sizing tags Cricket generates in its HTML output. Most browsers will
attempt to scale the image if the size hints passed in via HTML do not
match the actual size of the image. The result is a hard-to-read graph
that took too long to draw. Thus it is critical that if you
choose to use sizing hints to help the browser layout the page, you
make them precisely the same as the size of the generated image.
Because RRD pads the image with extra space, it's not possible for
Cricket to guess the finished size of the image using the width
and height tags. Instead, you need to find this number
yourself by measuring an actual image produced by RRD. In Netscape
Navigator, you
can do this by right clicking on the image, then choosing Open this
Image. Once the image is loaded, check the title bar for the actual
size of the image.
default-ranges
Default value: "d:w"
What set of graphs are initially displayed. If you tend to be
fetching graphs at low bandwidth, you might like to frob this.
Setting it to "d", will make Cricket only send you the daily
graph, instead of the daily and weekly graphs.
interlaced
Default value: false
Set this tag to true to enable interlaced image. An interlaced image
will appear to "fade in" in most web browsers.
Set this tag to 'gif' to get RRD Tool to create GIFs.
The GIFs created by RRD are big and slow, because they do not use
patented compression techniques. Cricket will use GIFs if the
browser will not support PNG's.
rrd-graph-args
Default value: none
This tag can be used to pass through arguments to the RRD Tool.
The most appropriate use for this tag is to send color tags through
to the RRD Tool. For instance, to make the canvas that the graph
is drawn on appear black, you can set rrd-graph-args
to "-c CANVAS#000000". This tag is split on whitespace before
it is sent to RRD Tool, so it is not possible at this time to
send arguments with embedded whitespace to RRD Tool.
vrule-color
Default value: none
Vertical rules are lines added to the graph by Cricket to help you
visually find patterns in the data related to time of day. A vertical
rule is placed at each "zero time" which appears on a graph. For an
hourly graph, a zero time is midnight. For a daily graph, a zero time
is the beginning of the most recent Monday.
For a weekly graph, a zero time is the first day of the month.
For a monthly graph, a zero time is the first day of the year.
At this time, the definition of zero time for a
given scale is hardcoded into Cricket's grapher.cgi script.
To enable vertical rules, use the vrule-color tag to choose a
color for them. That's all there is to it. If vrule-color is
defined, Cricket will automatically add the vertical rules for
you.
width
Default value: 500
Like height, this is the height of the data area of the graph. The
actual height of the resulting image will differ.
width-hint
Default value: none
Like height-hint above, this controls the value used
by Cricket for the height tag in its HTML output. See
height-hint for more information about how to set this.
y-max
Default value: none
Using this tag (and its opposite, y-min) you can
explicitly control the vertical scale of the graph.
If you use either y-min or y-max,
you disable auto-scaling, and so you must explicitly set both of them. These
tags are especially useful when you are graphing some value which should
normally be very tightly bounded (for instance between 0 and 1 second), but
occasionally jumps far above 1 second. In this case, all variation under
one second will be essentially invisible on the graph, unless you set the
y-min to 0 and the y-max to 1.
Because the graph dictionary is expanded with respect to the
target dictionary, you could say y-max = %specific-y-max%,
then set the tag specific-y-max on a per-target
basis.
In general, it's a good idea to leave these unset and rely on
auto-scaling, unless you have a situation that calls for explicit
bounds.
y-min
Default value: none
See y-max, above.
The following tags are per-datasource. They can occur in the
--default-- dictionary, in which case they are inherited into
all subsequent per-datasource dictionaries. However, unlike the
generic tags above, they are only ever referenced with respect to a
certain datasource.
bytes
Default value: none
If this is set to true, then the conversion to SI units will
use powers of 2 instead of powers of 10. For instance, if a router is
reporting that it's moving 1048576 bits per second through a
particular interface, and "bytes" is set to 1 (or "true") then
the value will be reported in the HTML summary as 1 Mbit/sec.
Without the bytes tag, the value would be reported at
1.04 Mbit/sec, which is slightly misleading. When measuring
very large numbers of bytes, the difference can be significant.
The numbers on the vertical axis of a graph are scaled
by powers of 2 if the bytes tag is set to true for any of the
datasources on the graph.
color
Default value: none
Use the color tag to explicitly control the color of the datasource
as it appears both on the graph, and in the HTML summary. If this is left
unset, then Cricket will automatically choose colors according to the
--order-- key in the color dictionary.
If you choose to set it, either set it to one of the color names in the color
dictionary, or set it to an HTML-style color specification without the
pound sign. For instance, to make a datasource's line red, set color to
"ff0000".
draw-as
Default value: ?
This tag tells Cricket how to draw the datasource on the graph. The choices
are as follows:
AREA
draws a filled-in shape representing the value of the datasource
over time.
LINE1
uses a thin line
LINE2
uses a medium line
LINE3
uses a heavy line
draw-max-as
Default value: LINE2
Same as draw-as but for maximums enabled with show-max.
legend
Default value: datasource name
Using legend allows you to customize the datasource name which is
displayed on the graph's legend, and in the HTML summary. If you don't
use a legend tag, the name of the datasource (as specified
by the ds tag in the targetType dictionary) will be used.
max-color
Default value: none
Same as color but for maximums enabled with show-max.
precision
Default value: 2
You can adjust the number of decimal points in the HTML summary values using
the precision tag. The default is two. If you simply want the value
displayed to be rounded to the nearest integer, set precision to
zero. Alternatively, you can set it to the string "integer".
scale
Default value: none
If scale is set, then the datasource is run through a computation
(usually a simple scaling operation) before it it plotted or listed
in the HTML summary. The tag is interpreted as a string of operations
that will be executed by a Reverse Polish Notation (RPN)
calculator, separated by commas. When the
expression begins executing, the current value of the datasource is
already on the stack. Thus setting scale to "8,*" will multiply
the datasource by 8 before plotting it.
The RPN operations available are "+" (plus), "-" (minus), "*" (multiply),
"/" (divide), and "LOG" (take the natural logarithm of the top of the stack).
Any other token is pushed onto the stack as a number. The top of the stack at the
end of the string of operations is taken as the scaled value.
This feature is very useful when plotting bits per second from a router
interface. Routers tend to report bandwidth in bytes per second, but
humans tend to think about link capacity in bits per second. Using a scale
tag of "8,*" can bridge this gap by scaling the bytes per second from the router
into bits per second for human use.
show-avg-max
Default value: true
This controls the amount of summary data shown on the top of graphs.
If set to true, Cricket makes an extra call to RRD Tool to fetch the
average and the maximum for the current day of data. If set to false, only
the current reading is shown.
show-max
Default value: false
This controls whether or not the maximums stored for a data source are drawn
on the graph.
si-units
Default value: true
Setting this tag to "false" will prevent Cricket from transforming
the value printed in the HTML summary into SI units (i.e.
2000 bytes/sec is transformed into 2 kbytes/sec). The scale
on the graph, however, will still have the transformation done
to it. Set this tag to "false" for items that are not typically
counted with SI units, like system load average.
Here are the SI units that are used by Cricket:
Symbol
Magnitude
Name
a
10e-18
Ato
f
10e-15
Femto
p
10e-12
Pico
n
10e-9
Nano
µ
10e-6
Micro
milli
10e-3
Milli
k
10e3
Kilo
M
10e6
Mega
G
10e9
Giga
T
10e12
Terra
P
10e15
Peta
E
10e18
Exa
Note that on graphs, 'milli' is denoted by 'm'. In the HTML summary,
where there is more room, Cricket uses the less ambiguous 'milli'.
space
Default value: one space
This tag can be used by the extremely fastidious user to control the HTML
summary. Usually, one space is exactly what you'd want between the value
and the unit specifier of the value. However, for certain units, like the
degree sign, no space is called for. In this case, set space
to "", the empty string.
units
Default value: the value of the y-axis tag
In the HTML summary, the units tag is appended after the
value of the datasource. If a datasource is collecting bandwidth information,
for instance, it would make sense to set y-axis to "bits per second",
since there is plenty of room for it. In the legend, where room is more limited,
it would be better to set units to "bps", instead of letting it
default to "bits per second".
y-max
Default value: unset
See y-max in the generic section. If there is a generic
y-max, it overrides the per-datasource y-max.
If there are multiple per-datasource y-maxes, then the maximum of
all of them is used.
The color dictionary is used to configure Cricket's auto-color
selection system and to map color names to HTML-style color
specifications (without the pound sign).
Every key, except for the special key --order--
is considered a color name, and should have a color specification.
The special key --order-- is used to tell Cricket what order to
assign the colors when doing auto-selection.
An HTML-style color specification consists of three hex numbers ranging
from 00 to ff. The numbers represent the intensity of
the red, green, and blue components of the final color.
For an example of a correctly configured color dictionary, see the
Defaults file in the root of the sample config tree.
The OID dictionary is a convenient place to put OID's to make the
config files more readable. Before any SNMP operation, the user-supplied
OID is scanned. Any text parts of the OID that match an entry in the
OID dictionary get replaced. Note that this is a separate process from
variable expansion, for historical reasons. The keys and values in
this table are separated by whitespace. Each entry starts with the
keyword "OID".
In keeping with the conventions of ASN.1 and SNMP, OID names
are case insensitive, must start with a letter, and can
otherwise consist of letters and numbers.
The HTML dictionary holds components of the UI that is
created by the grapher using HTML. Before it is used,
the HTML dictionary is expanded with respect to itself.
auto-error
Default value: any errors generated on this page
Any runtime errors that the grapher finds while attempting
to create the page are added to this tag. It is usually
referenced in the page-footer.
Note that only
errors that Cricket can find while it's running will show
up here. Problems finding the Perl interpreter, or parsing
grapher.cgi will still show up in the webserver's
error log.
auto-long-version
Default value: the contents of the VERSION file
This is the complete version string, including the version
number and the time it was packaged for release.
auto-short-version
Default value: the version number
This is simply the version number from the
complete Cricket version string.
auto-title
Default value: the title
This tag is set by the grapher to the title it expects
to use on this page. It is normally referenced in the
head tag.
body-options
Default value: none
This tag is incorporated into the HTML body tag. This is
the perfect place to set a background color. It's not
useful for much else, unless you want your graphs to play
a MIDI file in the background.
head
Default value: none
This is HTML that will be inserted between the <head>
and </head> tags. It can be used to incorporate a cascading
style sheet into the Cricket user interface. This would allow
you to easily control aspects of the UI design that are hardcoded
in the source code.
To incorporate a CSS called "cricket.css", use a head
tag like this:
html head
<link rel="stylesheet" src="cricket.css" type="text/css">
page-footer
Default value: none
This is the HTML that will go on the bottom of the page. As Cricket
is shipped, it includes a link to the RRD Tool website. Tobias
Oetiker, the author of RRD Tool, has respectfully
asked frontend authors to
feature a link to RRD Tool. Please take into account his wishes
as you edit this tag.
The version of page-footer in the sample-config directory
refers to a tag called contact, which can be used to put
sub-tree specific contact information into the bottom of the page.
This is only meant as an example. You might choose to put completely
different information at the bottom of the page.
page-header
Default value: none
This is the HTML that will go at the top of the page,
after the <body> tag, but before the rest of the
user interface. As shipped, it illustrates how you might
put a company logo on each page.
This dictionary holds information related to events. An
event is some point in time which you'd like to mark on graphs
so that later, you'll remember why it was that those graphs
look the way they do. An event is named, just like a target
or a datasource. The event
names are used in the target dictionary tag called events.
See the entry for that tag for more information.
Each event should have the following tags set:
color
The color of the event. This should be the name of a color in the
color dictionary.
date
The time the event happened, which controls where on a graph the
vertical rule appears.
name
This is the text that will show up in the legend on the graph.
The RRA dictionary holds parameters used by Cricket when it is setting
up a new RRD file. These parameters control how much data RRD stores,
and on what schedule it consolidates high resolution data into lower
resolution data.
The RRA dictionary that ships with Cricket in the
sample config tree will rollup and retain data using the same schedule
that MRTG 2.x has used for years. This has proven satisfactory for
most users. If you change the polling rate from 5 minutes, this
dictionary needs to be edited. Likewise, if you want to keep history
farther back in time, you'll need to edit these entries.
Because this table is only used when a new RRD is being created,
you would need to delete any existing datafile, losing all of the data
in it, before a change to the RRA dictionary takes effect.
For more information on the format of these dictionary entries, read
the RRD Tool documentation on the "create" command.