From 80ba48283c09c9720766ee399f2b26f9d65f45a2 Mon Sep 17 00:00:00 2001 From: Adrien Grand Date: Thu, 3 Sep 2020 19:12:17 +0200 Subject: [PATCH 1/6] Document standard metadata entries. We standardize on some metadata entries that we plan to later leverage in Kibana in order to provide a better out-of-the-box experience, e.g. different visualizations make sense on gauges and counters. --- docs/reference/mapping/params/meta.asciidoc | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/reference/mapping/params/meta.asciidoc b/docs/reference/mapping/params/meta.asciidoc index d97c9c1a21420..7d53d1287f1d5 100644 --- a/docs/reference/mapping/params/meta.asciidoc +++ b/docs/reference/mapping/params/meta.asciidoc @@ -29,3 +29,24 @@ than or equal to 50. NOTE: Field metadata is updatable by submitting a mapping update. The metadata of the update will override the metadata of the existing field. + +Elastic products standardize on the following metadata, which you may use too +in order to get a better out-of-the-box experience with your data. + +unit:: + + The unit of the field. Recognizes `"byte"` as well as + <>. By default, fields are assumed to not have a unit. + This information should only be specified on numeric fields. + +metric_type:: + + The type of metric. Recognizes `"gauge"` and `"counter"`. By default, fields + are assumed to not be a metric. This information should only be specified on + numeric fields. + +ratio:: + + Whether the field is a ratio. Recognizes `true` and `false` (default). The + value should not be `true` when a `unit` is also specified. This information + should only be specified on numeric fields. From 3d9c6c6590d9bb7e59ada3e11320cdc328ad52e5 Mon Sep 17 00:00:00 2001 From: Adrien Grand Date: Fri, 4 Sep 2020 11:11:21 +0200 Subject: [PATCH 2/6] more info about gauge vs metric --- docs/reference/mapping/params/meta.asciidoc | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/reference/mapping/params/meta.asciidoc b/docs/reference/mapping/params/meta.asciidoc index 7d53d1287f1d5..8337876252c2f 100644 --- a/docs/reference/mapping/params/meta.asciidoc +++ b/docs/reference/mapping/params/meta.asciidoc @@ -41,9 +41,12 @@ unit:: metric_type:: - The type of metric. Recognizes `"gauge"` and `"counter"`. By default, fields - are assumed to not be a metric. This information should only be specified on - numeric fields. + The type of metric. Recognizes `"gauge"` and `"counter"`. A gauge is a + single-valued measurement that can go up or down over time, such as a + temperature. A counter is a single-valued cumulative counter that only goes + up, such as the number of requests processed by a web server. By default, + fields are assumed to not be a metric. This information should only be + specified on numeric fields. ratio:: From b6dcdf5a216933003458f745b79006e2ea196a58 Mon Sep 17 00:00:00 2001 From: Adrien Grand Date: Fri, 4 Sep 2020 11:13:15 +0200 Subject: [PATCH 3/6] iter --- docs/reference/mapping/params/meta.asciidoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/reference/mapping/params/meta.asciidoc b/docs/reference/mapping/params/meta.asciidoc index 8337876252c2f..ea197dd527540 100644 --- a/docs/reference/mapping/params/meta.asciidoc +++ b/docs/reference/mapping/params/meta.asciidoc @@ -37,7 +37,7 @@ unit:: The unit of the field. Recognizes `"byte"` as well as <>. By default, fields are assumed to not have a unit. - This information should only be specified on numeric fields. + This information may only be specified on numeric fields. metric_type:: @@ -45,11 +45,11 @@ metric_type:: single-valued measurement that can go up or down over time, such as a temperature. A counter is a single-valued cumulative counter that only goes up, such as the number of requests processed by a web server. By default, - fields are assumed to not be a metric. This information should only be + fields are assumed to not be a metric. This information may only be specified on numeric fields. ratio:: Whether the field is a ratio. Recognizes `true` and `false` (default). The value should not be `true` when a `unit` is also specified. This information - should only be specified on numeric fields. + may only be specified on numeric fields. From c607d8bd93e75e0b049523642ed8beab93463aea Mon Sep 17 00:00:00 2001 From: Adrien Grand Date: Thu, 8 Oct 2020 14:58:45 +0200 Subject: [PATCH 4/6] Apply suggestions from code review Co-authored-by: debadair --- docs/reference/mapping/params/meta.asciidoc | 23 +++++++++------------ 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/docs/reference/mapping/params/meta.asciidoc b/docs/reference/mapping/params/meta.asciidoc index ea197dd527540..ddbb7b0edec98 100644 --- a/docs/reference/mapping/params/meta.asciidoc +++ b/docs/reference/mapping/params/meta.asciidoc @@ -30,26 +30,23 @@ than or equal to 50. NOTE: Field metadata is updatable by submitting a mapping update. The metadata of the update will override the metadata of the existing field. -Elastic products standardize on the following metadata, which you may use too -in order to get a better out-of-the-box experience with your data. +Elastic products use the following standard metadata entries for fields. You can follow these same metadata conventions to get a better out-of-the-box experience with your data. unit:: - The unit of the field. Recognizes `"byte"` as well as - <>. By default, fields are assumed to not have a unit. - This information may only be specified on numeric fields. + The unit associated with a numeric field: `"byte"` or a + <>. By default, a field does not have a unit. + Only valid for numeric fields. metric_type:: - The type of metric. Recognizes `"gauge"` and `"counter"`. A gauge is a - single-valued measurement that can go up or down over time, such as a - temperature. A counter is a single-valued cumulative counter that only goes + The metric type of a numeric field: `"gauge"` or `"counter"`. A gauge is a + single-value measurement that can go up or down over time, such as a + temperature. A counter is a single-value cumulative counter that only goes up, such as the number of requests processed by a web server. By default, - fields are assumed to not be a metric. This information may only be - specified on numeric fields. + no metric type is associated with a field. Only valid for numeric fields. ratio:: - Whether the field is a ratio. Recognizes `true` and `false` (default). The - value should not be `true` when a `unit` is also specified. This information - may only be specified on numeric fields. + A boolean value that indicates whether a field is a ratio. Defaults to `false`. The + Leave set to `false` if a `unit` is specified. Only valid for numeric fields. From e8e21424fc1e0019115f66567b344dfbd1cb25b2 Mon Sep 17 00:00:00 2001 From: Adrien Grand Date: Thu, 8 Oct 2020 15:06:07 +0200 Subject: [PATCH 5/6] Make `percent` a unit and remove `ratio`. --- docs/reference/mapping/params/meta.asciidoc | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/docs/reference/mapping/params/meta.asciidoc b/docs/reference/mapping/params/meta.asciidoc index ddbb7b0edec98..4a9f0e08e54a9 100644 --- a/docs/reference/mapping/params/meta.asciidoc +++ b/docs/reference/mapping/params/meta.asciidoc @@ -30,11 +30,13 @@ than or equal to 50. NOTE: Field metadata is updatable by submitting a mapping update. The metadata of the update will override the metadata of the existing field. -Elastic products use the following standard metadata entries for fields. You can follow these same metadata conventions to get a better out-of-the-box experience with your data. +Elastic products use the following standard metadata entries for fields. You +can follow these same metadata conventions to get a better out-of-the-box +experience with your data. unit:: - The unit associated with a numeric field: `"byte"` or a + The unit associated with a numeric field: `"percent"`, `"byte"` or a <>. By default, a field does not have a unit. Only valid for numeric fields. @@ -44,9 +46,4 @@ metric_type:: single-value measurement that can go up or down over time, such as a temperature. A counter is a single-value cumulative counter that only goes up, such as the number of requests processed by a web server. By default, - no metric type is associated with a field. Only valid for numeric fields. - -ratio:: - - A boolean value that indicates whether a field is a ratio. Defaults to `false`. The - Leave set to `false` if a `unit` is specified. Only valid for numeric fields. + no metric type is associated with a field. Only valid for numeric fields. From cd30656dfe00aadd7865d49c6c21e20956be645e Mon Sep 17 00:00:00 2001 From: Adrien Grand Date: Thu, 8 Oct 2020 15:08:20 +0200 Subject: [PATCH 6/6] iter --- docs/reference/mapping/params/meta.asciidoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/reference/mapping/params/meta.asciidoc b/docs/reference/mapping/params/meta.asciidoc index 4a9f0e08e54a9..16f4394ba57fb 100644 --- a/docs/reference/mapping/params/meta.asciidoc +++ b/docs/reference/mapping/params/meta.asciidoc @@ -38,7 +38,8 @@ unit:: The unit associated with a numeric field: `"percent"`, `"byte"` or a <>. By default, a field does not have a unit. - Only valid for numeric fields. + Only valid for numeric fields. The convention for percents is to use + value `1` to mean `100%`. metric_type::