Improve dashboard documentation (part 2) (#11065)
* Finish initial draft * Finish with draft of installation flow * Change analytics path * Rename file and improve flow * Init new files * Init new dashboard files * Init new file * Finish revising existing docs * Finish initial draft * Finish with draft of installation flow * Change analytics path * Rename file and improve flow * Init new file * Finish revising existing docs * Fix link * Tweak on contexts for Thiago * Clarify dimension values and units * Tweaks for Ilya
Joel Hans committed
May 5, 2021 at 10:17 UTC
4a87b0f92e891aa52062c2f488df0c33cf2942e8
5 files changed
+182
-7
docs/dashboard/dimensions-contexts-families.mdx
new
+92
@@ -0,0 +1,92 @@
1
+---
2
+title: "Chart dimensions, contexts, and families"
3
+description: "Netdata organizes charts into dimensions, contexts, and families to automatically and meaningfully organize thousands of metrics into interactive charts."
4
+type: explanation
5
+custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/dashboard/dimensions-contexts-families.mdx
6
+---
7
+
8
+# Chart dimensions, contexts, and families
9
+
10
+While Netdata's charts require no configuration and are [easy to interact with](/docs/dashboards/interact-charts.mdx),
11
+they have a lot of underlying complexity. To meaningfully organize charts out of the box based on what's happening in
12
+your nodes, Netdata uses the concepts of **dimensions**, **contexts**, and **families**.
13
+
14
+Understanding how these work will help you more easily navigate the dashboard, [write new
15
+alarms](/docs/monitor/configure-alars.md), or play around with the [API](/web/api/README.md).
16
+
17
+For a refresher on the anatomy of a chart, see [dashboards and charts](/docs/dashboards/dashboards-charts.mdx).
18
+
19
+## Dimension
20
+
21
+A **dimension** is a value that gets shown on a chart. The value can be raw data or calculated values, such as the
22
+average (the default), minimum, or maximum. These values can then be given any type of unit. For example, CPU
23
+utilization is represented as a percentage, disk I/O as `MiB/s`, and available RAM as an absolute value in `MiB` or
24
+`GiB`.
25
+
26
+Beneath every chart (or on the right-side if you [configure the
27
+dashboard](/docs/dashboards/customize.mdx#change-chart-legend-position)) is a legend of dimensions. When there are
28
+multiple dimensions, you'll see a different entry in the legend for each dimension.
29
+
30
+The **Apps CPU Time** chart (with the [context](#contexts) `apps.cpu`), which visualizes CPU utilization of
31
+different types of processes/services/applications on your node, always provides a vibrant example of a chart with
32
+multiple dimensions.
33
+
34
+
36
+
37
+The chart shows 13 unique dimensions, such as `httpd` for the CPU utilization for web servers, `kernel` for anything
38
+related to the Linux kernel, and so on. In your dashboard, these specific dimensions will almost certainly be different.
39
+
40
+Dimensions can be [hidden](/docs/dashboards/interact-charts.mdx#show-and-hide-dimensions) to help you focus your
41
+attention.
42
+
43
+## Context
44
+
45
+A **context** is a way of grouping charts by the types of metrics collected and dimensions displayed. It's kind of like
46
+a machine-readable naming and organization scheme.
47
+
48
+For example, the **Apps CPU Time** has the context `apps.cpu`. A little further down on the dashboard is a similar
49
+chart, **Apps Real Memory (w/o shared)** with the context `apps.mem`. The `apps` portion of the context is the **type**,
50
+whereas anything after the `.` is specified either by the chart's developer or by the [**family**](#family).
51
+
52
+By default, a chart's type affects where it fits in the menu, while its family creates submenus.
53
+
54
+Netdata also relies on contexts for [alarm configuration](/docs/monitor/configure-alarms.md) (the [`on`
55
+line](/health/REFERENCE.md#alarm-line-on)).
56
+
57
+## Family
58
+
59
+**Families** are a _single instance_ of a hardware or software resource that needs to be displayed separately from
60
+similar instances.
61
+
62
+For example, let's look at the **Disks** section, which contains a number of charts with contexts like `disk.io`,
63
+`disk.ops`, `disk.backlog`, and `disk.util`. If your node has multiple disk drives at `sda` and `sdb`, Netdata creates
64
+a separate family for each.
65
+
66
+Netdata now merges the contexts and families to create charts that are grouped by family, following a
67
+`[context].[family]` naming scheme, so that you can see the `disk.io` and `disk.ops` charts for `sda` right next to each
68
+other.
69
+
70
+Given the four example contexts, and two families of `sda` and `sdb`, Netdata will create the following charts and their
71
+names:
72
+
73
+| Context | `sda` family | `sdb` family |
74
+| :------------- | ------------------ | ------------------ |
75
+| `disk.io` | `disk_io.sda` | `disk_io.sdb` |
76
+| `disk.ops` | `disk_ops.sda` | `disk_ops.sdb` |
77
+| `disk.backlog` | `disk_backlog.sda` | `disk_backlog.sdb` |
78
+| `disk.util` | `disk_util.sda` | `disk_util.sdb` |
79
+
80
+## What's next?
81
+
82
+With an understanding of a chart's dimensions, context, and family, you're now ready to dig even deeper into Netdata's
83
+dashboard. We recommend looking into [using the timeframe selector](/docs/dashboards/select-timeframes.mdx).
84
+
85
+If you feel comfortable with the [dashboard](/docs/dashboard/how-dashboard-works.mdx) and interacting with charts, we
86
+recommend learning about [configuration](/docs/configure/nodes.md). While Netdata doesn't _require_ a complicated setup
87
+process or a query language to create charts, there are a lot of ways to tweak the experience to match your needs.
88
+
89
+### Further reading & related information
90
+
91
+- [How the dashboard works](/docs/dashboard/how-dashboard-works.mx)
92
+- [Interact with charts](/docs/dashboard/interact-charts.mdx)
docs/dashboard/how-dashboard-works.mdx
+3
-1
@@ -95,7 +95,9 @@ method](/docs/monitor/enable-notifications.md).
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.
98
+show/hide dimensions to best understand the state of your node in any timeframe. A complete understanding of [chart
99
+dimensions, contexts, and families](/docs/dashboard/dimensions-contexts-families.mdx) will also help with how Netdata
100
+organizes its dashboard and operates [alarms](/docs/monitor/configure-alarms.md).
101
102
### Further reading & related information
103
docs/dashboard/interact-charts.mdx
+4
-3
@@ -116,9 +116,10 @@ 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. -->
119
+We recommend you read up on the differences between [chart dimensions, contexts, and
120
+families](/docs/dashboard/dimensions-contexts-families.mdx) to complete your understanding of how Netdata organizes its
121
+dashboards. Another valuable way to interact with charts is to use the [timeframe
122
+selector](/docs/dashboard/select-timeframes.mdx), which helps you visualize specific moments of historical metrics.
123
124
If you feel comfortable with the [dashboard](/docs/dashboard/how-dashboard-works.mdx) and interacting with charts, we
125
recommend moving on to learning about [configuration](/docs/configure/nodes.md). While Netdata doesn't _require_ a
docs/dashboard/select-timeframes.mdx
new
+79
@@ -0,0 +1,79 @@
1
+---
2
+title: "Select timeframes to visualize"
3
+description: "Netdata's dashboard features a rich timeframe selector, with useful defaults and rich customization, to help you narrow your focus when troubleshooting issues or anomalies."
4
+type: how-to
5
+custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/dashboard/select-timeframes.mdx
6
+---
7
+
8
+# Pick timeframes to visualize
9
+
10
+While [panning through time and zooming in/out](/docs/dashboard/interact-charts.mdx) from charts is helpful when
11
+you're looking a recent history, or want to do granular troubleshooting, what if you want to see metrics from 6 hours
12
+ago? Or 6 days?
13
+
14
+Netdata's dashboard features a **timeframe selector** to help you visualize specific timeframes in a few helpful ways.
15
+By default, it shows a certain number of minutes of historical metrics based on the your browser's viewport to ensure
16
+it's always showing per-second granularity.
17
+
18
+## Open the timeframe selector
19
+
20
+To visualize a new timeframe, you need to open the picker, which appears just above the menu, near the top-right cover
21
+of the dashboard.
22
+
23
+
25
+
26
+The **Clear** button resets the dashboard back to its default state based on your browser viewport, and **Apply** closes
27
+the picker and shifts all charts to the selected timeframe.
28
+
29
+## Use the Quick Selector
30
+
31
+Click any of the following options in the **Quick Selector** to choose a commonly-used timeframe.
32
+
33
+- Last 5 minutes
34
+- Last 15 minutes
35
+- Last 2 hours
36
+- Last 6 hours
37
+- Last 12 hours
38
+
39
+Click **Apply** to see metrics from your selected timeframe.
40
+
41
+## Choose a specific interval
42
+
43
+Beneath the Quick Selector is an input field and dropdown you use in combination to select a specific timeframe of
44
+minutes, hours, days, or months. Enter a number and choose the appropriate unit of time, then click **Apply**.
45
+
46
+## Choose multiple days
47
+
48
+Use the calendar to select multiple days. Click on a date to begin the timeframe selection, then an ending date. The
49
+timeframe begins at noon on the beginning and end dates. Click **Apply** to see your selected multi-day timeframe.
50
+
51
+## Caveats and considerations
52
+
53
+**Longer timeframes will decrease metrics granularity**. At the default timeframe, based on your browser viewport, each
54
+"tick" on charts represents one second. If you select a timeframe of 6 hours, each tick represents the _average_ value
55
+across a larger period of time.
56
+
57
+**You can only see metrics as far back in history as your metrics retention policy allows**. Netdata uses an internal
58
+time-series database (TSDB) to store as many metrics as it can within a specific amount of disk space. The default
59
+storage is 256 MiB, which should be enough for 1-3 days of historical metrics. If you navigate back to a timeframe
60
+beyond stored historical metrics, you'll see this message:
61
+
62
+
64
+
65
+At any time, [configure the internal TSDB's storage capacity](/docs/store/change-metrics-storage.md) to expand your
66
+depth of historical metrics.
67
+
68
+## What's next?
69
+
70
+<!-- We recommend you dive deeper into some additional dashboard features, such as [import/exporting
71
+snapshots](/docs/dashboards/import-export-snapshots.mdx) or
72
+[customization](/docs/dashboards/customize-standard-dashboard.mdx). -->
73
+
74
+
75
+
76
+### Further reading & related information
77
+
78
+- [Interact with charts](/docs/dashboards/interact-charts.mdx)
79
+- [Database engine reference](/database/engine/README.md)
docs/store/change-metrics-storage.md
+4
-3
@@ -60,9 +60,10 @@ method](/docs/configure/start-stop-restart.md) for your system, to change the da
60
61
## What's next?
62
63
-If you have multiple nodes with the Netdata Agent installed, you can [stream metrics](/docs/store/stream-metrics.md)
64
-from any number of _child_ nodes to a _parent_ node and store metrics using a centralized time-series database.Streaming
65
-allows you to centralize your data, run Agents as headless collectors, replicate data, and more.
63
+If you have multiple nodes with the Netdata Agent installed, you can [stream
64
+metrics](/docs/metrics-storage-management/how-streaming-works.mdx) from any number of _child_ nodes to a _parent_ node
65
+and store metrics using a centralized time-series database. Streaming allows you to centralize your data, run Agents as
66
+headless collectors, replicate data, and more.
67
68
Storing metrics with the database engine is completely interoperable with [exporting to other time-series
69
databases](/docs/export/external-databases.md). With exporting, you can use the node's resources to surface metrics