diff --git a/docs/reference/cat.asciidoc b/docs/reference/cat.asciidoc index d1040d000c583..6f12302b30ec0 100644 --- a/docs/reference/cat.asciidoc +++ b/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[] diff --git a/docs/reference/cat/datafeeds.asciidoc b/docs/reference/cat/datafeeds.asciidoc new file mode 100644 index 0000000000000..95a830aa82347 --- /dev/null +++ b/docs/reference/cat/datafeeds.asciidoc @@ -0,0 +1,155 @@ +[role="xpack"] +[testenv="platinum"] +[[cat-datafeeds]] +=== cat {dfeeds} API +++++ +cat {dfeeds} +++++ + +Returns configuration and usage information about {dfeeds}. + +[[cat-datafeeds-request]] +==== {api-request-title} + +`GET /_cat/ml/datafeeds/` + + +`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 +<> 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} + +``:: +(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] diff --git a/docs/reference/ml/anomaly-detection/apis/get-datafeed-stats.asciidoc b/docs/reference/ml/anomaly-detection/apis/get-datafeed-stats.asciidoc index 21a907a703c9a..463d17771cc2c 100644 --- a/docs/reference/ml/anomaly-detection/apis/get-datafeed-stats.asciidoc +++ b/docs/reference/ml/anomaly-detection/apis/get-datafeed-stats.asciidoc @@ -68,15 +68,16 @@ 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 of a node. +(string) +include::{docdir}/ml/ml-shared.asciidoc[tag=assignment-explanation] `datafeed_id`:: (string) include::{docdir}/ml/ml-shared.asciidoc[tag=datafeed-id] `node`:: -(object) For started {dfeeds} only, the node upon which the {dfeed} is started. -The {dfeed} and job will be on the same node. +(object) +include::{docdir}/ml/ml-shared.asciidoc[tag=node] `node`.`id`::: The unique identifier of the node. For example, "0-o0tOoRTwKFZifatTWKNw". `node`.`name`::: The node name. For example, `0-o0tOo`. `node`.`ephemeral_id`::: The node ephemeral ID. @@ -85,27 +86,33 @@ 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: -+ --- -* `started`: The {dfeed} is actively receiving data. -* `stopped`: The {dfeed} is stopped and will not receive data until it is -re-started. --- +(string) +include::{docdir}/ml/ml-shared.asciidoc[tag=state-datafeed] `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 in milliseconds. + +`timing_stats`.`search_count`::: +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]] diff --git a/docs/reference/ml/ml-shared.asciidoc b/docs/reference/ml/ml-shared.asciidoc index 0d6c85d958f72..ce12ddba27e38 100644 --- a/docs/reference/ml/ml-shared.asciidoc +++ b/docs/reference/ml/ml-shared.asciidoc @@ -137,6 +137,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[] @@ -154,6 +158,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} @@ -903,6 +911,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 @@ -995,6 +1008,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`. @@ -1041,6 +1070,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 diff --git a/x-pack/plugin/ml/src/main/java/org/elasticsearch/xpack/ml/rest/cat/RestCatDatafeedsAction.java b/x-pack/plugin/ml/src/main/java/org/elasticsearch/xpack/ml/rest/cat/RestCatDatafeedsAction.java index c457f4bc2bdf5..f0bbc3f872e1d 100644 --- a/x-pack/plugin/ml/src/main/java/org/elasticsearch/xpack/ml/rest/cat/RestCatDatafeedsAction.java +++ b/x-pack/plugin/ml/src/main/java/org/elasticsearch/xpack/ml/rest/cat/RestCatDatafeedsAction.java @@ -92,7 +92,7 @@ protected Table getTableWithHeader(RestRequest request) { .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) diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_datafeeds.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_datafeeds.json index b94ace85ee1b7..d750ff56b8972 100644 --- a/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_datafeeds.json +++ b/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":{