.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Collectd::Unixsock 3pm" .TH Collectd::Unixsock 3pm "2016-07-29" "perl v5.20.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Collectd::Unixsock \- Abstraction layer for accessing the functionality by collectd's unixsock plugin. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Collectd::Unixsock (); \& \& my $sock = Collectd::Unixsock\->new ($path); \& \& my $value = $sock\->getval (%identifier); \& $sock\->putval (%identifier, \& time => time (), \& values => [123, 234, 345]); \& \& $sock\->destroy (); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" collectd's unixsock plugin allows external programs to access the values it has collected or received and to submit own values. This Perl-module is simply a little abstraction layer over this interface to make it even easier for programmers to interact with the daemon. .SH "VALUE IDENTIFIERS" .IX Header "VALUE IDENTIFIERS" The values in the collectd are identified using an five-tuple (host, plugin, plugin-instance, type, type-instance) where only plugin-instance and type-instance may be \s-1NULL \s0(or undefined). Many functions expect an \&\fI\f(CI%identifier\fI\fR hash that has at least the members \fBhost\fR, \fBplugin\fR, and \&\fBtype\fR, possibly completed by \fBplugin_instance\fR and \fBtype_instance\fR. .PP Usually you can pass this hash as follows: .PP .Vb 1 \& $obj\->method (host => $host, plugin => $plugin, type => $type, %other_args); .Ve .SH "PUBLIC METHODS" .IX Header "PUBLIC METHODS" .ie n .IP "\fI\fI$obj\fI\fR = Collectd::Unixsock\->\fBnew\fR ([\fI\fI$path\fI\fR]);" 4 .el .IP "\fI\f(CI$obj\fI\fR = Collectd::Unixsock\->\fBnew\fR ([\fI\f(CI$path\fI\fR]);" 4 .IX Item "$obj = Collectd::Unixsock->new ([$path]);" Creates a new connection to the daemon. The optional \fI\f(CI$path\fI\fR argument gives the path to the \s-1UNIX\s0 socket of the \f(CW\*(C`unixsock plugin\*(C'\fR and defaults to \&\fI/var/run/collectd\-unixsock\fR. Returns the newly created object on success and false on error. .ie n .IP "\fI\fI$res\fI\fR = \fI\fI$obj\fI\fR\->\fBgetval\fR (\fI\fI%identifier\fI\fR);" 4 .el .IP "\fI\f(CI$res\fI\fR = \fI\f(CI$obj\fI\fR\->\fBgetval\fR (\fI\f(CI%identifier\fI\fR);" 4 .IX Item "$res = $obj->getval (%identifier);" Requests a value-list from the daemon. On success a hash-ref is returned with the name of each data-source as the key and the according value as, well, the value. On error false is returned. .ie n .IP "\fI\fI$res\fI\fR = \fI\fI$obj\fI\fR\->\fBgetthreshold\fR (\fI\fI%identifier\fI\fR);" 4 .el .IP "\fI\f(CI$res\fI\fR = \fI\f(CI$obj\fI\fR\->\fBgetthreshold\fR (\fI\f(CI%identifier\fI\fR);" 4 .IX Item "$res = $obj->getthreshold (%identifier);" Requests a threshold from the daemon. On success a hash-ref is returned with the threshold data. On error false is returned. .ie n .IP "\fI\fI$obj\fI\fR\->\fBputval\fR (\fI\fI%identifier\fI\fR, \fBtime\fR => \fI\fI$time\fI\fR, \fBvalues\fR => [...]);" 4 .el .IP "\fI\f(CI$obj\fI\fR\->\fBputval\fR (\fI\f(CI%identifier\fI\fR, \fBtime\fR => \fI\f(CI$time\fI\fR, \fBvalues\fR => [...]);" 4 .IX Item "$obj->putval (%identifier, time => $time, values => [...]);" Submits a value-list to the daemon. If the \fBtime\fR argument is omitted \&\f(CW\*(C`time()\*(C'\fR is used. The required argument \fBvalues\fR is a reference to an array of values that is to be submitted. The number of values must match the number of values expected for the given \fBtype\fR (see \*(L"\s-1VALUE IDENTIFIERS\*(R"\s0), though this is checked by the daemon, not the Perl module. Also, gauge data-sources (e.\ g. system-load) may be \f(CW\*(C`undef\*(C'\fR. Returns true upon success and false otherwise. .ie n .IP "\fI\fI$res\fI\fR = \fI\fI$obj\fI\fR\->\fBlistval\fR ()" 4 .el .IP "\fI\f(CI$res\fI\fR = \fI\f(CI$obj\fI\fR\->\fBlistval\fR ()" 4 .IX Item "$res = $obj->listval ()" Queries a list of values from the daemon. The list is returned as an array of hash references, where each hash reference is a valid identifier. The \f(CW\*(C`time\*(C'\fR member of each hash holds the epoch value of the last update of that value. .ie n .IP "\fI\fI$res\fI\fR = \fI\fI$obj\fI\fR\->\fBputnotif\fR (\fBseverity\fR => \fI\fI$severity\fI\fR, \fBmessage\fR => \fI\fI$message\fI\fR, ...);" 4 .el .IP "\fI\f(CI$res\fI\fR = \fI\f(CI$obj\fI\fR\->\fBputnotif\fR (\fBseverity\fR => \fI\f(CI$severity\fI\fR, \fBmessage\fR => \fI\f(CI$message\fI\fR, ...);" 4 .IX Item "$res = $obj->putnotif (severity => $severity, message => $message, ...);" Submits a notification to the daemon. .Sp Valid options are: .RS 4 .IP "\fBseverity\fR" 4 .IX Item "severity" Sets the severity of the notification. The value must be one of the following strings: \f(CW\*(C`failure\*(C'\fR, \f(CW\*(C`warning\*(C'\fR, or \f(CW\*(C`okay\*(C'\fR. Case does not matter. This option is mandatory. .IP "\fBmessage\fR" 4 .IX Item "message" Sets the message of the notification. This option is mandatory. .IP "\fBtime\fR" 4 .IX Item "time" Sets the time. If omitted, \f(CW\*(C`time()\*(C'\fR is used. .IP "\fIValue identifier\fR" 4 .IX Item "Value identifier" All the other fields of the value identifiers, \fBhost\fR, \fBplugin\fR, \&\fBplugin_instance\fR, \fBtype\fR, and \fBtype_instance\fR, are optional. When given, the notification is associated with the performance data of that identifier. For more details, please see \fIcollectd\-unixsock\fR\|(5). .RE .RS 4 .RE .ie n .IP "\fI\fI$obj\fI\fR\->\fBflush\fR (\fBtimeout\fR => \fI\fI$timeout\fI\fR, \fBplugins\fR => [...], \fBidentifier\fR => [...]);" 4 .el .IP "\fI\f(CI$obj\fI\fR\->\fBflush\fR (\fBtimeout\fR => \fI\f(CI$timeout\fI\fR, \fBplugins\fR => [...], \fBidentifier\fR => [...]);" 4 .IX Item "$obj->flush (timeout => $timeout, plugins => [...], identifier => [...]);" Flush cached data. .Sp Valid options are: .RS 4 .IP "\fBtimeout\fR" 4 .IX Item "timeout" If this option is specified, only data older than \fI\f(CI$timeout\fI\fR seconds is flushed. .IP "\fBplugins\fR" 4 .IX Item "plugins" If this option is specified, only the selected plugins will be flushed. The argument is a reference to an array of strings. .IP "\fBidentifier\fR" 4 .IX Item "identifier" If this option is specified, only the given identifier(s) will be flushed. The argument is a reference to an array of identifiers. Identifiers, in this case, are hash references and have the members as outlined in \*(L"\s-1VALUE IDENTIFIERS\*(R"\s0. .RE .RS 4 .RE .ie n .IP "\fI\fI$obj\fI\fR\->destroy ();" 4 .el .IP "\fI\f(CI$obj\fI\fR\->destroy ();" 4 .IX Item "$obj->destroy ();" Closes the socket before the object is destroyed. This function is also automatically called then the object goes out of scope. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIcollectd\fR\|(1), \&\fIcollectd.conf\fR\|(5), \&\fIcollectd\-unixsock\fR\|(5) .SH "AUTHOR" .IX Header "AUTHOR" Florian octo Forster