105 lines
5.2 KiB
Plaintext
105 lines
5.2 KiB
Plaintext
[[ml-configuring-url]]
|
|
=== Adding Custom URLs To Machine Learning Results
|
|
|
|
When you create an advanced job or edit any job in {kib}, you can optionally
|
|
attach one or more custom URLs. You can also specify these custom settings when
|
|
you create or update jobs by using the {ml} APIs.
|
|
|
|
The custom URLs provide links from the anomalies table in the Anomaly Explorer
|
|
or Single Metric Viewer window in {kib} to custom dashboards 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.
|
|
|
|
For each custom URL, you must supply the URL and a label, which is the link text
|
|
that appears in the anomalies table.
|
|
|
|
[role="screenshot"]
|
|
image::images/ml-customurl.jpg["Links in the Anomaly Explorer anoamilies table"]
|
|
|
|
[float]
|
|
==== String Substitution in Custom URLs
|
|
|
|
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.
|
|
|
|
NOTE: 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$`.
|
|
|
|
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.
|
|
|
|
The `$mlcategoryregex$` and `$mlcategoryterms$` tokens pertain to jobs where you
|
|
are categorizing field values. For more information about this type of analysis,
|
|
see <<ml-configuring-categories>>.
|
|
|
|
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.
|
|
|
|
For example, the following API updates a `log_categories` job to add a custom
|
|
URL that uses `$earliest$`, `$latest$`, and `$mlcategoryterms$` tokens:
|
|
|
|
[source,js]
|
|
----------------------------------
|
|
POST _xpack/ml/anomaly_detectors/log_categories/_update
|
|
{
|
|
"custom_settings": {
|
|
"custom_urls": [
|
|
{
|
|
"url_name": "test-link1",
|
|
"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))"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
----------------------------------
|
|
|
|
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 when 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}"]
|
|
|
|
[TIP]
|
|
===============================
|
|
* The custom URL links in the anomaly tables use pop-ups. You must configure
|
|
your web browser so that it does not block pop-up windows or create an exception
|
|
for your {kib} URL.
|
|
* When creating a link to a {kib} dashboard, the URLs for dashboards can be very
|
|
long. Be careful of typos, end of line characters, and URL encoding. Also ensure
|
|
you use the appropriate index ID for the target {kib} index pattern.
|
|
* If you use an influencer name for string substitution, keep in mind that it
|
|
might not always be available in the analysis results and the URL is invalid in
|
|
those cases. There is not always a statistically significant influencer for each
|
|
anomaly.
|
|
* The dates substituted for `$earliest$` and `$latest$` tokens are in
|
|
ISO-8601 format and the target system must understand this format.
|
|
* If the job performs an analysis against nested JSON fields, the tokens for
|
|
string substitution can refer to these fields using dot notation. For example,
|
|
`$cpu.total$`.
|
|
* {es} source data mappings might make it difficult for the query string to work.
|
|
Test the custom URL before saving the job configuration to check that it works
|
|
as expected, particularly when using string substitution.
|
|
===============================
|