COLLECTDCTL(1)

💖 COLLECTDCTL 💖

okay bestie, welcome to collectdctl(1) — the manual page for the control interface of collectd, from the collectd gang. yes we're doing this, grab a snack 🍓

---

✨ NAME ✨

collectdctl — Control interface for collectd

---

🎀 SYNOPSIS 🎀

collectdctl [options] <command> [command options]

---

🦋 DESCRIPTION 🦋

So basically, collectdctl is your lil control interface for collectd, and you use it to talk to the daemon through the "unixsock plugin". That's it, that's the vibe. It's giving "remote control but make it UNIX socket". 💅

---

✨ OPTIONS ✨

collectdctl is out here supporting these options, no cap:

• -s socket — Path to the UNIX socket that collectd's "unixsock plugin" opened. Default is /var/run/collectd-unixsock — literally the default, don't come for me.
• -h — Display usage information and exit. the "help me bestie" button 🫶

---

👑 AVAILABLE COMMANDS 👑

These are the commands you get to play with, and they're all iconic:

🌸 getval <identifier>

Query the latest collected value that's identified by the <identifier> you gave it (peep the IDENTIFIERS section below, iykyk). The value-list tied to that data-set comes back as a list of key-value pairs, each one on its own line. Keys and values are separated by the equal sign ("="). periodt.

🌈 flush [timeout=<seconds>] [plugin=<name>] [identifier=<id>]

Flush the daemon. why do you care? because it's useful, e. g., when you wanna make sure the latest values actually got written to the respective RRD file before you graph them or copy them somewhere else. no stale data in the group chat 💀

The flush command supports these options:

• timeout=<seconds> — Flush values older than the specified timeout (in seconds) only.
• plugin=<name> — Flush the specified plugin only. I. e., data cached by the specified plugin gets written to disk (or network or whatever), if the plugin supports that operation. Example: rrdtool.
• identifier=<id> — If this option is present, only the data specified by the specified identifier (see below) will be flushed. Heads up bestie: this option is not supported by all plugins (e. g., the "network" plugin does not support this). 😭

The plugin and identifier options may be specified more than once. In that case, all combinations of specified plugins and identifiers will be flushed only.

🧚 listval

Returns a list of all values (by their identifier) available to the "unixsock" plugin. Each value is printed on its own line. I. e., this command hands you a list of valid identifiers that you may use with the other commands. it's the guest list fr fr 📝

💜 putval <identifier> [interval=<seconds>] <value-list(s)>

Submit one or more values (identified by <identifier>, see below) to the daemon, which will then dispatch them to the write plugins. interval specifies the interval (in seconds) used to collect the values following that option. It defaults to the default of the running collectd instance receiving the data. Multiple <value-list(s)> (see below) may be specified. Each of them will be submitted to the daemon. The values have to match the data-set definition specified by the type as given in the identifier (see types.db(5) for details). slay.

---

🌟 IDENTIFIERS 🌟

An identifier has this exact format, character for character:

[hostname/]plugin[-plugin_instance]/type[-type_instance]

Examples, bestie:

 somehost/cpu-0/cpu-idle
 uptime/uptime
 otherhost/memory/memory-used

Hostname defaults to the local (non-fully qualified) hostname if omitted. And ⚠️ no error is returned if the specified identifier does not exist (this is a limitation in the "libcollectdclient" library). yeah. it just. doesn't tell you. 🙈

---

🍓 VALUE-LIST 🍓

A value list describes one data-set as handled by collectd. It's a colon (":") separated list of the time and the values. Each value is either given as an integer if the data-type is a counter, or as a double if the data-type is a gauge value. A literal "U" is interpreted as an undefined gauge value. The number of values and the data-types have to match the type specified in the identifier (see types.db(5) for details). The time is specified as epoch (i. e., standard UNIX time) or as a literal "N" which will be interpreted as now. ⭐

---

💅 EXAMPLES 💅

okay these are the moments, let's go:

"collectdctl flush plugin=rrdtool identifier=somehost/cpu-0/cpu-wait"

Flushes all CPU wait RRD values of the first CPU of the local host. I. e., writes all pending RRD updates of that data-source to disk. ate. 🔥

"for ident in \collectdctl listval | grep users/users`; do collectdctl getval $ident; done"`

Query the latest number of logged in users on all hosts known to the local collectd instance. iconic loop behavior, honestly.

---

🌈 SEE ALSO 🌈

collectd(1), collectd.conf(5), collectd-unixsock(5), types.db(5)

---

💖 AUTHOR 💖

collectd has been written by Florian Forster <octo at collectd.org> and many contributors (see AUTHORS').

collectdctl has been written by HXkon J Dugstad Johnsen <hakon-dugstad.johnsen at telenor.com> and Sebastian Harl <sh at tokkee.org>.

---

and that's the whole page, bestie 🫶 this was version 5.11.0.94.g41b1e33, dated 2020-07-20, and it's part of the collectd manual. go forth and flush responsibly 💜✨