diff --git a/docs/reference/ml/anomaly-detection/ml-configuring-url.asciidoc b/docs/reference/ml/anomaly-detection/ml-configuring-url.asciidoc index e5bf4a400c1..cfad35348a7 100644 --- a/docs/reference/ml/anomaly-detection/ml-configuring-url.asciidoc +++ b/docs/reference/ml/anomaly-detection/ml-configuring-url.asciidoc @@ -2,50 +2,27 @@ [[ml-configuring-url]] = Adding custom URLs to machine learning results -When you create an advanced {anomaly-job} or edit any {anomaly-jobs} in {kib}, -you can optionally attach one or more custom URLs. - -The custom URLs provide links from the anomalies table in the *Anomaly Explorer* -or *Single Metric Viewer* window in {kib} to {kib} dashboards, the *Discovery* -page, or external websites. For example, you can define a custom URL that -provides a way for users to drill down to the source data from the results set. - -When you edit an {anomaly-job} in {kib}, it simplifies the creation of the -custom URLs for {kib} dashboards and the *Discover* page and it enables you to -test your URLs. For example: +You can optionally attach one or more custom URLs to your {anomaly-jobs}. These +links appear in the anomalies table in the *Anomaly Explorer* and +*Single Metric Viewer* and can direct you to dashboards, the *Discover* app, or +external websites. For example, you can define a custom URL that provides a way +for users to drill down to the source data from the results set: [role="screenshot"] -image::images/ml-customurl-edit.jpg["Edit a job to add a custom URL"] +image::images/ml-customurl.gif["An example of the custom URL links in the Anomaly Explorer anomalies table"] + +When you create or edit an {anomaly-job} in {kib}, it simplifies the creation +of the custom URLs for {kib} dashboards and the *Discover* app and it enables +you to test your URLs. For example: + +[role="screenshot"] +image::images/ml-customurl-edit.gif["Add a custom URL in {kib}",width=50%] For each custom URL, you must supply the URL and a label, which is the link text that appears in the anomalies table. You can also optionally supply a time -range. For example, these are the values that are added for `My link 1`: - -[role="screenshot"] -image::images/ml-customurl-detail.jpg["An example of a label and URL"] - -As in this case, the custom URL can contain -<>, which -are populated when you click the link in the anomalies table. In this example, -the custom URL contains `$earliest$`, `$latest$`, and `$service$` tokens, which -pass the beginning and end of the time span of the selected anomaly and the -pertinent `service` field value to the target page. If you were interested in -the following anomaly, for example: - -[role="screenshot"] -image::images/ml-customurl.jpg["An example of the custom URL links in the Anomaly Explorer anomalies table"] - -...clicking `My Link 1` opens the *Discover* page and shows results for the -service and date that were identified in the anomaly: - -[role="screenshot"] -image::images/ml-customurl-discover.jpg["An example of the results on the Discover page"] - -Since we specified a time range of 2 hours, the time filter restricts the -results to the time period two hours before and after the anomaly. - -You can also specify these custom URL settings when you create or update -{anomaly-jobs} by using the APIs. +range. When you link to *Discover* or a {kib} dashboard, you'll have additional +options for specifying the pertinent index pattern or dashboard name and query +entities. [discrete] [[ml-configuring-url-strings]] @@ -53,41 +30,33 @@ You can also specify these custom URL settings when you create or update You can use dollar sign ($) delimited tokens in a custom URL. These tokens are substituted for the values of the corresponding fields in the anomaly records. -For example, for a configured URL of -`http://my.datastore.com/dashboards?user=$user_name$`, the value of the -`user_name` field in the anomaly record is substituted into the `$user_name$` -token when you click the link in the anomalies table. +For example, the `Raw data` URL might resolve to `discover#/?_g=(time:(from:'$earliest$',mode:absolute,to:'$latest$'))&_a=(index:ff959d40-b880-11e8-a6d9-e546fe2bba5f,query:(language:kuery,query:'customer_full_name.keyword:"$customer_full_name.keyword$"'))`. In this case, the pertinent value of the `customer_full_name.keyword` field +is passed to the target page when you click the link. -NOTE: Not all fields in your source data exist in the anomaly results. If a +TIP: Not all fields in your source data exist in the anomaly results. If a field is specified in the detector as the `field_name`, `by_field_name`, `over_field_name`, or `partition_field_name`, for example, it can be used in a -custom URL. A field that is only used in the `categorization_field_name` -property, however, does not exist in the anomaly results. - -The following keywords can also be used as tokens for string substitution in a -custom URL: `$earliest$`; `$latest$`; `$mlcategoryregex$`; `$mlcategoryterms$`. +custom URL. A field that is used only in the `categorization_field_name` +property, however, does not exist in the anomaly results. When you create your +custom URL in {kib}, the *Query entities* option is shown only when there are +appropriate fields in the detectors. The `$earliest$` and `$latest$` tokens pass the beginning and end of the time span of the selected anomaly to the target page. The tokens are substituted with date-time strings in ISO-8601 format. If you selected an interval of 1 hour for the anomalies table, these tokens use one hour on either side of the anomaly -time as the earliest and latest times. The same is also true if the interval is -set to `Auto` and a one hour interval was chosen. You can override this behavior -by using the `time_range` setting. - -The `$mlcategoryregex$` and `$mlcategoryterms$` tokens pertain to {anomaly-jobs} -where you are categorizing field values. For more information about this type of -analysis, see <>. - -The `$mlcategoryregex$` token passes the regular expression value of the -category of the selected anomaly, as identified by the value of the `mlcategory` -field of the anomaly record. - -The `$mlcategoryterms$` token likewise passes the terms value of the category of -the selected anomaly. Each categorization term is prefixed by a plus (+) -character, so that when the token is passed to a {kib} dashboard, the resulting -dashboard query seeks a match for all of the terms of the category. +time as the earliest and latest times. You can alter this behavior by setting a +time range for the custom URL. +There are also `$mlcategoryregex$` and `$mlcategoryterms$` tokens, which pertain +to {anomaly-jobs} where you are categorizing field values. For more information +about this type of analysis, see <>. The +`$mlcategoryregex$` token passes the regular expression value of the category of +the selected anomaly, as identified by the value of the `mlcategory` field of +the anomaly record. The `$mlcategoryterms$` token passes the terms value of the +category of the selected anomaly. Each categorization term is prefixed by a plus +(+) character, so that when the token is passed to a {kib} dashboard, the +resulting dashboard query seeks a match for all of the terms of the category. For example, the following API updates a job to add a custom URL that uses `$earliest$`, `$latest$`, and `$mlcategoryterms$` tokens: @@ -100,7 +69,7 @@ POST _ml/anomaly_detectors/sample_job/_update { "url_name": "test-link1", "time_range": "1h", - "url_value": "http://localhost:5601/app/kibana#/discover?_g=(refreshInterval:(display:Off,pause:!f,value:0),time:(from:'$earliest$',mode:quick,to:'$latest$'))&_a=(columns:!(_source),index:AV3OWB68ue3Ht69t29aw,interval:auto,query:(query_string:(analyze_wildcard:!t,query:'$mlcategoryterms$')),sort:!(time,desc))" + "url_value": "discover#/?_g=(time:(from:'$earliest$',mode:quick,to:'$latest$'))&_a=(index:'90943e30-9a47-11e8-b64d-95841ca0b247',query:(language:lucene,query_string:(analyze_wildcard:!t,query:'$mlcategoryterms$')),sort:!(time,desc))" } ] } @@ -110,12 +79,9 @@ POST _ml/anomaly_detectors/sample_job/_update When you click this custom URL in the anomalies table in {kib}, it opens up the *Discover* page and displays source data for the period one hour before and -after the anomaly occurred. Since this job was categorizing log messages, some -`$mlcategoryterms$` token values that were passed to the target page for an -example anomaly are as follows: - -[role="screenshot"] -image::images/ml-categoryterms.jpg["A query for category terms on the Discover page in {kib}"] +after the anomaly occurred. Since this job is categorizing log messages, some +`$mlcategoryterms$` token values that are passed to the target page in the query +might include `+REC +Not +INSERTED +TRAN +Table +hostname +dbserver.acme.com`. [TIP] =============================== diff --git a/docs/reference/ml/images/ml-categoryterms.jpg b/docs/reference/ml/images/ml-categoryterms.jpg deleted file mode 100644 index 331bce30d33..00000000000 Binary files a/docs/reference/ml/images/ml-categoryterms.jpg and /dev/null differ diff --git a/docs/reference/ml/images/ml-customurl-detail.jpg b/docs/reference/ml/images/ml-customurl-detail.jpg deleted file mode 100644 index f7b2907c556..00000000000 Binary files a/docs/reference/ml/images/ml-customurl-detail.jpg and /dev/null differ diff --git a/docs/reference/ml/images/ml-customurl-discover.jpg b/docs/reference/ml/images/ml-customurl-discover.jpg deleted file mode 100644 index 991560919bd..00000000000 Binary files a/docs/reference/ml/images/ml-customurl-discover.jpg and /dev/null differ diff --git a/docs/reference/ml/images/ml-customurl-edit.gif b/docs/reference/ml/images/ml-customurl-edit.gif new file mode 100644 index 00000000000..e32312fb643 Binary files /dev/null and b/docs/reference/ml/images/ml-customurl-edit.gif differ diff --git a/docs/reference/ml/images/ml-customurl-edit.jpg b/docs/reference/ml/images/ml-customurl-edit.jpg deleted file mode 100644 index a209284c786..00000000000 Binary files a/docs/reference/ml/images/ml-customurl-edit.jpg and /dev/null differ diff --git a/docs/reference/ml/images/ml-customurl.gif b/docs/reference/ml/images/ml-customurl.gif new file mode 100644 index 00000000000..a8a0f6be404 Binary files /dev/null and b/docs/reference/ml/images/ml-customurl.gif differ diff --git a/docs/reference/ml/images/ml-customurl.jpg b/docs/reference/ml/images/ml-customurl.jpg deleted file mode 100644 index e43c6d2588c..00000000000 Binary files a/docs/reference/ml/images/ml-customurl.jpg and /dev/null differ