XYMOND_RRD(8)

💖 xymond_rrd — the manual, but make it cute 💖

okay so bestie, welcome to xymond_rrd, from section 8 of the System Manager's Manual (that's the admin-stuff section, iykyk). she's a xymond worker module whose whole job is updating your Xymon RRD files. sit down, grab a strawberry, we're doing this. 🍓

---

✨ NAME ✨

xymond_rrd — a xymond worker module for updating Xymon RRD files. that's it, that's the name, she's iconic and she knows it. 💅

---

🌸 SYNOPSIS 🌸

xymond_channel --channel=status xymond_rrd [options]
xymond_channel --channel=data xymond_rrd [options]

two whole ways to summon her. look at her go. ✨

---

🦋 DESCRIPTION 🦋

so xymond_rrd is a worker module for xymond, which means she doesn't really do the solo-main-character thing — she's normally run via the xymond_channel(8) program. she receives "status" and "data" messages from xymond over stdin, and then updates the RRD databases that get used to generate your trend-graphs. graphs, bestie! the little lines! 📈

clients can send data to Xymon using both status- messages and data- messages. so yeah, you'll normally be running two instances of this module: one for the "status" channel and one for the "data" channel. two of her. double the slay. 👑

xymond_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, fr fr. 🐟

⚠️ Note, and this one matters: for certain types of data, the RRD files used by Xymon are incompatible with those generated by the Big Brother LARRD add-on. see the COMPATIBILITY section below. don't say I didn't warn you. 😭

---

💅 OPTIONS 💅

• --debug — turns on debugging output. she's telling you everything, no filter, we love a transparent queen. 🔍
• --rrddir=DIRECTORY — tells her where the RRD-files live. if you don't pass this option, xymond_rrd will use whatever location the XYMONRRDS environment variable points to. pick a home, bestie. 🏠
• --no-cache — by default xymond_rrd caches updates to the RRD files, so she doesn't have to do a million tiny disk writes — the data gets collected for a 30 minute period and then committed to disk in one single update. this option disables that caching, so data is stored on disk immediately. instant gratification, no waiting. ⚡
• --processor=FILENAME — xymond_rrd can send a parallel copy of all RRD updates to one single external process as a stream on its STDIN. the data comes in a format similar to the one rrdupdate(1) uses:

<rrdtemplate> ts:<rrdvalue(s)> host <rrdparameters>

and if that process exits? she just re-launches it. resilient queen. 🔁

• --extra-script=FILENAME — the script that gets run to grab RRD data for tests that aren't built into xymond_rrd. you also have to say which tests are handled by the external script, using the --extra-tests option. this option can only be given once, so that one script has to 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's only required for data where you've got a custom script parsing the status message and extracting the data that goes into the graph. 📜
• --extra-tests=TEST[,TEST] — the list of testnames handled by that external script. see the CUSTOM RRD DATA section below. and note that NCV graphs should NOT be listed here — those go in the TEST2RRD environment variable instead, see below. 🙅‍♀️
• --no-rrd — disables the actual writing of RRD files entirely. this is only really useful if you're sending all of the data destined for the RRD files off to an external processor (that's the --extra-script or --processor options). basically: she stops writing, the externals take over. ✂️

---

🌈 ENVIRONMENT 🌈

• TEST2RRD — defines the mapping between a status-log columnname and the corresponding RRD database format. this is normally defined in the xymonserver.cfg(5) file. 🗺️
• XYMONRRDS — the default directory where RRD files are stored. 📁
• NCV_testname — defines the types of data collected by the "ncv" module in xymond_rrd. see below for more info, bestie. 🔎
• SPLITNCV_testname — same energy as NCV_testname, but it keeps the data in separate files. like, it creates one rrd file per "NAME : value" line found in the status message. super useful when the list of NCV lines is varying. 🌱
• TRACKMAX — a comma-separated list of columnname for which you want to keep the maximum values alongside the default average values. this only works for the NCV backend. no cap, only NCV. 📊

---

🎀 COLLECTED DATA 🎀

these are the RRD-file datasets generated by xymond_rrd:

• la — records the CPU load average. data is collected from the "cpu" status report. requires that a Xymon client is running on the monitored server. 🖥️
• disk — records the disk utilization. data comes from the "disk" status report. requires a Xymon-compatible client running on the monitored server. 💾
• memory — records memory- and swap-utilization. data comes from the "memory" status report. if there's no "memory" status reported, she'll use the data from the Win32 client "cpu" status report to generate this dataset instead. requires a Xymon-compatible client running on the monitored server. 🧠
• netstat — records TCP and UDP statistics. data is collected from the "netstat" status report; but ngl, this data is often sent via the Xymon "data" protocol, so there doesn't need to be a "netstat" column visible on the Xymon 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; but again, this data is often sent via the Xymon "data" protocol, so there need not be a "vmstat" column visible on the Xymon 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 Xymon 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 hosts.cfg(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 one's an experimental set of data collected from BEA Weblogic servers via SNMP, by the "beastats" tool included with Xymon. 🧪
• 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 Xymon 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 Xymon contrib/ directory. 🖇️

---

okay that's the tea so far — part 2 is coming, don't go anywhere bestie 🫶

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

Okay bestie so listen — so many data-collection scripts out there report their data like "NAME : value" or "NAME = value", right? So there's a generic module inside xymond_rrd that makes tracking this kind of data so easy. 🎀

The ncv module will automatically detect every single occurrence 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 that message (unless you use SPLITNCV, see above 👀). The colon or the equal-sign must be there — if there's only whitespace, this module will fail. No cap. 💀

Only the valid letters (A-Z, a-z) and digits (0-9) get used in the dataset names; whitespace and other characters are stripped off automatically. And only the first 19 characters of a dataset name are used (that's an RRD limitation, not us being extra). Underscore '_' is not allowed, even though RRDtool permits it, and it will get stripped from the name too. Bye 👋

When you're using the alternative SPLITNCV_testname though, 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". Slay.

⚠️ Heads up: each "NAME : value" must be on a line by itself. If you've got a custom script generating the status- or data-message that gets fed into the NCV handler, make sure it inserts a newline before each of the data-items you want to track. Fr fr.

Any lines in the status message prepended with a "<!-- ncv_skip -->" will be skipped by the module. This is how you prevent unneeded RRD files from an existing dataset from being created. 🙈

A line prepended with a "<!-- ncv_skipstart -->" will be ignored, along with all subsequent lines until a line starting with "<!-- ncv_skipend -->" is found, at which point processing resumes. Perfect for ignoring explanatory text or other yapping in a mostly-ncv message. 💅

"<!-- ncv_ignore -->" can be used to ignore certain text at the beginning of a line, up until a closing '</-->' tag on the same line, at which point the line continues to be processed as usual. Wrapping is not supported; but skipstart/skipend can be used to handle multiple lines. 🫶

A bare "<!-- ncv_end -->" on its own line will stop further NCV processing of that message. Done. Periodt.

All of these ncv_ terms are case-sensitive. And ngl, if you have full control over your NCV output, it's most efficient to have your NCV data near the top of your message and use "<!-- ncv_end -->" once your data is complete. Efficiency is the vibe. ⭐

To enable the ncv module for a status, add a "COLUMNNAME=ncv" to the TEST2RRD setting and the COLUMNNAME to the GRAPHS setting in xymonserver.cfg(5), then restart Xymon. Xymon will now send all status-messages for the column COLUMNNAME through the xymond_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've got data that's of the type GAUGE, you can override the default via an environment variable NCV_COLUMNNAME (or SPLITNCV_COLUMNAME). 🌸

E.g. if you're 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 xymonserver.cfg:

NCV_mysql="Queriespersecondavg:GAUGE"

If you have multiple datasets that you must 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 xymond_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. And 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. Iconic. 👑

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 Xymon server. 📖

---

📡 SENDING METRIC DATA TO AN ADDITIONAL PROCESS 📡

xymond_rrd provides a mechanism to send a copy of isolated metric data to a single external processor for further processing. This can be used to inject metric data that xymond_rrd has prepared into other storage systems, such as OpenTSDB, graphite, etc. The data is printed in a format nearly suitable for injection using rrdupdate(1) and easily transformable to other formats. And if the process exits, xymond_rrd will re-launch it automatically. Resilient queen. 💖

---

🧚 CUSTOM RRD DATA VIA SCRIPTS 🧚

xymond_rrd provides a simple mechanism for adding custom graphs to the set of data collected on your Xymon server. By adding the "--extra-script" and "--extra-tests" options, data reported to Xymon from selected tests is 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 xymond_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 xymond_rrd tool or writing a separate stream listener that injects appropriate "trends" data messages back to xymond. Big data = big oof, bestie. 😭

Apart from writing the script, you must also add a section to graphs.cfg(5) so that showgraph.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 xymonserver.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 command-line 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 xymond_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 Xymon 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 xymond_rrd are incompatible with the files generated by the Big Brother LARRD add-on. Sad but true:

• 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 xymond_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 xymond_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. xymond_rrd uses a different RRD file-format with separate counters for packets and bytes and tracks whatever data the system is reporting.

---

👀 SEE ALSO 👀

xymond_channel(8), xymond(8), xymonserver.cfg(5), xymon(7)

---

And that's the whole page, bestie!! 🫶 This was Xymon, Version 4.3.30, dated 4 Sep 2019, and the manual page itself is XYMOND_RRD(8) — go forth and graph, you absolute legend. 💜✨