51
.\" Escape single quotes in literal strings from groff's Unicode transform.
51
55
.\" If the F register is turned on, we'll generate index entries on stderr for
52
56
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53
57
.\" entries marked with X<> in POD. Of course, you'll have to process the
54
58
.\" output yourself in some meaningful fashion.
57
61
. tm Index:\\$1\t\\n%\t"\\$2"
63
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64
.\" way too many mistakes in technical documents.
68
71
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69
72
.\" Fear. Run. Save yourself. No user-serviceable parts.
159
166
connections. Once a connection is established the client can send commands to
160
167
the daemon which it will answer, if it understand them.
169
In general the plugin answers with a status line of the following form:
171
\&\fIStatus\fR \fIMessage\fR
173
If \fIStatus\fR is greater than or equal to zero the message indicates success,
174
if \fIStatus\fR is less than zero the message indicates failure. \fIMessage\fR is a
175
human-readable string that further describes the return value.
177
On success, \fIStatus\fR furthermore indicates the number of subsequent lines of
178
output (not including the status line). Each such lines usually contains a
179
single return value. See the description of each command for details.
162
181
The following commands are implemented:
163
182
.IP "\fB\s-1GETVAL\s0\fR \fIIdentifier\fR" 4
164
183
.IX Item "GETVAL Identifier"
165
184
If the value identified by \fIIdentifier\fR (see below) is found the complete
166
value-list is returned. The response is a space separated list of
169
\&\fInum\fR \fIname\fR\fB=\fR\fIvalue\fR[ \fIname\fR\fB=\fR\fIvalue\fR[ ...]]
171
If \fInum\fR is less then zero, an error occurred. Otherwise it contains the
172
number of values that follow. Each value is of the form \fIname\fR\fB=\fR\fIvalue\fR.
185
value-list is returned. The response is a list of name-value-pairs, each pair
186
on its own line (the number of lines is indicated by the status line \- see
187
above). Each name-value-pair is of the form \fIname\fR\fB=\fR\fIvalue\fR.
173
188
Counter-values are converted to a rate, e.\ g. bytes per second.
174
189
Undefined values are returned as \fBNaN\fR.
177
192
\-> | \s-1GETVAL\s0 myhost/cpu\-0/cpu\-user
178
<\- | 1 value=1.260000e+00
194
<\- | value=1.260000e+00
179
195
.IP "\fB\s-1LISTVAL\s0\fR" 4
180
196
.IX Item "LISTVAL"
181
197
Returns a list of the values available in the value cache together with the
182
198
time of the last update, so that querying applications can issue a \fB\s-1GETVAL\s0\fR
183
command for the values that have changed.
185
The first line's status number is the number of identifiers returned or less
186
than zero if an error occurred. Each of the following lines contains the
187
update time as an epoch value and the identifier, separated by a space.
199
command for the values that have changed. Each return value consists of the
200
update time as an epoch value and the identifier, separated by a space. The
201
update time is the time of the last value, as provided by the collecting
202
instance and may be very different from the time the server considers to be
190
206
\-> | \s-1LISTVAL\s0
191
207
<\- | 69 Values found
192
<\- | 1182204284 leeloo/cpu\-0/cpu\-idle
193
<\- | 1182204284 leeloo/cpu\-0/cpu\-nice
194
<\- | 1182204284 leeloo/cpu\-0/cpu\-system
195
<\- | 1182204284 leeloo/cpu\-0/cpu\-user
208
<\- | 1182204284 myhost/cpu\-0/cpu\-idle
209
<\- | 1182204284 myhost/cpu\-0/cpu\-nice
210
<\- | 1182204284 myhost/cpu\-0/cpu\-system
211
<\- | 1182204284 myhost/cpu\-0/cpu\-user
197
213
.IP "\fB\s-1PUTVAL\s0\fR \fIIdentifier\fR [\fIOptionList\fR] \fIValuelist\fR" 4
198
214
.IX Item "PUTVAL Identifier [OptionList] Valuelist"
199
215
Submits one or more values (identified by \fIIdentifier\fR, see below) to the
200
daemon which will dispatch it to all it's write\-plugins.
216
daemon which will dispatch it to all it's write-plugins.
202
218
An \fIIdentifier\fR is of the form
203
219
\&\f(CW\*(C`\f(CIhost\f(CW\f(CB/\f(CW\f(CIplugin\f(CW\f(CB\-\f(CW\f(CIinstance\f(CW\f(CB/\f(CW\f(CItype\f(CW\f(CB\-\f(CW\f(CIinstance\f(CW\*(C'\fR with both
205
221
omitted, too. \fIplugin\fR and each \fIinstance\fR\-part may be chosen freely as long
206
222
as the tuple (plugin, plugin instance, type instance) uniquely identifies the
207
223
plugin within collectd. \fItype\fR identifies the type and number of values
208
(i.\ e. data\-set) passed to collectd. A large list of predefined
224
(i.\ e. data-set) passed to collectd. A large list of predefined
209
225
data-sets is available in the \fBtypes.db\fR file.
211
227
The \fIOptionList\fR is an optional list of \fIOptions\fR, where each option is a
212
key\-value\-pair. A list of currently understood options can be found below, all
228
key-value-pair. A list of currently understood options can be found below, all
213
229
other options will be ignored.
215
231
\&\fIValuelist\fR is a colon-separated list of the time and the values, each either
294
310
\-> | \s-1PUTNOTIF\s0 type=temperature severity=warning time=1201094702 message=The roof is on fire!
313
.IP "\fB\s-1FLUSH\s0\fR [\fBtimeout=\fR\fITimeout\fR] [\fBplugin=\fR\fIPlugin\fR [...]]" 4
314
.IX Item "FLUSH [timeout=Timeout] [plugin=Plugin [...]]"
315
Flushes all cached data older than \fITimeout\fR seconds. If no timeout has been
316
specified, it defaults to \-1 which causes all data to be flushed. \fBtimeout\fR
317
may be specified multiple times \- each occurrence applies to plugins listed
320
If specified, only specific plugins are flushed. Otherwise all plugins
321
providing a flush callback are flushed.
297
326
.Sh "Identifiers"
298
327
.IX Subsection "Identifiers"
299
328
Value or value-lists are identified in a uniform fashion:
310
339
\& myhost/memory/memory\-used
311
340
\& myhost/disk\-sda/disk_octets
314
.IX Subsection "Return values"
315
Unless otherwise noted the plugin answers with a line of the following form:
317
\&\fINum\fR \fIMessage\fR
319
If \fINum\fR is zero the message indicates success, if \fINum\fR is non-zero the
320
message indicates failure. \fIMessage\fR is a human-readable string that describes
321
the return value further.
323
Commands that return values may use \fINum\fR to return the number of values that
324
follow, such as the \fB\s-1GETVAL\s0\fR command. These commands usually return a negative
325
value on failure and never return zero.
326
342
.SH "ABSTRACTION LAYER"
327
343
.IX Header "ABSTRACTION LAYER"
328
344
\&\fBcollectd\fR ships the Perl-Module Collectd::Unixsock which
added
removed
src/collectd-unixsock.5
