docs(monitoring): Update description of MetricDescriptor#unit in lowe…

…r-level API

google-cloud-monitoring/lib/google/cloud/monitoring/v3/doc/google/api/metric.rb

@@ -49,6 +49,58 @@ module Api
     #     Some combinations of `metric_kind` and `value_type` might not be supported.
     # @!attribute [rw] unit
     #   @return [String]
+    #     The units in which the metric value is reported. It is only applicable
+    #     if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The `unit`
+    #     defines the representation of the stored metric values.
+    #
+    #     Different systems may scale the values to be more easily displayed (so a
+    #     value of `0.02KBy` _might_ be displayed as `20By`, and a value of
+    #     `3523KBy` _might_ be displayed as `3.5MBy`). However, if the `unit` is
+    #     `KBy`, then the value of the metric is always in thousands of bytes, no
+    #     matter how it may be displayed..
+    #
+    #     If you want a custom metric to record the exact number of CPU-seconds used
+    #     by a job, you can create an `INT64 CUMULATIVE` metric whose `unit` is
+    #     `s{CPU}` (or equivalently `1s{CPU}` or just `s`). If the job uses 12,005
+    #     CPU-seconds, then the value is written as `12005`.
+    #
+    #     Alternatively, if you want a custome metric to record data in a more
+    #     granular way, you can create a `DOUBLE CUMULATIVE` metric whose `unit` is
+    #     `ks{CPU}`, and then write the value `12.005` (which is `12005/1000`),
+    #     or use `Kis{CPU}` and write `11.723` (which is `12005/1024`).
+    #
+    #     The supported units are a subset of [The Unified Code for Units of
+    #     Measure](http://unitsofmeasure.org/ucum.html) standard:
+    #
+    #     **Basic units (UNIT)**
+    #
+    #     * `bit`   bit
+    #     * `By`    byte
+    #     * `s`     second
+    #     * `min`   minute
+    #     * `h`     hour
+    #     * `d`     day
+    #
+    #     **Prefixes (PREFIX)**
+    #
+    #     * `k`     kilo    (10^3)
+    #     * `M`     mega    (10^6)
+    #     * `G`     giga    (10^9)
+    #     * `T`     tera    (10^12)
+    #     * `P`     peta    (10^15)
+    #     * `E`     exa     (10^18)
+    #     * `Z`     zetta   (10^21)
+    #     * `Y`     yotta   (10^24)
+    #
+    #     * `m`     milli   (10^-3)
+    #     * `u`     micro   (10^-6)
+    #     * `n`     nano    (10^-9)
+    #     * `p`     pico    (10^-12)
+    #     * `f`     femto   (10^-15)
+    #     * `a`     atto    (10^-18)
+    #     * `z`     zepto   (10^-21)
+    #     * `y`     yocto   (10^-24)
+    #
     #     * `Ki`    kibi    (2^10)
     #     * `Mi`    mebi    (2^20)
     #     * `Gi`    gibi    (2^30)