From 3b660e5d618c9b68354e9bdd86c3b2b76d79154e Mon Sep 17 00:00:00 2001
From: Sebastian Harl <sh@tokkee.org>
Date: Sat, 18 Apr 2015 21:44:22 +0200
Subject: [PATCH] collectd.conf(5): Add documentation for cURL statistics.

---
 src/collectd.conf.pod  | 105 +++++++++++++++++++++++++++++++++++++++++
 src/utils_curl_stats.h |   6 +--
 2 files changed, 108 insertions(+), 3 deletions(-)

diff --git a/src/collectd.conf.pod b/src/collectd.conf.pod
index 058cd935..925262c1 100644
--- a/src/collectd.conf.pod
+++ b/src/collectd.conf.pod
@@ -1451,6 +1451,92 @@ number.
 
 =back
 
+=head2 cURL Statistics
+
+All cURL-based plugins support collection of generic, request-based
+statistics. These are disabled by default and can be enabled selectively for
+each page or URL queried from the curl, curl_json, or curl_xml plugins. See
+the documentation of those plugins for specific information. This section
+describes the available metrics that can be configured with each plugin. All
+options are disabled by default.
+
+See L<http://curl.haxx.se/libcurl/c/curl_easy_getinfo.html> for more details.
+
+=over 4
+
+=item B<total_time> B<true|false>
+
+Total time of the transfer, including name resolving, TCP connect, etc.
+
+=item B<namelookup_time> B<true|false>
+
+Time it took from the start until name resolving was completed.
+
+=item B<connect_time> B<true|false>
+
+Time it took from the start until the connect to the remote host (or proxy)
+was completed.
+
+=item B<appconnect_time> B<true|false>
+
+Time it took from the start until the SSL/SSH connect/handshake to the remote
+host was completed.
+
+=item B<pretransfer_time> B<true|false>
+
+Time it took from the start until the file transfer is just about to begin.
+
+=item B<starttransfer_time> B<true|false>
+
+Time it took from the start until the first byte was received.
+
+=item B<redirect_time> B<true|false>
+
+Time it took for all redirection steps include name lookup, connect,
+pre-transfer and transfer before final transaction was started.
+
+=item B<redirect_count> B<true|false>
+
+The total number of redirections that were actually followed.
+
+=item B<size_upload> B<true|false>
+
+The total amount of bytes that were uploaded.
+
+=item B<size_download> B<true|false>
+
+The total amount of bytes that were downloaded.
+
+=item B<speed_download> B<true|false>
+
+The average download speed that curl measured for the complete download.
+
+=item B<speed_upload> B<true|false>
+
+The average upload speed that curl measured for the complete upload.
+
+=item B<header_size> B<true|false>
+
+The total size of all the headers received.
+
+=item B<request_size> B<true|false>
+
+The total size of the issued requests.
+
+=item B<content_length_download> B<true|false>
+
+The content-length of the download.
+
+=item B<content_length_upload> B<true|false>
+
+The specified size of the upload.
+
+=item B<num_connects> B<true|false>
+
+The number of new connections that were created to achieve the transfer.
+
+=back
+
 =head2 Plugin C<curl>
 
 The curl plugin uses the B<libcurl> (L<http://curl.haxx.se/>) to read web pages
@@ -1556,6 +1642,13 @@ requests.
 Measure response code for the request. If this setting is enabled, B<Match>
 blocks (see below) are optional. Disabled by default.
 
+=item B<E<lt>StatisticsE<gt>>
+
+One B<Statistics> block can be used to specify cURL statistics to be collected
+for each request to the remote web site. See the section "cURL Statistics"
+above for details. If this setting is enabled, B<Match> blocks (see below) are
+optional.
+
 =item B<E<lt>MatchE<gt>>
 
 One or more B<Match> blocks that define how to match information in the data
@@ -1668,6 +1761,12 @@ URL. By default the global B<Interval> setting will be used.
 These options behave exactly equivalent to the appropriate options of the
 I<cURL> plugin. Please see there for a detailed description.
 
+=item B<E<lt>StatisticsE<gt>>
+
+One B<Statistics> block can be used to specify cURL statistics to be collected
+for each request to the remote URL. See the section "cURL Statistics" above
+for details.
+
 =back
 
 The following options are valid within B<Key> blocks:
@@ -1770,6 +1869,12 @@ Examples:
 These options behave exactly equivalent to the appropriate options of the
 I<cURL plugin>. Please see there for a detailed description.
 
+=item B<E<lt>StatisticsE<gt>>
+
+One B<Statistics> block can be used to specify cURL statistics to be collected
+for each request to the remote URL. See the section "cURL Statistics" above
+for details.
+
 =item E<lt>B<XPath> I<XPath-expression>E<gt>
 
 Within each B<URL> block, there must be one or more B<XPath> blocks. Each
diff --git a/src/utils_curl_stats.h b/src/utils_curl_stats.h
index 3a0a26eb..ef925605 100644
--- a/src/utils_curl_stats.h
+++ b/src/utils_curl_stats.h
@@ -36,9 +36,9 @@ struct curl_stats_s;
 typedef struct curl_stats_s curl_stats_t;
 
 /*
- * curl_stats_from_config allocates and constructs a CURL statistics object
+ * curl_stats_from_config allocates and constructs a cURL statistics object
  * from the specified configuration which is expected to be a single block of
- * boolean options named after CURL information fields. The boolean value
+ * boolean options named after cURL information fields. The boolean value
  * indicates whether to collect the respective information.
  *
  * See http://curl.haxx.se/libcurl/c/curl_easy_getinfo.html
@@ -50,7 +50,7 @@ void curl_stats_destroy (curl_stats_t *s);
 
 /*
  * curl_stats_dispatch dispatches performance values from the the specified
- * CURL session to the daemon.
+ * cURL session to the daemon.
  */
 int curl_stats_dispatch (curl_stats_t *s, CURL *curl,
 		const char *hostname, const char *plugin, const char *plugin_instance,
-- 
2.30.2