297 lines
8.2 KiB
Plaintext
297 lines
8.2 KiB
Plaintext
[role="xpack"]
|
|
[testenv="platinum"]
|
|
[[ml-put-job]]
|
|
=== Create {anomaly-jobs} API
|
|
++++
|
|
<titleabbrev>Create jobs</titleabbrev>
|
|
++++
|
|
|
|
Instantiates an {anomaly-job}.
|
|
|
|
[[ml-put-job-request]]
|
|
==== {api-request-title}
|
|
|
|
`PUT _ml/anomaly_detectors/<job_id>`
|
|
|
|
[[ml-put-job-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* If the {es} {security-features} are enabled, you must have `manage_ml` or
|
|
`manage` cluster privileges to use this API. See
|
|
<<security-privileges>>.
|
|
|
|
[[ml-put-job-desc]]
|
|
==== {api-description-title}
|
|
|
|
IMPORTANT: You must use {kib} or this API to create an {anomaly-job}. Do not put
|
|
a job directly to the `.ml-config` index using the {es} index API. If {es}
|
|
{security-features} are enabled, do not give users `write` privileges on the
|
|
`.ml-config` index.
|
|
|
|
[[ml-put-job-path-parms]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<job_id>`::
|
|
(Required, string)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection-define]
|
|
|
|
[[ml-put-job-request-body]]
|
|
==== {api-request-body-title}
|
|
|
|
`allow_lazy_open`::
|
|
(Optional, boolean)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=allow-lazy-open]
|
|
|
|
[[put-analysisconfig]]`analysis_config`::
|
|
(Required, object)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=analysis-config]
|
|
|
|
`analysis_config`.`bucket_span`:::
|
|
(<<time-units,time units>>)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=bucket-span]
|
|
|
|
`analysis_config`.`categorization_field_name`:::
|
|
(string)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=categorization-field-name]
|
|
|
|
`analysis_config`.`categorization_filters`:::
|
|
(array of strings)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=categorization-filters]
|
|
|
|
`analysis_config`.`categorization_analyzer`:::
|
|
(object or string)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=categorization-analyzer]
|
|
|
|
`analysis_config`.`detectors`:::
|
|
(array) An array of detector configuration objects. Detector configuration
|
|
objects specify which data fields a job analyzes. They also specify which
|
|
analytical functions are used. You can specify multiple detectors for a job.
|
|
+
|
|
--
|
|
NOTE: If the `detectors` array does not contain at least one detector,
|
|
no analysis can occur and an error is returned.
|
|
|
|
A detector has the following properties:
|
|
--
|
|
|
|
`analysis_config`.`detectors`.`by_field_name`::::
|
|
(string)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=by-field-name]
|
|
|
|
`analysis_config`.`detectors`.`custom_rules`::::
|
|
+
|
|
--
|
|
(array)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-rules]
|
|
|
|
`analysis_config`.`detectors`.`custom_rules`.`actions`:::
|
|
(array)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-rules-actions]
|
|
|
|
`analysis_config`.`detectors`.`custom_rules`.`scope`:::
|
|
(object)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-rules-scope]
|
|
|
|
`analysis_config`.`detectors`.`custom_rules`.`scope`.`filter_id`::::
|
|
(string)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-rules-scope-filter-id]
|
|
|
|
`analysis_config`.`detectors`.`custom_rules`.`scope`.`filter_type`::::
|
|
(string)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-rules-scope-filter-type]
|
|
|
|
`analysis_config`.`detectors`.`custom_rules`.`conditions`:::
|
|
(array)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-rules-conditions]
|
|
|
|
`analysis_config`.`detectors`.`custom_rules`.`conditions`.`applies_to`::::
|
|
(string)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-rules-conditions-applies-to]
|
|
|
|
`analysis_config`.`detectors`.`custom_rules`.`conditions`.`operator`::::
|
|
(string)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-rules-conditions-operator ]
|
|
|
|
`analysis_config`.`detectors`.`custom_rules`.`conditions`.`value`::::
|
|
(double)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-rules-conditions-value]
|
|
--
|
|
|
|
`analysis_config`.`detectors`.`detector_description`::::
|
|
(string)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=detector-description]
|
|
|
|
`analysis_config`.`detectors`.`detector_index`::::
|
|
+
|
|
--
|
|
(integer)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=detector-index]
|
|
If you specify a value for this property, it is ignored.
|
|
--
|
|
|
|
`analysis_config`.`detectors`.`exclude_frequent`::::
|
|
(string)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=exclude-frequent]
|
|
|
|
`analysis_config`.`detectors`.`field_name`::::
|
|
(string)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=detector-field-name]
|
|
|
|
`analysis_config`.`detectors`.`function`::::
|
|
(string)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=function]
|
|
|
|
`analysis_config`.`detectors`.`over_field_name`::::
|
|
(string)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=over-field-name]
|
|
|
|
`analysis_config`.`detectors`.`partition_field_name`::::
|
|
(string)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=partition-field-name]
|
|
|
|
`analysis_config`.`detectors`.`use_null`::::
|
|
(boolean)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=use-null]
|
|
|
|
`analysis_config`.`influencers`:::
|
|
(array of strings)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=influencers]
|
|
|
|
`analysis_config`.`latency`:::
|
|
(<<time-units,time units>>)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=latency]
|
|
|
|
`analysis_config`.`multivariate_by_fields`:::
|
|
(boolean)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=multivariate-by-fields]
|
|
|
|
`analysis_config`.`summary_count_field_name`:::
|
|
(string)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=summary-count-field-name]
|
|
|
|
[[put-analysislimits]]`analysis_limits`::
|
|
(Optional, object)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=analysis-limits]
|
|
+
|
|
--
|
|
The `analysis_limits` object has the following properties:
|
|
--
|
|
|
|
`analysis_limits`.`categorization_examples_limit`:::
|
|
(long)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=categorization-examples-limit]
|
|
|
|
`analysis_limits`.`model_memory_limit`:::
|
|
(long or string)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=model-memory-limit]
|
|
|
|
`background_persist_interval`::
|
|
(Optional, <<time-units, time units>>)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=background-persist-interval]
|
|
|
|
[[put-customsettings]]`custom_settings`::
|
|
(Optional, object)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-settings]
|
|
|
|
[[put-datadescription]]`data_description`::
|
|
(Required, object)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=data-description]
|
|
|
|
`description`::
|
|
(Optional, string) A description of the job.
|
|
|
|
`groups`::
|
|
(Optional, array of strings)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=groups]
|
|
|
|
`model_plot_config`::
|
|
(Optional, object)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=model-plot-config]
|
|
|
|
`model_plot_config`.`enabled`:::
|
|
(boolean)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=model-plot-config-enabled]
|
|
|
|
`model_plot_config`.`terms`:::
|
|
experimental[] (string)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=model-plot-config-terms]
|
|
|
|
`model_snapshot_retention_days`::
|
|
(Optional, long)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=model-snapshot-retention-days]
|
|
|
|
`renormalization_window_days`::
|
|
(Optional, long)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=renormalization-window-days]
|
|
|
|
`results_index_name`::
|
|
(Optional, string)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=results-index-name]
|
|
|
|
`results_retention_days`::
|
|
(Optional, long)
|
|
include::{docdir}/ml/ml-shared.asciidoc[tag=results-retention-days]
|
|
|
|
[[ml-put-job-example]]
|
|
==== {api-examples-title}
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT _ml/anomaly_detectors/total-requests
|
|
{
|
|
"description" : "Total sum of requests",
|
|
"analysis_config" : {
|
|
"bucket_span":"10m",
|
|
"detectors": [
|
|
{
|
|
"detector_description": "Sum of total",
|
|
"function": "sum",
|
|
"field_name": "total"
|
|
}
|
|
]
|
|
},
|
|
"data_description" : {
|
|
"time_field":"timestamp",
|
|
"time_format": "epoch_ms"
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
When the job is created, you receive the following results:
|
|
|
|
[source,console-result]
|
|
----
|
|
{
|
|
"job_id" : "total-requests",
|
|
"job_type" : "anomaly_detector",
|
|
"job_version" : "7.5.0",
|
|
"description" : "Total sum of requests",
|
|
"create_time" : 1562352500629,
|
|
"analysis_config" : {
|
|
"bucket_span" : "10m",
|
|
"detectors" : [
|
|
{
|
|
"detector_description" : "Sum of total",
|
|
"function" : "sum",
|
|
"field_name" : "total",
|
|
"detector_index" : 0
|
|
}
|
|
],
|
|
"influencers" : [ ]
|
|
},
|
|
"analysis_limits" : {
|
|
"model_memory_limit" : "1024mb",
|
|
"categorization_examples_limit" : 4
|
|
},
|
|
"data_description" : {
|
|
"time_field" : "timestamp",
|
|
"time_format" : "epoch_ms"
|
|
},
|
|
"model_snapshot_retention_days" : 1,
|
|
"results_index_name" : "shared",
|
|
"allow_lazy_open" : false
|
|
}
|
|
----
|
|
// TESTRESPONSE[s/"job_version" : "7.5.0"/"job_version" : $body.job_version/]
|
|
// TESTRESPONSE[s/1562352500629/$body.$_path/]
|