Merge pull request #2681 from ipfs/feature/spruce-upstat

Add helptext, default logic to `ipfs stats`

core/commands/stat.go

@@ -18,8 +18,10 @@ import (
 
 var StatsCmd = &cmds.Command{
 	Helptext: cmds.HelpText{
-		Tagline:          "Query IPFS statistics.",
-		ShortDescription: ``,
+		Tagline:          "Query ipfs statistics.",
+		Synopsis:         "ipfs stats <command>",
+		ShortDescription: `'ipfs stats' is a set of commands to help look at statistics for your ipfs node.`,
+		LongDescription: `'ipfs stats' is a set of commands to help look at statistics for your ipfs node.`,
 	},
 
 	Subcommands: map[string]*cmds.Command{
@@ -30,13 +32,48 @@ var StatsCmd = &cmds.Command{
 var statBwCmd = &cmds.Command{
 	Helptext: cmds.HelpText{
 		Tagline:          "Print ipfs bandwidth information.",
-		ShortDescription: ``,
+		Synopsis:          "ipfs stats bw [--peer <peerId> | -p] [--proto <protocol> | -t] [--poll] [--interval <timeInterval> | -i]",
+		ShortDescription: `'ipfs stats bw' prints bandwidth information for the ipfs daemon.
+It displays: TotalIn, TotalOut, RateIn, RateOut.
+		`,
+		LongDescription: `'ipfs stats bw' prints bandwidth information for the ipfs daemon.
+It displays: TotalIn, TotalOut, RateIn, RateOut.
+
+By default, overall bandwidth and all protocols are shown. To limit bandwidth to
+a particular peer, use the 'peer' option along with that peer's multihash id. To
+specify a specific protocol, use the 'proto' option. The 'peer' and 'proto'
+options cannot be specified simultaneously. The protocols that be queried using
+this method are outlined in the specification: https://github.com/ipfs/specs/blob/master/libp2p/7-properties.md#757-protocol-multicodecs
+
+Example protocol options:
+  - /ipfs/id/1.0.0
+  - /ipfs/bitswap
+  - /ipfs/dht
+
+Example:
+
+    > ipfs stats bw -t /ipfs/bitswap
+    Bandwidth
+    TotalIn: 5.0MB
+    TotalOut: 0B
+    RateIn: 343B/s
+    RateOut: 0B/s
+    > ipfs stats bw -p QmepgFW7BHEtU4pZJdxaNiv75mKLLRQnPi1KaaXmQN4V1a
+    Bandwidth
+    TotalIn: 4.9MB
+    TotalOut: 12MB
+    RateIn: 0B/s
+    RateOut: 0B/s
+`,
 	},
 	Options: []cmds.Option{
 		cmds.StringOption("peer", "p", "Specify a peer to print bandwidth for."),
 		cmds.StringOption("proto", "t", "Specify a protocol to print bandwidth for."),
-		cmds.BoolOption("poll", "Print bandwidth at an interval. Default: false."),
-		cmds.StringOption("interval", "i", "Time interval to wait between updating output, if 'poll' is true."),
+		cmds.BoolOption("poll", "Print bandwidth at an interval.").Default(false),
+		cmds.StringOption("interval", "i", `Time interval to wait between updating output, if 'poll' is true.
+
+    This accepts durations such as "300s", "1.5h" or "2h45m". Valid time units are:
+    "ns", "us" (or "µs"), "ms", "s", "m", "h".`).Default("1s"),
 	},
 
 	Run: func(req cmds.Request, res cmds.Response) {
@@ -78,19 +115,15 @@ var statBwCmd = &cmds.Command{
 			pid = checkpid
 		}
 
-		interval := time.Second
-		timeS, found, err := req.Option("interval").String()
+		timeS, _, err := req.Option("interval").String()
 		if err != nil {
 			res.SetError(err, cmds.ErrNormal)
 			return
 		}
-		if found {
-			v, err := time.ParseDuration(timeS)
-			if err != nil {
-				res.SetError(err, cmds.ErrNormal)
-				return
-			}
-			interval = v
+		interval, err := time.ParseDuration(timeS)
+		if err != nil {
+			res.SetError(err, cmds.ErrNormal)
+			return
 		}
 
 		doPoll, _, err := req.Option("poll").Bool()