Add zpool_influxdb command

A zpool_influxdb command is introduced to ease the collection
of zpool statistics into the InfluxDB time-series database.
Examples are given on how to integrate with the telegraf
statistics aggregator, a companion to influxdb.

Finally, a grafana dashboard template is included to show
how pool latency distributions can be visualized in a
ZFS + telegraf + influxdb  + grafana environment.

Reviewed-by: Brian Behlendorf <[email protected]>
Reviewed-by: Ryan Moeller <[email protected]>
Signed-off-by: Richard Elling <[email protected]>
Closes #10786 

2 files changed, 95 insertions, 1 deletions

diff --git a/man/man8/Makefile.am b/man/man8/Makefile.am
index 07f6aefa6..602645180 100644
--- a/man/man8/Makefile.am
+++ b/man/man8/Makefile.am
@@ -82,7 +82,8 @@ dist_man_MANS = \
 	zpool-upgrade.8 \
 	zpool-wait.8 \
 	zstream.8 \
-	zstreamdump.8
+	zstreamdump.8 \
+	zpool_influxdb.8
 
 nodist_man_MANS = \
 	zed.8 \
diff --git a/man/man8/zpool_influxdb.8 b/man/man8/zpool_influxdb.8
new file mode 100644
index 000000000..bd899dbe9
--- /dev/null
+++ b/man/man8/zpool_influxdb.8
@@ -0,0 +1,93 @@
+.\"
+.\" CDDL HEADER START
+.\"
+.\" The contents of this file are subject to the terms of the
+.\" Common Development and Distribution License (the "License").
+.\" You may not use this file except in compliance with the License.
+.\"
+.\" You can obtain a copy of the license at
+.\" https://opensource.org/licenses/CDDL-1.0
+.\" See the License for the specific language governing permissions
+.\" and limitations under the License.
+.\"
+.\" When distributing Covered Code, include this CDDL HEADER in each
+.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
+.\" If applicable, add the following below this CDDL HEADER, with the
+.\" fields enclosed by brackets "[]" replaced with your own identifying
+.\" information: Portions Copyright [yyyy] [name of copyright owner]
+.\"
+.\" CDDL HEADER END
+.\"
+.\"
+.\" Copyright 2020 Richard Elling
+.\" .Dd June 14, 2020
+.TH zpool_influxdb 8
+.SH NAME
+zpool_influxdb \- collect zpool statistics in influxdb line protocol format
+.SH SYNOPSIS
+.LP
+.nf
+\fBzpool_influxdb\fR [--execd] [--no-histogram] [--sum-histogram-buckets]
+[--tags key=value] [pool]
+\fBzpool_influxdb\fR --help
+.fi
+.SH DESCRIPTION
+The \fBzpool_influxdb\fR command produces influxdb line protocol compatible
+metrics from zpools. Like the \fBzpool\fR command, \fBzpool_influxdb\fR
+reads the current pool status and statistics. Unlike the \fBzpool\fR
+command which is intended for humans, \fBzpool_influxdb\fR formats the
+output in influxdb line protocol. The expected use is as a plugin to a
+metrics collector or aggregator, such as telegraf.
+
+By default, \fBzpool_influxdb\fR prints pool metrics and status in the
+influxdb line protocol format. All pools are printed, similar to
+the \fBzpool status\fR command. Providing a pool name restricts the
+output to the named pool.
+
+Like the \fBzpool\fR command, \fBzpool_influxdb\fR uses internal data
+structures that can change over time as new ZFS releases are made.
+Therefore, the \fBzpool_influxdb\fR command must be compiled against the
+ZFS source. It is expected that later releases of ZFS includes compatible
+\fBzpool_influxdb\fR and \fBzpool\fR commands.
+
+.SH OPTIONS
+.TP
+\fB\--execd\fR, \fB-e\fR
+Run in daemon mode compatible with telegraf`s \fBexecd\fR plugin.
+In this mode, the pools are sampled every time there is a [return] on stdin.
+Once a sample printed, \fBzpool_influxdb\fR waits for another [return].
+When run on a terminal, use [ctrl+C] to exit.
+.TP
+\fB\--no-histogram\fR, \fB-n\fR
+Do not print latency and I/O size histograms. This can reduce the total
+amount of data, but one should consider the value brought by the insights
+that latency and I/O size distributions provide. The resulting values
+are suitable for graphing with grafana's heatmap plugin.
+.TP
+\fB--sum-histogram-buckets\fR, \fB-s\fR
+Accumulates bucket values. By default, the values are not accumulated and
+the raw data appears as shown by \fBzpool iostat\fR. This works well for
+grafana's heatmap plugin. Summing the buckets produces output similar to
+prometheus histograms.
+.TP
+\fB--tags\fR, \fB-t\fR
+Adds specified tags to the tag set. Tags are key=value pairs and multiple
+tags are separated by commas. No sanity checking is performed.
+See the InfluxDB Line Protocol format documentation for details on escaping
+special characters used in tags.
+.TP
+\fB\--help\fR, \fB\-h\fR
+Print a usage summary.
+
+.SH SEE ALSO
+.LP
+\fBzpool-status\fR(8)
+\fBzpool-iostat\fR(8)
+.PP
+Influxdb https://github.com/influxdata/influxdb
+.PP
+Telegraf https://github.com/influxdata/telegraf
+.PP
+Grafana https://grafana.com
+.PP
+Prometheus https://prometheus.io