1COLLECTDCTL(1) collectd COLLECTDCTL(1)
2
6 collectdctl - Control interface for collectd
7
9 collectdctl [options] <command> [command options]
10
12 collectdctl provides a control interface for collectd, which may be
13 used to interact with the daemon using the "unixsock plugin".
14
16 collectdctl supports the following options:
17 -s socket
19 Path to the UNIX socket opened by collectd's "unixsock plugin".
20 Default: /var/run/collectd-unixsock
21 -h Display usage information and exit.
23
25 The following commands are supported:
26 getval <identifier>
28 Query the latest collected value identified by the specified
29 <identifier> (see below). The value-list associated with that data-
30 set is returned as a list of key-value-pairs, each on its own line.
31 Keys and values are separated by the equal sign ("=").
32 flush [timeout=<seconds>] [plugin=<name>] [identifier=<id>]
34 Flush the daemon. This is useful, e. g., to make sure that the
35 latest values have been written to the respective RRD file before
36 graphing them or copying them to somewhere else.
37 The following options are supported by the flush command:
39 timeout=<seconds>
41 Flush values older than the specified timeout (in seconds)
42 only.
43 plugin=<name>
45 Flush the specified plugin only. I. e., data cached by the
46 specified plugin is written to disk (or network or whatever),
47 if the plugin supports that operation.
48 Example: rrdtool.
50 identifier=<id>
52 If this option is present, only the data specified by the
53 specified identifier (see below) will be flushed. Note that
54 this option is not supported by all plugins (e. g., the
55 "network" plugin does not support this).
56 The plugin and identifier options may be specified more than once.
58 In that case, all combinations of specified plugins and identifiers
59 will be flushed only.
60 listval
62 Returns a list of all values (by their identifier) available to the
63 "unixsock" plugin. Each value is printed on its own line. I. e.,
64 this command returns a list of valid identifiers that may be used
65 with the other commands.
66 putval <identifier> [interval=<seconds>] <value-list(s)>
68 Submit one or more values (identified by <identifier>, see below)
69 to the daemon which will then dispatch them to the write plugins.
70 interval specifies the interval (in seconds) used to collect the
71 values following that option. It defaults to the default of the
72 running collectd instance receiving the data. Multiple
73 <value-list(s)> (see below) may be specified. Each of them will be
74 submitted to the daemon. The values have to match the data-set
75 definition specified by the type as given in the identifier (see
76 types.db(5) for details).
77
79 An identifier has the following format:
80 [hostname/]plugin[-plugin_instance]/type[-type_instance]
82 Examples:
84 somehost/cpu-0/cpu-idle
85 uptime/uptime
86 otherhost/memory/memory-used
87 Hostname defaults to the local (non-fully qualified) hostname if
89 omitted. No error is returned if the specified identifier does not
90 exist (this is a limitation in the "libcollectdclient" library).
91
93 A value list describes one data-set as handled by collectd. It is a
94 colon (":") separated list of the time and the values. Each value is
95 either given as an integer if the data-type is a counter, or as a
96 double if the data-type is a gauge value. A literal "U" is interpreted
97 as an undefined gauge value. The number of values and the data-types
98 have to match the type specified in the identifier (see types.db(5) for
99 details). The time is specified as epoch (i. e., standard UNIX time) or
100 as a literal "N" which will be interpreted as now.
101
103 "collectdctl flush plugin=rrdtool identifier=somehost/cpu-0/cpu-wait"
104 Flushes all CPU wait RRD values of the first CPU of the local host.
105 I. e., writes all pending RRD updates of that data-source to disk.
106 "for ident in `collectdctl listval | grep users/users`; do collectdctl
108 getval $ident; done"
109 Query the latest number of logged in users on all hosts known to
110 the local collectd instance.
111
113 collectd(1), collectd.conf(5), collectd-unixsock(5), types.db(5)
114
116 collectd has been written by Florian Forster <octo at collectd.org> and
117 many contributors (see `AUTHORS').
118 collectdctl has been written by HXkon J Dugstad Johnsen
120 <hakon-dugstad.johnsen at telenor.com> and Sebastian Harl <sh at
121 tokkee.org>.
1225.11.0.94.g41b1e33 2020-07-20 COLLECTDCTL(1)