[DOCS] Adds cat datafeeds API (#52738)

docs/reference/cat.asciidoc

@@ -231,6 +231,8 @@ include::cat/count.asciidoc[]
 
 include::cat/dataframeanalytics.asciidoc[]
 
+include::cat/datafeeds.asciidoc[]
+
 include::cat/fielddata.asciidoc[]
 
 include::cat/health.asciidoc[]

docs/reference/cat/datafeeds.asciidoc

@@ -0,0 +1,155 @@
+[role="xpack"]
+[testenv="platinum"]
+[[cat-datafeeds]]
+=== cat {dfeeds} API
+++++
+<titleabbrev>cat {dfeeds}</titleabbrev>
+++++
+
+Returns configuration and usage information about {dfeeds}.
+
+[[cat-datafeeds-request]]
+==== {api-request-title}
+
+`GET /_cat/ml/datafeeds/<feed_id>` +
+
+`GET /_cat/ml/datafeeds`
+
+[[cat-datafeeds-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `monitor_ml`,
+`monitor`, `manage_ml`, or `manage` cluster privileges to use this API. See
+<<security-privileges>> and {ml-docs}/setup.html[Set up {ml-features}].
+
+////
+[[cat-datafeeds-desc]]
+==== {api-description-title}
+
+TBD: This API returns a maximum of 10,000 {dfeeds}. 
+////
+
+[[cat-datafeeds-path-params]]
+==== {api-path-parms-title}
+
+`<feed_id>`::
+(Optional, string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=datafeed-id]
+
+[[cat-datafeeds-query-params]]
+==== {api-query-parms-title}
+
+`allow_no_datafeeds`::
+(Optional, boolean)
+include::{docdir}/ml/ml-shared.asciidoc[tag=allow-no-datafeeds]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=http-format]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-h]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=help]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=time]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v]
+
+[[cat-datafeeds-results]]
+==== {api-response-body-title}
+
+`assignment_explanation`::
+include::{docdir}/ml/ml-shared.asciidoc[tag=assignment-explanation]
++
+To retrieve this information, specify the `ae` column in the `h` query parameter. 
+
+`bucket.count`:: 
+include::{docdir}/ml/ml-shared.asciidoc[tag=bucket-count]
++
+To retrieve this information, specify the `bc` or `bucketCount` column in the
+`h` query parameter.
+
+`id`::
+include::{docdir}/ml/ml-shared.asciidoc[tag=datafeed-id]
++
+To retrieve this information, specify the `id` column in the `h` query parameter.
+  
+`node.address`::
+The network address of the node.
++ 
+include::{docdir}/ml/ml-shared.asciidoc[tag=node]
++
+To retrieve this information, specify the `na` or `nodeAddress` column in the
+`h` query parameter.
+  
+`node.ephemeral_id`::
+The ephemeral ID of the node.
++
+include::{docdir}/ml/ml-shared.asciidoc[tag=node]
++
+To retrieve this information, specify the `ne` or `nodeEphemeralId` column in
+the `h` query parameter.
+  
+`node.id`::
+The unique identifier of the node.
++
+include::{docdir}/ml/ml-shared.asciidoc[tag=node]
++
+To retrieve this information, specify the `ni` or `nodeId` column in the `h`
+query parameter.
+
+`node.name`::
+The node name.
++
+include::{docdir}/ml/ml-shared.asciidoc[tag=node]
++
+To retrieve this information, specify the `nn` or `nodeName` column in the `h`
+query parameter.
+
+`search.bucket_avg`::
+include::{docdir}/ml/ml-shared.asciidoc[tag=search-bucket-avg]
++
+To retrieve this information, specify the `sba` or `searchBucketAvg` column in
+the `h` query parameter.
+  
+`search.count`::
+include::{docdir}/ml/ml-shared.asciidoc[tag=search-count]
++
+To retrieve this information, specify the `sc` or `searchCount` column in the
+`h` query parameter.
+
+`search.exp_avg_hour`::
+include::{docdir}/ml/ml-shared.asciidoc[tag=search-exp-avg-hour]
++
+To retrieve this information, specify the `seah` or `searchExpAvgHour` column in
+the `h` query parameter.
+
+`search.time`::
+include::{docdir}/ml/ml-shared.asciidoc[tag=search-time]
++
+To retrieve this information, specify the `st` or `searchTime` column in the `h`
+query parameter.
+
+`state`::
+include::{docdir}/ml/ml-shared.asciidoc[tag=state-datafeed]
++
+To retrieve this information, specify the `s` column in the `h` query parameter. 
+
+[[cat-datafeeds-example]]
+==== {api-examples-title}
+
+[source,console]
+--------------------------------------------------
+GET _cat/ml/datafeeds?v
+--------------------------------------------------
+// TEST[skip:kibana sample data]
+
+[source,console-result]
+----
+id                              state bucket.count search.count
+datafeed-high_sum_total_sales stopped 743          7
+datafeed-low_request_rate     stopped 1457         3
+datafeed-response_code_rates  stopped 1460         18
+datafeed-url_scanning         stopped 1460         18
+----
+// TESTRESPONSE[skip:kibana sample data]

docs/reference/ml/anomaly-detection/apis/get-datafeed-stats.asciidoc

@@ -67,18 +67,17 @@ The API returns an array of {dfeed} count objects. All of these properties are
 informational; you cannot update their values.
 
 `assignment_explanation`::
-(string) For started {dfeeds} only, contains messages relating to the selection
+(string)
-of a node.
+include::{docdir}/ml/ml-shared.asciidoc[tag=assignment-explanation]
 
 `datafeed_id`::
 (string)
 include::{docdir}/ml/ml-shared.asciidoc[tag=datafeed-id]
 
 `node`::
-(object) The node upon which the {dfeed} is started. The {dfeed} and job will be
+(object)
-on the same node.
+include::{docdir}/ml/ml-shared.asciidoc[tag=node]
-`node`.`id`::: The unique identifier of the node. For example,
+`node`.`id`::: The unique identifier of the node. For example, "0-o0tOoRTwKFZifatTWKNw".
-`0-o0tOoRTwKFZifatTWKNw`.
 `node`.`name`::: The node name. For example, `0-o0tOo`.
 `node`.`ephemeral_id`::: The node ephemeral ID.
 `node`.`transport_address`::: The host and port where transport HTTP connections
@@ -86,28 +85,34 @@ are accepted. For example, `127.0.0.1:9300`.
 `node`.`attributes`::: For example, `{"ml.machine_memory": "17179869184"}`.
 
 `state`::
-(string) The status of the {dfeed}, which can be one of the following values:
+(string)
-+
+include::{docdir}/ml/ml-shared.asciidoc[tag=state-datafeed]
---
-* `started`::: The {dfeed} is actively receiving data.
-* `stopped`::: The {dfeed} is stopped and will not receive data until it is
-re-started.
---
 
 `timing_stats`::
 (object) An object that provides statistical information about timing aspect of
 this {dfeed}.
+
 `timing_stats`.`average_search_time_per_bucket_ms`:::
-(double) Average of the {dfeed} search times in milliseconds.
+(double)
+include::{docdir}/ml/ml-shared.asciidoc[tag=search-bucket-avg]
+
 `timing_stats`.`bucket_count`:::
-(long) The number of buckets processed. 
+(long)
+include::{docdir}/ml/ml-shared.asciidoc[tag=bucket-count]
+
 `timing_stats`.`exponential_average_search_time_per_hour_ms`:::
-(double) Exponential moving average of the {dfeed} search times in milliseconds.
+(double)
+include::{docdir}/ml/ml-shared.asciidoc[tag=search-exp-avg-hour]
+
 `timing_stats`.`job_id`:::
 include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
-`timing_stats`.`search_count`::: Number of searches performed by this {dfeed}.
+
-`timing_stats`.`total_search_time_ms`::: Total time the {dfeed} spent searching
+`timing_stats`.`search_count`:::
-in milliseconds.
+include::{docdir}/ml/ml-shared.asciidoc[tag=search-count]
+
+`timing_stats`.`total_search_time_ms`:::
+include::{docdir}/ml/ml-shared.asciidoc[tag=search-time]
+
 
 [[ml-get-datafeed-stats-response-codes]]
 ==== {api-response-codes-title}

docs/reference/ml/ml-shared.asciidoc

@@ -136,6 +136,10 @@ tag::analyzed-fields-includes[]
 An array of strings that defines the fields that will be included in the analysis.
 end::analyzed-fields-includes[]
 
+tag::assignment-explanation[]
+For started {dfeeds} only, contains messages relating to the selection of a node.
+end::assignment-explanation[]
+
 tag::assignment-explanation-dfanalytics[]
 Contains messages relating to the selection of a node.
 end::assignment-explanation-dfanalytics[]
@@ -153,6 +157,10 @@ so do not set the `background_persist_interval` value too low.
 --
 end::background-persist-interval[]
 
+tag::bucket-count[]
+The number of buckets processed.
+end::bucket-count[]
+
 tag::bucket-span[]
 The size of the interval that the analysis is aggregated into, typically between
 `5m` and `1h`. The default value is `5m`. If the {anomaly-job} uses a {dfeed}
@@ -901,6 +909,11 @@ improve diversity in the ensemble. Therefore, only override this if you are
 confident that the value you choose is appropriate for the data set.
 end::n-neighbors[]
 
+tag::node[]
+For started {dfeeds} only, this information pertains to the node upon which the
+{dfeed} is started.
+end::node[]
+
 tag::num-top-classes[]
 Defines the number of categories for which the predicted 
 probabilities are reported. It must be non-negative. If it is greater than the 
@@ -993,6 +1006,22 @@ tag::scroll-size[]
 The `size` parameter that is used in {es} searches. The default value is `1000`.
 end::scroll-size[]
 
+tag::search-bucket-avg[]
+The average search time per bucket, in milliseconds.
+end::search-bucket-avg[]
+
+tag::search-count[]
+The number of searches run by the {dfeed}.
+end::search-count[]
+
+tag::search-exp-avg-hour[]
+The exponential average search time per hour, in milliseconds.
+end::search-exp-avg-hour[]
+
+tag::search-time[]
+The total time the {dfeed} spent searching, in milliseconds.
+end::search-time[]
+
 tag::size[]
 Specifies the maximum number of {dfanalytics-jobs} to obtain. The default value 
 is `100`.
@@ -1039,6 +1068,16 @@ more information, see
 https://en.wikipedia.org/wiki/Feature_scaling#Standardization_(Z-score_Normalization)[this wiki page about standardization].
 end::standardization-enabled[]
 
+tag::state-datafeed[]
+The status of the {dfeed}, which can be one of the following values:
++
+--
+* `started`: The {dfeed} is actively receiving data.
+* `stopped`: The {dfeed} is stopped and will not receive data until it is
+re-started.
+--
+end::state-datafeed[]
+
 tag::summary-count-field-name[]
 If this property is specified, the data that is fed to the job is expected to be
 pre-summarized. This property value is the name of the field that contains the 

x-pack/plugin/ml/src/main/java/org/elasticsearch/xpack/ml/rest/cat/RestCatDatafeedsAction.java

@@ -96,7 +96,7 @@ public class RestCatDatafeedsAction extends AbstractCatAction {
                 .build());
         table.addCell("search.bucket_avg",
             TableColumnAttributeBuilder.builder("the average search time per bucket (millisecond)", false)
-                .setAliases("sba", "bucketTimeMin")
+                .setAliases("sba", "searchBucketAvg")
                 .build());
         table.addCell("search.exp_avg_hour",
             TableColumnAttributeBuilder.builder("the exponential average search time per hour (millisecond)", false)

x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_datafeeds.json

@@ -1,7 +1,7 @@
 {
   "cat.ml_datafeeds":{
     "documentation":{
-      "url":"http://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-datafeed-stats.html"
+      "url":"http://www.elastic.co/guide/en/elasticsearch/reference/current/cat-datafeeds.html"
     },
     "stability":"stable",
     "url":{