follow-up

* CLI docs; up module

Signed-off-by: Alex Aizman <[email protected]>

cmd/cli/go.mod

@@ -4,7 +4,7 @@ go 1.21
 
 // direct
 require (
-	github.com/NVIDIA/aistore v1.3.21-0.20231020145509-a29b06b4c9d3
+	github.com/NVIDIA/aistore v1.3.21-0.20231020160354-468c3004def8
 	github.com/fatih/color v1.15.0
 	github.com/json-iterator/go v1.1.12
 	github.com/onsi/ginkgo v1.16.5

cmd/cli/go.sum

@@ -1,7 +1,7 @@
 code.cloudfoundry.org/bytefmt v0.0.0-20190710193110-1eb035ffe2b6/go.mod h1:wN/zk7mhREp/oviagqUXY3EwuHhWyOvAdsn5Y4CzOrc=
 github.com/BurntSushi/toml v1.3.2/go.mod h1:CxXYINrC8qIiEnFrOxCa7Jy5BFHlXnUU2pbicEuybxQ=
-github.com/NVIDIA/aistore v1.3.21-0.20231020145509-a29b06b4c9d3 h1:NRjBrI4KbUsT9osy988EZKUNpORwpm39oJtcXbhvgAM=
-github.com/NVIDIA/aistore v1.3.21-0.20231020145509-a29b06b4c9d3/go.mod h1:+iSnZg0ovMaLgaT9fLAs2WmYBP7IfeTW1WYkbKrwP4g=
+github.com/NVIDIA/aistore v1.3.21-0.20231020160354-468c3004def8 h1:PyRwhNw44rc4qTZoJWsr0/a3pm3skTD3ez2AEIvGCQ0=
+github.com/NVIDIA/aistore v1.3.21-0.20231020160354-468c3004def8/go.mod h1:+iSnZg0ovMaLgaT9fLAs2WmYBP7IfeTW1WYkbKrwP4g=
 github.com/OneOfOne/xxhash v1.2.8 h1:31czK/TI9sNkxIKfaUfGlU47BAxQ0ztGgd9vPyqimf8=
 github.com/OneOfOne/xxhash v1.2.8/go.mod h1:eZbhyaAYD41SGSSsnmcpxVoRiQ/MPUTjUdIIOT9Um7Q=
 github.com/VividCortex/ewma v1.1.1/go.mod h1:2Tkkvm3sRDVXaiyucHiACn4cqf7DpdyLvmxzcbUokwA=

docs/cli/bucket.md

@@ -685,6 +685,8 @@ To check the status, run: ais show job xaction copy-bck ais://bck2
 
 `ais storage summary [command options] PROVIDER:[//BUCKET_NAME] - show bucket sizes and the respective percentages of used capacity on a per-bucket basis
 
+`ais bucket summary` - same as above.
+
 ### Options
 
 ```console
@@ -697,19 +699,19 @@ USAGE:
 OPTIONS:
    --refresh value   interval for continuous monitoring;
                      valid time units: ns, us (or µs), ms, s (default), m, h
-   --count value     used together with '--refresh' to limit the number of generated reports (default: 0)
+   --count value     used together with '--refresh' to limit the number of generated reports, e.g.:
+                      '--refresh 10 --count 5' - run 5 times with 10s interval (default: 0)
    --prefix value    for each bucket, select only those objects (names) that start with the specified prefix, e.g.:
                      '--prefix a/b/c' - sum-up sizes of the virtual directory a/b/c and objects from the virtual directory
                      a/b that have names (relative to this directory) starting with the letter c
    --cached          list only those objects from a remote bucket that are present ("cached")
-   --all             all buckets, including accessible remote buckets that are not present in the cluster
    --units value     show statistics and/or parse command-line specified sizes using one of the following _units of measurement_:
                      iec - IEC format, e.g.: KiB, MiB, GiB (default)
                      si  - SI (metric) format, e.g.: KB, MB, GB
                      raw - do not convert to (or from) human-readable format
-   --verbose, -v     verbose
-   --timeout value   maximum time to wait for a job to finish; if omitted wait forever or Ctrl-C;
-                     valid time units: ns, us (or µs), ms, s (default), m, h
+   --verbose, -v     verbose output
+   --dont-wait       when _summarizing_ buckets do not wait for the respective job to finish -
+                     use the job's UUID to query the results interactively
    --no-headers, -H  display tables without headers
    --help, -h        show help
 ```
@@ -753,17 +755,22 @@ ais://nnn        49873           200.00MiB       0%
 ```
 
 ```console
-# 3. summarize ais://abc to show min/avg/max object sizes and _apparent_ bucket sizes
-###
-###   Apparent bucket size is the sum(sizes of all objects in the bucket) - will
-###   always be smaller than the actual disk usage. The difference will be even more
-###   pronounced in presence of mirroring and/or erasure coding.
-###   E.g., in a mirrored bucket configured for 3 replicas, the sum of all object
-###   sizes will be more than 3 times smaller than the size on disk.
-###
-$ ais bucket summary ais://abc --fast=false
-NAME             OBJECTS         OBJECT SIZE (min, avg, max)             SIZE (sum object sizes)   USAGE(%)
-ais://abc        10902           1.07KiB    515.01KiB  1023.51KiB        5.35GiB                   1%
+# 3.  "summarize" all s3:// buckets; count both "cached" and remote objects:
+$ ais bucket summary s3: --all
+```
+
+```console
+# 4. same as above with progress updates every 3 seconds:
+$ ais bucket summary s3: --all --refresh 3
+```
+
+```console
+# 4. "summarize" a given gs:// bucket; start the job and exit without waiting for it to finish
+# (see prompt below):
+$ ais bucket summary gs://abc --all --dont-wait
+
+Job summary[wl-s5lIWA] has started. To monitor, run 'ais storage summary gs://abc wl-s5lIWA --dont-wait' or 'ais show job wl-s5lIWA;
+see '--help' for details'
 ```
 
 ## Start N-way Mirroring

docs/cli/storage.md

@@ -69,53 +69,9 @@ Further references:
 
 ## Show capacity usage
 
-`ais storage summary [BUCKET | PROVIDER]`
+For command line options and usage examples, please refer to:
 
-Show summary information on a per bucket basis. If `BUCKET` is specified in the command line, the output gets narrowed down to this specific bucket. The same goes for `PROVIDER` (e.g., `ais://`, `aws://`, `gs://`, etc.) - again, only if specified.
-
-> Bucket providers and supported remote backends are documented [here](/docs/providers.md).
-
-Depending on the command line options (listed below), per-bucket information includes total number of objects, size of the bucket in bytes or megabytes, and percentage of the total capacity used by the bucket.
-
-A recently added `--validate` option is intended to analyze integrity of the stored distributed content. The questions that we ask at validation time "cover" location of stored objects and their replicas, the number of replicas (and whether this number agrees with the bucket configuration), etc.
-
-In particular, location of each objects stored in the cluster must at any point in time correspond to the current cluster map and, within each storage target, to the target's *mountpaths* (disks).  A failure to abide by location rules is called "misplacement"; misplaced objects - if any - must be migrated to their proper locations via automated processes called `global rebalance` and `resilver`:
-
-* [global rebalance and reslver](/docs/rebalance.md)
-* [resilvering selected targets: advanced usage](/docs/resourcesvanced.md)
-
-When `--fast` option is used the summary will include (internal-usage) details such as temporary objects, copies, EC slices, metadata files, and more.
-
-### Options
-
-| Flag | Type | Description | Default |
-| --- | --- | --- | --- |
-| `--fast` | `bool` | The option is designed primarily for internal usage. The output may not accurately reflect user-accessible content. | `false` |
-| `--validate` | `bool` | Check objects for errors: misplaced, insufficient number of copies etc | `false` |
-| `--cached` | `bool` | For buckets that have remote backend, list only objects stored in the cluster | `false` |
-| `--count` | `int` | Can be used in combination with `--refresh` option to limit the number of generated reports | `1` |
-| `--refresh` | `duration` | Refresh interval - time duration between reports. The usual unit suffixes are supported and include `m` (for minutes), `s` (seconds), `ms` (milliseconds) | ` ` |
-
-
-### Example
-
-Show summary for all buckets.
-
-```console
-$ ais storage summary
-NAME             OBJECTS         SIZE            USED %
-ais://bck        2               59.24KiB        0.00%
-```
-
-Show estimated summary.
-
-```console
-$ ais storage summary --fast
-NAME             EST. OBJECTS    EST. SIZE       EST. USED %
-ais://bck        4               224.00KiB       0.00%
-```
-
-The bucket `ais://bck` has mirroring enabled, so its number of objects doubles.
+* [bucket summary](/docs/cli/bucket.md#show-bucket-summary)
 
 ## Validate buckets