diff options
| author | Joel Hans <joel@netdata.cloud> | 2021-04-29 08:53:02 -0700 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2021-04-29 08:53:02 -0700 |
| commit | bb91989024f8e34056e82be79c02193a6ad94c7f (patch) | |
| tree | eecdcb6b3695350b399573bed62e3b1521046c83 /docs | |
| parent | db60f4928d55628d8a88b0fcf7bcaeb8d02069ce (diff) | |
Improve dashboard documentation (part 1) (#11015)
* Finish initial draft
* Finish with draft of installation flow
* Change analytics path
* Rename file and improve flow
* Init new files
* Init new dashboard files
* Finish initial draft
* Finish with draft of installation flow
* Change analytics path
* Rename file and improve flow
* Init new files
* Init new dashboard files
* Proofreading
* Clarify alarm states
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/dashboard/how-dashboard-works.mdx | 103 | ||||
| -rw-r--r-- | docs/dashboard/interact-charts.mdx | 126 | ||||
| -rw-r--r-- | docs/get-started.mdx | 48 | ||||
| -rw-r--r-- | docs/monitor/view-active-alarms.md | 6 |
4 files changed, 240 insertions, 43 deletions
diff --git a/docs/dashboard/how-dashboard-works.mdx b/docs/dashboard/how-dashboard-works.mdx new file mode 100644 index 0000000000..1c0e2bdd99 --- /dev/null +++ b/docs/dashboard/how-dashboard-works.mdx @@ -0,0 +1,103 @@ +--- +title: "How the dashboard works" +description: "Learn how to navigate Netdata's preconfigured dashboard to get started exploring, visualizing, and troubleshooting in real time." +type: explanation +custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/dashboard/how-dashboard-works.mdx +--- + +# How the dashboard works + +Because Netdata is a monitoring and _troubleshooting_ platform, a dashboard with real-time, meaningful, and +context-aware charts is essential. + +As soon as you [install Netdata](/docs/get-started.mdx), it autodetects hardware, OS, containers, services, and +applications running on your node and builds a dashboard on a single, scrollable webpage. This page features hundreds of +charts, which are preconfigured to save you time from learning a query language, all stacked on top of one another. This +vertical rhythm is designed to encourage exploration and help you visually identify connections between the metrics +visualized in different charts. + +It's essential to understand the core concepts and features of Netdata's dashboard if you want to maximize your Netdata +experience right after installation. + +## Open the dashboard + +Access Netdata's dashboard by navigating to `http://NODE:19999` in your browser, replacing `NODE` with either +`localhost` or the hostname/IP address of a remote node. + + + +Many features of the internal web server that serves the dashboard are [configurable](/web/server/README.md), including +the listen port, enforced TLS, and even disabling the dashboard altogether. + +## Sections and menus + +As mentioned in the introduction, Netdata automatically organizes all the metrics it collects from your node, and places +them into **sections** of closely related charts. + +The first section on any dashboard is the **System Overview**, followed by **CPUs**, **Memory**, and so on. + +These sections populate the **menu**, which is on the right-hand side of the dashboard. Instead of manually scrolling up +and down to explore the dashboard, it's generally faster to click on the relevant menu item to jump to that position on +the dashboard. + +Many menu items also contain a **submenu**, with links to additional categories. For example, the **Disks** section is often separated into multiple groups based on the number of disk drives/partitions on your node, which are also known as a family. + + + +## Charts + +Every **chart** in the Netdata dashboard is [fully interactive](/docs/dashboard/interact-charts.mdx). Netdata +synchronizes your interactions to help you understand exactly how a node behaved in any timeframe, whether that's +seconds or days. + +A chart is an individual, interactive, always-updating graphic displaying one or more collected/calculated metrics, +which are generated by [collectors](/docs/collect/how-collectors-work.md). + + + +Hover over any chart to temporarily pause it and see the exact metrics values presented as different dimensions. Click +or tap to stop the chart from automatically updating with new metrics, thereby locking it to a single timeframe. +Double-click it to resume auto-updating. + +Let's cover two of the most important ways to interact with charts: panning through time and zooming. + +To pan through time, **click and hold** (or touch and hold) on any chart, then **drag your mouse** (or finger) to the +left or right. Drag to the right to pan backward through time, or drag to the left to pan forward in time. Think of it +like pushing the current timeframe off the screen to see what came before or after. + +To zoom, press and hold `Shift`, then use your mouse's scroll wheel, or a two-finger pinch if you're using a touchpad. + +See [interact with charts](/docs/dashboard/interact-charts.mdx) for all the possible ways to interact with the charts on +your dashboard. + +## Alarms + +Many of the preconfigured charts on the Netdata dashboard also come with preconfigured alarms. Netdata sends three +primary alarm states via alarms: `CLEAR`, `WARNING`, and `CRITICAL`. If an alarm moves from a `CLEAR` state to either +`WARNING` or `CRITICAL`, Netdata creates a notification to let you know exactly what's going on. There are [other alarm +states](/health/REFERENCE.md#alarm-statuses) as well. + +The easiest way to see alarms is by clicking on the alarm icon  +in the top panel to open the alarms panel, which shows you all the active alarms. The other **All** tab shows every +active alarm, and the **Log** tab shows a historical record of exactly when alarms triggered and to which state. + + + +Learn more about [viewing active alarms](/docs/monitor/view-active-alarms.md), [configuring +alarms](/docs/monitor/configure-alarms.md), or [enabling a new notification +method](/docs/monitor/enable-notifications.md). + +## What's next? + +Learn more about [interacting with charts](/docs/dashboard/interact-charts.mdx) to quickly pan through time, zoom, and +show/hide dimensions to best understand the state of your node in any timeframe. + +### Further reading & related information + +- [HTTP API](/web/api/README.md) +- [Custom dashboards](/web/gui/custom/README.md) diff --git a/docs/dashboard/interact-charts.mdx b/docs/dashboard/interact-charts.mdx new file mode 100644 index 0000000000..d0a447bd43 --- /dev/null +++ b/docs/dashboard/interact-charts.mdx @@ -0,0 +1,126 @@ +--- +title: "Interact with charts" +description: "Learn how to pan, zoom, select, and customize Netdata's preconfigured charts to help you troubleshooting with real-time, per-second metrics data." +type: how-to +custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/dashboard/interact-charts.mdx +--- + +# Interact with charts + +While charts that update every second with new metrics are helpful for understanding the immediate state of a node, deep +troubleshooting and root cause analysis begins by manipulating the default charts. To help you troubleshoot, Netdata +synchronizes every chart every time you interact with one of them. + +Here's what synchronization looks like: + + + +Once you understand all the interactions available to you, you'll be able to quickly move around the dashboard, search +for anomalies, and find root causes using per-second metrics. + +## Pause or stop + +| Interaction | Keyboard/mouse | Touchpad/touchscreen | +| :---------------- | :------------- | :------------------- | +| **Pause** a chart | `hover` | `n/a` | +| **Stop** a chart | `click` | `tap` | + +By hovering over any chart, you temporarily pause it so that you can hover over a specific timeframe and see the exact +values presented as dimensions. Click on the chart to lock it to this timeframe, which is useful if you want to jump to +a different chart to look for possible correlations. + + + +## Pan + +| Interaction | Keyboard/mouse | Touchpad/touchscreen | +| :---------- | :------------- | :------------------- | +| **Pan** | `click + drag` | `swipe` | + +Drag your mouse/finger to the right to pan backward through time, or drag to the left to pan forward in time. Think of +it like pushing the current timeframe off the screen to see what came before or after. + +## Zoom + +| Interaction | Keyboard/mouse | Touchpad/touchscreen | +| :------------------------------- | :-------------------------- | :--------------------------------------------------- | +| **Zoom** in or out | `Shift + mouse scrollwheel` | `two-finger pinch` <br />`Shift + two-finger scroll` | +| **Zoom** to a specific timeframe | `Shift + mouse selection` | `n/a` | + +Zooming in helps you see metrics with maximum granularity, which is useful when you're trying to diagnose the root cause +of an anomaly or outage. Zooming out lets you see metrics within the larger context, such as the last hour, day, or +week, which is useful in understanding what "normal" looks like, or to identify long-term trends, like a slow creep in +memory usage. + +## Select + +| Interaction | Keyboard/mouse | Touchpad/touchscreen | +| :------------------------------ | :-------------------------------------------------------- | :------------------- | +| **Select** a specific timeframe | `Alt + mouse selection` or `⌘ + mouse selection` (macOS) | `n/a` | + +Selecting timeframes is useful when you see an interesting spike or change in a chart and want to investigate further. + +Select a timeframe, then move to different charts/sections of the dashboard. Each chart shows the same selection to help +you immediately identify the timeframe and look for correlations. + +## Reset a chart to its default state + +| Interaction | Keyboard/mouse | Touchpad/touchscreen | +| :---------------- | :------------- | :------------------- | +| **Reset** a chart | `double-click` | `n/a` | + +Double-check on a chart to restore it to the default auto-updating state, with a timeframe based on your browser +viewport. + +## Resize + +Click-and-drag the icon on the bottom-right corner of any chart. To restore the chart to its original height, +double-click the same icon. + + + +## Show and hide dimensions + +| Interaction | Keyboard/mouse | Touchpad/touchscreen | +| :------------------------------------- | :-------------- | :------------------- | +| **Show one** dimension and hide others | `click` | `tap` | +| **Toggle (show/hide)** one dimension | `Shift + click` | `n/a` | + +Hiding dimensions simplifies the chart and can help you better discover exactly which aspect of your system might be +behaving strangely. + +## See the context + +Hover your mouse over the date that appears just beneath the chart itself. A tooltip will tell you the context for that +chart. Below, the context is `apps.cpu`. + + + +## See the resolution and update frequency + +Hover your mouse over the timestamp just to the right of the date. `resolution` is the number of seconds between each +"tick" in the chart. `collection every` is how often Netdata collects and stores that metric. + +If the `resolution` value is higher than `collection every`, such as `resolution 5 secs, collected every 1 sec`, this +means that each tick is calculating represents the average values across a 5-second period. You can zoom in to increase +the resolution to `resolution 1 sec` to see the exact values. + +## Chart controls + +Many of the above interactions can also be triggered using the icons on the bottom-right corner of every chart. They +are, respectively, `Pan Left`, `Reset`, `Pan Right`, `Zoom In`, and `Zoom Out`. + +## What's next? + +<!-- We recommend you read up on the differences between [charts, contexts, dimensions, and +families](/docs/dashboards/chart-dimensions-contexts-families.mdx) to complete your understanding of how Netdata's +dashboards are organized. --> + +If you feel comfortable with the [dashboard](/docs/dashboard/how-dashboard-works.mdx) and interacting with charts, we +recommend moving on to learning about [configuration](/docs/configure/nodes.md). While Netdata doesn't _require_ a +complicated setup process or a query language to create charts, there are a lot of ways to tweak the experience to match +your needs. diff --git a/docs/get-started.mdx b/docs/get-started.mdx index ccd39d922d..ef1d3f9a66 100644 --- a/docs/get-started.mdx +++ b/docs/get-started.mdx @@ -70,7 +70,8 @@ Copy the script, paste it into your node's terminal, and hit `Enter` to begin th <OneLineInstall /> -Next, [open and explore the dashboard](#open-and-explore-the-dashboard). +Jump down to [what's next](#whats-next) to learn how to view your new dashboard and take your next steps monitoring and +troubleshooting with Netdata. ## Run Netdata with Docker @@ -94,47 +95,17 @@ docker run -d --name=netdata \ netdata/netdata ``` -Next, [open and explore the dashboard](#open-and-explore-the-dashboard). - -## Open and explore the dashboard +## What's next? To start using Netdata, open a browser and navigate to `http://NODE:19999`, replacing `NODE` with either `localhost` or the hostname/IP address of a remote node. - - -Netdata's dashboard is a single page with hundreds of preconfigured charts and thousands of metrics that update every -second. Everything you see is autodetected and organized with zero configuration required. - -To see more charts, scroll down or use the **menu** on the right-hand side of the dashboard to navigate between -**sections**, which are groups of closely related charts. - - - -## Interact with charts - -Every chart in the Netdata dashboard is fully interactive, and Netdata synchronizes your interactions to help you -understand exactly how a node behaved in any timeframe, whether that's seconds or days. - - - -Let's cover two of the most important ways to interact with charts: panning through time and zooming. - -To pan through time, **click and hold** (or touch and hold) on any chart, then **drag your mouse** (or finger) to the -left or right. Dragging to the right pans backward through time, while dragging to the left pans forward in time. Think -of it like pushing the current timeframe off the screen so you can see what came before or after. - -To zoom, press and hold `Shift`, then use your mouse's scroll wheel, or a two-finger pinch if you're using a touchpad. +Where you go from here is based on your use case, immediate needs, and experience with monitoring and troubleshooting. -## What's next? +### Dashboard -You've now installed Netdata, visited the dashboard at `http://NODE:19999`, learned the basics of getting around, and -learned how to interact with charts by zooming and panning through time. - -Where you go from here is based on your use case, immediate needs, and experience with monitoring and troubleshooting. +Learn more about [how the dashboard works](/docs/dashboard/how-dashboard-works.mdx), or dive directly into the many ways +to [interact with charts](/docs/dashboard/interact-charts.mdx). ### Configuration @@ -142,11 +113,6 @@ Discover the recommended way to [configure Netdata's settings or behavior](/docs `edit-config` script, then apply that knowledge to mission-critical tweaks, such as [changing how long Netdata stores metrics](/docs/store/change-metrics-storage.md). -### Dashboard - -Learn even more about [navigating Netdata's dashboard and interacting with -charts](/docs/visualize/interact-dashboards-charts.md). - ### Data collection If Netdata didn't autodetect all the hardware, containers, services, or applications running on your node, you should diff --git a/docs/monitor/view-active-alarms.md b/docs/monitor/view-active-alarms.md index 63ddfdde14..b23e2d7212 100644 --- a/docs/monitor/view-active-alarms.md +++ b/docs/monitor/view-active-alarms.md @@ -37,8 +37,10 @@ Cloud](https://user-images.githubusercontent.com/1153921/108564813-f08d2000-72c0 ## Local Netdata Agent dashboard -Find the bell 🔔 icon in the top navigation to bring up a modal that shows currently raised alarms, all running alarms, -and the alarms log. Here is an example of a raised `system.cpu` alarm, followed by the full list and alarm log: +Find the alarms icon  +in the top navigation to bring up a modal that shows currently raised alarms, all running alarms, and the alarms log. +Here is an example of a raised `system.cpu` alarm, followed by the full list and alarm log:  |