From f57422bbfd676b72c17fee28f3c4350e74804bc1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Wed, 26 Feb 2020 11:09:37 +0100 Subject: [PATCH] [DOCS] Adds cat data frame analytics API (#52764) Co-authored-by: Lisa Cawley --- docs/reference/cat.asciidoc | 2 + .../reference/cat/dataframeanalytics.asciidoc | 165 ++++++++++++++++++ docs/reference/ml/ml-shared.asciidoc | 4 + .../api/cat.ml_data_frame_analytics.json | 2 +- 4 files changed, 172 insertions(+), 1 deletion(-) create mode 100644 docs/reference/cat/dataframeanalytics.asciidoc diff --git a/docs/reference/cat.asciidoc b/docs/reference/cat.asciidoc index 8df183a136c..d1040d000c5 100644 --- a/docs/reference/cat.asciidoc +++ b/docs/reference/cat.asciidoc @@ -229,6 +229,8 @@ include::cat/allocation.asciidoc[] include::cat/count.asciidoc[] +include::cat/dataframeanalytics.asciidoc[] + include::cat/fielddata.asciidoc[] include::cat/health.asciidoc[] diff --git a/docs/reference/cat/dataframeanalytics.asciidoc b/docs/reference/cat/dataframeanalytics.asciidoc new file mode 100644 index 00000000000..0537a0cda83 --- /dev/null +++ b/docs/reference/cat/dataframeanalytics.asciidoc @@ -0,0 +1,165 @@ +[role="xpack"] +[testenv="platinum"] +[[cat-dfanalytics]] +=== cat {dfanalytics} API +++++ +cat {dfanalytics} +++++ + +Returns configuration and usage information about {dfanalytics-jobs}. + + +[[cat-dfanalytics-request]] +==== {api-request-title} + +`GET /_cat/ml/data_frame/analytics/` + + +`GET /_cat/ml/data_frame/analytics` + + +[[cat-dfanalytics-prereqs]] +==== {api-prereq-title} + +If the {es} {security-features} are enabled, you must have the following +privileges: + +* cluster: `monitor_ml` + +For more information, see <> and {ml-docs}/setup.html[Set up {ml-features}]. + + +//// +[[cat-dfanalytics-desc]] +==== {api-description-title} + +TBD +//// + +[[cat-dfanalytics-path-params]] +==== {api-path-parms-title} + +``:: +(Optional, string) +include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-data-frame-analytics-default] + + +[[cat-dfanalytics-query-params]] +==== {api-query-parms-title} + +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-dfanalytics-results]] +==== {api-response-body-title} + +`assignment_explanation`:: +include::{docdir}/ml/ml-shared.asciidoc[tag=assignment-explanation-dfanalytics] ++ +-- +To retrieve this information, specify the `ae` column in the `h` query +parameter. +-- + +`create_time`:: +The time when the {dfanalytics-job} was created. To retrieve this information, +specify the `ct` or `createTime` column in the `h` query parameter. + +`description`:: +include::{docdir}/ml/ml-shared.asciidoc[tag=description-dfa] ++ +-- +To retrieve this information, specify the `d` column in the `h` query parameter. +-- + +`dest_index`:: +Name of the destination index. To retrieve this information, specify the `di` or +the `destIndex` column in the `h` query parameter. + +`failure_reason`:: +Contains messages about the reason why a {dfanalytics-job} failed. To retrieve +this information, specify the `fr` or the `failureReason` column in the `h` +query parameter. + +`id`:: +include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-data-frame-analytics] ++ +-- +To retrieve this information, specify the `id` column in the `h` query +parameter. +-- + +`model_memory_limit`:: +The approximate maximum amount of memory resources that are permitted for the +{dfanalytics-job}. To retrieve this information, specify the `mml` or the +`modelMemoryLimit` column in the `h` query parameter. + +`node.address`:: +The network address of the node that the {dfanalytics-job} is assigned to. To +retrieve this information, specify the `na` or `nodeAddress` column in the `h` +query parameter. + +`node.ephemeral_id`:: +The ephemeral ID of the node that the {dfanalytics-job} is assigned to. To +retrieve this information, specify the `ne` or `nodeEphemeralId` column in the +`h` query parameter. + +`node.id`:: +The unique identifier of the node that the {dfanalytics-job} is assigned to. To +retrieve this information, specify the `ni` or `nodeId` column in the `h` query +parameter. + +`node.name`:: +The name of the node that the {dfanalytics-job} is assigned to. To retrieve this +information, specify the `nn` or `nodeName` column in the `h` query +parameter. + +`progress`:: +The progress report of the {dfanalytics-job} by phase. To retrieve this +information, specify the `p` column in the `h` query parameter. + +`source_index`:: +Name of the source index. To retrieve this information, specify the `si` or the +`sourceIndex` column in the `h` query parameter. + +`state`:: +Current state of the {dfanalytics-job}. To retrieve this information, specify +the `s` column in the `h` query parameter. + +`type`:: +The type of analysis that the {dfanalytics-job} performs. To retrieve this +information, specify the `t` column in the `h` query parameter. + +`version`:: +The {es} version number in which the {dfanalytics-job} was created. To retrieve +this information, specify the `v` column in the `h` query parameter. + + +[[cat-dfanalytics-example]] +==== {api-examples-title} + +[source,console] +-------------------------------------------------- +GET _cat/ml/data_frame/analytics?v +-------------------------------------------------- +// TEST[skip:kibana sample data] + +[source,console-result] +---- +id create_time type state +classifier_job_1 2020-02-12T11:49:09.594Z classification stopped +classifier_job_2 2020-02-12T11:49:14.479Z classification stopped +classifier_job_3 2020-02-12T11:49:16.928Z classification stopped +classifier_job_4 2020-02-12T11:49:19.127Z classification stopped +classifier_job_5 2020-02-12T11:49:21.349Z classification stopped +---- +// TESTRESPONSE[skip:kibana sample data] diff --git a/docs/reference/ml/ml-shared.asciidoc b/docs/reference/ml/ml-shared.asciidoc index e444331a3c5..91773a67142 100644 --- a/docs/reference/ml/ml-shared.asciidoc +++ b/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-dfanalytics[] +Contains messages relating to the selection of a node. +end::assignment-explanation-dfanalytics[] + tag::background-persist-interval[] Advanced configuration option. The time between each periodic persistence of the model. The default value is a randomized value between 3 to 4 hours, which diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_data_frame_analytics.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_data_frame_analytics.json index f8e3f4c46ea..072ba74f6f8 100644 --- a/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_data_frame_analytics.json +++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_data_frame_analytics.json @@ -1,7 +1,7 @@ { "cat.ml_data_frame_analytics":{ "documentation":{ - "url":"http://www.elastic.co/guide/en/elasticsearch/reference/current/get-dfanalytics-stats.html" + "url":"http://www.elastic.co/guide/en/elasticsearch/reference/current/cat-dfanalytics.html" }, "stability":"stable", "url":{