src/collectdctl.1

   1 .\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is turned on, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{
  60 .    if \nF \{
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "COLLECTDCTL 1"
 136 .TH COLLECTDCTL 1 "2015-03-10" "5.4.1.805.g42e4d6c" "collectd"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 collectdctl \- Control interface for collectd
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 collectdctl \fI[options]\fR \fI<command>\fR \fI[command options]\fR
 146 .SH "DESCRIPTION"
 147 .IX Header "DESCRIPTION"
 148 collectdctl provides a control interface for collectd, which may be used to
 149 interact with the daemon using the \f(CW\*(C`unixsock plugin\*(C'\fR.
 150 .SH "OPTIONS"
 151 .IX Header "OPTIONS"
 152 collectdctl supports the following options:
 153 .IP "\fB\-s\fR \fIsocket\fR" 4
 154 .IX Item "-s socket"
 155 Path to the \s-1UNIX\s0 socket opened by collectd's \f(CW\*(C`unixsock plugin\*(C'\fR.
 156 Default: /var/run/collectd\-unixsock
 157 .IP "\fB\-h\fR" 4
 158 .IX Item "-h"
 159 Display usage information and exit.
 160 .SH "AVAILABLE COMMANDS"
 161 .IX Header "AVAILABLE COMMANDS"
 162 The following commands are supported:
 163 .IP "\fBgetval\fR \fI<identifier>\fR" 4
 164 .IX Item "getval <identifier>"
 165 Query the latest collected value identified by the specified
 166 \&\fI<identifier>\fR (see below). The value-list associated with that
 167 data-set is returned as a list of key-value-pairs, each on its own line. Keys
 168 and values are separated by the equal sign (\f(CW\*(C`=\*(C'\fR).
 169 .IP "\fBflush\fR [\fBtimeout=\fR\fI<seconds>\fR] [\fBplugin=\fR\fI<name>\fR] [\fBidentifier=\fR\fI<id>\fR]" 4
 170 .IX Item "flush [timeout=<seconds>] [plugin=<name>] [identifier=<id>]"
 171 Flush the daemon. This is useful, e.\ g., to make sure that the latest
 172 values have been written to the respective \s-1RRD\s0 file before graphing them or
 173 copying them to somewhere else.
 174 .Sp
 175 The following options are supported by the flush command:
 176 .RS 4
 177 .IP "\fBtimeout=\fR\fI<seconds>\fR" 4
 178 .IX Item "timeout=<seconds>"
 179 Flush values older than the specified timeout (in seconds) only.
 180 .IP "\fBplugin=\fR\fI<name>\fR" 4
 181 .IX Item "plugin=<name>"
 182 Flush the specified plugin only. I.\ e., data cached by the specified
 183 plugin is written to disk (or network or whatever), if the plugin supports
 184 that operation.
 185 .Sp
 186 Example: \fBrrdtool\fR.
 187 .IP "\fBidentifier=\fR\fI<id>\fR" 4
 188 .IX Item "identifier=<id>"
 189 If this option is present, only the data specified by the specified identifier
 190 (see below) will be flushed. Note that this option is not supported by all
 191 plugins (e.\ g., the \f(CW\*(C`network\*(C'\fR plugin does not support this).
 192 .RE
 193 .RS 4
 194 .Sp
 195 The \fBplugin\fR and \fBidentifier\fR options may be specified more than once. In
 196 that case, all combinations of specified plugins and identifiers will be
 197 flushed only.
 198 .RE
 199 .IP "\fBlistval\fR" 4
 200 .IX Item "listval"
 201 Returns a list of all values (by their identifier) available to the
 202 \&\f(CW\*(C`unixsock\*(C'\fR plugin. Each value is printed on its own line. I.\ e., this
 203 command returns a list of valid identifiers that may be used with the other
 204 commands.
 205 .IP "\fBputval\fR \fI<identifier>\fR [\fBinterval=\fR\fI<seconds>\fR] \fI<value\-list(s)>\fR" 4
 206 .IX Item "putval <identifier> [interval=<seconds>] <value-list(s)>"
 207 Submit one or more values (identified by \fI<identifier>\fR, see below)
 208 to the daemon which will then dispatch them to the write plugins. \fBinterval\fR
 209 specifies the interval (in seconds) used to collect the values following that
 210 option. It defaults to the default of the running collectd instance receiving
 211 the data. Multiple \fI<value\-list(s)>\fR (see below) may be specified.
 212 Each of them will be submitted to the daemon. The values have to match the
 213 data-set definition specified by the type as given in the identifier (see
 214 \&\fItypes.db\fR\|(5) for details).
 215 .SH "IDENTIFIERS"
 216 .IX Header "IDENTIFIERS"
 217 An identifier has the following format:
 218 .PP
 219 [\fIhostname\fR/]\fIplugin\fR[\-\fIplugin_instance\fR]/\fItype\fR[\-\fItype_instance\fR]
 220 .PP
 221 Examples:
 222  somehost/cpu\-0/cpu\-idle
 223  uptime/uptime
 224  otherhost/memory/memory\-used
 225 .PP
 226 Hostname defaults to the local (non-fully qualified) hostname if omitted. No
 227 error is returned if the specified identifier does not exist (this is a
 228 limitation in the \f(CW\*(C`libcollectdclient\*(C'\fR library).
 229 .SH "VALUE-LIST"
 230 .IX Header "VALUE-LIST"
 231 A value list describes one data-set as handled by collectd. It is a colon
 232 (\f(CW\*(C`:\*(C'\fR) separated list of the time and the values. Each value is either given
 233 as an integer if the data-type is a counter, or as a double if the data-type
 234 is a gauge value. A literal \f(CW\*(C`U\*(C'\fR is interpreted as an undefined gauge value.
 235 The number of values and the data-types have to match the type specified in
 236 the identifier (see \fItypes.db\fR\|(5) for details). The time is specified as
 237 epoch (i.\ e., standard \s-1UNIX\s0 time) or as a literal \f(CW\*(C`N\*(C'\fR which will be
 238 interpreted as now.
 239 .SH "EXAMPLES"
 240 .IX Header "EXAMPLES"
 241 .ie n .IP """collectdctl flush plugin=rrdtool identifier=somehost/cpu\-0/cpu\-wait""" 4
 242 .el .IP "\f(CWcollectdctl flush plugin=rrdtool identifier=somehost/cpu\-0/cpu\-wait\fR" 4
 243 .IX Item "collectdctl flush plugin=rrdtool identifier=somehost/cpu-0/cpu-wait"
 244 Flushes all \s-1CPU\s0 wait \s-1RRD\s0 values of the first \s-1CPU\s0 of the local host.
 245 I.\ e., writes all pending \s-1RRD\s0 updates of that data-source to disk.
 246 .ie n .IP """for ident in \`collectdctl listval | grep users/users\`; do collectdctl getval $ident; done""" 4
 247 .el .IP "\f(CWfor ident in \`collectdctl listval | grep users/users\`; do collectdctl getval $ident; done\fR" 4
 248 .IX Item "for ident in collectdctl listval | grep users/users; do collectdctl getval $ident; done"
 249 Query the latest number of logged in users on all hosts known to the local
 250 collectd instance.
 251 .SH "SEE ALSO"
 252 .IX Header "SEE ALSO"
 253 \&\fIcollectd\fR\|(1),
 254 \&\fIcollectd.conf\fR\|(5),
 255 \&\fIcollectd\-unixsock\fR\|(5),
 256 \&\fItypes.db\fR\|(5)
 257 .SH "AUTHOR"
 258 .IX Header "AUTHOR"
 259 collectd has been written by Florian Forster <octo at collectd.org>
 260 and many contributors (see `\s-1AUTHORS\s0').
 261 .PP
 262 collectdctl has been written by
 263 HXkon J Dugstad Johnsen <hakon\-dugstad.johnsen\ at\ telenor.com>
 264 and Sebastian Harl <sh at tokkee.org>.