Add support for documented byte/size units and for micros as a time unit in _cat API

We advertise in our documentation that byte units are like `kb`, `mb`... But we actually only support the simple notation `k` or `m`.
This commit adds support for the documented form and keeps the non documented options to avoid any breaking change.

It also adds support for `micros`, `nanos` and `d` as a time unit in `_cat` API.

Remove the support for `b` as a SizeValue unit. Actually, for numbers, when using raw numbers without unit, there is no text to add/parse after the number. For example, you don't write `10` as `10b`. We support option like `size=` in `_cat` API which means that we want to display raw data without unit (singles).

Documentation updated accordingly.

Add test for the empty size option.

Fix missing TimeValues options for some cat APIs

core/src/main/java/org/elasticsearch/common/unit/SizeValue.java

@@ -175,9 +175,7 @@ public class SizeValue implements Streamable {
         }
         long singles;
         try {
-            if (sValue.endsWith("b")) {
-                singles = Long.parseLong(sValue.substring(0, sValue.length() - 1));
-            } else if (sValue.endsWith("k") || sValue.endsWith("K")) {
+            if (sValue.endsWith("k") || sValue.endsWith("K")) {
                 singles = (long) (Double.parseDouble(sValue.substring(0, sValue.length() - 1)) * SizeUnit.C1);
             } else if (sValue.endsWith("m") || sValue.endsWith("M")) {
                 singles = (long) (Double.parseDouble(sValue.substring(0, sValue.length() - 1)) * SizeUnit.C2);
@@ -232,4 +230,4 @@ public class SizeValue implements Streamable {
         result = 31 * result + (sizeUnit != null ? sizeUnit.hashCode() : 0);
         return result;
     }
-}
+}

core/src/main/java/org/elasticsearch/rest/action/support/RestTable.java

@@ -303,15 +303,15 @@ public class RestTable {
             String resolution = request.param("bytes");
             if ("b".equals(resolution)) {
                 return Long.toString(v.bytes());
-            } else if ("k".equals(resolution)) {
+            } else if ("k".equals(resolution) || "kb".equals(resolution)) {
                 return Long.toString(v.kb());
-            } else if ("m".equals(resolution)) {
+            } else if ("m".equals(resolution) || "mb".equals(resolution)) {
                 return Long.toString(v.mb());
-            } else if ("g".equals(resolution)) {
+            } else if ("g".equals(resolution) || "gb".equals(resolution)) {
                 return Long.toString(v.gb());
-            } else if ("t".equals(resolution)) {
+            } else if ("t".equals(resolution) || "tb".equals(resolution)) {
                 return Long.toString(v.tb());
-            } else if ("p".equals(resolution)) {
+            } else if ("p".equals(resolution) || "pb".equals(resolution)) {
                 return Long.toString(v.pb());
             } else {
                 return v.toString();
@@ -320,7 +320,7 @@ public class RestTable {
         if (value instanceof SizeValue) {
             SizeValue v = (SizeValue) value;
             String resolution = request.param("size");
-            if ("b".equals(resolution)) {
+            if ("".equals(resolution)) {
                 return Long.toString(v.singles());
             } else if ("k".equals(resolution)) {
                 return Long.toString(v.kilo());
@@ -339,7 +339,11 @@ public class RestTable {
         if (value instanceof TimeValue) {
             TimeValue v = (TimeValue) value;
             String resolution = request.param("time");
-            if ("ms".equals(resolution)) {
+            if ("nanos".equals(resolution)) {
+                return Long.toString(v.nanos());
+            } else if ("micros".equals(resolution)) {
+                return Long.toString(v.micros());
+            } else if ("ms".equals(resolution)) {
                 return Long.toString(v.millis());
             } else if ("s".equals(resolution)) {
                 return Long.toString(v.seconds());
@@ -347,6 +351,8 @@ public class RestTable {
                 return Long.toString(v.minutes());
             } else if ("h".equals(resolution)) {
                 return Long.toString(v.hours());
+            } else if ("d".equals(resolution)) {
+                return Long.toString(v.days());
             } else {
                 return v.toString();
             }

docs/reference/api-conventions.asciidoc

@@ -361,12 +361,14 @@ are:
 `m`::   Minute
 `s`::   Second
 `ms`::  Milli-second
+`micros`::  Micro-second
+`nanos`::  Nano-second
 
-[[size-units]]
+[[byte-units]]
 [float]
-=== Data size units
+=== Byte size units
 
-Whenever the size of data needs to be specified, eg when setting a buffer size
+Whenever the byte size of data needs to be specified, eg when setting a buffer size
 parameter, the value must specify the unit, like `10kb` for 10 kilobytes.  The
 supported units are:
 
@@ -378,6 +380,23 @@ supported units are:
 `tb`::  Terabytes
 `pb`::  Petabytes
 
+[[size-units]]
+[float]
+=== Unit-less quantities
+
+Unit-less quantities means that they don't have a "unit" like "bytes" or "Hertz" or "meter" or "long tonne".
+
+If one of these quantities is large we'll print it out like 10m for 10,000,000 or 7k for 7,000. We'll still print 87
+when we mean 87 though. These are the supported multipliers:
+
+[horizontal]
+``::   Single
+`k`::  Kilo
+`m`::  Mega
+`g`::  Giga
+`t`::  Tera
+`p`::  Peta
+
 [[distance-units]]
 [float]
 === Distance Units

docs/reference/cat.asciidoc

@@ -74,8 +74,8 @@ with `bulk.`.
 [[numeric-formats]]
 === Numeric formats
 
-Many commands provide a few types of numeric output, either a byte
-value or a time value.  By default, these types are human-formatted,
+Many commands provide a few types of numeric output, either a byte, size
+or a time value.  By default, these types are human-formatted,
 for example, `3.5mb` instead of `3763212`.  The human values are not
 sortable numerically, so in order to operate on these values where
 order is important, you can change it.
@@ -95,6 +95,12 @@ green wiki1 3 0 10000 413 103776272 103776272
 green foo   1 0   227   0   2065131   2065131
 --------------------------------------------------
 
+If you want to change the <<time-units,time units>>, use `time` parameter.
+
+If you want to change the <<size-units,size units>>, use `size` parameter.
+
+If you want to change the <<byte-units,byte units>>, use `bytes` parameter.
+
 [float]
 === Response as text, json, smile, yaml or cbor
 

rest-api-spec/src/main/resources/rest-api-spec/api/cat.allocation.json

@@ -19,7 +19,7 @@
         "bytes": {
           "type": "enum",
           "description" : "The unit in which to display byte values",
-          "options": [ "b", "k", "m", "g" ]
+          "options": [ "b", "k", "kb", "m", "mb", "g", "gb", "t", "tb", "p", "pb" ]
         },
         "local": {
           "type" : "boolean",

rest-api-spec/src/main/resources/rest-api-spec/api/cat.fielddata.json

@@ -19,7 +19,7 @@
         "bytes": {
           "type": "enum",
           "description" : "The unit in which to display byte values",
-          "options": [ "b", "k", "m", "g" ]
+          "options": [ "b", "k", "kb", "m", "mb", "g", "gb", "t", "tb", "p", "pb" ]
         },
         "local": {
           "type" : "boolean",

rest-api-spec/src/main/resources/rest-api-spec/api/cat.recovery.json

@@ -19,7 +19,7 @@
         "bytes": {
           "type": "enum",
           "description" : "The unit in which to display byte values",
-          "options": [ "b", "k", "m", "g" ]
+          "options": [ "b", "k", "kb", "m", "mb", "g", "gb", "t", "tb", "p", "pb" ]
         },
         "master_timeout": {
           "type" : "time",

rest-api-spec/src/main/resources/rest-api-spec/api/cat.thread_pool.json

@@ -12,6 +12,11 @@
           "type" : "string",
           "description" : "a short version of the Accept header, e.g. json, yaml"
         },
+        "size": {
+          "type": "enum",
+          "description" : "The multiplier in which to display values",
+          "options": [ "", "k", "m", "g", "t", "p" ]
+        },
         "local": {
           "type" : "boolean",
           "description" : "Return local information, do not retrieve the state from master node (default: false)"

rest-api-spec/src/main/resources/rest-api-spec/test/cat.allocation/10_basic.yaml

@@ -215,7 +215,7 @@
 
   - do:
       cat.allocation:
-        bytes: g
+        bytes: gb
 
   - match:
       $body: |

rest-api-spec/src/main/resources/rest-api-spec/test/cat.thread_pool/10_basic.yaml

@@ -147,3 +147,13 @@
       $body: |
                /^  id  \s+  warmer.type              \s+  warmer.active  \s+  warmer.size  \s+  warmer.queue  \s+  warmer.queueSize  \s+  warmer.rejected  \s+  warmer.largest  \s+  warmer.completed  \s+  warmer.min  \s+  warmer.max  \s+  warmer.keepAlive    \n
                   (\S+ \s+  (cached|fixed|scaling)?  \s+            \d+  \s+          \d+  \s+           \d+  \s+               \d*  \s+              \d+  \s+             \d+  \s+               \d+  \s+         \d*  \s+         \d*  \s+               \S*    \n)+  $/
+
+  - do:
+      cat.thread_pool:
+          size: ""
+
+  - match:
+      $body: |
+               /  #host       ip                          bulk.active       bulk.queue       bulk.rejected       index.active       index.queue       index.rejected       search.active       search.queue       search.rejected
+               ^  (\S+   \s+  (\d{1,3}\.){3}\d{1,3}  \s+  \d+          \s+  \d+         \s+  \d+            \s+  \d+           \s+  \d+          \s+  \d+             \s+  \d+            \s+  \d+           \s+  \d+                \n)+  $/
+