Expand docs per code review.

collector/native_collector.go

@@ -34,17 +34,17 @@ type diskStat struct {
 var (
 	// Docs from https://www.kernel.org/doc/Documentation/iostats.txt
 	diskStatsMetrics = []diskStat{
-		{"reads_completed", prometheus.NewCounter(), "# of reads completed"},
+		{"reads_completed", prometheus.NewCounter(), "The total number of reads completed successfully."},
-		{"reads_merged", prometheus.NewCounter(), "# of reads merged"},
+		{"reads_merged", prometheus.NewCounter(), "The number of reads merged. Reads and writes which are adjacent to each other may be merged for efficiency. Thus two 4K reads may become one 8K read before it is ultimately handed to the disk, and so it will be counted (and queued) as only one I/O. This metric lets you know how often this was done."},
-		{"sectors_read", prometheus.NewCounter(), "# of sectors read"},
+		{"sectors_read", prometheus.NewCounter(), "The total number of sectors read successfully."},
-		{"read_time_ms", prometheus.NewCounter(), "# of milliseconds spent reading"},
+		{"read_time_ms", prometheus.NewCounter(), "the total number of milliseconds spent by all reads (as measured from __make_request() to end_that_request_last())."},
-		{"writes_completed", prometheus.NewCounter(), "# of writes completed"},
+		{"writes_completed", prometheus.NewCounter(), "The total number of writes completed successfully."},
-		{"writes_merged", prometheus.NewCounter(), "# of writes merges"},
+		{"writes_merged", prometheus.NewCounter(), "The number of writes merged. Reads and writes which are adjacent to each other may be merged for efficiency. Thus two 4K reads may become one 8K read before it is ultimately handed to the disk, and so it will be counted (and queued) as only one I/O. This metric lets you know how often this was done."},
-		{"sectors_written", prometheus.NewCounter(), "# of sectors written"},
+		{"sectors_written", prometheus.NewCounter(), "The total number of sectors written successfully."},
-		{"write_time_ms", prometheus.NewCounter(), "# of milliseconds spent writing"},
+		{"write_time_ms", prometheus.NewCounter(), "This is the total number of milliseconds spent by all writes (as measured from __make_request() to end_that_request_last())."},
-		{"io_now", prometheus.NewGauge(), "# of I/Os currently in progress"},
+		{"io_now", prometheus.NewGauge(), "The number of I/Os currently in progress. Incremented as requests are given to appropriate struct request_queue and decremented as they finish."},
-		{"io_time_ms", prometheus.NewCounter(), "# of milliseconds spent doing I/Os"},
+		{"io_time_ms", prometheus.NewCounter(), "Milliseconds spent doing I/Os. This metric increases so long as node_disk_io_now is nonzero."},
-		{"io_time_weighted", prometheus.NewCounter(), "weighted # of milliseconds spent doing I/Os"},
+		{"io_time_weighted", prometheus.NewCounter(), "The weighted # of milliseconds spent doing I/Os. This metric is incremented at each I/O start, I/O completion, I/O merge, or read of these stats by the number of I/Os in progress (node_disk_io_now) times the number of milliseconds spent doing I/O since the last update of this field.  This can provide an easy measure of both I/O completion time and the backlog that may be accumulating."},
 	}
 	lastSeen         = prometheus.NewGauge()
 	load1            = prometheus.NewGauge()
@@ -82,7 +82,7 @@ func NewNativeCollector(config Config, registry prometheus.Registry) (Collector,
 
 	registry.Register(
 		"node_last_login_time",
-		"The time of the last login",
+		"The time of the last login.",
 		prometheus.NilLabels,
 		lastSeen,
 	)