Chore(clean-up): docs + timestamp (int64)

internal/cmd/stats.go

@@ -21,6 +21,9 @@ type stat struct {
 	Uploaded   int
 }
 
+// show stats is really expensive, it will (attempt to) crawl the entire `?ostor-usage` endpoint
+// and look up individual entries when returned, so for n pages returned from `?ostor-usage`, it
+// will make n * number of items returned requests to `?ostor-usage&obj=FOO`
 func ShowStats(cCtx *cli.Context) error {
 	client := cCtx.Context.Value(OstorClient).(*ostor.Ostor)
 

pkg/ostor/types.go

@@ -49,12 +49,18 @@ type OStorResponse struct {
 // }
 
 type OStorObjectUsageResponse struct {
-	Version   int    `json:"fmt_version"`
+	// probably an API version of some kind
+	Version int `json:"fmt_version"`
+	// volume ID (ostor-ctl get-config)
 	ServiceID string `json:"service_id"`
-	StartTS   int    `json:"start_ts"`
-	Period    int    `json:"period"`
-	Count     int    `json:"nr_items"`
-	Items     []struct {
+	// start time of the object you are looking at
+	StartTS int64 `json:"start_ts"`
+	// sample interval of the object (usually ~30 seconds)
+	Period int `json:"period"`
+	// number of items in the response
+	Count int `json:"nr_items"`
+	// the actual items
+	Items []struct {
 		Key      ItemKey `json:"key"`
 		Counters struct {
 			Operations ItemCountersOps `json:"ops"`
@@ -65,6 +71,7 @@ type OStorObjectUsageResponse struct {
 
 type ItemKey struct {
 	Bucket string `json:"bucket"`
+	// identifier for the item/record
 	Epoch  int    `json:"epoch"`
 	UserID string `json:"user_id"`
 	Tag    string `json:"tag"`