[DOCS] Add documentation for new Analysis tab in logs app #49165
Conversation
Titch990
added
Team:Docs
Team:Infra Monitoring UI - DEPRECATED
|
Pinging @elastic/kibana-docs (Team:Docs) |
|
Pinging @elastic/logs-metrics-ui (Team:logs-metrics-ui) |
Titch990
changed the title
|
@elasticmachine, run elasticsearch-ci/docs |
💚 Build Succeeded |
There was a problem hiding this comment.
This is a solid start to this PR. A few things to consider:
- You can tighten up a lot of your content by switching to active voice.
- Make sure you're using consistent terms. With the Kibana docs, we use the UI terms, which can get redundant, but helps with navigating the UI. Especially for first time users.
If you have any questions, please reach out.
docs/logs/analysis-tab.asciidoc
Outdated
|
|
||
| beta::[] | ||
|
|
||
| The *Analysis* page in the Logs app allows you to automatically detect some kinds of log anomalies using machine learning. |
There was a problem hiding this comment.
page > UI
Since this is in the Logs section, you don't need to say in the Logs app.
machine learning > Machine Learning
How about this for an into sentence:
To help you spot suspicious behavior, the Analysis UI enables you to inspect log entries and anomalies using Machine Learning. Anomalies highlight periods (of time?) where the log rate is outside of the (specified?) limits.
|
|
||
| The *Analysis* page in the Logs app allows you to automatically detect some kinds of log anomalies using machine learning. | ||
|
|
||
| The analysis automatically highlights periods where the log rate is outside the expected limits and therefore may be anomalous. |
There was a problem hiding this comment.
periods of what? Time?
What makes them expected limits? Are they specified somewhere?
There was a problem hiding this comment.
Yep, this is periods of time.
They are expected limits based on the model defined by the machine learning module, and the "learning" it has done on the datasets to date. Therefore these values will always differ based on the individual dataset. A rate of 10 might be anomalous in one dataset, but not anomalous in another. The ML model will adapt itself over time as it learns from more data.
It may be better to use the word "bounds" here over "limit" as that's the ML terminology.
| The *Analysis* page in the Logs app allows you to automatically detect some kinds of log anomalies using machine learning. | ||
|
|
||
| The analysis automatically highlights periods where the log rate is outside the expected limits and therefore may be anomalous. | ||
| This helps you to spot suspicious behavior without significant human intervention. |
There was a problem hiding this comment.
I really like this bit. I would move it to the top.
| The *Analysis* page in the Logs app allows you to automatically detect some kinds of log anomalies using machine learning. | ||
|
|
||
| The analysis automatically highlights periods where the log rate is outside the expected limits and therefore may be anomalous. | ||
| This helps you to spot suspicious behavior without significant human intervention. |
There was a problem hiding this comment.
significant human intervention is interesting. Maybe unpack that some more?
There was a problem hiding this comment.
Ideally, this would stop users having to manually sample their log data, calculate the rates, and decide whether those rates are "normal".
|
|
||
| The analysis automatically highlights periods where the log rate is outside the expected limits and therefore may be anomalous. | ||
| This helps you to spot suspicious behavior without significant human intervention. | ||
| You can use this information as a basis for further investigations. |
There was a problem hiding this comment.
further investigations into what?
There was a problem hiding this comment.
This could be various things:
- A spike in the log rate could denote a DDoS attack. This may lead to investigating things like IP addresses from incoming requests.
- A significant drop in the log rate could suggest that some some piece of infrastructure has stopped responding, and thus we're serving less requests.
These are just examples, mileage will vary between datasets and anomalies.
Also want to clarify that whilst the backing model which has been trained will have a lower and upper bound for what it considers "normal" and non-anomalous, it doesn't mean anomalous values will always land within these bounds. The model could have upper as 50 and lower as 10, and 30 could still, in the right circumstances, flag as anomalous if something else about the rate is still considered anomalous.
| If you have a license that includes the machine learning features, you can click *Analysis* to <<xpack-logs-analysis-page, use machine learning to detect and inspect anomalies>> in your log data. | ||
|
|
||
| [float] | ||
| === Other actions |
There was a problem hiding this comment.
Is there something more descriptive we can use here besides Other actions?
docs/logs/analysis-tab.asciidoc
Outdated
|
|
||
| beta::[] | ||
|
|
||
| The *Analysis* page in the Logs app allows you to automatically detect some kinds of log anomalies using machine learning. |
There was a problem hiding this comment.
I think it's worth stating right off the bat that this page isn't applicable if you don't have the appropriate ML features available. For example:
| The *Analysis* page in the Logs app allows you to automatically detect some kinds of log anomalies using machine learning. | |
| If the {ml} {anomaly-detect} features are enabled, you can use | |
| the *Analysis* page in the Logs app to automatically detect some kinds of log anomalies. |
|
@KOTungseth Thanks for the extremely detailed review. I've responded to the individual points. Can you give me an example of where you suggest I should switch to active voice? The only passives I can see are for things the system does, for example "Where a time period is flagged as anomalous . . . ". I think "Where the system flags a time period as anomalous . . . " is more clunky, and can get repetitive. I have tried to use consistent terms, but if you spot anything I've missed, please let me know. |
💚 Build Succeeded |
|
Closing as it's probably easier to start from scratch. |
Implements #45645
Adds new docs page "Detecting and inspecting log anomalies" (see http://kibana_49165.docs-preview.app.elstc.co/guide/en/kibana/master/xpack-logs-analysis-page.html), and related linking text near the bottom of the main Logs app page "Using the Logs app" (see http://kibana_49165.docs-preview.app.elstc.co/guide/en/kibana/master/xpack-logs-using.html).