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
Joel Hans committed
Apr 29, 2021 at 08:53 UTC
bb91989024f8e34056e82be79c02193a6ad94c7f
4 files changed
+240
-43
docs/dashboard/how-dashboard-works.mdx
new
+103
@@ -0,0 +1,103 @@
1
+---
2
+title: "How the dashboard works"
3
+description: "Learn how to navigate Netdata's preconfigured dashboard to get started exploring, visualizing, and troubleshooting in real time."
4
+type: explanation
5
+custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/dashboard/how-dashboard-works.mdx
6
+---
7
+
8
+# How the dashboard works
9
+
10
+Because Netdata is a monitoring and _troubleshooting_ platform, a dashboard with real-time, meaningful, and
11
+context-aware charts is essential.
12
+
13
+As soon as you [install Netdata](/docs/get-started.mdx), it autodetects hardware, OS, containers, services, and
14
+applications running on your node and builds a dashboard on a single, scrollable webpage. This page features hundreds of
15
+charts, which are preconfigured to save you time from learning a query language, all stacked on top of one another. This
16
+vertical rhythm is designed to encourage exploration and help you visually identify connections between the metrics
17
+visualized in different charts.
18
+
19
+It's essential to understand the core concepts and features of Netdata's dashboard if you want to maximize your Netdata
20
+experience right after installation.
21
+
22
+## Open the dashboard
23
+
24
+Access Netdata's dashboard by navigating to `http://NODE:19999` in your browser, replacing `NODE` with either
25
+`localhost` or the hostname/IP address of a remote node.
26
+
27
+
29
+
30
+Many features of the internal web server that serves the dashboard are [configurable](/web/server/README.md), including
31
+the listen port, enforced TLS, and even disabling the dashboard altogether.
32
+
33
+## Sections and menus
34
+
35
+As mentioned in the introduction, Netdata automatically organizes all the metrics it collects from your node, and places
36
+them into **sections** of closely related charts.
37
+
38
+The first section on any dashboard is the **System Overview**, followed by **CPUs**, **Memory**, and so on.
39
+
40
+These sections populate the **menu**, which is on the right-hand side of the dashboard. Instead of manually scrolling up
41
+and down to explore the dashboard, it's generally faster to click on the relevant menu item to jump to that position on
42
+the dashboard.
43
+
44
+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.
45
+
46
+
48
+
49
+## Charts
50
+
51
+Every **chart** in the Netdata dashboard is [fully interactive](/docs/dashboard/interact-charts.mdx). Netdata
52
+synchronizes your interactions to help you understand exactly how a node behaved in any timeframe, whether that's
53
+seconds or days.
54
+
55
+A chart is an individual, interactive, always-updating graphic displaying one or more collected/calculated metrics,
56
+which are generated by [collectors](/docs/collect/how-collectors-work.md).
57
+
58
+
60
+
61
+Hover over any chart to temporarily pause it and see the exact metrics values presented as different dimensions. Click
62
+or tap to stop the chart from automatically updating with new metrics, thereby locking it to a single timeframe.
63
+Double-click it to resume auto-updating.
64
+
65
+Let's cover two of the most important ways to interact with charts: panning through time and zooming.
66
+
67
+To pan through time, **click and hold** (or touch and hold) on any chart, then **drag your mouse** (or finger) to the
68
+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
69
+like pushing the current timeframe off the screen to see what came before or after.
70
+
71
+To zoom, press and hold `Shift`, then use your mouse's scroll wheel, or a two-finger pinch if you're using a touchpad.
72
+
73
+See [interact with charts](/docs/dashboard/interact-charts.mdx) for all the possible ways to interact with the charts on
74
+your dashboard.
75
+
76
+## Alarms
77
+
78
+Many of the preconfigured charts on the Netdata dashboard also come with preconfigured alarms. Netdata sends three
79
+primary alarm states via alarms: `CLEAR`, `WARNING`, and `CRITICAL`. If an alarm moves from a `CLEAR` state to either
80
+`WARNING` or `CRITICAL`, Netdata creates a notification to let you know exactly what's going on. There are [other alarm
81
+states](/health/REFERENCE.md#alarm-statuses) as well.
82
+
83
+The easiest way to see alarms is by clicking on the alarm icon 
85
+in the top panel to open the alarms panel, which shows you all the active alarms. The other **All** tab shows every
86
+active alarm, and the **Log** tab shows a historical record of exactly when alarms triggered and to which state.
87
+
88
+
90
+
91
+Learn more about [viewing active alarms](/docs/monitor/view-active-alarms.md), [configuring
92
+alarms](/docs/monitor/configure-alarms.md), or [enabling a new notification
93
+method](/docs/monitor/enable-notifications.md).
94
+
95
+## What's next?
96
+
97
+Learn more about [interacting with charts](/docs/dashboard/interact-charts.mdx) to quickly pan through time, zoom, and
98
+show/hide dimensions to best understand the state of your node in any timeframe.
99
+
100
+### Further reading & related information
101
+
102
+- [HTTP API](/web/api/README.md)
103
+- [Custom dashboards](/web/gui/custom/README.md)
docs/dashboard/interact-charts.mdx
new
+126
@@ -0,0 +1,126 @@
1
+---
2
+title: "Interact with charts"
3
+description: "Learn how to pan, zoom, select, and customize Netdata's preconfigured charts to help you troubleshooting with real-time, per-second metrics data."
4
+type: how-to
5
+custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/dashboard/interact-charts.mdx
6
+---
7
+
8
+# Interact with charts
9
+
10
+While charts that update every second with new metrics are helpful for understanding the immediate state of a node, deep
11
+troubleshooting and root cause analysis begins by manipulating the default charts. To help you troubleshoot, Netdata
12
+synchronizes every chart every time you interact with one of them.
13
+
14
+Here's what synchronization looks like:
15
+
16
+
18
+
19
+Once you understand all the interactions available to you, you'll be able to quickly move around the dashboard, search
20
+for anomalies, and find root causes using per-second metrics.
21
+
22
+## Pause or stop
23
+
24
+| Interaction | Keyboard/mouse | Touchpad/touchscreen |
25
+| :---------------- | :------------- | :------------------- |
26
+| **Pause** a chart | `hover` | `n/a` |
27
+| **Stop** a chart | `click` | `tap` |
28
+
29
+By hovering over any chart, you temporarily pause it so that you can hover over a specific timeframe and see the exact
30
+values presented as dimensions. Click on the chart to lock it to this timeframe, which is useful if you want to jump to
31
+a different chart to look for possible correlations.
32
+
33
+
35
+
36
+## Pan
37
+
38
+| Interaction | Keyboard/mouse | Touchpad/touchscreen |
39
+| :---------- | :------------- | :------------------- |
40
+| **Pan** | `click + drag` | `swipe` |
41
+
42
+Drag your mouse/finger to the right to pan backward through time, or drag to the left to pan forward in time. Think of
43
+it like pushing the current timeframe off the screen to see what came before or after.
44
+
45
+## Zoom
46
+
47
+| Interaction | Keyboard/mouse | Touchpad/touchscreen |
48
+| :------------------------------- | :-------------------------- | :--------------------------------------------------- |
49
+| **Zoom** in or out | `Shift + mouse scrollwheel` | `two-finger pinch` <br />`Shift + two-finger scroll` |
50
+| **Zoom** to a specific timeframe | `Shift + mouse selection` | `n/a` |
51
+
52
+Zooming in helps you see metrics with maximum granularity, which is useful when you're trying to diagnose the root cause
53
+of an anomaly or outage. Zooming out lets you see metrics within the larger context, such as the last hour, day, or
54
+week, which is useful in understanding what "normal" looks like, or to identify long-term trends, like a slow creep in
55
+memory usage.
56
+
57
+## Select
58
+
59
+| Interaction | Keyboard/mouse | Touchpad/touchscreen |
60
+| :------------------------------ | :-------------------------------------------------------- | :------------------- |
61
+| **Select** a specific timeframe | `Alt + mouse selection` or `⌘ + mouse selection` (macOS) | `n/a` |
62
+
63
+Selecting timeframes is useful when you see an interesting spike or change in a chart and want to investigate further.
64
+
65
+Select a timeframe, then move to different charts/sections of the dashboard. Each chart shows the same selection to help
66
+you immediately identify the timeframe and look for correlations.
67
+
68
+## Reset a chart to its default state
69
+
70
+| Interaction | Keyboard/mouse | Touchpad/touchscreen |
71
+| :---------------- | :------------- | :------------------- |
72
+| **Reset** a chart | `double-click` | `n/a` |
73
+
74
+Double-check on a chart to restore it to the default auto-updating state, with a timeframe based on your browser
75
+viewport.
76
+
77
+## Resize
78
+
79
+Click-and-drag the icon on the bottom-right corner of any chart. To restore the chart to its original height,
80
+double-click the same icon.
81
+
82
+
84
+
85
+## Show and hide dimensions
86
+
87
+| Interaction | Keyboard/mouse | Touchpad/touchscreen |
88
+| :------------------------------------- | :-------------- | :------------------- |
89
+| **Show one** dimension and hide others | `click` | `tap` |
90
+| **Toggle (show/hide)** one dimension | `Shift + click` | `n/a` |
91
+
92
+Hiding dimensions simplifies the chart and can help you better discover exactly which aspect of your system might be
93
+behaving strangely.
94
+
95
+## See the context
96
+
97
+Hover your mouse over the date that appears just beneath the chart itself. A tooltip will tell you the context for that
98
+chart. Below, the context is `apps.cpu`.
99
+
100
+
102
+
103
+## See the resolution and update frequency
104
+
105
+Hover your mouse over the timestamp just to the right of the date. `resolution` is the number of seconds between each
106
+"tick" in the chart. `collection every` is how often Netdata collects and stores that metric.
107
+
108
+If the `resolution` value is higher than `collection every`, such as `resolution 5 secs, collected every 1 sec`, this
109
+means that each tick is calculating represents the average values across a 5-second period. You can zoom in to increase
110
+the resolution to `resolution 1 sec` to see the exact values.
111
+
112
+## Chart controls
113
+
114
+Many of the above interactions can also be triggered using the icons on the bottom-right corner of every chart. They
115
+are, respectively, `Pan Left`, `Reset`, `Pan Right`, `Zoom In`, and `Zoom Out`.
116
+
117
+## What's next?
118
+
119
+<!-- We recommend you read up on the differences between [charts, contexts, dimensions, and
120
+families](/docs/dashboards/chart-dimensions-contexts-families.mdx) to complete your understanding of how Netdata's
121
+dashboards are organized. -->
122
+
123
+If you feel comfortable with the [dashboard](/docs/dashboard/how-dashboard-works.mdx) and interacting with charts, we
124
+recommend moving on to learning about [configuration](/docs/configure/nodes.md). While Netdata doesn't _require_ a
125
+complicated setup process or a query language to create charts, there are a lot of ways to tweak the experience to match
126
+your needs.
docs/get-started.mdx
+7
-41
@@ -70,7 +70,8 @@ Copy the script, paste it into your node's terminal, and hit `Enter` to begin th
70
71
<OneLineInstall />
72
73
-Next, [open and explore the dashboard](#open-and-explore-the-dashboard).
73
+Jump down to [what's next](#whats-next) to learn how to view your new dashboard and take your next steps monitoring and
74
+troubleshooting with Netdata.
75
76
## Run Netdata with Docker
77
@@ -94,47 +95,17 @@ docker run -d --name=netdata \
95
netdata/netdata
96
```
97
97
-Next, [open and explore the dashboard](#open-and-explore-the-dashboard).
98
-
99
-## Open and explore the dashboard
98
+## What's next?
99
100
To start using Netdata, open a browser and navigate to `http://NODE:19999`, replacing `NODE` with either `localhost` or
101
the hostname/IP address of a remote node.
102
104
-
106
-
107
-Netdata's dashboard is a single page with hundreds of preconfigured charts and thousands of metrics that update every
108
-second. Everything you see is autodetected and organized with zero configuration required.
109
-
110
-To see more charts, scroll down or use the **menu** on the right-hand side of the dashboard to navigate between
111
-**sections**, which are groups of closely related charts.
112
-
113
-
115
-
116
-## Interact with charts
117
-
118
-Every chart in the Netdata dashboard is fully interactive, and Netdata synchronizes your interactions to help you
119
-understand exactly how a node behaved in any timeframe, whether that's seconds or days.
120
-
121
-
123
-
124
-Let's cover two of the most important ways to interact with charts: panning through time and zooming.
125
-
126
-To pan through time, **click and hold** (or touch and hold) on any chart, then **drag your mouse** (or finger) to the
127
-left or right. Dragging to the right pans backward through time, while dragging to the left pans forward in time. Think
128
-of it like pushing the current timeframe off the screen so you can see what came before or after.
129
-
130
-To zoom, press and hold `Shift`, then use your mouse's scroll wheel, or a two-finger pinch if you're using a touchpad.
103
+Where you go from here is based on your use case, immediate needs, and experience with monitoring and troubleshooting.
104
132
-## What's next?
105
+### Dashboard
106
134
-You've now installed Netdata, visited the dashboard at `http://NODE:19999`, learned the basics of getting around, and
135
-learned how to interact with charts by zooming and panning through time.
136
-
137
-Where you go from here is based on your use case, immediate needs, and experience with monitoring and troubleshooting.
107
+Learn more about [how the dashboard works](/docs/dashboard/how-dashboard-works.mdx), or dive directly into the many ways
108
+to [interact with charts](/docs/dashboard/interact-charts.mdx).
109
110
### Configuration
111
@@ -142,11 +113,6 @@ Discover the recommended way to [configure Netdata's settings or behavior](/docs
113
`edit-config` script, then apply that knowledge to mission-critical tweaks, such as [changing how long Netdata stores
114
metrics](/docs/store/change-metrics-storage.md).
115
145
-### Dashboard
146
-
147
-Learn even more about [navigating Netdata's dashboard and interacting with
148
-charts](/docs/visualize/interact-dashboards-charts.md).
149
-
116
### Data collection
117
118
If Netdata didn't autodetect all the hardware, containers, services, or applications running on your node, you should
docs/monitor/view-active-alarms.md
+4
-2
@@ -37,8 +37,10 @@ Cloud](https://user-images.githubusercontent.com/1153921/108564813-f08d2000-72c0
37
38
## Local Netdata Agent dashboard
39
40
-Find the bell 🔔 icon in the top navigation to bring up a modal that shows currently raised alarms, all running alarms,
41
-and the alarms log. Here is an example of a raised `system.cpu` alarm, followed by the full list and alarm log:
40
+Find the alarms icon 
42
+in the top navigation to bring up a modal that shows currently raised alarms, all running alarms, and the alarms log.
43
+Here is an example of a raised `system.cpu` alarm, followed by the full list and alarm log:
44
45
