Updating "Best practices: Naming lables" #2469 (#2549)

Best practices: Refine metric naming recommendations

---------

Signed-off-by: Gopi-eng2202 <[email protected]>
Signed-off-by: gopi <[email protected]>
Signed-off-by: beorn7 <[email protected]>
Co-authored-by: Ben Kochie <[email protected]>
Co-authored-by: beorn7 <[email protected]>

Author: 3 people

content/docs/practices/naming.md

@@ -20,30 +20,41 @@ A metric name...
   client libraries. For metrics specific to an application, the prefix is
   usually the application name itself. Sometimes, however, metrics are more
   generic, like standardized metrics exported by client libraries. Examples:
- * <code><b>prometheus</b>\_notifications\_total</code>
-   (specific to the Prometheus server)
- * <code><b>process</b>\_cpu\_seconds\_total</code>
-   (exported by many client libraries)
- * <code><b>http</b>\_request\_duration\_seconds</code>
-   (for all HTTP requests)
+  * <code><b>prometheus</b>\_notifications\_total</code>
+    (specific to the Prometheus server)
+  * <code><b>process</b>\_cpu\_seconds\_total</code>
+    (exported by many client libraries)
+  * <code><b>http</b>\_request\_duration\_seconds</code>
+    (for all HTTP requests)
 * ...must have a single unit (i.e. do not mix seconds with milliseconds, or seconds with bytes).
-* ...should use base units (e.g. seconds, bytes, meters - not milliseconds, megabytes, kilometers). See below for a list of base units.
-* ...should have a suffix describing the unit, in plural form. Note that an accumulating count has `total` as a suffix, in addition to the unit if applicable.
- * <code>http\_request\_duration\_<b>seconds</b></code>
- * <code>node\_memory\_usage\_<b>bytes</b></code>
- * <code>http\_requests\_<b>total</b></code>
-   (for a unit-less accumulating count)
- * <code>process\_cpu\_<b>seconds\_total</b></code>
-   (for an accumulating count with unit)
- * <code>foobar_build<b>\_info</b></code>
-   (for a pseudo-metric that provides [metadata](https://www.robustperception.io/exposing-the-software-version-to-prometheus) about the running binary)
- * <code>data\_pipeline\_last\_record\_processed\_<b>timestamp_seconds</b></code>
-  (for a timestamp that tracks the time of the latest record processed in a data processing pipeline)
+* ...should use base units (e.g. seconds, bytes, meters - not milliseconds, megabytes, kilometers).See below for a list of base units.
+* ...should have a suffix describing the unit, in plural form. Note that an accumulating count has `total` as a suffix, in addition to the unit if applicable. Also note that this applies to units in the narrow sense (like the units in the table below), but not to countable things in general. For example, <code>connections</code> or <code>notifications</code> are not considered units for this rule and do not have to be at the end of the metric name. (See also examples in the next paragraph.)
+  * <code>http\_request\_duration\_<b>seconds</b></code>
+  * <code>node\_memory\_usage\_<b>bytes</b></code>
+  * <code>http\_requests\_<b>total</b></code>
+    (for a unit-less accumulating count)
+  * <code>process\_cpu\_<b>seconds\_total</b></code>
+    (for an accumulating count with unit)
+  * <code>foobar_build<b>\_info</b></code>
+    (for a pseudo-metric that provides [metadata](https://www.robustperception.io/exposing-the-software-version-to-prometheus) about the running binary)
+  * <code>data\_pipeline\_last\_record\_processed\_<b>timestamp_seconds</b></code>
+    (for a timestamp that tracks the time of the latest record processed in a data processing pipeline)
+* ...may order its name components in a way that leads to convenient grouping when a list of metric names is sorted lexicographically, as long as all the other rules are followed. The following examples have their the common name components first so that all the related metrics are sorted together:
+  * <code>prometheus\_tsdb\_head\_truncations\_closed\_total</code>
+  * <code>prometheus\_tsdb\_head\_truncations\_established\_total</code>
+  * <code>prometheus\_tsdb\_head\_truncations\_failed\_total</code>
+  * <code>prometheus\_tsdb\_head\_truncations\_total</code>
+
+  The following examples are also valid, but are following a different trade-off. They are easier to read individually, but unrelated metrics like <code>prometheus\_tsdb\_head\_series</code> might get sorted in between.
+  * <code>prometheus\_tsdb\_head\_closed\_truncations\_total</code>
+  * <code>prometheus\_tsdb\_head\_established\_truncations\_total</code>
+  * <code>prometheus\_tsdb\_head\_failed\_truncations\_total</code>
+  * <code>prometheus\_tsdb\_head\_truncations\_total</code>
 * ...should represent the same logical thing-being-measured across all label
   dimensions.
- * request duration
- * bytes of data transfer
- * instantaneous resource usage as a percentage
+  * request duration
+  * bytes of data transfer
+  * instantaneous resource usage as a percentage
 
 As a rule of thumb, either the `sum()` or the `avg()` over all dimensions of a
 given metric should be meaningful (though not necessarily useful). If it is not