1COLLECTD-EXEC(5) collectd COLLECTD-EXEC(5)
2
6 collectd-exec - Documentation of collectd's "exec plugin"
7
9 # See collectd.conf(5)
10 LoadPlugin exec
11 # ...
12 <Plugin exec>
13 Exec "myuser:mygroup" "myprog"
14 Exec "otheruser" "/path/to/another/binary" "arg0" "arg1"
15 NotificationExec "user" "/usr/lib/collectd/exec/handle_notification"
16 </Plugin>
17
19 The "exec plugin" forks off an executable either to receive values or
20 to dispatch notifications to the outside world. The syntax of the
21 configuration is explained in collectd.conf(5) but summarized in the
22 above synopsis.
23 If you want/need better performance or more functionality you should
25 take a long look at the "perl plugin", collectd-perl(5).
26
28 There are currently two types of executables that can be executed by
29 the "exec plugin":
30 "Exec"
32 These programs are forked and values that it writes to "STDOUT" are
33 read back. The executable is forked in a fashion similar to init:
34 It is forked once and not again until it exits. If it exited, it
35 will be forked again after at most Interval seconds. It is
36 perfectly legal for the executable to run for a long time and
37 continuously write values to "STDOUT".
38 See "EXEC DATA FORMAT" below for a description of the output format
40 expected from these programs.
41 Warning: If the executable only writes one value and then exits it
43 will be executed every Interval seconds. If Interval is short (the
44 default is 10 seconds) this may result in serious system load.
45 "NotificationExec"
47 The program is forked once for each notification that is handled by
48 the daemon. The notification is passed to the program on "STDIN"
49 in a fashion similar to HTTP-headers. In contrast to programs
50 specified with "Exec" the execution of this program is not
51 serialized, so that several instances of this program may run at
52 once if multiple notifications are received.
53 See "NOTIFICATION DATA FORMAT" below for a description of the data
55 passed to these programs.
56
58 The forked executable is expected to print values to "STDOUT". The
59 expected format is as follows:
60 Comments
62 Each line beginning with a "#" (hash mark) is ignored.
63 PUTVAL Identifier [OptionList] Valuelist
65 Submits one or more values (identified by Identifier, see below) to
66 the daemon which will dispatch it to all its write-plugins.
67 An Identifier is of the form "host/plugin-instance/type-instance"
69 with both instance-parts being optional. If they're omitted the
70 hyphen must be omitted, too. plugin and each instance-part may be
71 chosen freely as long as the tuple (plugin, plugin instance, type
72 instance) uniquely identifies the plugin within collectd. type
73 identifies the type and number of values (i. e. data-set) passed to
74 collectd. A large list of predefined data-sets is available in the
75 types.db file. See types.db(5) for a description of the format of
76 this file.
77 The OptionList is an optional list of Options, where each option is
79 a key-value-pair. A list of currently understood options can be
80 found below, all other options will be ignored. Values that contain
81 spaces must be quoted with double quotes.
82 Valuelist is a colon-separated list of the time and the values,
84 each either an integer if the data-source is a counter, or a double
85 if the data-source is of type "gauge". You can submit an undefined
86 gauge-value by using U. When submitting U to a counter the behavior
87 is undefined. The time is given as epoch (i. e. standard UNIX time)
88 or N to use the current time.
89 You can mix options and values, but the order is important: Options
91 only effect following values, so specifying an option as last field
92 is allowed, but useless. Also, an option applies to all following
93 values, so you don't need to re-set an option over and over again.
94 The currently defined Options are:
96 interval=seconds
98 Gives the interval in which the data identified by Identifier
99 is being collected.
100 Please note that this is the same format as used in the unixsock
102 plugin, see collectd-unixsock(5). There's also a bit more
103 information on identifiers in case you're confused.
104 Since examples usually let one understand a lot better, here are
106 some:
107 PUTVAL leeloo/cpu-0/cpu-idle N:2299366
109 PUTVAL alice/interface/if_octets-eth0 interval=10 1180647081:421465:479194
110 PUTNOTIF [OptionList] message=Message
112 Submits a notification to the daemon which will then dispatch it to
113 all plugins which have registered for receiving notifications.
114 The PUTNOTIF if followed by a list of options which further
116 describe the notification. The message option is special in that it
117 will consume the rest of the line as its value. The message,
118 severity, and time options are mandatory.
119 Valid options are:
121 message=Message (REQUIRED)
123 Sets the message of the notification. This is the message that
124 will be made accessible to the user, so it should contain some
125 useful information. As with all options: If the message
126 includes spaces, it must be quoted with double quotes. This
127 option is mandatory.
128 severity=failure|warning|okay (REQUIRED)
130 Sets the severity of the notification. This option is
131 mandatory.
132 time=Time (REQUIRED)
134 Sets the time of the notification. The time is given as
135 "epoch", i. e. as seconds since January 1st, 1970, 00:00:00.
136 This option is mandatory.
137 host=Hostname
139 plugin=Plugin
140 plugin_instance=Plugin-Instance
141 type=Type
142 type_instance=Type-Instance
143 These "associative" options establish a relation between this
144 notification and collected performance data. This connection is
145 purely informal, i. e. the daemon itself doesn't do anything
146 with this information. However, websites or GUIs may use this
147 information to place notifications near the affected graph or
148 table. All the options are optional, but plugin_instance
149 without plugin or type_instance without type doesn't make much
150 sense and should be avoided.
151 type:key=value
153 Sets user defined meta information. The type key is a single
154 character defining the type of the meta information.
155 The current supported types are:
157 s A string passed as-is.
159 Please note that this is the same format as used in the unixsock
161 plugin, see collectd-unixsock(5).
162 When collectd exits it sends a SIGTERM to all still running child-
164 processes upon which they have to quit.
165
167 The notification executables receive values rather than providing them.
168 In fact, after the program is started "STDOUT" is connected to
169 "/dev/null".
170 The data is passed to the executables over "STDIN" in a format very
172 similar to HTTP: At first there is a "header" with one line per field.
173 Every line consists of a field name, ended by a colon, and the
174 associated value until end-of-line. The "header" is ended by two
175 newlines immediately following another, i.e. an empty line. The rest,
176 basically the "body", is the message of the notification.
177 The following is an example notification passed to a program:
179 Severity: FAILURE
181 Time: 1200928930.515
182 Host: myhost.mydomain.org
183 \n
184 This is a test notification to demonstrate the format
185 The following header files are currently used. Please note, however,
187 that you should ignore unknown header files to be as forward-compatible
188 as possible.
189 Severity
191 Severity of the notification. May either be FAILURE, WARNING, or
192 OKAY.
193 Time
195 The time in epoch, i.e. as seconds since 1970-01-01 00:00:00 UTC.
196 The value currently has millisecond precision (i.e. three decimal
197 places), but scripts should accept arbitrary numbers of decimal
198 places, including no decimal places.
199 Host
201 Plugin
202 PluginInstance
203 Type
204 TypeInstance
205 Identification of the performance data this notification is
206 associated with. All of these fields are optional because
207 notifications do not need to be associated with a certain value.
208
210 The following environment variables are set by the plugin before
211 calling exec:
212 COLLECTD_INTERVAL
214 Value of the global interval setting.
215 COLLECTD_HOSTNAME
217 Hostname used by collectd to dispatch local values.
218
220 Though the interface is far from perfect, there are tons of plugins for
221 Nagios. You can use these plugins with collectd by using a simple
222 transition layer, "exec-nagios.px", which is shipped with the collectd
223 distribution in the "contrib/" directory. It is a simple Perl script
224 that comes with embedded documentation. To see it, run the following
225 command:
226 perldoc exec-nagios.px
228 This script expects a configuration file, "exec-nagios.conf". You can
230 find an example in the "contrib/" directory, too.
231 Even a simple mechanism to submit "performance data" to collectd is
233 implemented. If you need a more sophisticated setup, please rewrite the
234 plugin to make use of collectd's more powerful interface.
235
237 · The user, the binary is executed as, may not have root privileges,
238 i. e. must have an UID that is non-zero. This is for your own
239 good.
240 · Early versions of the plugin did not use a command but treated all
242 lines as if they were arguments to the PUTVAL command. When the
243 PUTNOTIF command was implemented, this behavior was kept for lines
244 which start with an unknown command for backwards compatibility.
245 This compatibility code has been removed in collectd 5.
246
248 collectd(1), collectd.conf(5), collectd-perl(5), collectd-unixsock(5),
249 fork(2), exec(3)
250
252 Florian Forster <octo@collectd.org>
2535.9.2 2019-09-16 COLLECTD-EXEC(5)