diff --git a/docs/en/rest-api/ml/close-job.asciidoc b/docs/en/rest-api/ml/close-job.asciidoc index d2da4029788..49ae7cab5a1 100644 --- a/docs/en/rest-api/ml/close-job.asciidoc +++ b/docs/en/rest-api/ml/close-job.asciidoc @@ -8,10 +8,12 @@ A job can be opened and closed multiple times throughout its lifecycle. A closed job cannot receive data or perform analysis operations, but you can still explore and navigate results. + ===== Request `POST _xpack/ml/anomaly_detectors//_close` + ===== Description //A job can be closed once all data has been analyzed. @@ -33,15 +35,13 @@ associated actions such as flushing buffers and persisting the model snapshots complete. Therefore, do not use that parameter in a script that expects the job to be in a consistent state after the close job API returns. -You must have `manage_ml`, or `manage` cluster privileges to use this API. -For more information, see <>. - ===== Path Parameters `job_id` (required):: (string) Identifier for the job + ===== Query Parameters `force`:: @@ -53,16 +53,12 @@ For more information, see <>. The default value is 30 minutes. -//// -===== Responses +===== Authorization + +You must have `manage_ml`, or `manage` cluster privileges to use this API. +For more information, see <>. + -200 -(EmptyResponse) The cluster has been successfully deleted -404 -(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found) -412 -(BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) -//// ===== Examples The following example closes the `event_rate` job: diff --git a/docs/en/rest-api/ml/delete-datafeed.asciidoc b/docs/en/rest-api/ml/delete-datafeed.asciidoc index 943ff67a198..38902adf207 100644 --- a/docs/en/rest-api/ml/delete-datafeed.asciidoc +++ b/docs/en/rest-api/ml/delete-datafeed.asciidoc @@ -4,16 +4,16 @@ The delete data feed API allows you to delete an existing data feed. + ===== Request `DELETE _xpack/ml/datafeeds/` + ===== Description NOTE: You must stop the data feed before you can delete it. -You must have `manage_ml`, or `manage` cluster privileges to use this API. -For more information, see <>. ===== Path Parameters @@ -30,6 +30,13 @@ For more information, see <>. (BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) //// + +===== Authorization + +You must have `manage_ml`, or `manage` cluster privileges to use this API. +For more information, see <>. + + ===== Examples The following example deletes the `datafeed-it-ops` data feed: diff --git a/docs/en/rest-api/ml/delete-job.asciidoc b/docs/en/rest-api/ml/delete-job.asciidoc index a6d966a537c..cb611cbbc49 100644 --- a/docs/en/rest-api/ml/delete-job.asciidoc +++ b/docs/en/rest-api/ml/delete-job.asciidoc @@ -4,10 +4,12 @@ The delete job API allows you to delete an existing anomaly detection job. + ===== Request `DELETE _xpack/ml/anomaly_detectors/` + ===== Description All job configuration, model state and results are deleted. @@ -17,29 +19,23 @@ IMPORTANT: Deleting a job must be done via this API only. Do not delete the DELETE Document API. When {security} is enabled, make sure no `write` privileges are granted to anyone over the `.ml-*` indices. -You must have `manage_ml`, or `manage` cluster privileges to use this API. -For more information, see <>. +Before you can delete a job, you must delete the data feeds that are associated +with it. See <>. -Before you can delete a job, you must delete the data feeds that are associated with it. -See <>. - -It is not currently possible to delete multiple jobs using wildcards or a comma separated list. +It is not currently possible to delete multiple jobs using wildcards or a comma +separated list. ===== Path Parameters `job_id` (required):: (string) Identifier for the job -//// -===== Responses -200 -(EmptyResponse) The cluster has been successfully deleted -404 -(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found) -412 -(BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) -//// +===== Authorization + +You must have `manage_ml`, or `manage` cluster privileges to use this API. +For more information, see <>. + ===== Examples diff --git a/docs/en/rest-api/ml/delete-snapshot.asciidoc b/docs/en/rest-api/ml/delete-snapshot.asciidoc index ed22e98d49d..3f546b9b6f6 100644 --- a/docs/en/rest-api/ml/delete-snapshot.asciidoc +++ b/docs/en/rest-api/ml/delete-snapshot.asciidoc @@ -3,6 +3,7 @@ The delete model snapshot API enables you to delete an existing model snapshot. + ===== Request `DELETE _xpack/ml/anomaly_detectors//model_snapshots/` @@ -13,9 +14,6 @@ The delete model snapshot API enables you to delete an existing model snapshot. IMPORTANT: You cannot delete the active model snapshot. To delete that snapshot, first revert to a different one. -You must have `manage_ml`, or `manage` cluster privileges to use this API. -For more information, see <>. - //TBD: Where do you see restorePriority? Per old docs, the active model snapshot //is "...the snapshot with the highest restorePriority". @@ -26,17 +24,14 @@ For more information, see <>. `snapshot_id` (required):: (string) Identifier for the model snapshot -//// -===== Responses -200 -(EmptyResponse) The cluster has been successfully deleted -404 -(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found) -412 -(BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) -//// +===== Authorization + +You must have `manage_ml`, or `manage` cluster privileges to use this API. +For more information, see <>. + + ===== Examples The following example deletes the `1491948163` snapshot: diff --git a/docs/en/rest-api/ml/flush-job.asciidoc b/docs/en/rest-api/ml/flush-job.asciidoc index b381bbf834d..a09a69c6629 100644 --- a/docs/en/rest-api/ml/flush-job.asciidoc +++ b/docs/en/rest-api/ml/flush-job.asciidoc @@ -4,27 +4,30 @@ The flush job API forces any buffered data to be processed by the job. + ===== Request `POST _xpack/ml/anomaly_detectors//_flush` + ===== Description -The flush job API is only applicable when sending data for analysis using the <>. Depending on the content of the buffer, then it might additionally calculate new results. +The flush job API is only applicable when sending data for analysis using the +<>. Depending on the content of the buffer, then it +might additionally calculate new results. Both flush and close operations are similar, however the flush is more efficient -if you are expecting to send more data for analysis. -When flushing, the job remains open and is available to continue analyzing data. -A close operation additionally prunes and persists the model state to disk -and the job must be opened again before analyzing further data. +if you are expecting to send more data for analysis. When flushing, the job +remains open and is available to continue analyzing data. A close operation +additionally prunes and persists the model state to disk and the job must be +opened again before analyzing further data. -You must have `manage_ml`, or `manage` cluster privileges to use this API. -For more information, see <>. ===== Path Parameters `job_id` (required):: -(string) Identifier for the job +(string) Identifier for the job + ===== Query Parameters @@ -43,15 +46,13 @@ For more information, see <>. (string) When used in conjunction with `calc_interim`, specifies the range of buckets on which to calculate interim results. -//// -===== Responses -200 -(EmptyResponse) The cluster has been successfully deleted -404 -(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found) -412 -(BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) -//// + +===== Authorization + +You must have `manage_ml`, or `manage` cluster privileges to use this API. +For more information, see <>. + + ===== Examples The following example flushes the `farequote` job: diff --git a/docs/en/rest-api/ml/get-bucket.asciidoc b/docs/en/rest-api/ml/get-bucket.asciidoc index 9635664ea4c..44be30a7ad7 100644 --- a/docs/en/rest-api/ml/get-bucket.asciidoc +++ b/docs/en/rest-api/ml/get-bucket.asciidoc @@ -5,21 +5,18 @@ The get bucket API enables you to retrieve information about buckets in the results from a job. + ===== Request `GET _xpack/ml/anomaly_detectors//results/buckets` + `GET _xpack/ml/anomaly_detectors//results/buckets/` + ===== Description This API presents a chronological view of the records, grouped by bucket. -You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster -privileges to use this API. You also need `read` index privilege on the index -that stores the results. The `machine_learning_admin` and `machine_learning_user` -roles provide these privileges. For more information, see -<> and <>. ===== Path Parameters @@ -31,6 +28,7 @@ roles provide these privileges. For more information, see If you do not specify this optional parameter, the API returns information about all buckets. + ===== Request Body `anomaly_score`:: @@ -55,6 +53,7 @@ roles provide these privileges. For more information, see `start`:: (string) Returns buckets with timestamps after this time. + ===== Results The API returns the following information: @@ -63,16 +62,16 @@ The API returns the following information: (array) An array of bucket objects. For more information, see <>. -//// -===== Responses -200 -(EmptyResponse) The cluster has been successfully deleted -404 -(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found) -412 -(BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) -//// +===== Authorization + +You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster +privileges to use this API. You also need `read` index privilege on the index +that stores the results. The `machine_learning_admin` and `machine_learning_user` +roles provide these privileges. For more information, see +<> and <>. + + ===== Examples The following example gets bucket information for the `it-ops-kpi` job: diff --git a/docs/en/rest-api/ml/get-category.asciidoc b/docs/en/rest-api/ml/get-category.asciidoc index 8abc2fe1a94..a496f315b1a 100644 --- a/docs/en/rest-api/ml/get-category.asciidoc +++ b/docs/en/rest-api/ml/get-category.asciidoc @@ -5,19 +5,14 @@ The get categories API enables you to retrieve information about the categories in the results for a job. + ===== Request `GET _xpack/ml/anomaly_detectors//results/categories` + `GET _xpack/ml/anomaly_detectors//results/categories/` -===== Description - -You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster -privileges to use this API. You also need `read` index privilege on the index -that stores the results. The `machine_learning_admin` and `machine_learning_user` -roles provide these privileges. For more information, see -<> and <>. +//===== Description ===== Path Parameters @@ -28,6 +23,7 @@ roles provide these privileges. For more information, see (string) Identifier for the category. If you do not specify this optional parameter, the API returns information about all categories in the job. + ===== Request Body //TBD: Test these properties, since they didn't work on older build. @@ -38,6 +34,7 @@ roles provide these privileges. For more information, see `size`:: (integer) Specifies the maximum number of categories to obtain. + ===== Results The API returns the following information: @@ -45,16 +42,17 @@ The API returns the following information: `categories`:: (array) An array of category objects. For more information, see <>. -//// -===== Responses -200 -(EmptyResponse) The cluster has been successfully deleted -404 -(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found) -412 -(BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) -//// + +===== Authorization + +You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster +privileges to use this API. You also need `read` index privilege on the index +that stores the results. The `machine_learning_admin` and `machine_learning_user` +roles provide these privileges. For more information, see +<> and <>. + + ===== Examples The following example gets category information for the `it_ops_new_logs` job: diff --git a/docs/en/rest-api/ml/get-datafeed-stats.asciidoc b/docs/en/rest-api/ml/get-datafeed-stats.asciidoc index 574fbd9bc2b..6cf9b2405f0 100644 --- a/docs/en/rest-api/ml/get-datafeed-stats.asciidoc +++ b/docs/en/rest-api/ml/get-datafeed-stats.asciidoc @@ -5,19 +5,19 @@ The get data feed statistics API enables you to retrieve usage information for data feeds. + ===== Request `GET _xpack/ml/datafeeds/_stats` + `GET _xpack/ml/datafeeds//_stats` + ===== Description If the data feed is stopped, the only information you receive is the `datafeed_id` and the `state`. -You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster -privileges to use this API. For more information, see <>. ===== Path Parameters @@ -26,6 +26,7 @@ privileges to use this API. For more information, see < This parameter does not support wildcards, but you can specify `_all` or omit the `feed_id` to get information about all data feeds. + ===== Results The API returns the following information: @@ -34,16 +35,13 @@ The API returns the following information: (array) An array of data feed count objects. For more information, see <>. -//// -===== Responses -200 -(EmptyResponse) The cluster has been successfully deleted -404 -(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found) -412 -(BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) -//// +===== Authorization + +You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster +privileges to use this API. For more information, see <>. + + ===== Examples The following example gets usage information for the diff --git a/docs/en/rest-api/ml/get-datafeed.asciidoc b/docs/en/rest-api/ml/get-datafeed.asciidoc index a2d3b4c3b81..cd7a1eeac3d 100644 --- a/docs/en/rest-api/ml/get-datafeed.asciidoc +++ b/docs/en/rest-api/ml/get-datafeed.asciidoc @@ -11,12 +11,7 @@ data feeds. `GET _xpack/ml/datafeeds/` -===== Description - -You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster -privileges to use this API. For more information, see <>. - -//TBD: The get job API can also be applied to all jobs by using `_all` as the job name. +//===== Description ===== Path Parameters @@ -25,6 +20,7 @@ privileges to use this API. For more information, see < This parameter does not support wildcards, but you can specify `_all` or omit the `feed_id` to get information about all data feeds. + ===== Results The API returns the following information: @@ -33,16 +29,13 @@ The API returns the following information: (array) An array of data feed objects. For more information, see <>. -//// -===== Responses -200 -(EmptyResponse) The cluster has been successfully deleted -404 -(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found) -412 -(BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) -//// +===== Authorization + +You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster +privileges to use this API. For more information, see <>. + + ===== Examples The following example gets configuration information for the diff --git a/docs/en/rest-api/ml/get-influencer.asciidoc b/docs/en/rest-api/ml/get-influencer.asciidoc index 3a9cc7206e6..31ac847236e 100644 --- a/docs/en/rest-api/ml/get-influencer.asciidoc +++ b/docs/en/rest-api/ml/get-influencer.asciidoc @@ -4,18 +4,12 @@ The get influencers API enables you to retrieve information about the influencers in a job. + ===== Request `GET _xpack/ml/anomaly_detectors//results/influencers` - -===== Description - -You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster -privileges to use this API. You also need `read` index privilege on the index -that stores the results. The `machine_learning_admin` and `machine_learning_user` -roles provide these privileges. For more information, see -<> and <>. +//===== Description ===== Path Parameters @@ -35,7 +29,6 @@ roles provide these privileges. For more information, see (boolean) If true, the output excludes interim results. By default, interim results are included. - `from`:: (integer) Skips the specified number of influencers. @@ -52,6 +45,7 @@ roles provide these privileges. For more information, see `start`:: (string) Returns influencers with timestamps after this time. + ===== Results The API returns the following information: @@ -60,16 +54,16 @@ The API returns the following information: (array) An array of influencer objects. For more information, see <>. -//// -===== Responses -200 -(EmptyResponse) The cluster has been successfully deleted -404 -(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found) -412 -(BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) -//// +===== Authorization + +You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster +privileges to use this API. You also need `read` index privilege on the index +that stores the results. The `machine_learning_admin` and `machine_learning_user` +roles provide these privileges. For more information, see +<> and <>. + + ===== Examples The following example gets influencer information for the `it_ops_new_kpi` job: diff --git a/docs/en/rest-api/ml/get-job-stats.asciidoc b/docs/en/rest-api/ml/get-job-stats.asciidoc index 3cf1289ee65..839a28375c0 100644 --- a/docs/en/rest-api/ml/get-job-stats.asciidoc +++ b/docs/en/rest-api/ml/get-job-stats.asciidoc @@ -4,17 +4,14 @@ The get jobs API allows you to retrieve usage information for jobs. + ===== Request `GET _xpack/ml/anomaly_detectors/_stats` + `GET _xpack/ml/anomaly_detectors//_stats` - -===== Description - -You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster -privileges to use this API. For more information, see <>. +//===== Description ===== Path Parameters @@ -32,16 +29,13 @@ The API returns the following information: (array) An array of job count objects. For more information, see <>. -//// -===== Responses -200 -(EmptyResponse) The cluster has been successfully deleted -404 -(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found) -412 -(BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) -//// +===== Authorization + +You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster +privileges to use this API. For more information, see <>. + + ===== Examples The following example gets usage information for the `farequote` job: diff --git a/docs/en/rest-api/ml/get-job.asciidoc b/docs/en/rest-api/ml/get-job.asciidoc index 2d0f9c42dd0..18845357434 100644 --- a/docs/en/rest-api/ml/get-job.asciidoc +++ b/docs/en/rest-api/ml/get-job.asciidoc @@ -4,17 +4,14 @@ The get jobs API enables you to retrieve configuration information for jobs. + ===== Request `GET _xpack/ml/anomaly_detectors/` + `GET _xpack/ml/anomaly_detectors/` - -===== Description - -You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster -privileges to use this API. For more information, see <>. +//===== Description ===== Path Parameters @@ -23,6 +20,7 @@ privileges to use this API. For more information, see < This parameter does not support wildcards, but you can specify `_all` or omit the `job_id` to get information about all jobs. + ===== Results The API returns the following information: @@ -31,16 +29,13 @@ The API returns the following information: (array) An array of job resources. For more information, see <>. -//// -===== Responses -200 -(EmptyResponse) The cluster has been successfully deleted -404 -(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found) -412 -(BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) -//// +===== Authorization + +You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster +privileges to use this API. For more information, see <>. + + ===== Examples The following example gets configuration information for the `farequote` job: diff --git a/docs/en/rest-api/ml/get-record.asciidoc b/docs/en/rest-api/ml/get-record.asciidoc index 101c7064642..c79fe6a6846 100644 --- a/docs/en/rest-api/ml/get-record.asciidoc +++ b/docs/en/rest-api/ml/get-record.asciidoc @@ -4,24 +4,19 @@ The get records API enables you to retrieve anomaly records for a job. + ===== Request `GET _xpack/ml/anomaly_detectors//results/records` - -===== Description - -You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster -privileges to use this API. You also need `read` index privilege on the index -that stores the results. The `machine_learning_admin` and `machine_learning_user` -roles provide these privileges. For more information, see -<> and <>. +//===== Description ===== Path Parameters `job_id`:: (string) Identifier for the job. + ===== Request Body `desc`:: @@ -50,6 +45,7 @@ roles provide these privileges. For more information, see `start`:: (string) Returns records with timestamps after this time. + ===== Results The API returns the following information: @@ -58,16 +54,16 @@ The API returns the following information: (array) An array of record objects. For more information, see <>. -//// - ===== Responses - 200 - (EmptyResponse) The cluster has been successfully deleted - 404 - (BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found) - 412 - (BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) -//// +===== Authorization + +You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster +privileges to use this API. You also need `read` index privilege on the index +that stores the results. The `machine_learning_admin` and `machine_learning_user` +roles provide these privileges. For more information, see +<> and <>. + + ===== Examples The following example gets bucket information for the `it-ops-kpi` job: diff --git a/docs/en/rest-api/ml/get-snapshot.asciidoc b/docs/en/rest-api/ml/get-snapshot.asciidoc index b73501074a2..a9c8adc3169 100644 --- a/docs/en/rest-api/ml/get-snapshot.asciidoc +++ b/docs/en/rest-api/ml/get-snapshot.asciidoc @@ -4,16 +4,14 @@ The get model snapshots API enables you to retrieve information about model snapshots. + ===== Request `GET _xpack/ml/anomaly_detectors//model_snapshots` + `GET _xpack/ml/anomaly_detectors//model_snapshots/` -===== Description - -You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster -privileges to use this API. For more information, see <>. +//===== Description ===== Path Parameters @@ -50,6 +48,7 @@ NOTE: It might be necessary to URL encode the description. `start`:: (string) Returns snapshots with timestamps after this time. + ===== Results The API returns the following information: @@ -58,16 +57,12 @@ The API returns the following information: (array) An array of model snapshot objects. For more information, see <>. -//// -===== Responses -200 -(EmptyResponse) The cluster has been successfully deleted -404 -(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found) -412 -(BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) -//// +===== Authorization + +You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster +privileges to use this API. For more information, see <>. + ===== Examples diff --git a/docs/en/rest-api/ml/open-job.asciidoc b/docs/en/rest-api/ml/open-job.asciidoc index b23c396d422..8eeb6144df1 100644 --- a/docs/en/rest-api/ml/open-job.asciidoc +++ b/docs/en/rest-api/ml/open-job.asciidoc @@ -5,10 +5,12 @@ A job must be opened in order for it to be ready to receive and analyze data. A job can be opened and closed multiple times throughout its lifecycle. + ===== Request `POST _xpack/ml/anomaly_detectors/{job_id}/_open` + ===== Description A job must be open in order to it to accept and analyze data. @@ -18,14 +20,13 @@ When you open a new job, it starts with an empty model. When you open an existing job, the most recent model state is automatically loaded. The job is ready to resume its analysis from where it left off, once new data is received. -You must have `manage_ml`, or `manage` cluster privileges to use this API. -For more information, see <>. ===== Path Parameters `job_id` (required):: (string) Identifier for the job + ===== Request Body `open_timeout`:: @@ -36,16 +37,13 @@ For more information, see <>. (boolean) If true (default), any gap in data since it was last closed is treated as a maintenance window. That is to say, it is not an anomaly -//// -===== Responses -200 -(EmptyResponse) The cluster has been successfully deleted -404 -(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found) -412 -(BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) -//// +===== Authorization + +You must have `manage_ml`, or `manage` cluster privileges to use this API. +For more information, see <>. + + ===== Examples The following example opens the `event_rate` job and sets an optional property: diff --git a/docs/en/rest-api/ml/post-data.asciidoc b/docs/en/rest-api/ml/post-data.asciidoc index d20cacf22d3..73cd7c954e6 100644 --- a/docs/en/rest-api/ml/post-data.asciidoc +++ b/docs/en/rest-api/ml/post-data.asciidoc @@ -5,10 +5,12 @@ The post data API allows you to send data to an anomaly detection job for analysis. The job must have been opened prior to sending data. + ===== Request `POST _xpack/ml/anomaly_detectors//_data --data-binary @` + ===== Description File sizes are limited to 100 Mb, so if your file is larger, @@ -21,14 +23,13 @@ Use a single connection synchronously to send data, close, flush, or delete a si It is not currently possible to post data to multiple jobs using wildcards or a comma separated list. -You must have `manage_ml`, or `manage` cluster privileges to use this API. -For more information, see <>. ===== Path Parameters `job_id` (required):: (string) Identifier for the job + ===== Request Body `reset_start`:: @@ -37,19 +38,13 @@ For more information, see <>. `reset_end`:: (string) Specifies the end of the bucket resetting range -//// -===== Responses + +===== Authorization + +You must have `manage_ml`, or `manage` cluster privileges to use this API. +For more information, see <>. - 200 - (EmptyResponse) The cluster has been successfully deleted - 404 - (BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found) - 412 - (BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) - - The following example sends data from file `data-file.json` to a job called `my_analysis`. -//// ===== Examples The following example posts data from the farequote.json file to the `farequote` job: diff --git a/docs/en/rest-api/ml/preview-datafeed.asciidoc b/docs/en/rest-api/ml/preview-datafeed.asciidoc index 6bd30083e73..1e964e5dddb 100644 --- a/docs/en/rest-api/ml/preview-datafeed.asciidoc +++ b/docs/en/rest-api/ml/preview-datafeed.asciidoc @@ -4,6 +4,7 @@ The preview data feed API enables you to preview a data feed. + ===== Request `GET _xpack/ml/datafeeds//_preview` @@ -15,31 +16,19 @@ The API returns the first "page" of results from the `search` that is created by using the current data feed settings. This preview shows the structure of the data that will be passed to the anomaly detection engine. -You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster -privileges to use this API. For more information, see <>. ===== Path Parameters `datafeed_id` (required):: (string) Identifier for the data feed -//// -===== Request Body -None +===== Authorization + +You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster +privileges to use this API. For more information, see <>. -===== Responses -TBD -//// -//// -200 -(EmptyResponse) The cluster has been successfully deleted -404 -(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found) -412 -(BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) -//// ===== Examples The following example obtains a preview of the `datafeed-farequote` data feed: diff --git a/docs/en/rest-api/ml/put-datafeed.asciidoc b/docs/en/rest-api/ml/put-datafeed.asciidoc index 790f21235ce..302bde4131b 100644 --- a/docs/en/rest-api/ml/put-datafeed.asciidoc +++ b/docs/en/rest-api/ml/put-datafeed.asciidoc @@ -4,23 +4,24 @@ The create data feed API enables you to instantiate a data feed. + ===== Request `PUT _xpack/ml/datafeeds/` + ===== Description You must create a job before you create a data feed. You can associate only one data feed to each job. -You must have `manage_ml`, or `manage` cluster privileges to use this API. -For more information, see <>. ===== Path Parameters `feed_id` (required):: (string) A numerical character string that uniquely identifies the data feed. + ===== Request Body `aggregations`:: @@ -55,18 +56,12 @@ For more information, see <>. For more information about these properties, see <>. -//// -===== Responses -TBD -200 -(EmptyResponse) The cluster has been successfully deleted -404 -(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found) -412 -(BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) +===== Authorization + +You must have `manage_ml`, or `manage` cluster privileges to use this API. +For more information, see <>. -//// ===== Examples The following example creates the `datafeed-it-ops-kpi` data feed: diff --git a/docs/en/rest-api/ml/put-job.asciidoc b/docs/en/rest-api/ml/put-job.asciidoc index 42d5bf61b97..ce799a246e6 100644 --- a/docs/en/rest-api/ml/put-job.asciidoc +++ b/docs/en/rest-api/ml/put-job.asciidoc @@ -8,11 +8,7 @@ The create job API enables you to instantiate a job. `PUT _xpack/ml/anomaly_detectors/` - -===== Description - -You must have `manage_ml`, or `manage` cluster privileges to use this API. -For more information, see <>. +//===== Description ===== Path Parameters @@ -45,19 +41,11 @@ For more information, see <>. The default value is `shared`, which corresponds to the index name `.ml-anomalies-shared`. -//// -===== Responses -TBD -//// -//// -200 -(EmptyResponse) The cluster has been successfully deleted -404 -(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found) -412 -(BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) -//// +===== Authorization + +You must have `manage_ml`, or `manage` cluster privileges to use this API. +For more information, see <>. ===== Examples diff --git a/docs/en/rest-api/ml/resultsresource.asciidoc b/docs/en/rest-api/ml/resultsresource.asciidoc index 2e3bff309e8..5a3a03ac26a 100644 --- a/docs/en/rest-api/ml/resultsresource.asciidoc +++ b/docs/en/rest-api/ml/resultsresource.asciidoc @@ -2,32 +2,40 @@ [[ml-results-resource]] ==== Results Resources -Different results types are created for each job. -Anomaly results for _buckets_, _influencers_ and _records_ can be queried using the results API. +Several different result types are created for each job. You can query anomaly +results for _buckets_, _influencers_ and _records_ by using the results API. -These results are written for every `bucket_span`, with the timestamp being the start of the time interval. +Results are written for each `bucket_span`. The timestamp for the results is the +start of the bucket time interval. -As part of the results, scores are calculated for each anomaly result type and each bucket interval. -These are aggregated in order to reduce noise, and normalized in order to identify and rank the most mathematically significant anomalies. +The results include scores, which are calculated for each anomaly result type and +each bucket interval. These scores are aggregated in order to reduce noise, and +normalized in order to identify and rank the most mathematically significant +anomalies. -Bucket results provide the top level, overall view of the job and are ideal for alerting on. -For example, at 16:05 the system was unusual. -This is a summary of all the anomalies, pinpointing when they occurred. +Bucket results provide the top level, overall view of the job and are ideal for +alerts. For example, the bucket results might indicate that at 16:05 the system +was unusual. This information is a summary of all the anomalies, pinpointing +when they occurred. -Influencer results show which entities were anomalous and when. -For example, at 16:05 `user_name: Bob` was unusual. -This is a summary of all anomalies for each entity, so there can be a lot of these results. -Once you have identified a notable bucket time, you can look to see which entites were significant. +Influencer results show which entities were anomalous and when. For example, +the influencer results might indicate that at 16:05 `user_name: Bob` was unusual. +This information is a summary of all the anomalies for each entity, so there +can be a lot of these results. Once you have identified a notable bucket time, +you can look to see which entities were significant. -Record results provide the detail showing what the individual anomaly was, when it occurred and which entity was involved. -For example, at 16:05 Bob sent 837262434 bytes, when the typical value was 1067 bytes. -Once you have identified a bucket time and/or a significant entity, you can drill through to the record results -in order to investigate the anomalous behavior. +Record results provide details about what the individual anomaly was, when it +occurred and which entity was involved. For example, the record results might +indicate that at 16:05 Bob sent 837262434 bytes, when the typical value was +1067 bytes. Once you have identified a bucket time and perhaps a significant +entity too, you can drill through to the record results in order to investigate +the anomalous behavior. //TBD Add links to categorization -Categorization results contain the definitions of _categories_ that have been identified. -These are only applicable for jobs that are configured to analyze unstructured log data using categorization. -These results do not contain a timestamp or any calculated scores. +Categorization results contain the definitions of _categories_ that have been +identified. These are only applicable for jobs that are configured to analyze +unstructured log data using categorization. These results do not contain a +timestamp or any calculated scores. * <> * <> @@ -38,27 +46,30 @@ These results do not contain a timestamp or any calculated scores. [[ml-results-buckets]] ===== Buckets -Bucket results provide the top level, overall view of the job and are best for alerting. +Bucket results provide the top level, overall view of the job and are best for +alerting. Each bucket has an `anomaly_score`, which is a statistically aggregated and -normalized view of the combined anomalousness of all record results within each bucket. +normalized view of the combined anomalousness of all the record results within +each bucket. -One bucket result is written for each `bucket_span` for each job, even if it is not considered to be anomalous -(when it will have an `anomaly_score` of zero). +One bucket result is written for each `bucket_span` for each job, even if it is +not considered to be anomalous. If the bucket is not anomalous, it has an +`anomaly_score` of zero. -Upon identifying an anomalous bucket, you can investigate further by either -expanding the bucket resource to show the records as nested objects or by -accessing the records resource directly and filtering upon date range. +When you identify an anomalous bucket, you can investigate further by expanding +the bucket resource to show the records as nested objects. Alternatively, you +can access the records resource directly and filter by the date range. A bucket resource has the following properties: `anomaly_score`:: - (number) The maximum anomaly score, between 0-100, for any of the bucket influencers. - This is an overall, rate limited score for the job. - All the anomaly records in the bucket contribute to this score. - This value may be updated as new data is analyzed. + (number) The maximum anomaly score, between 0-100, for any of the bucket + influencers. This is an overall, rate-limited score for the job. All the + anomaly records in the bucket contribute to this score. This value might be + updated as new data is analyzed. -`bucket_influencers[]`:: +`bucket_influencers`:: (array) An array of bucket influencer objects. For more information, see <>. @@ -71,26 +82,29 @@ A bucket resource has the following properties: `initial_anomaly_score`:: (number) The maximum `anomaly_score` for any of the bucket influencers. - This is this initial value calculated at the time the bucket was processed. + This is the initial value that was calculated at the time the bucket was + processed. `is_interim`:: - (boolean) If true, then this bucket result is an interim result. - In other words, it is calculated based on partial input data. + (boolean) If true, this is an interim result. In other words, the bucket + results are calculated based on partial input data. `job_id`:: (string) The unique identifier for the job that these results belong to. `processing_time_ms`:: - (number) The time in milliseconds taken to analyze the bucket contents and calculate results. + (number) The amount of time, in milliseconds, that it took to analyze the + bucket contents and calculate results. `record_count`:: (number) The number of anomaly records in this bucket. `result_type`:: - (string) Internal. This value is always set to "bucket". + (string) Internal. This value is always set to `bucket`. `timestamp`:: - (date) The start time of the bucket. This timestamp uniquely identifies the bucket. + + (date) The start time of the bucket. This timestamp uniquely identifies the + bucket. + NOTE: Events that occur exactly at the timestamp of the bucket are included in the results for the bucket. @@ -100,97 +114,109 @@ the results for the bucket. [[ml-results-bucket-influencers]] ===== Bucket Influencers -Bucket influencer results are available as nested objects contained within bucket results. -These results are an aggregation for each the type of influencer. -For example if both client_ip and user_name were specified as influencers, -then you would be able to find when client_ip's or user_name's were collectively anomalous. +Bucket influencer results are available as nested objects contained within +bucket results. These results are an aggregation for each type of influencer. +For example, if both `client_ip` and `user_name` were specified as influencers, +then you would be able to determine when the `client_ip` or `user_name` values +were collectively anomalous. -There is a built-in bucket influencer called `bucket_time` which is always available. -This is the aggregation of all records in the bucket, and is not just limited to a type of influencer. +There is a built-in bucket influencer called `bucket_time` which is always +available. This bucket influencer is the aggregation of all records in the +bucket; it is not just limited to a type of influencer. -NOTE: A bucket influencer is a type of influencer. For example, `client_ip` or `user_name` -can be bucket influencers, whereas `192.168.88.2` and `Bob` are influencers. +NOTE: A bucket influencer is a type of influencer. For example, `client_ip` or +`user_name` can be bucket influencers, whereas `192.168.88.2` and `Bob` are +influencers. An bucket influencer object has the following properties: `anomaly_score`:: - (number) A normalized score between 0-100, calculated for each bucket influencer. - This score may be updated as newer data is analyzed. + (number) A normalized score between 0-100, which is calculated for each bucket + influencer. This score might be updated as newer data is analyzed. `bucket_span`:: - (time units) The length of the bucket. - This value matches the `bucket_span` that is specified in the job. + (time units) The length of the bucket. This value matches the `bucket_span` + that is specified in the job. `initial_anomaly_score`:: - (number) The score between 0-100 for each bucket influencers. - This is this initial value calculated at the time the bucket was processed. + (number) The score between 0-100 for each bucket influencer. This score is + the initial value that was calculated at the time the bucket was processed. `influencer_field_name`:: - (string) The field name of the influencer. For example `client_ip` or `user_name`. + (string) The field name of the influencer. For example `client_ip` or + `user_name`. `influencer_field_value`:: - (string) The field value of the influencer. For example `192.168.88.2` or `Bob`. + (string) The field value of the influencer. For example `192.168.88.2` or + `Bob`. `is_interim`:: - (boolean) If true, then this is an interim result. - In other words, it is calculated based on partial input data. + (boolean) If true, this is an interim result. In other words, the bucket + influencer results are calculated based on partial input data. `job_id`:: (string) The unique identifier for the job that these results belong to. `probability`:: - (number) The probability that the bucket has this behavior, in the range 0 to 1. For example, 0.0000109783. - This value can be held to a high precision of over 300 decimal places, so the `anomaly_score` is provided as a + (number) The probability that the bucket has this behavior, in the range 0 + to 1. For example, 0.0000109783. This value can be held to a high precision + of over 300 decimal places, so the `anomaly_score` is provided as a human-readable and friendly interpretation of this. `raw_anomaly_score`:: (number) Internal. `result_type`:: - (string) Internal. This value is always set to "bucket_influencer". + (string) Internal. This value is always set to `bucket_influencer`. `sequence_num`:: (number) Internal. `timestamp`:: - (date) This value is the start time of the bucket for which these results have been calculated for. + (date) The start time of the bucket for which these results were calculated. [float] [[ml-results-influencers]] ===== Influencers -Influencers are the entities that have contributed to, or are to blame for, the anomalies. -Influencer results will only be available if an `influencer_field_name` has been specified in the job configuration. +Influencers are the entities that have contributed to, or are to blame for, +the anomalies. Influencer results are available only if an +`influencer_field_name` is specified in the job configuration. -Influencers are given an `influencer_score`, which is calculated -based on the anomalies that have occurred in each bucket interval. -For jobs with more than one detector, this gives a powerful view of the most anomalous entities. +Influencers are given an `influencer_score`, which is calculated based on the +anomalies that have occurred in each bucket interval. For jobs with more than +one detector, this gives a powerful view of the most anomalous entities. -For example, if analyzing unusual bytes sent and unusual domains visited, if user_name was -specified as the influencer, then an 'influencer_score' for each anomalous user_name would be written per bucket. -E.g. If `user_name: Bob` had an `influencer_score` > 75, -then `Bob` would be considered very anomalous during this time interval in either or both of those attack vectors. +For example, if you are analyzing unusual bytes sent and unusual domains +visited and you specified `user_name` as the influencer, then an +`influencer_score` for each anomalous user name is written per bucket. For +example, if `user_name: Bob` had an `influencer_score` greater than 75, then +`Bob` would be considered very anomalous during this time interval in one or +both of those areas (unusual bytes sent or unusual domains visited). -One `influencer` result is written per bucket for each influencer that is considered anomalous. +One influencer result is written per bucket for each influencer that is +considered anomalous. -Upon identifying an influencer with a high score, you can investigate further +When you identify an influencer with a high score, you can investigate further by accessing the records resource for that bucket and enumerating the anomaly -records that contain this influencer. +records that contain the influencer. An influencer object has the following properties: `bucket_span`:: - (time units) The length of the bucket. - This value matches the `bucket_span` that is specified in the job. + (time units) The length of the bucket. This value matches the `bucket_span` + that is specified in the job. `influencer_score`:: - (number) A normalized score between 0-100, based on the probability of the influencer in this bucket, - aggregated across detectors. - Unlike `initial_influencer_score`, this value will be updated by a re-normalization process as new data is analyzed. + (number) A normalized score between 0-100, which is based on the probability + of the influencer in this bucket aggregated across detectors. Unlike + `initial_influencer_score`, this value will be updated by a re-normalization + process as new data is analyzed. `initial_influencer_score`:: - (number) A normalized score between 0-100, based on the probability of the influencer, aggregated across detectors. - This is this initial value calculated at the time the bucket was processed. + (number) A normalized score between 0-100, which is based on the probability + of the influencer aggregated across detectors. This is the initial value that + was calculated at the time the bucket was processed. `influencer_field_name`:: (string) The field name of the influencer. @@ -200,55 +226,57 @@ An influencer object has the following properties: anomaly. `is_interim`:: - (boolean) If true, then this is an interim result. - In other words, it is calculated based on partial input data. + (boolean) If true, this is an interim result. In other words, the influencer + results are calculated based on partial input data. `job_id`:: (string) The unique identifier for the job that these results belong to. `probability`:: - (number) The probability that the influencer has this behavior, in the range 0 to 1. - For example, 0.0000109783. - This value can be held to a high precision of over 300 decimal places, - so the `influencer_score` is provided as a human-readable and friendly interpretation of this. + (number) The probability that the influencer has this behavior, in the range + 0 to 1. For example, 0.0000109783. This value can be held to a high precision + of over 300 decimal places, so the `influencer_score` is provided as a + human-readable and friendly interpretation of this. // For example, 0.03 means 3%. This value is held to a high precision of over //300 decimal places. In scientific notation, a value of 3.24E-300 is highly //unlikely and therefore highly anomalous. `result_type`:: - (string) Internal. This value is always set to "influencer". + (string) Internal. This value is always set to `influencer`. `sequence_num`:: (number) Internal. `timestamp`:: - (date) The start time of the bucket for which these results have been calculated for. + (date) The start time of the bucket for which these results were calculated. -NOTE: Additional influencer properties are added, depending on the fields being analyzed. -For example, if analysing `user_name` as an influencer, then a field `user_name` would be added to the -result document. This allows easier filtering of the anomaly results. +NOTE: Additional influencer properties are added, depending on the fields being +analyzed. For example, if it's analyzing `user_name` as an influencer, then a +field `user_name` is added to the result document. This information enables you to +filter the anomaly results more easily. [float] [[ml-results-records]] ===== Records -Records contain the detailed analytical results. They describe the anomalous activity that -has been identified in the input data based upon the detector configuration. +Records contain the detailed analytical results. They describe the anomalous +activity that has been identified in the input data based on the detector +configuration. -For example, if you are looking for unusually large data transfers, -an anomaly record would identify the source IP address, the destination, -the time window during which it occurred, the expected and actual size of the -transfer and the probability of this occurring. +For example, if you are looking for unusually large data transfers, an anomaly +record can identify the source IP address, the destination, the time window +during which it occurred, the expected and actual size of the transfer, and the +probability of this occurrence. -There can be many anomaly records depending upon the characteristics and size -of the input data; in practice too many to be able to manually process. -The {xpack} {ml} features therefore perform a sophisticated aggregation of -the anomaly records into buckets. - -The number of record results depends on the number of anomalies found in each bucket -which relates to the number of timeseries being modelled and the number of detectors. +There can be many anomaly records depending on the characteristics and size of +the input data. In practice, there are often too many to be able to manually +process them. The {xpack} {ml} features therefore perform a sophisticated +aggregation of the anomaly records into buckets. +The number of record results depends on the number of anomalies found in each +bucket, which relates to the number of time series being modeled and the number of +detectors. A record object has the following properties: @@ -260,36 +288,36 @@ A record object has the following properties: This value matches the `bucket_span` that is specified in the job. `by_field_name`:: - (string) The name of the analyzed field. Only present if specified in the detector. - For example, `client_ip`. + (string) The name of the analyzed field. This value is present only if + it is specified in the detector. For example, `client_ip`. `by_field_value`:: - (string) The value of `by_field_name`. Only present if specified in the detector. - For example, `192.168.66.2`. + (string) The value of `by_field_name`. This value is present only if + it is specified in the detector. For example, `192.168.66.2`. -`causes` - (array) For population analysis, an over field must be specified in the detector. - This property contains an array of anomaly records that are the causes for the anomaly - that has been identified for the over field. - If no over fields exist, this field will not be present. - This sub-resource contains the most anomalous records for the `over_field_name`. - For scalability reasons, a maximum of the 10 most significant causes of - the anomaly will be returned. As part of the core analytical modeling, - these low-level anomaly records are aggregated for their parent over field record. - The causes resource contains similar elements to the record resource, - namely `actual`, `typical`, `*_field_name` and `*_field_value`. - Probability and scores are not applicable to causes. +`causes`:: + (array) For population analysis, an over field must be specified in the + detector. This property contains an array of anomaly records that are the + causes for the anomaly that has been identified for the over field. If no + over fields exist, this field is not present. This sub-resource contains + the most anomalous records for the `over_field_name`. For scalability reasons, + a maximum of the 10 most significant causes of the anomaly are returned. As + part of the core analytical modeling, these low-level anomaly records are + aggregated for their parent over field record. The causes resource contains + similar elements to the record resource, namely `actual`, `typical`, + `*_field_name` and `*_field_value`. Probability and scores are not applicable + to causes. `detector_index`:: (number) A unique identifier for the detector. `field_name`:: - (string) Certain functions require a field to operate on. E.g. `sum()`. - For those functions, this is the name of the field to be analyzed. + (string) Certain functions require a field to operate on, for example, `sum()`. + For those functions, this value is the name of the field to be analyzed. `function`:: - (string) The function in which the anomaly occurs, as specified in the detector configuration. - For example, `max`. + (string) The function in which the anomaly occurs, as specified in the + detector configuration. For example, `max`. `function_description`:: (string) The description of the function in which the anomaly occurs, as @@ -297,75 +325,83 @@ A record object has the following properties: `influencers`:: (array) If `influencers` was specified in the detector configuration, then - this array contains influencers that contributed to or were to blame for an anomaly. + this array contains influencers that contributed to or were to blame for an + anomaly. `initial_record_score`:: - (number) A normalized score between 0-100, based on the probability of the anomalousness of this record. - This is this initial value calculated at the time the bucket was processed. + (number) A normalized score between 0-100, which is based on the + probability of the anomalousness of this record. This is the initial value + that was calculated at the time the bucket was processed. `is_interim`:: - (boolean) If true, then this anomaly record is an interim result. - In other words, it is calculated based on partial input data + (boolean) If true, this is an interim result. In other words, the anomaly + record is calculated based on partial input data. `job_id`:: (string) The unique identifier for the job that these results belong to. `over_field_name`:: - (string) The name of the over field that was used in the analysis. Only present if specified in the detector. - Over fields are used in population analysis. - For example, `user`. + (string) The name of the over field that was used in the analysis. This value + is present only if it was specified in the detector. Over fields are used + in population analysis. For example, `user`. `over_field_value`:: - (string) The value of `over_field_name`. Only present if specified in the detector. - For example, `Bob`. + (string) The value of `over_field_name`. This value is present only if it + was specified in the detector. For example, `Bob`. `partition_field_name`:: - (string) The name of the partition field that was used in the analysis. Only present if specified in the detector. - For example, `region`. + (string) The name of the partition field that was used in the analysis. This + value is present only if it was specified in the detector. For example, + `region`. `partition_field_value`:: - (string) The value of `partition_field_name`. Only present if specified in the detector. - For example, `us-east-1`. + (string) The value of `partition_field_name`. This value is present only if + it was specified in the detector. For example, `us-east-1`. `probability`:: - (number) The probability of the individual anomaly occurring, in the range 0 to 1. For example, 0.0000772031. - This value can be held to a high precision of over 300 decimal places, so the `record_score` is provided as a + (number) The probability of the individual anomaly occurring, in the range + 0 to 1. For example, 0.0000772031. This value can be held to a high precision + of over 300 decimal places, so the `record_score` is provided as a human-readable and friendly interpretation of this. //In scientific notation, a value of 3.24E-300 is highly unlikely and therefore //highly anomalous. `record_score`:: - (number) A normalized score between 0-100, based on the probability of the anomalousness of this record. - Unlike `initial_record_score`, this value will be updated by a re-normalization process as new data is analyzed. + (number) A normalized score between 0-100, which is based on the probability + of the anomalousness of this record. Unlike `initial_record_score`, this + value will be updated by a re-normalization process as new data is analyzed. `result_type`:: - (string) Internal. This is always set to "record". + (string) Internal. This is always set to `record`. `sequence_num`:: (number) Internal. `timestamp`:: - (date) The start time of the bucket for which these results have been calculated for. + (date) The start time of the bucket for which these results were calculated. `typical`:: (array) The typical value for the bucket, according to analytical modeling. -NOTE: Additional record properties are added, depending on the fields being analyzed. -For example, if analyzing `hostname` as a _by field_, then a field `hostname` would be added to the -result document. This allows easier filtering of the anomaly results. +NOTE: Additional record properties are added, depending on the fields being +analyzed. For example, if it's analyzing `hostname` as a _by field_, then a field +`hostname` is added to the result document. This information enables you to +filter the anomaly results more easily. [float] [[ml-results-categories]] ===== Categories -When `categorization_field_name` is specified in the job configuration, -it is possible to view the definitions of the resulting categories. -A category definition describes the common terms matched and contains examples of matched values. +When `categorization_field_name` is specified in the job configuration, it is +possible to view the definitions of the resulting categories. A category +definition describes the common terms matched and contains examples of matched +values. -The anomaly results from a categorization analysis are available as _buckets_, _influencers_ and _records_ results. -For example, at 16:45 there was an unusual count of log message category 11. -These definitions can be used to describe and show examples of `categorid_id: 11`. +The anomaly results from a categorization analysis are available as bucket, +influencer, and record results. For example, the results might indicate that +at 16:45 there was an unusual count of log message category 11. You can then +examine the description and examples of that category. A category resource has the following properties: @@ -380,10 +416,13 @@ A category resource has the following properties: `max_matching_length`:: (unsigned integer) The maximum length of the fields that matched the category. - The value is increased by 10% to enable matching for similar fields that have not been analyzed. + The value is increased by 10% to enable matching for similar fields that have + not been analyzed. `regex`:: - (string) A regular expression that is used to search for values that match the category. + (string) A regular expression that is used to search for values that match the + category. `terms`:: - (string) A space separated list of the common tokens that are matched in values of the category. + (string) A space separated list of the common tokens that are matched in + values of the category. diff --git a/docs/en/rest-api/ml/revert-snapshot.asciidoc b/docs/en/rest-api/ml/revert-snapshot.asciidoc index 54b02cc75d9..aa599939d39 100644 --- a/docs/en/rest-api/ml/revert-snapshot.asciidoc +++ b/docs/en/rest-api/ml/revert-snapshot.asciidoc @@ -50,8 +50,6 @@ IMPORTANT: Before you revert to a saved snapshot, you must close the job. Sending data to a closed job changes its status to `open`, so you must also ensure that you do not expect data imminently. -You must have `manage_ml`, or `manage` cluster privileges to use this API. -For more information, see <>. ===== Path Parameters @@ -72,17 +70,12 @@ NOTE: If you choose not to delete intervening results when reverting a snapshot, the job will not accept input data that is older than the current time. If you want to resend data, then delete the intervening results. -//// -===== Responses -TBD -200 -(EmptyResponse) The cluster has been successfully deleted -404 -(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found) -412 -(BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) -//// +===== Authorization + +You must have `manage_ml`, or `manage` cluster privileges to use this API. +For more information, see <>. + ===== Examples diff --git a/docs/en/rest-api/ml/start-datafeed.asciidoc b/docs/en/rest-api/ml/start-datafeed.asciidoc index dd7237afd3c..5d419b1221f 100644 --- a/docs/en/rest-api/ml/start-datafeed.asciidoc +++ b/docs/en/rest-api/ml/start-datafeed.asciidoc @@ -50,8 +50,6 @@ because the job might not have completely processed all data for that millisecon If you specify a `start` value that is earlier than the timestamp of the latest processed record, that value is ignored. -You must have `manage_ml`, or `manage` cluster privileges to use this API. -For more information, see <>. ===== Path Parameters @@ -72,16 +70,13 @@ For more information, see <>. (time) Controls the amount of time to wait until a data feed starts. The default value is 20 seconds. -//// -===== Responses -200 -(EmptyResponse) The cluster has been successfully deleted -404 -(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found) -412 -(BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) -//// +===== Authorization + +You must have `manage_ml`, or `manage` cluster privileges to use this API. +For more information, see <>. + + ===== Examples The following example opens the `datafeed-it-ops-kpi` data feed: diff --git a/docs/en/rest-api/ml/stop-datafeed.asciidoc b/docs/en/rest-api/ml/stop-datafeed.asciidoc index 68126f0037e..9e21f5e8717 100644 --- a/docs/en/rest-api/ml/stop-datafeed.asciidoc +++ b/docs/en/rest-api/ml/stop-datafeed.asciidoc @@ -9,10 +9,7 @@ A data feed can be started and stopped multiple times throughout its lifecycle. `POST _xpack/ml/datafeeds//_stop` -===== Description - -You must have `manage_ml`, or `manage` cluster privileges to use this API. -For more information, see <>. +//===== Description ===== Path Parameters @@ -28,16 +25,12 @@ For more information, see <>. (time) Controls the amount of time to wait until a data feed stops. The default value is 20 seconds. -//// -===== Responses -200 -(EmptyResponse) The cluster has been successfully deleted -404 -(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found) -412 -(BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) -//// +===== Authorization + +You must have `manage_ml`, or `manage` cluster privileges to use this API. +For more information, see <>. + ===== Examples The following example stops the `datafeed-it-ops-kpi` data feed: diff --git a/docs/en/rest-api/ml/update-datafeed.asciidoc b/docs/en/rest-api/ml/update-datafeed.asciidoc index 0625a381e94..fa4f5590873 100644 --- a/docs/en/rest-api/ml/update-datafeed.asciidoc +++ b/docs/en/rest-api/ml/update-datafeed.asciidoc @@ -8,11 +8,7 @@ The update data feed API enables you to update certain properties of a data feed `POST _xpack/ml/datafeeds//_update` - -===== Description - -You must have `manage_ml`, or `manage` cluster privileges to use this API. -For more information, see <>. +//===== Description ===== Path Parameters @@ -55,18 +51,12 @@ The following properties can be updated after the data feed is created: For more information about these properties, see <>. -//// -===== Responses -TBD +===== Authorization + +You must have `manage_ml`, or `manage` cluster privileges to use this API. +For more information, see <>. -200 -(EmptyResponse) The cluster has been successfully deleted -404 -(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found) -412 -(BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) -//// ===== Examples The following example updates the `it-ops-kpi` job: diff --git a/docs/en/rest-api/ml/update-job.asciidoc b/docs/en/rest-api/ml/update-job.asciidoc index b7890702337..7bde19039d2 100644 --- a/docs/en/rest-api/ml/update-job.asciidoc +++ b/docs/en/rest-api/ml/update-job.asciidoc @@ -9,12 +9,11 @@ The update job API allows you to update certain properties of a job. `POST _xpack/ml/anomaly_detectors//_update` +//// ===== Description -You must have `manage_ml`, or `manage` cluster privileges to use this API. -For more information, see <>. //TBD: Important:: Updates do not take effect until after then job is closed and re-opened. - +//// ===== Path Parameters `job_id` (required):: @@ -46,21 +45,12 @@ want to re-run this job with an increased `model_memory_limit`. `description`:: (string) An optional description of the job. -//// -This expects data to be sent in JSON format using the POST `_data` API. -===== Responses +===== Authorization + +You must have `manage_ml`, or `manage` cluster privileges to use this API. +For more information, see <>. -TBD -//// -//// -200 -(EmptyResponse) The cluster has been successfully deleted -404 -(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found) -412 -(BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) -//// ===== Examples diff --git a/docs/en/rest-api/ml/update-snapshot.asciidoc b/docs/en/rest-api/ml/update-snapshot.asciidoc index 56a1b45f2fc..f8f37b7fe6b 100644 --- a/docs/en/rest-api/ml/update-snapshot.asciidoc +++ b/docs/en/rest-api/ml/update-snapshot.asciidoc @@ -12,12 +12,9 @@ The update model snapshot API enables you to update certain properties of a snap ===== Description //TBD. Is the following still true? - not sure but close/open would be the method - Updates to the configuration are only applied after the job has been closed and re-opened. -You must have `manage_ml`, or `manage` cluster privileges to use this API. -For more information, see <>. ===== Path Parameters @@ -41,17 +38,12 @@ The following properties can be updated after the model snapshot is created: Note that this snapshot will still be deleted when the job is deleted. The default value is false. -//// -===== Responses -TBD -200 -(EmptyResponse) The cluster has been successfully deleted -404 -(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found) -412 -(BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) -//// +===== Authorization + +You must have `manage_ml`, or `manage` cluster privileges to use this API. +For more information, see <>. + ===== Examples diff --git a/docs/en/rest-api/ml/validate-detector.asciidoc b/docs/en/rest-api/ml/validate-detector.asciidoc index 87cc85f3803..a1e4072c65e 100644 --- a/docs/en/rest-api/ml/validate-detector.asciidoc +++ b/docs/en/rest-api/ml/validate-detector.asciidoc @@ -12,28 +12,19 @@ The validate detectors API validates detector configuration information. This API enables you validate the detector configuration before you create a job. -You must have `manage_ml`, or `manage` cluster privileges to use this API. -For more information, see <>. -//// -===== Path Parameters - -//// ===== Request Body For a list of the properties that you can specify in the body of this API, see <>. -//// -===== Responses -200 -(EmptyResponse) The cluster has been successfully deleted -404 -(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found) -412 -(BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) -//// +===== Authorization + +You must have `manage_ml`, or `manage` cluster privileges to use this API. +For more information, see <>. + + ===== Examples The following example validates detector configuration information: diff --git a/docs/en/rest-api/ml/validate-job.asciidoc b/docs/en/rest-api/ml/validate-job.asciidoc index 9d964d159e2..89c2e4c41fd 100644 --- a/docs/en/rest-api/ml/validate-job.asciidoc +++ b/docs/en/rest-api/ml/validate-job.asciidoc @@ -12,27 +12,19 @@ The validate jobs API validates job configuration information. This API enables you validate the job configuration before you create the job. -You must have `manage_ml`, or `manage` cluster privileges to use this API. -For more information, see <>. -//// -===== Path Parameters -//// ===== Request Body For a list of the properties that you can specify in the body of this API, see <>. -//// -===== Responses -200 -(EmptyResponse) The cluster has been successfully deleted -404 -(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found) -412 -(BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error) -//// +===== Authorization + +You must have `manage_ml`, or `manage` cluster privileges to use this API. +For more information, see <>. + + ===== Examples The following example validates job configuration information: