[ML][DOCS] Add documentation for detector rules and filters #32013

dimitris-athanasiou · 2018-07-12T16:00:41Z

No description provided.

elasticmachine · 2018-07-12T16:00:43Z

Pinging @elastic/es-docs

elasticmachine · 2018-07-12T16:00:44Z

Pinging @elastic/ml-core

lcawl · 2018-07-18T17:25:33Z

x-pack/docs/en/rest-api/ml/filterresource.asciidoc

+A filter resource has the following properties:
+
+`filter_id`::
+  (string) A string that uniquely identifies the calendar.


I think this should be "filter" instead of "calendar"

lcawl · 2018-07-18T17:29:29Z

x-pack/docs/en/rest-api/ml/delete-filter.asciidoc

+==== Path Parameters
+
+`filter_id` (required)::
+  (string) Identifier for the calendar.


Ditto, I think this should be "filter" instead of "calendar".

lcawl · 2018-07-18T17:34:22Z

x-pack/docs/en/rest-api/ml/put-filter.asciidoc

+===== Description
+
+A filter contains a list of strings and can
+be referenced by ML anomaly detectors' `custom_rules`.


I recommend replacing "ML" with "{ml}" so it's spelled out.

lcawl · 2018-07-18T17:35:50Z

x-pack/docs/en/rest-api/ml/update-filter.asciidoc

+<titleabbrev>Update Filter</titleabbrev>
++++
+
+Posts scheduled events in a calendar.


I think this description should be something like "Updates properties of a filter".

lcawl · 2018-07-18T17:38:37Z

x-pack/docs/en/ml/detector-custom-rules.asciidoc

+partition field value is in a filter sounds equivalent to having a query
+that filters out such documents. But it is not. There is a fundamental
+difference. When the data is filtered before reaching a job it is as if they
+do never existed for the job. With rules, the data still reaches the job and


Typo "do never"

lcawl · 2018-07-18T17:40:40Z

x-pack/docs/en/ml/detector-custom-rules.asciidoc

+that filters out such documents. But it is not. There is a fundamental
+difference. When the data is filtered before reaching a job it is as if they
+do never existed for the job. With rules, the data still reaches the job and
+depending the rule actions they are affecting the job.


Unclear. Maybe change to "... data still reaches the job and can affect the results (depending on the rule actions)".

davidkyle · 2018-07-19T10:01:38Z

x-pack/docs/en/rest-api/ml/jobresource.asciidoc

+  `skip_result`::: the result will not be created. Note this also means this result
+  will not impact the scoring of results. The model be normally updated with the
+  corresponding series value. This is the default action and it serves to skip
+  results that undesired.


Note this also means this result will not impact the scoring of results. - what does this mean?
The model be normally -> The model *will* be normally or updated as normal
results that undesired -> results that are undesired

davidkyle · 2018-07-19T10:27:14Z

x-pack/docs/en/rest-api/ml/jobresource.asciidoc

+  corresponding series value. This is the default action and it serves to skip
+  results that undesired.
+  `skip_model_update`::: the value for that series will not be used to update the model.
+  If there is an anomalous record for that series it will be normally created. This


If there is an anomalous record for that series it will be normally created. - I think you can delete this line and the paragraph makes more sense

Can you add a note about using skip_model_update and skip_results in union:
'skip_results and skip_model_update may be used together which prevents the model from updating and will not generate anomaly results. If skip_model_update is used without skip_results then the anomalies are created but the model does not learn changing behaviour'

davidkyle · 2018-07-19T10:34:11Z

x-pack/docs/en/rest-api/ml/jobresource.asciidoc

+  To add a scope for a field add the field name as a key in the scope object and
+  set its value to an object with properties:
+    `filter_id`::
+      (string) The id of the filter to be used


Can you link to the filter resource page so the reader knows what a filter is.

davidkyle · 2018-07-19T10:43:38Z

x-pack/docs/en/rest-api/ml/put-filter.asciidoc

+--------------------------------------------------
+// CONSOLE
+
+When the filter is created, you receive the following results:


don't need results it's confusing as we often refer to anomaly results

davidkyle · 2018-07-19T10:44:51Z

x-pack/docs/en/rest-api/ml/update-filter.asciidoc

+==== Request Body
+
+`description`::
+  (string) A description for the filter. See <<ml-event-resource>>.


ml-event-resource -> ml-filter-resource

davidkyle · 2018-07-19T10:51:38Z

x-pack/docs/en/ml/detector-custom-rules.asciidoc

+This is useful when we want the rule to apply to a range. We simply create
+a rule with two conditions, one for each end of the desired range.
+
+Here is an example where a cound detector will skip results when the count


cound -> count

davidkyle · 2018-07-19T10:54:03Z

x-pack/docs/en/ml/detector-custom-rules.asciidoc

+
+==== Rules in the life-cycle of a job
+
+Rules only apply for results created after the rules were created.


2 createds close together

Rules only affect results created after the rules were applied.

droberts195 · 2018-07-19T11:39:04Z

In the code we have:

    /**
     * Functions that do not support rule conditions:
     * <ul>
     * <li>lat_long - because it is a multivariate feature
     * <li>metric - because having the same conditions on min,max,mean is
     * error-prone
     * <li>rare - because the actual/typical value is not something a user can anticipate
     * <li>freq_rare - because the actual/typical value is not something a user can anticipate
     * </ul>
     */
    static final EnumSet<DetectorFunction> FUNCTIONS_WITHOUT_RULE_CONDITION_SUPPORT = EnumSet.of(
            DetectorFunction.LAT_LONG, DetectorFunction.METRIC, DetectorFunction.RARE, DetectorFunction.FREQ_RARE);

I couldn't see this in the docs in this PR. Does it need to be added or is it somewhere else?

droberts195 · 2018-07-20T16:33:36Z

x-pack/docs/en/ml/functions/metric.asciidoc

@@ -15,6 +15,9 @@ The {xpackml} features include the following metric functions:
 * <<ml-metric-metric,`metric`>>
 * xref:ml-metric-varp[`varp`, `high_varp`, `low_varp`]

+NOTE: You cannot add rules with conditions to detectors that use metric 
+functions. 


I think it should be:

NOTE: You cannot add rules with conditions to detectors that use the metric
function.

min, max and mean are metric functions, and they conditions should be fine with them. The reason conditions aren't allowed with metric is that metric looks at all 3 of min, max and mean, and it would be very hard to reason about which of the 3 statistics the condition had been applied to.

dimitris-athanasiou · 2018-07-23T11:24:01Z

x-pack/docs/en/ml/detector-custom-rules.asciidoc

+
+Rules and filters enable you to change the behavior of anomaly detectors based 
+on domain-specific knowledge.
+//TO-DO: Add link to rules overview page


Can we do this already? If not, what do we refer to by rules overview page?

lcawl

LGTM

lcawl · 2018-07-24T19:20:13Z

retest this please

lcawl · 2018-07-24T22:38:35Z

retest this please

dimitris-athanasiou · 2018-07-25T12:02:00Z

retest this please

* master: [DOCS] Fix formatting error in Slack action Painless: Fix documentation links to use existing refs (#32335) Painless: Decouple PainlessLookupBuilder and Whitelists (#32346) [DOCS] Adds recommendation for xpack.security.enabled (#32345) [TEST] Mute ConvertProcessortTests.testConvertIntHexError [TEST] Fix failure due to exception message in java11 (#32321) [DOCS] Fixes typo in ML aggregations page [DOCS] Adds link from bucket_span property to common time units [ML][DOCS] Add documentation for detector rules and filters (#32013) Add opaque_id to index audit logging (#32260) Add 6.5.0 version to master fixes broken build for third-party-tests (#32353)

* 6.x: Only enforce password hashing check if FIPS enabled (#32383) Introduce fips_mode setting and associated checks (#32326) [DOCS] Fix formatting error in Slack action Ingest: Support integer and long hex values in convert (#32213) Release pipelined request in netty server tests (#32368) Add opaque_id to index audit logging (#32260) Painless: Fix documentation links to use existing refs (#32335) Painless: Decouple PainlessLookupBuilder and Whitelists (#32346) [DOCS] Adds recommendation for xpack.security.enabled (#32345) [test] package pre-install java check (#32259) [DOCS] Adds link from bucket_span property to common time units [DOCS] Fixes typo in ML aggregations page [ML][DOCS] Add documentation for detector rules and filters (#32013) Bump the 6.x branch to 6.5.0 (#32361) fixes broken build repository-s3 for third-party-tests

dimitris-athanasiou added >non-issue review v7.0.0 :ml Machine learning v6.4.0 labels Jul 12, 2018

dimitris-athanasiou requested a review from lcawl July 12, 2018 16:00

lcawl reviewed Jul 18, 2018

View reviewed changes

lcawl mentioned this pull request Jul 19, 2018

[DOCS] Adds overview for machine learning rules and filters elastic/stack-docs#84

Merged

davidkyle reviewed Jul 19, 2018

View reviewed changes

droberts195 reviewed Jul 20, 2018

View reviewed changes

dimitris-athanasiou commented Jul 23, 2018

View reviewed changes

dimitris-athanasiou force-pushed the docs-for-ml-rules-and-filters branch 2 times, most recently from e554890 to 4c11131 Compare July 24, 2018 18:03

lcawl approved these changes Jul 24, 2018

View reviewed changes

dimitris-athanasiou and others added 5 commits July 25, 2018 10:59

[ML][DOCS] Add documentation for detector rules and filters

05a2540

[DOCS] Fixes small typos

9f72c12

[DOCS] Addresses review feedback

882a602

[DOCS] Moves overview info to Stack Overview

635aea5

[DOCS] Added rule limitations to function reference

5b255f2

lcawl and others added 5 commits July 25, 2018 10:59

[DOCS] Clarifies rule restriction for metric function

b2d74f8

[DOCS] Adds function limitations to rule conditions

2bb5623

[DOCS] Fixes formatting of limitations in rule conditions

d874740

[DOCS] Remove confusing comment about results scoring for skip_result

0f8b4af

[DOCS] Adds links to rules overview

fc47818

dimitris-athanasiou force-pushed the docs-for-ml-rules-and-filters branch from 4c11131 to fc47818 Compare July 25, 2018 09:59

dimitris-athanasiou merged commit 9a7a649 into elastic:master Jul 25, 2018

dimitris-athanasiou deleted the docs-for-ml-rules-and-filters branch July 25, 2018 15:10

dimitris-athanasiou added a commit that referenced this pull request Jul 25, 2018

[ML][DOCS] Add documentation for detector rules and filters (#32013)

3e2ef0f

dimitris-athanasiou added a commit that referenced this pull request Jul 25, 2018

[ML][DOCS] Add documentation for detector rules and filters (#32013)

4cdef4e

jimczi added v7.0.0-beta1 and removed v7.0.0 labels Feb 7, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[ML][DOCS] Add documentation for detector rules and filters #32013

[ML][DOCS] Add documentation for detector rules and filters #32013

dimitris-athanasiou commented Jul 12, 2018

elasticmachine commented Jul 12, 2018

elasticmachine commented Jul 12, 2018

lcawl Jul 18, 2018

lcawl Jul 18, 2018

lcawl Jul 18, 2018

lcawl Jul 18, 2018

lcawl Jul 18, 2018

lcawl Jul 18, 2018

davidkyle Jul 19, 2018

davidkyle Jul 19, 2018

davidkyle Jul 19, 2018

davidkyle Jul 19, 2018

davidkyle Jul 19, 2018

davidkyle Jul 19, 2018

davidkyle Jul 19, 2018

droberts195 commented Jul 19, 2018

droberts195 Jul 20, 2018

dimitris-athanasiou Jul 23, 2018

lcawl left a comment

lcawl commented Jul 24, 2018

lcawl commented Jul 24, 2018

dimitris-athanasiou commented Jul 25, 2018


		==== Rules in the life-cycle of a job

		Rules only apply for results created after the rules were created.

[ML][DOCS] Add documentation for detector rules and filters #32013

[ML][DOCS] Add documentation for detector rules and filters #32013

Conversation

dimitris-athanasiou commented Jul 12, 2018

elasticmachine commented Jul 12, 2018

elasticmachine commented Jul 12, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

droberts195 commented Jul 19, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lcawl left a comment

Choose a reason for hiding this comment

lcawl commented Jul 24, 2018

lcawl commented Jul 24, 2018

dimitris-athanasiou commented Jul 25, 2018