HTTP Digest support for curl plugins

[collectd.git] / src / collectd.conf.pod

diff --git a/src/collectd.conf.pod b/src/collectd.conf.pod
index 11db1cc..532e4af 100644 (file)
--- a/src/collectd.conf.pod
+++ b/src/collectd.conf.pod
@@ -730,6 +730,29 @@ default for backwards compatibility, the time will be reported in minutes.
 
 =back
 
 
 =back
 

+=head2 Plugin C<aquaero>
+
+This plugin collects the value of the available sensors in an
+I<AquaeroE<nbsp>5> board. AquaeroE<nbsp>5 is a water-cooling controller board,
+manufactured by Aqua Computer GmbH L<http://www.aquacomputer.de/>, with a USB2
+connection for monitoring and configuration. The board can handle multiple
+temperature sensors, fans, water pumps and water level sensors and adjust the
+output settings such as fan voltage or power used by the water pump based on
+the available inputs using a configurable controller included in the board.
+This plugin collects all the available inputs as well as some of the output
+values chosen by this controller. The plugin is based on the I<libaquaero5>
+library provided by I<aquatools-ng>.
+
+=over 4
+
+=item B<Device> I<DevicePath>
+
+Device path of the AquaeroE<nbsp>5's USB HID (human interface device), usually
+in the form C</dev/usb/hiddevX>. If this option is no set the plugin will try
+to auto-detect the Aquaero 5 USB device based on vendor-ID and product-ID.
+
+=back
+

 =head2 Plugin C<ascent>
 
 This plugin collects information about an Ascent server, a free server for the
 =head2 Plugin C<ascent>
 
 This plugin collects information about an Ascent server, a free server for the


@@ -1023,6 +1046,10 @@ Username to use if authorization is required to read the page.
 
 Password to use if authorization is required to read the page.
 
 
 Password to use if authorization is required to read the page.
 

+=item B<Digest> B<true>|B<false>
+
+Enable HTTP digest authentication.
+

 =item B<VerifyPeer> B<true>|B<false>
 
 Enable or disable peer SSL certificate verification. See
 =item B<VerifyPeer> B<true>|B<false>
 
 Enable or disable peer SSL certificate verification. See


@@ -1072,13 +1099,15 @@ is set to B<true>, B<Match> blocks are optional.
 
 =head2 Plugin C<curl_json>
 
 
 =head2 Plugin C<curl_json>
 

-The B<curl_json plugin> uses B<libcurl> (L<http://curl.haxx.se/>) and
-B<libyajl> (L<http://www.lloydforge.org/projects/yajl/>) to retrieve JSON data
-via cURL. This can be used to collect values from CouchDB documents (which are
-stored JSON notation), for example.
+The B<curl_json plugin> collects values from JSON data to be parsed by
+B<libyajl> (L<http://www.lloydforge.org/projects/yajl/>) retrieved via
+either B<libcurl> (L<http://curl.haxx.se/>) or read directly from a
+unix socket. The former can be used, for example, to collect values
+from CouchDB documents (which are stored JSON notation), and the
+latter to collect values from a uWSGI stats socket.

 
 

-The following example will collect several values from the built-in `_stats'
-runtime statistics module of CouchDB
+The following example will collect several values from the built-in
+C<_stats> runtime statistics module of I<CouchDB>

 (L<http://wiki.apache.org/couchdb/Runtime_Statistics>).
 
   <Plugin curl_json>
 (L<http://wiki.apache.org/couchdb/Runtime_Statistics>).
 
   <Plugin curl_json>


@@ -1098,11 +1127,30 @@ runtime statistics module of CouchDB
     </URL>
   </Plugin>
 
     </URL>
   </Plugin>
 

-In the B<Plugin> block, there may be one or more B<URL> blocks, each defining
-a URL to be fetched via HTTP (using libcurl) and one or more B<Key> blocks.
-The B<Key> string argument must be in a path format, which is used to collect a
-value from a JSON map object. If a path element of B<Key> is the
-I<*>E<nbsp>wildcard, the values for all keys will be collectd.
+This example will collect data directly from a I<uWSGI> "Stats Server" socket.
+
+  <Plugin curl_json>
+    <Sock "/var/run/uwsgi.stats.sock">
+      Instance "uwsgi"
+      <Key "workers/*/requests">
+        Type "http_requests"
+      </Key>
+
+      <Key "workers/*/apps/*/requests">
+        Type "http_requests"
+      </Key>
+    </Sock>
+  </Plugin>
+
+In the B<Plugin> block, there may be one or more B<URL> blocks, each
+defining a URL to be fetched via HTTP (using libcurl) or B<Sock>
+blocks defining a unix socket to read JSON from directly.  Each of
+these blocks may have one or more B<Key> blocks.
+
+The B<Key> string argument must be in a path format. Each component is
+used to match the key from a JSON map or the index of an JSON
+array. If a path component of a B<Key> is a I<*>E<nbsp>wildcard, the
+values for all map keys or array indices will be collectd.

 
 The following options are valid within B<URL> blocks:
 
 
 The following options are valid within B<URL> blocks:
 


@@ -1113,11 +1161,19 @@ The following options are valid within B<URL> blocks:
 Sets the plugin instance to I<Instance>.
 
 =item B<User> I<Name>
 Sets the plugin instance to I<Instance>.
 
 =item B<User> I<Name>

+

 =item B<Password> I<Password>
 =item B<Password> I<Password>

+
+=item B<Digest> B<true>|B<false>
+

 =item B<VerifyPeer> B<true>|B<false>
 =item B<VerifyPeer> B<true>|B<false>

+

 =item B<VerifyHost> B<true>|B<false>
 =item B<VerifyHost> B<true>|B<false>

+

 =item B<CACert> I<file>
 =item B<CACert> I<file>

+

 =item B<Header> I<Header>
 =item B<Header> I<Header>

+

 =item B<Post> I<Body>
 
 These options behave exactly equivalent to the appropriate options of the
 =item B<Post> I<Body>
 
 These options behave exactly equivalent to the appropriate options of the


@@ -1206,6 +1262,8 @@ Examples:
 
 =item B<Password> I<Password>
 
 
 =item B<Password> I<Password>
 

+=item B<Digest> B<true>|B<false>
+

 =item B<VerifyPeer> B<true>|B<false>
 
 =item B<VerifyHost> B<true>|B<false>
 =item B<VerifyPeer> B<true>|B<false>
 
 =item B<VerifyHost> B<true>|B<false>


@@ -1559,17 +1617,17 @@ transfer agents and web caches.
 
 =item B<ValuesAbsolute> B<true>|B<false>
 
 
 =item B<ValuesAbsolute> B<true>|B<false>
 

-Enables or disables reporting of free, used and used disk space in 1K-blocks. 
-Defaults to true.
+Enables or disables reporting of free and used disk space in 1K-blocks.
+Defaults to B<true>.

 
 

-=item B<ValuesPercentage> B<true>|B<false>
+=item B<ValuesPercentage> B<false>|B<true>

 
 

-Enables or disables reporting of free, used and used disk space in percentage.
-Defaults to false.
+Enables or disables reporting of free and used disk space in percentage.
+Defaults to B<false>.

 
 

-This is useful for deploying collectd on the cloud, where machines with
-different disk size may exist. Then it is more practical to configure thresholds
-based on relative disk size.
+This is useful for deploying I<collectd> on the cloud, where machines with
+different disk size may exist. Then it is more practical to configure
+thresholds based on relative disk size.

 
 =back
 
 
 =back
 


@@ -2155,6 +2213,25 @@ interface path might change between reboots of a guest or across migrations.
 
 =back
 
 
 =back
 

++=head2 Plugin C<load>
+
+The I<Load plugin> collects the system load. These numbers give a rough overview
+over the utilization of a machine. The system load is defined as the number of
+runnable tasks in the run-queue and is provided by many operating systems as a
+one, five or fifteen minute average.
+
+The following configuration options are available:
+
+=over 4
+
+=item B<ReportRelative> B<false>|B<true>
+
+When enabled, system load divided by number of available CPU cores is reported
+for intervals 1 min, 5 min and 15 min. Defaults to false.
+
+=back
+
+

 =head2 Plugin C<logfile>
 
 =over 4
 =head2 Plugin C<logfile>
 
 =over 4


@@ -2367,11 +2444,11 @@ B<Synopsis:>
    Temperature vddg
    Temperature vddq
    IgnoreSelectedTemperature true
    Temperature vddg
    Temperature vddq
    IgnoreSelectedTemperature true

-
+   

    ShowPower true
    Power total0
    Power total1
    ShowPower true
    Power total0
    Power total1

-   IgnoreSelectedPower true   
+   IgnoreSelectedPower true

  </Plugin>
 
 The following options are valid inside the B<PluginE<nbsp>mic> block:
  </Plugin>
 
 The following options are valid inside the B<PluginE<nbsp>mic> block:


@@ -2428,7 +2505,7 @@ Fan In
 
 =item fout
 
 
 =item fout
 

-Fan Out 
+Fan Out

 
 =item vccp
 
 
 =item vccp
 


@@ -2469,11 +2546,11 @@ Known power names are:
 
 =item total0
 
 
 =item total0
 

-Total power utilization averaged over Time Window 0 (uWatts). 
+Total power utilization averaged over Time Window 0 (uWatts).

 
 =item total1
 
 
 =item total1
 

-Total power utilization averaged over Time Window 0 (uWatts). 
+Total power utilization averaged over Time Window 0 (uWatts).

 
 =item inst
 
 
 =item inst
 


@@ -2481,34 +2558,55 @@ Instantaneous power (uWatts).
 
 =item imax
 
 
 =item imax
 

-Max instantaneous power (uWatts). 
+Max instantaneous power (uWatts).

 
 =item pcie
 
 
 =item pcie
 

-PCI-E connector power (uWatts). 
+PCI-E connector power (uWatts).

 
 =item c2x3
 
 
 =item c2x3
 

-2x3 connector power (uWatts). 
+2x3 connector power (uWatts).

 
 =item c2x4
 
 
 =item c2x4
 

-2x4 connector power (uWatts). 
+2x4 connector power (uWatts).

 
 =item vccp
 
 
 =item vccp
 

-Core rail (uVolts). 
+Core rail (uVolts).

 
 =item vddg
 
 
 =item vddg
 

-Uncore rail (uVolts). 
+Uncore rail (uVolts).

 
 =item vddq
 
 
 =item vddq
 

-Memory subsystem rail (uVolts). 
+Memory subsystem rail (uVolts).
+
+=back

 
 =back
 
 
 =back
 

+=head2 Plugin C<memory>
+
+The I<memory plugin> provides the following configuration options:
+
+=over 4
+
+=item B<ValuesAbsolute> B<true>|B<false>
+
+Enables or disables reporting of physical memory usage in absolute numbers,
+i.e. bytes. Defaults to B<true>.
+
+=item B<ValuesPercentage> B<false>|B<true>
+
+Enables or disables reporting of physical memory usage in percentages, e.g.
+percent of physical memory used. Defaults to B<false>.
+
+This is useful for deploying I<collectd> in a heterogeneous environment in
+which the sizes of physical memory vary.
+

 =back
 
 =head2 Plugin C<modbus>
 =back
 
 =head2 Plugin C<modbus>


@@ -5148,12 +5246,129 @@ and all other sensors are collected.
 
 =back
 
 
 =back
 

+=head2 Plugin C<sigrok>
+
+The I<sigrok plugin> uses I<libsigrok> to retrieve measurements from any device
+supported by the L<sigrok|http://sigrok.org/> project.
+
+B<Synopsis>
+
+ <Plugin sigrok>
+   LogLevel 3
+   <Device "AC Voltage">
+      Driver "fluke-dmm"
+      MinimumInterval 10
+      Conn "/dev/ttyUSB2"
+   </Device>
+   <Device "Sound Level">
+      Driver "cem-dt-885x"
+      Conn "/dev/ttyUSB1"
+   </Device>
+ </Plugin>
+
+=over 4
+
+=item B<LogLevel> B<0-5>
+
+The I<sigrok> logging level to pass on to the I<collectd> log, as a number
+between B<0> and B<5> (inclusive). These levels correspond to C<None>,
+C<Errors>, C<Warnings>, C<Informational>, C<Debug >and C<Spew>, respectively.
+The default is B<2> (C<Warnings>). The I<sigrok> log messages, regardless of
+their level, are always submitted to I<collectd> at its INFO log level.
+
+=item E<lt>B<Device> I<Name>E<gt>
+
+A sigrok-supported device, uniquely identified by this section's options. The
+I<Name> is passed to I<collectd> as the I<plugin instance>.
+
+=item B<Driver> I<DriverName>
+
+The sigrok driver to use for this device.
+
+=item B<Conn> I<ConnectionSpec>
+
+If the device cannot be auto-discovered, or more than one might be discovered
+by the driver, I<ConnectionSpec> specifies the connection string to the device.
+It can be of the form of a device path (e.g.E<nbsp>C</dev/ttyUSB2>), or, in
+case of a non-serial USB-connected device, the USB I<VendorID>B<.>I<ProductID>
+separated by a period (e.g.E<nbsp>C<0403.6001>). A USB device can also be
+specified as I<Bus>B<.>I<Address> (e.g.E<nbsp>C<1.41>).
+
+=item B<SerialComm> I<SerialSpec>
+
+For serial devices with non-standard port settings, this option can be used
+to specify them in a form understood by I<sigrok>, e.g.E<nbsp>C<9600/8n1>.
+This should not be necessary; drivers know how to communicate with devices they
+support.
+
+=item B<MinimumInterval> I<Seconds>
+
+Specifies the minimum time between measurement dispatches to I<collectd>, in
+seconds. Since some I<sigrok> supported devices can acquire measurements many
+times per second, it may be necessary to throttle these. For example, the
+I<RRD plugin> cannot process writes more than once per second.
+
+The default B<MinimumInterval> is B<0>, meaning measurements received from the
+device are always dispatched to I<collectd>. When throttled, unused
+measurements are discarded.
+
+=back
+

 =head2 Plugin C<snmp>
 
 Since the configuration of the C<snmp plugin> is a little more complicated than
 other plugins, its documentation has been moved to an own manpage,
 L<collectd-snmp(5)>. Please see there for details.
 
 =head2 Plugin C<snmp>
 
 Since the configuration of the C<snmp plugin> is a little more complicated than
 other plugins, its documentation has been moved to an own manpage,
 L<collectd-snmp(5)>. Please see there for details.
 

+=head2 Plugin C<statsd>
+
+The I<statsd plugin> listens to a UDP socket, reads "events" in the statsd
+protocol and dispatches rates or other aggregates of these numbers
+periodically.
+
+The plugin implements the I<Counter>, I<Timer>, I<Gauge> and I<Set> types which
+are dispatched as the I<collectd> types C<derive>, C<latency>, C<gauge> and
+C<objects> respectively.
+
+The following configuration options are valid:
+
+=over 4
+
+=item B<Host> I<Host>
+
+Bind to the hostname / address I<Host>. By default, the plugin will bind to the
+"any" address, i.e. accept packets sent to any of the hosts addresses.
+
+=item B<Port> I<Port>
+
+UDP port to listen to. This can be either a service name or a port number.
+Defaults to C<8125>.
+
+=item B<DeleteCounters> B<false>|B<true>
+
+=item B<DeleteTimers> B<false>|B<true>
+
+=item B<DeleteGauges> B<false>|B<true>
+
+=item B<DeleteSets> B<false>|B<true>
+
+These options control what happens if metrics are not updated in an interval.
+If set to B<False>, the default, metrics are dispatched unchanged, i.e. the
+rate of counters and size of sets will be zero, timers report C<NaN> and gauges
+are unchanged. If set to B<True>, the such metrics are not dispatched and
+removed from the internal cache.
+
+=item B<TimerPercentile> I<Percent>
+
+Calculate and dispatch the configured percentile, i.e. compute the latency, so
+that I<Percent> of all reported timers are smaller than or equal to the
+computed latency. This is useful for cutting off the long tail latency, as it's
+often done in I<Service Level Agreements> (SLAs).
+
+If not specified, no percentile is calculated / dispatched.
+
+=back
+

 =head2 Plugin C<swap>
 
 The I<Swap plugin> collects information about used and available swap space. On
 =head2 Plugin C<swap>
 
 The I<Swap plugin> collects information about used and available swap space. On


@@ -5176,6 +5391,19 @@ This option is only available if the I<Swap plugin> can read C</proc/swaps>
 When enabled, the I<swap I/O> is reported in bytes. When disabled, the default,
 I<swap I/O> is reported in pages. This option is available under Linux only.
 
 When enabled, the I<swap I/O> is reported in bytes. When disabled, the default,
 I<swap I/O> is reported in pages. This option is available under Linux only.
 

+=item B<ValuesAbsolute> B<true>|B<false>
+
+Enables or disables reporting of absolute swap metrics, i.e. number of I<bytes>
+available and used. Defaults to B<true>.
+
+=item B<ValuesPercentage> B<false>|B<true>
+
+Enables or disables reporting of relative swap metrics, i.e. I<percent>
+available and free. Defaults to B<false>.
+
+This is useful for deploying I<collectd> in a heterogeneous environment, where
+swap sizes differ and you want to specify generic thresholds or similar.
+

 =back
 
 =head2 Plugin C<syslog>
 =back
 
 =head2 Plugin C<syslog>


@@ -5924,7 +6152,7 @@ Synopsis:
    <Node "example">
      Host "localhost"
      Port "2003"
    <Node "example">
      Host "localhost"
      Port "2003"

-     Protocol "udp"
+     Protocol "tcp"

      LogSendErrors true
      Prefix "collectd"
    </Node>
      LogSendErrors true
      Prefix "collectd"
    </Node>


@@ -6127,6 +6355,7 @@ Synopsis:
      TTLFactor 2.0
    </Node>
    Tag "foobar"
      TTLFactor 2.0
    </Node>
    Tag "foobar"

+   Attribute "foo" "bar"

  </Plugin>
 
 The following options are understood by the I<write_riemann plugin>:
  </Plugin>
 
 The following options are understood by the I<write_riemann plugin>:


@@ -6187,6 +6416,11 @@ default value.
 Add the given string as an additional tag to the metric being sent to
 I<Riemann>.
 
 Add the given string as an additional tag to the metric being sent to
 I<Riemann>.
 

+=item B<Attribute> I<String> I<String>
+
+Consider the two given strings to be the key and value of an additional
+attribute for each metric being sent out to I<Riemann>.
+

 =back
 
 =head1 THRESHOLD CONFIGURATION
 =back
 
 =head1 THRESHOLD CONFIGURATION


@@ -6221,7 +6455,7 @@ When a value comes within range again or is received after it was missing, an
 Here is a configuration example to get you started. Read below for more
 information.
 
 Here is a configuration example to get you started. Read below for more
 information.
 

- <Threshold>
+ <Plugin threshold>

    <Type "foo">
      WarningMin    0.00
      WarningMax 1000.00
    <Type "foo">
      WarningMin    0.00
      WarningMax 1000.00


@@ -6252,7 +6486,7 @@ information.
        </Type>
      </Plugin>
    </Host>
        </Type>
      </Plugin>
    </Host>

- </Threshold>
+ </Plugin>

 
 There are basically two types of configuration statements: The C<Host>,
 C<Plugin>, and C<Type> blocks select the value for which a threshold should be
 
 There are basically two types of configuration statements: The C<Host>,
 C<Plugin>, and C<Type> blocks select the value for which a threshold should be