Add high level explanation of dashboard contents (#6648)
* Moved content about charts/families/contexts to web * Working on dashboard docs * Working on dashboard docs * Improvements to charts, families, contexts * Working more on dashboard overview * More improvements to web dashboards docs * Fixing broken links * More fixes to the dashboard areas * Grammar check on revised docs * Fixing broken table * Addressing Chris' comments * Addressing Cosmix's comments plus a few additions * Fixing lint issues * Fixing linter errors and re-adding lost links * Addressing Cosmix' requests * Fixing context issue
Joel Hans committed
Sep 4, 2019 at 17:04 UTC
89e71c474c865da29415b68b03795221721c72de
7 files changed
+659
-266
daemon/config/README.md
+1
-1
@@ -143,6 +143,6 @@ External plugins that need additional configuration may support a dedicated file
143
144
### Per chart configuration
145
146
-In this section you will find a separate subsection for each chart shown on the dashboard. You can control all aspects of a specific chart here. You can understand what each option does by reading [how charts are defined](../../collectors/plugins.d/#chart). If you don't know how to find the name of a chart, you can learn about it [here](../../docs/Charts.md).
146
+In this section you will find a separate subsection for each chart shown on the dashboard. You can control all aspects of a specific chart here. You can understand what each option does by reading [how charts are defined](../../collectors/plugins.d/#chart). If you don't know how to find the name of a chart, you can learn about it [here](../../web/README.md#charts-contexts-families).
147
148
[](<>)
docs/Charts.md
deleted
-27
@@ -1,27 +0,0 @@
1
-# Charts, contexts, families
2
-
3
-Before configuring an alarm or writing a collector, it's important to understand how Netdata organizes collected metrics into charts.
4
-
5
-## Charts
6
-
7
-Each chart that you see on the Netdata dashboard contains one or more dimensions, one for each collected or calculated metric.
8
-
9
-The chart name or chart id is what you see in parentheses at the top left corner of the chart you are interested in. For example, if you go to the system cpu chart: `http://your.netdata.ip:19999/#menu_system_submenu_cpu`, you will see at the top left of the chart the label "Total CPU utilization (system.cpu)". In this case, the chart name is `system.cpu`.
10
-
11
-## Dimensions
12
-
13
-Most charts depict more than one dimensions. The dimensions of a chart are called "series" in some applications. You can see these dimensions on the right side of a chart, right under the date and time. For the system.cpu example we used, you will see the dimensions softirq, irq, user etc. Note that these are not always simple metrics (raw data). They could be calculated values (percentages, aggregates and more).
14
-
15
-## Families
16
-
17
-When you have several instances of a monitored hardware or software resource (e.g. network interfaces, mysql instances etc.), you need to be able to identify each one separately. Netdata uses "families" to identify such instances. For example, if I have the network interfaces `eth0` and `eth1`, `eth0` will be one family, and `eth1` will be another.
18
-
19
-The reasoning behind calling these instances "families" is that different charts for the same instance can and many times are related (relatives, family, you get it). The family of a chart is usually the name of the Netdata dashboard submenu that you see selected on the right navigation pane, when you are looking at a chart. For the example of the two network interfaces, you would see a submenu `eth0` and a submenu `eth1` under the "Network Interfaces" menu on the right navigation pane.
20
-
21
-## Contexts
22
-
23
-A context is a grouping of identical charts, for each instance of the hardware or software monitored. For example, `health/health.d/net.conf` refers to four contexts: `net.drops`, `net.fifo`, `net.net`, `net.packets`. You can see the context of a chart if you hover over the date right above the dimensions of the chart. The line that appears shows you two things: the collector that produces the chart and the chart context.
24
-
25
-For example, let's take the `net.packets` context. You will see on the dashboard as many charts with context net.packets as you have network interfaces (families). These charts will be named `net_packets.[family]`. For the example of the two interfaces `eth0` and `eth1`, you will see charts named `net_packets.eth0` and `net_packets.eth1`. Both of these charts show the exact same dimensions, but for different instances of a network interface.
26
-
27
-[](<>)
docs/generator/buildyaml.sh
+3
-4
@@ -154,7 +154,6 @@ echo -ne " - 'docs/what-is-netdata.md'
154
- 'daemon/README.md'
155
- 'docs/configuration-guide.md'
156
- 'daemon/config/README.md'
157
- - 'docs/Charts.md'
157
"
158
navpart 2 web/server "" "Web server"
159
navpart 3 web/server "" "" 2 excludefirstlevel
@@ -182,6 +181,9 @@ echo -ne "
181
- 'docs/netdata-cloud/nodes-view.md'
182
"
183
184
+navpart 1 web "README" "Dashboards"
185
+navpart 2 web/gui "" "" 3
186
+
187
navpart 1 collectors "" "Data collection" 1
188
echo -ne " - 'docs/Add-more-charts-to-netdata.md'
189
- Internal plugins:
@@ -261,9 +263,6 @@ navpart 1 streaming "" "" 4
263
264
navpart 1 backends "" "Archiving to backends" 3
265
264
-navpart 1 web "README" "Dashboards"
265
-navpart 2 web/gui "" "" 3
266
-
266
navpart 1 web/api "" "HTTP API"
267
navpart 2 web/api/exporters "" "Exporters" 2
268
navpart 2 web/api/formatters "" "Formatters" 2
health/README.md
+4
-3
@@ -144,7 +144,7 @@ This is useful when you centralize metrics from multiple hosts, to one Netdata.
144
This line is only used in alarm templates. It filters the charts. So, if you need to create
145
an alarm template for a few of a kind of chart (a few of your disks, or a few of your network
146
interfaces, or a few your mysql servers, etc), you can create an alarm template that would
147
-normally be applied to all of them, and filter them by [family](../docs/Charts.md#families).
147
+normally be applied to all of them, and filter them by [family](../web/README.md#families).
148
149
The format is:
150
@@ -446,12 +446,13 @@ You can find all the variables that can be used for a given chart, using
446
`http://your.netdata.ip:19999/api/v1/alarm_variables?chart=CHART_NAME`
447
Example: [variables for the `system.cpu` chart of the registry](https://registry.my-netdata.io/api/v1/alarm_variables?chart=system.cpu).
448
449
-_Hint: If you don't know how to find the CHART_NAME, you can read about it [here](../docs/Charts.md#charts)._
449
+_Hint: If you don't know how to find the CHART_NAME, you can read about it [here](../web/README.md#charts)._
450
451
Netdata supports 3 internal indexes for variables that will be used in health monitoring.
452
453
<details markdown="1"><summary>The variables below can be used in both chart alarms and context templates.</summary>
454
-Although the `alarm_variables` link shows you variables for a particular chart, the same variables can also be used in templates for charts belonging to the same [context](../docs/Charts.md#contexts). The reason is that all charts of a given contexts are essentially identical, with the only difference being the [family](../docs/Charts.md#families) that identifies a particular hardware or software instance. Charts and templates do not apply to specific families anyway, unless if you explicitly limit an alarm with the [alarm line `families`](#alarm-line-families).
454
+
455
+Although the `alarm_variables` link shows you variables for a particular chart, the same variables can also be used in templates for charts belonging to a given [context](../web/README.md#contexts). The reason is that all charts of a given context are essentially identical, with the only difference being the [family](../web/README.md#families) that identifies a particular hardware or software instance. Charts and templates do not apply to specific families anyway, unless if you explicitly limit an alarm with the [alarm line `families`](#alarm-line-families).
456
</details>
457
458
- **chart local variables**. All the dimensions of the chart are exposed as local variables. The value of $this for the other configured alarms of the chart also appears, under the name of each configured alarm.
web/README.md
+214
-14
@@ -1,28 +1,228 @@
1
# Web dashboards overview
2
3
-The default port is 19999; for example, to access the dashboard on localhost, use: <http://localhost:19999>
3
+Because Netdata is a health monitoring and _performance troubleshooting_ system,
4
+we put a lot of emphasis on real-time, meaningful, and context-aware charts.
5
5
-To view Netdata collected data you access its **[REST API v1](api/)**.
6
+We bundle Netdata with a dashboard and hundreds of charts, designed by both our
7
+team and the community, but you can also customize them yourself.
8
7
-For our convenience, Netdata provides 2 more layers:
9
+There are two primary ways to view Netdata's dashboards:
10
9
-1. The `dashboard.js` javascript library that allows us to design custom dashboards using plain HTML. For information on creating custom dashboards, see **[Custom Dashboards](gui/custom/)** and **[Atlassian Confluence Dashboards](gui/confluence/)**
11
+1. The [standard web dashboard](gui/) that comes pre-configured with every
12
+ Netdata installation. You can see it at `http://SERVER-IP:19999`, or
13
+ `http://localhost:19999` on `localhost`. You can customize the contents and
14
+ colors of the standard dashboard [using
15
+ JavaScript](gui/#customizing-the-standard-dashboard).
16
11
-2. Ready to be used web dashboards that render all the charts a Netdata server maintains.
17
+2. The [`dashboard.js` JavaScript library](#dashboardjs), which helps you
18
+ [customize the standard dashboards](gui/#customizing-the-standard-dashboard)
19
+ using JavaScript, or create entirely new [custom dashboards](gui/custom/) or
20
+ [Atlassian Confluence dashboards](gui/confluence/).
21
13
-## Customizing the standard dashboards
22
+You can also view all the data Netdata collects through the [REST API v1](api/).
23
15
-Charts information is stored at /usr/share/netdata/web/[dashboard_info.js](gui/dashboard_info.js). This file includes information that is rendered on the dashboard, controls chart colors, section and subsection heading, titles, etc.
24
+No matter where you use Netdata's charts, you'll want to know how to
25
+[use](#using-charts) them. You'll also want to understand how Netdata defines
26
+[charts](#charts), [dimensions](#dimensions), [families](#families), and
27
+[contexts](#contexts).
28
17
-If you change that file, your changes will be overwritten when Netdata is updated. You can preserve your settings by creating a new such file (there is /usr/share/netdata/web/[dashboard_info_custom_example.js](gui/dashboard_info_custom_example.js) you can use to start with).
29
+## Using charts
30
19
-You have to copy the example file under a new name, so that it will not be overwritten with Netdata updates.
31
+Netdata's charts are far from static. They are interactive, real-time, and work
32
+with your mouse, touchpad, or touchscreen!
33
21
-To configure your info file set in `netdata.conf`:
34
+Hover over any chart to temporarily pause it and see the exact values presented
35
+as different [dimensions](#dimensions). Click or tap stop the chart from automatically updating with new metrics, thereby locking it to a single timeframe.
36
37
+
39
+
40
+You can change how charts show their metrics by zooming in or out, moving
41
+forward or backward in time, or selecting a specific timeframe for more in-depth
42
+analysis.
43
+
44
+Whenever you use a chart in this way, Netdata synchronizes all the other charts
45
+to match it. Chart synchronization even works between separate Netdata agents if you connect
46
+them using the [node menu](../registry)!
47
+
48
+You can change how charts show their metrics in a few different ways, each of
49
+which have a few methods:
50
+
51
+| Manipulation | Method #1 | Method #2 | Method #3 |
52
+|--- |--- |--- |--- |
53
+| **Reset** charts to default auto-refreshing state | `double click` | `double tap` (touchpad/touchscreen) | |
54
+| **Select** a certain timeframe | `ALT` + `mouse selection` | `⌘` + `mouse selection` (macOS) | |
55
+| **Pan** forward or back in time | `click and drag` | `touch and drag` (touchpad/touchscreen) | |
56
+| **Zoom** to a specific timeframe | `SHIFT` + `mouse selection` | | |
57
+| **Zoom** in/out | `SHIFT`/`ALT` + `mouse scrollwheel` | `SHIFT`/`ALT` + `two-finger pinch` (touchpad/touchscreen) | `SHIFT`/`ALT` + `two-finger scroll` (touchpad/touchscreen) |
58
+
59
+Here's how chart synchronization looks while zooming and panning:
60
+
61
+
64
+
65
+You can also perform all these actions using the small
66
+rewind/play/fast-forward/zoom-in/zoom-out buttons that appear in the
67
+bottom-right corner of each chart.
68
+
69
+## Charts, contexts, families
70
+
71
+Before customizing the standard web dashboard, creating a custom dashboard,
72
+configuring an alarm, or writing a collector, it's crucial to understand how
73
+Netdata organizes metrics into charts, dimensions, families, and contexts.
74
+
75
+### Charts
76
+
77
+A **chart** is an individual, interactive, always-updating graphic displaying
78
+one or more collected/calculated metrics. Charts are generated by
79
+[collectors](../collectors/).
80
+
81
+Here's the system CPU chart, the first chart displayed on the standard
82
+dashboard:
83
+
84
+
86
+
87
+Netdata displays a chart's name in parentheses above the chart. For example, if
88
+you navigate to the system CPU chart, you'll see the label: **Total CPU
89
+utilization (system.cpu)**. In this case, the chart's name is `system.cpu`.
90
+Netdata derives the name from the chart's [context](#contexts).
91
+
92
+### Dimensions
93
+
94
+A **dimension** is a value that gets shown on a chart. The value can be raw data
95
+or calculated values, such as percentages, aggregates, and more.
96
+
97
+Charts are capable of showing more than one dimension. Netdata shows these
98
+dimensions on the right side of the chart, beneath the date and time. Again, the
99
+`system.cpu` chart will serve as a good example.
100
+
101
+
103
+
104
+Here, the `system.cpu` chart is showing many dimensions, such as `user`,
105
+`system`, `softirq`, `irq`, and more.
106
+
107
+Note that other applications sometimes use the word _series_ instead of
108
+_dimension_.
109
+
110
+### Families
111
+
112
+A **family** is _one_ instance of a monitored hardware or software resource that
113
+needs to be monitored and displayed separately from similar instances.
114
+
115
+For example, if your system has multiple disk drives at `sda` and `sdb`, Netdata
116
+will put each interface into their own family. Same goes for software resources,
117
+like multiple MySQL instances. We call these instances "families" because the
118
+charts associated with a single disk instance, for example, are often related to
119
+each other. Relatives, family... get it?
120
+
121
+When relevant, Netdata prefers to organize charts by family. When you visit the
122
+**Disks** section, you will see your disk drives organized into families, and
123
+each family will have one or more charts: `disk`, `disk_ops`, `disk_backlog`,
124
+`disk_util`, `disk_await`, `disk_avgsz`, `disk_svctm`, `disk_mops`, and
125
+`disk_iotime`.
126
+
127
+In the screenshot below, the disk family `sdb` shows a few gauges, followed by a
128
+few of the associated charts:
129
+
130
+
132
+
133
+Netdata also creates separate submenu entries for each family in the right
134
+navigation page so you can easily navigate to the instance you're interested in.
135
+Here, Netdata has made several submenus under the **Disk** menu.
136
+
137
+
139
+
140
+### Contexts
141
+
142
+A **context** is a way of grouping charts by the types of metrics collected and
143
+dimensions displayed. Different charts with the same context will show the same
144
+dimensions, but for different instances (families) of hardware/software
145
+resources.
146
+
147
+For example, the **Disks** section will often use many contexts (`disk.io`,
148
+`disk.ops`, `disk.backlog`, `disk.util`, and so on). Netdata then creates an
149
+individual chart for each context, and groups them by family.
150
+
151
+Netdata names charts according to their context according to the following
152
+structure: `[context].[family]`. A chart with the `disk.util` context, in the
153
+`sdb` family, gets the name `disk_util.sdb`. Netdata shows that name in the
154
+top-left corner of a chart.
155
+
156
+Given the four example contexts, and two families of `sdb` and `sdd`, Netdata
157
+will create the following charts and their names:
158
+
159
+Context | `sdb` family | `sdd` family
160
+--- | --- | ---
161
+`disk.io` | `disk_io.sdb` | `disk_io.sdd`
162
+`disk.ops` | `disk_ops.sdb` | `disk_ops.sdd`
163
+`disk.backlog` | `disk_backlog.sdb` | `disk_backlog.sdd`
164
+`disk.util` | `disk_util.sdb` | `disk_util.sdd`
165
+
166
+And here's what two of those charts in the `disk.io` context look like under
167
+`sdb` and `sdd` families:
168
+
169
+
170
+
171
+
172
+As you can see in the screenshot, you can view the context of a chart if you
173
+hover over the date above the list of dimensions. A tooltip will appear that
174
+shows you two pieces of information: the collector that produces the chart, and
175
+the chart's context.
176
+
177
+Netdata also uses [contexts for alarm
178
+templates](../health/#alarm-line-on). You can create an
179
+alarm for the `net.packets` context to receive alerts for any chart with that
180
+context, no matter which family it's attached to.
181
+
182
+## Positive and negative values on charts
183
+
184
+To improve clarity on charts, Netdata dashboards present **positive** values for
185
+metrics representing `read`, `input`, `inbound`, `received` and **negative**
186
+values for metrics representing `write`, `output`, `outbound`, `sent`.
187
+
188
+
189
+
190
+_Netdata charts showing the bandwidth and packets of a network interface.
191
+`received` is positive and `sent` is negative._
192
+
193
+## Autoscaled y-axis
194
+
195
+Netdata charts automatically zoom vertically, to visualize the variation of each
196
+metric within the visible timeframe.
197
+
198
+
199
+
200
+_A zero-based `stacked` chart, automatically switches to an auto-scaled `area`
201
+chart when a single dimension is selected._
202
+
203
+## dashboard.js
204
+
205
+Netdata uses the `dashboards.js` file to define, configure, create, and update
206
+all the charts and other visualizations that appear on any Netdata dashboard.
207
+You need to put `dashboard.js` on any HTML page that's going to render Netdata
208
+charts.
209
+
210
+The [custom dashboards documentation](gui/custom/) contains examples of such
211
+custom HTML pages.
212
+
213
+### Generating dashboard.js
214
+
215
+We build the `dashboards.js` file by concatenating all the source files located
216
+in the `web/gui/src/dashboard.js/` directory. That's done using the provided
217
+build script:
218
+
219
+```sh
220
+cd web/gui
221
+make
222
```
24
-[web]
25
- custom dashboard_info.js = your_file_name.js
26
-```
223
28
-[](<>)
224
+If you make any changes to the `src` directory when developing Netdata, you
225
+should regenerate the `dashboard.js` file before you commit to the Netdata
226
+repository.
227
+
228
+[]()
web/gui/README.md
+124
-83
@@ -1,118 +1,159 @@
1
-# Netdata agent web GUI
1
+# The standard web dashboard
2
3
-## Generating dashboard.js
3
+The standard web dashboard is the heart of Netdata's performance troubleshooting
4
+toolkit. You've probably seen it before:
5
5
-The monolithic `dashboards.js` file is automatically generated by concatenating the source files located in the `web/gui/src/dashboard.js/` directory by running the build script:
6
+
8
7
-```sh
8
-cd web/gui
9
-make
10
-```
9
+Learn more about how dashboards work and how they're populated using the
10
+`dashboards.js` file in our [web dashboards overview](../README.md).
11
12
-After every change in the `src` directory, the `dashboard.js` file should be regenerated and commited to the repository.
12
+By default, Netdata starts a web server for its dashboard at port `19999`. Open
13
+up your web browser of choice and navigate to `http://SERVER-IP:19999`, or
14
+`http://localhost:19999` on `localhost`.
15
14
-## Custom Dashboards
16
+Netdata uses an [internal, static-threaded web server](../server/) to host the
17
+HTML, CSS, and JavaScript files that make up the standard dashboard. You don't
18
+have to configure anything to access it, although you can adjust [your
19
+settings](../server/#other-netdataconf-web-section-options) in the
20
+`netdata.conf` file, or run Netdata behind an Nginx proxy, and so on.
21
16
-For information on creating custom dashboards, see **[Custom Dashboards](custom/)** and **[Atlassian Confluence Dashboards](confluence/)**
22
+## Navigating the standard dashboard
23
18
-## Supported chart libraries
24
+Beyond charts, the standard dashboard can be broken down into three key areas:
25
20
-- Dygraph
21
-- jQuery Sparkline
22
-- Peity
23
-- Google Charts
24
-- Morris
25
-- EasyPieChart
26
-- Gauge.js
27
-- D3
28
-- C3
26
+1. [**Sections**](#sections)
27
+2. [**Menus/submenus**](#menus)
28
+3. [**Nodes menu**](#nodes-menu)
29
30
-### Dygraph
30
+
32
32
-#### Settings
33
+### Sections
34
34
-[Example settings here](https://github.com/netdata/netdata/blob/e91f00d99f4965e985981b93fa46ef33f94dd726/web/dashboard.js#L3793)
35
+Netdata is broken up into multiple **sections**, such as **System Overview**,
36
+**CPU**, **Disk**, and more. Inside each section you'll find a number of charts,
37
+broken down into [contexts](../README.md#contexts) and
38
+[families](../README.md#families).
39
36
-#### Value Range
40
+An example of the **Memory** section on a Linux desktop system.
41
38
-You can set the min and max values of the y-axis using `data-dygraph-valuerange="[MIN, MAX]"`
42
+
44
40
-### EasyPieChart
45
+All sections and their associated charts appear on a single "page," so all you
46
+need to do to view different sections is scroll up and down the page. But it's
47
+usually quicker to use the [menus](#menus).
48
42
-#### Settings
49
+### Menus
50
44
-TBD
51
+**Menus** appears on the right-hand side of the standard dashboard. Netdata
52
+generates a menu for each section, and menus link to the section they're
53
+associated with.
54
46
-#### Value Range
55
+
57
48
-You can set the max value of the chart using the following snippet:
58
+Most menu items will contain several **submenu** entries, which represent any
59
+[families](../README.md#families) from that section. Netdata automatically
60
+generates these submenu entries.
61
50
-```html
51
-<div data-netdata="unique.id"
52
- data-chart-library="easypiechart"
53
- data-easypiechart-max-value="40"
54
- ></div>
55
-```
62
+Here's a **Disks** menu with several submenu entries for each disk drive and
63
+partition Netdata recognizes.
64
57
-Be aware that values that exceed the max value will get expanded (e.g. "41" is still 100%). Similar for the minimum:
65
+
67
59
-```html
60
-<div data-netdata="unique.id"
61
- data-chart-library="easypiechart"
62
- data-easypiechart-min-value="20"
63
- ></div>
64
-```
68
+### Nodes menu
69
+
70
+The nodes menu appears in the top-left corner of the standard dashboard and is
71
+labeled with the hostname of the system Netdata is monitoring.
72
+
73
+Clicking on it will display a drop-down menu of any nodes you might have
74
+connected via the [Netdata registry](../../registry/). By default, you'll find
75
+nothing under the **My nodes** heading, but you can try out any of the demo
76
+Netdata nodes to see how the nodes menu works.
77
+
78
+
80
+
81
+Once you add nodes via [Netdata Cloud](../../docs/netdata-cloud/) or a [private
82
+registry](../../registry/#run-your-own-registry), you will see them appear under
83
+the **My nodes** heading.
84
+
85
+
87
+
88
+The nodes menu will also show the master netdata node and all slave nodes
89
+streaming to that master, if you have [configured streaming](../../streaming).
90
66
-If you specify both minimum and maximum, the rendering behavior changes. Instead of displaying the `value` based from zero, it is now based on the range that is provided by the snippet:
91
+
93
68
-```html
69
-<div data-netdata="unique.id"
70
- data-chart-library="easypiechart"
71
- data-easypiechart-min-value="20"
72
- data-easypiechart-max-value="40"
73
- ></div>
94
+## Customizing the standard dashboard
95
+
96
+Netdata stores information about individual charts in the `dashboard_info.js`
97
+file. This file includes section and subsection headings, descriptions, colors,
98
+titles, tooltips, and other information for Netdata to render on the dashboard.
99
+
100
+For example, here is how `dashboard_info.js` defines the **System Overview**
101
+section.
102
+
103
+```javascript
104
+netdataDashboard.menu = {
105
+ 'system': {
106
+ title: 'System Overview',
107
+ icon: '<i class="fas fa-bookmark"></i>',
108
+ info: 'Overview of the key system metrics.'
109
+ },
110
```
111
76
-In the first example, a value of `30`, without specifying the minimum, fills the chart bar to `75%` (100% / 40 \* 30). However, in this example the range is now `20` (40 - 20 = 20). The value `30` will fill the chart to **`50%`**, since it's in the middle between 20 and 40.
112
+If you want to customize this information, you should avoid editing
113
+`dashboard_info.js` directly. These changes are not persistent; Netdata will
114
+overwrite the file when it's updated. Instead, you should create a new file with
115
+your customizations.
116
78
-This szenario is useful if you have metrics that change only within a specific range, e.g. temperatures that are very unlikely to fall out of range. In these cases it is more useful to have the chart render the values between the given min and max, to better highlight the changes within them.
117
+We created an example file at
118
+[`dashboard_info_custom_example.js`](dashboard_info_custom_example.js). You can
119
+copy this to a new file with a name of your choice in the `web/` directory. This
120
+directory changes based on your operating system and installation method. If
121
+you're on a Linux system, it should be at `/usr/share/netdata/web/`.
122
80
-#### Negative Values
123
+```shell
124
+cd /usr/share/netdata/web/
125
+sudo cp dashboard_info_custom_example.js your_dashboard_info_file.js
126
+```
127
82
-EasyPieCharts can render negative values with the following flag:
128
+Edit the file with your customizations. For example:
129
84
-```html
85
-<div data-netdata="unique.id"
86
- data-chart-library="easypiechart"
87
- data-override-options="signed"
88
- ></div>
130
+```javascript
131
+customDashboard.menu = {
132
+ 'system': {
133
+ title: 'Testing, testing, 1 2 3',
134
+ icon: '<i class="fas fa-thumbs-up"></i>',
135
+ info: 'This is overwritten info for the system overview section!'
136
+ },
137
+};
138
```
139
91
-Negative values are rendered counter-clockwise.
92
-
93
-#### Full example
94
-
95
-This is a chart that displays the hotwater temperature in the given range of 40 to 50.
96
-
97
-```html
98
-<div data-netdata="stiebeleltron_system.hotwater.hotwatertemp"
99
- data-title="Hot Water Temperature"
100
- data-decimal-digits="1"
101
- data-chart-library="easypiechart"
102
- data-colors="#FE3912"
103
- data-width="55%"
104
- data-height="50%"
105
- data-points="1200"
106
- data-after="-1200"
107
- data-dimensions="actual"
108
- data-units="°C"
109
- data-easypiechart-max-value="50"
110
- data-easypiechart-min-value="40"
111
- data-common-max="netdata-hotwater-max"
112
- data-common-min="netdata-hotwater-min"
113
-></div>
140
+Finally, tell Netdata where you placed your customization file by replacing
141
+`your_dashboard_info_file.js` below.
142
+
143
+```conf
144
+[web]
145
+ custom dashboard_info.js = your_dashboard_info_file.js
146
```
147
116
-
148
+Once you restart Netdata, refresh the dashboard to find your custom
149
+configuration:
150
+
151
+
153
+
154
+## Custom dashboards
155
+
156
+For information on creating custom dashboards from scratch, see the [custom
157
+dashboards](custom/) or [Atlassian Confluence dashboards](confluence/) guides.
158
159
[](<>)
web/gui/custom/README.md
+313
-134
@@ -2,18 +2,24 @@
2
3
You can:
4
5
-- create your own dashboards using simple HTML (no javascript is required for basic dashboards)
5
+- create your own dashboards using simple HTML (no javascript is required for
6
+ basic dashboards)
7
- utilizing any or all of the available chart libraries, on the same dashboard
8
- using data from one or more Netdata servers, on the same dashboard
9
- host your dashboard HTML page on any web server, anywhere
10
10
-Netdata charts can also be added to existing web pages.
11
+You can also add Netdata charts to existing web pages.
12
12
-Check this **[very simple working example of a custom dashboard](http://netdata.firehol.org/demo.html)**, and its **[html source](../demo.html)**.
13
+Check this **[very simple working example of a custom
14
+dashboard](http://netdata.firehol.org/demo.html)**, and its **[html
15
+source](../demo.html)**.
16
14
-You should also look at the **[custom dashboard template](https://my-netdata.io/dashboard.html)**, that contains samples of all supported charts. The code is [here](../dashboard.html).
17
+You should also look at the [custom dashboard
18
+template](https://my-netdata.io/dashboard.html), which contains samples of all
19
+supported charts. The code is [here](../dashboard.html).
20
16
-If you plan to put the dashboard on TV, check **[tv.html](../tv.html)**. This is a screenshot of it, monitoring 2 servers on the same page:
21
+If you plan to put the dashboard on TV, check out [tv.html](../tv.html). Here's
22
+is a screenshot of it, monitoring two servers on the same page:
23
24
25
@@ -21,27 +27,32 @@ If you plan to put the dashboard on TV, check **[tv.html](../tv.html)**. This is
27
28
## Web directory
29
24
-All of the mentioned examples are available on your local Netdata installation (e.g. `http://myhost:19999/dashboard.html`). The default web root directory with the HTML and JS code is `/usr/share/netdata/web`. The main dashboard is also in that directory and called `index.html`.\
25
-Note: index.html has a different syntax. Don't use it as a template for simple custom dashboards.
30
+All of the mentioned examples are available on your local Netdata installation
31
+(e.g. `http://myhost:19999/dashboard.html`). The default web root directory with
32
+the HTML and JS code is `/usr/share/netdata/web`. The main dashboard is also in
33
+that directory and called `index.html`.\
34
+Note: index.html has a different syntax. Don't use it as a template for simple
35
+custom dashboards.
36
37
## Example empty dashboard
38
29
-If you need to create a new dashboard on an empty page, we suggest the following header:
39
+If you need to create a new dashboard on an empty page, we suggest the following
40
+header:
41
42
```html
43
<!DOCTYPE html>
44
<html lang="en">
45
<head>
35
- <title>Your dashboard</title>
46
+ <title>Your dashboard</title>
47
37
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
38
- <meta charset="utf-8">
39
- <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
40
- <meta name="viewport" content="width=device-width, initial-scale=1">
41
- <meta name="apple-mobile-web-app-capable" content="yes">
42
- <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
48
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
49
+ <meta charset="utf-8">
50
+ <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
51
+ <meta name="viewport" content="width=device-width, initial-scale=1">
52
+ <meta name="apple-mobile-web-app-capable" content="yes">
53
+ <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
54
44
- <!-- here we will add dashboard.js -->
55
+ <!-- here we will add dashboard.js -->
56
57
</head>
58
<body>
@@ -107,73 +118,88 @@ To change the display order of your hosts, which is saved in localStorage, click
118
119
## dashboard.js
120
110
-To add Netdata charts to any web page (dedicated to Netdata or not), you need to include the `/dashboard.js` file of a Netdata server.
121
+To add Netdata charts to any web page (dedicated to Netdata or not), you need to
122
+include the `/dashboard.js` file of a Netdata server.
123
112
-For example, if your Netdata server listens at `http://box:19999/`, you will need to add the following to the `head` section of your web page:
124
+For example, if your Netdata server listens at `http://box:19999/`, you will
125
+need to add the following to the `head` section of your web page:
126
127
```html
128
<script type="text/javascript" src="http://box:19999/dashboard.js"></script>
129
```
130
118
-### what dashboard.js does?
131
+### What does dashboard.js do?
132
133
`dashboard.js` will automatically load the following:
134
135
1. `dashboard.css`, required for the Netdata charts
136
124
-2. `jquery.min.js`, (only if jquery is not already loaded for this web page)
137
+2. `jquery.min.js`, (only if jQuery is not already loaded for this web page)
138
126
-3. `bootstrap.min.js` (only if bootstrap is not already loaded) and `bootstrap.min.css`.
139
+3. `bootstrap.min.js` (only if Bootstrap is not already loaded) and
140
+ `bootstrap.min.css`.
141
128
- You can disable this by adding the following before loading `dashboard.js`:
142
+ You can disable this by adding the following before loading `dashboard.js`:
143
144
```html
145
<script>var netdataNoBootstrap = true;</script>
146
```
147
134
-4. `jquery.nanoscroller.min.js`, required for the scrollbar of the chart legends.
148
+4. `jquery.nanoscroller.min.js`, required for the scrollbar of the chart
149
+ legends.
150
136
-5. `bootstrap-toggle.min.js` and `bootstrap-toggle.min.css`, required for the settings toggle buttons.
151
+5. `bootstrap-toggle.min.js` and `bootstrap-toggle.min.css`, required for the
152
+ settings toggle buttons.
153
154
6. `font-awesome.min.css`, for icons.
155
140
-When `dashboard.js` loads will scan the page for elements that define charts (see below) and immediately start refreshing them. Keep in mind more javascript modules may be loaded (every chart library is a different javascript file, that is loaded on first use).
156
+When `dashboard.js` loads will scan the page for elements that define charts
157
+(see below) and immediately start refreshing them. Keep in mind more javascript
158
+modules may be loaded (every chart library is a different javascript file, that
159
+is loaded on first use).
160
161
### Prevent dashboard.js from starting chart refreshes
162
144
-If your web page is not static and you plan to add charts using javascript, you can tell `dashboard.js` not to start processing charts immediately after loaded, by adding this fragment before loading it:
163
+If your web page is not static and you plan to add charts using JavaScript, you
164
+can tell `dashboard.js` not to start processing charts immediately after loaded,
165
+by adding this fragment before loading it:
166
167
```html
168
<script>var netdataDontStart = true;</script>
148
-```
169
+`"
170
171
The above, will inform the `dashboard.js` to load everything, but not process the web page until you tell it to.
172
You can tell it to start processing the page, by running this javascript code:
173
174
```js
175
NETDATA.start();
155
-```
176
+`"
177
157
-Be careful not to call the `NETDATA.start()` multiple times. Each call to this function will spawn a new thread that will start refreshing the charts.
178
+Be careful not to call the `NETDATA.start()` multiple times. Each call to this
179
+function will spawn a new thread that will start refreshing the charts.
180
159
-If, after calling `NETDATA.start()` you need to update the page (or even get your javascript code synchronized with `dashboard.js`), you can call (after you loaded `dashboard.js`):
181
+If, after calling `NETDATA.start()` you need to update the page (or even get
182
+your javascript code synchronized with `dashboard.js`), you can call (after you
183
+loaded `dashboard.js`):
184
185
```js
186
NETDATA.pause(function() {
163
- // ok, it is paused
187
+ // ok, it is paused
188
165
- // update the DOM as you wish
189
+ // update the DOM as you wish
190
167
- // and then call this to let the charts refresh:
168
- NETDATA.unpause();
191
+ // and then call this to let the charts refresh:
192
+ NETDATA.unpause();
193
});
194
```
195
196
### The default Netdata server
197
174
-`dashboard.js` will attempt to auto-detect the URL of the Netdata server it is loaded from, and set this server as the default Netdata server for all charts.
198
+`dashboard.js` will attempt to auto-detect the URL of the Netdata server it is
199
+loaded from, and set this server as the default Netdata server for all charts.
200
176
-If you need to set any other URL as the default Netdata server for all charts that do not specify a Netdata server, add this before loading `dashboard.js`:
201
+If you need to set any other URL as the default Netdata server for all charts
202
+that do not specify a Netdata server, add this before loading `dashboard.js`:
203
204
```html
205
<script type="text/javascript">var netdataServer = "http://your.netdata.server:19999";</script>
@@ -183,11 +209,15 @@ If you need to set any other URL as the default Netdata server for all charts th
209
210
## Adding charts
211
186
-To add charts, you need to add a `div` for each of them. Each of these `div` elements accept a few `data-` attributes:
212
+To add charts, you need to add a `div` for each of them. Each of these `div`
213
+elements accept a few `data-` attributes:
214
215
### The chart unique ID
216
190
-The unique ID of a chart is shown at the title of the chart of the default Netdata dashboard. You can also find all the charts available at your Netdata server with this URL: `http://your.netdata.server:19999/api/v1/charts` ([example](http://netdata.firehol.org/api/v1/charts)).
217
+The unique ID of a chart is shown at the title of the chart of the default
218
+Netdata dashboard. You can also find all the charts available at your Netdata
219
+server with this URL: `http://your.netdata.server:19999/api/v1/charts`
220
+([example](http://netdata.firehol.org/api/v1/charts)).
221
222
To specify the unique id, use this:
223
@@ -195,26 +225,34 @@ To specify the unique id, use this:
225
<div data-netdata="unique.id"></div>
226
```
227
198
-The above is enough for adding a chart. It most probably have the wrong visual settings though. Keep reading...
228
+The above is enough for adding a chart. It most probably have the wrong visual
229
+settings though. Keep reading...
230
231
### The duration of the chart
232
202
-You can specify the duration of the chart (how much time of data it will show) using:
233
+You can specify the duration of the chart (how much time of data it will show)
234
+using:
235
236
```html
237
<div data-netdata="unique.id"
206
- data-after="AFTER_SECONDS"
207
- data-before="BEFORE_SECONDS"
208
- ></div>
238
+ data-after="AFTER_SECONDS"
239
+ data-before="BEFORE_SECONDS"
240
+ ></div>
241
```
242
211
-`AFTER_SECONDS` and `BEFORE_SECONDS` are numbers representing a time-frame in seconds.
243
+`AFTER_SECONDS` and `BEFORE_SECONDS` are numbers representing a time-frame in
244
+seconds.
245
246
The can be either:
247
215
-- **absolute** unix timestamps (in javascript terms, they are `new Date().getTime() / 1000`. Using absolute timestamps you can have a chart showing always the same time-frame.
248
+- **absolute** unix timestamps (in javascript terms, they are `new
249
+ Date().getTime() / 1000`. Using absolute timestamps you can have a chart
250
+ showing always the same time-frame.
251
217
-- **relative** number of seconds to now. To show the last 10 minutes of data, `AFTER_SECONDS` must be `-600` (relative to now) and `BEFORE_SECONDS` must be `0` (meaning: now). If you want the chart to auto-refresh the current values, you need to specify **relative** values.
252
+- **relative** number of seconds to now. To show the last 10 minutes of data,
253
+ `AFTER_SECONDS` must be `-600` (relative to now) and `BEFORE_SECONDS` must
254
+ be `0` (meaning: now). If you want the chart to auto-refresh the current
255
+ values, you need to specify **relative** values.
256
257
### Chart sizes
258
@@ -222,122 +260,160 @@ You can set the size of the chart using this:
260
261
```html
262
<div data-netdata="unique.id"
225
- data-width="WIDTH"
226
- data-height="HEIGHT"
227
- ></div>
263
+ data-width="WIDTH"
264
+ data-height="HEIGHT"
265
+ ></div>
266
```
267
230
-`WIDTH` and `HEIGHT` can be anything CSS accepts for width and height (e.g. percentages, pixels, etc).
231
-Keep in mind that for certain chart libraries, `dashboard.js` may apply an aspect ratio to these.
268
+`WIDTH` and `HEIGHT` can be anything CSS accepts for width and height (e.g.
269
+percentages, pixels, etc). Keep in mind that for certain chart libraries,
270
+`dashboard.js` may apply an aspect ratio to these.
271
233
-If you want `dashboard.js` to remember permanently (browser local storage) the dimensions of the chart (the user may resize it), you can add: `data-id="SETTINGS_ID"`, where `SETTINGS_ID` is anything that will be common for this chart across user sessions.
272
+If you want `dashboard.js` to permanently remember (browser local storage) the
273
+dimensions of the chart (the user may resize it), you can add: `data-id="
274
+SETTINGS_ID"`, where `SETTINGS_ID` is anything that will be common for this
275
+chart across user sessions.
276
277
### Netdata server
278
237
-Each chart can get data from a different Netdata server. You can give per chart the Netdata server using:
279
+Each chart can get data from a different Netdata server. You can specify the Netdata server to use for each chart using:
280
281
```html
282
<div data-netdata="unique.id"
241
- data-host="http://another.netdata.server:19999/"
242
- ></div>
283
+ data-host="http://another.netdata.server:19999/"
284
+ ></div>
285
```
286
245
-If you have ephemeral monitoring setup ([More info here](../../../streaming/#monitoring-ephemeral-nodes)) and have no direct access to the nodes dashboards, you can use the following:
287
+If you have ephemeral monitoring setup ([More info
288
+here](../../../streaming/#monitoring-ephemeral-nodes)) and have no direct access
289
+to the nodes dashboards, you can use the following:
290
291
```html
292
<div data-netdata="unique.id"
249
- data-host="http://yournetdata.server:19999/host/reported-hostname"
250
- ></div>
293
+ data-host="http://yournetdata.server:19999/host/reported-hostname"
294
+ ></div>
295
```
296
297
### Chart library
298
255
-The default chart library is `dygraph`. You set a different chart library per chart using this:
299
+Netdata supports a number of chart libraries. The default chart library is
300
+`dygraph`, but you can set a different chart library per chart using
301
+`data-chart-library`:
302
303
```html
304
<div data-netdata="unique.id"
259
- data-chart-library="gauge"
260
- ></div>
305
+ data-chart-library="gauge"
306
+ ></div>
307
```
308
263
-Each chart library may support more chart-library specific settings. Please refer to the documentation of the chart library you are interested, in this wiki or the source code:
309
+Each chart library has a number of specific settings. To learn more about them,
310
+you should investigate the documentation of the given chart library, or visit
311
+the appropriate JavaScript file that defines the library's options. These files
312
+are concatenated into the monolithin `dashboard.js` for deployment.
313
265
-- options `data-dygraph-XXX` [here](https://github.com/netdata/netdata/blob/643cfe20a8d8beba0ed31ec6afaade80853fd310/web/dashboard.js#L6251-L6361)
266
-- options `data-easypiechart-XXX` [here](https://github.com/netdata/netdata/blob/643cfe20a8d8beba0ed31ec6afaade80853fd310/web/dashboard.js#L7954-L7966)
267
-- options `data-gauge-XXX` [here](https://github.com/netdata/netdata/blob/643cfe20a8d8beba0ed31ec6afaade80853fd310/web/dashboard.js#L8182-L8189)
268
-- options `data-d3pie-XXX` [here](https://github.com/netdata/netdata/blob/643cfe20a8d8beba0ed31ec6afaade80853fd310/web/dashboard.js#L7394-L7561)
269
-- options `data-sparkline-XXX` [here](https://github.com/netdata/netdata/blob/643cfe20a8d8beba0ed31ec6afaade80853fd310/web/dashboard.js#L5940-L5985)
270
-- options `data-peity-XXX` [here](https://github.com/netdata/netdata/blob/643cfe20a8d8beba0ed31ec6afaade80853fd310/web/dashboard.js#L5892)
314
+- [Dygraph](https://github.com/netdata/netdata/blob/5b57fc441c40959514c4e2d0863be2e6a417e352/web/gui/dashboard.js#L2034)
315
+- [d3](https://github.com/netdata/netdata/blob/5b57fc441c40959514c4e2d0863be2e6a417e352/web/gui/dashboard.js#L4095)
316
+- [d3pie](https://github.com/netdata/netdata/blob/5b57fc441c40959514c4e2d0863be2e6a417e352/web/gui/dashboard.js#L3753)
317
+- [Gauge.js](https://github.com/netdata/netdata/blob/5b57fc441c40959514c4e2d0863be2e6a417e352/web/gui/dashboard.js#L3065)
318
+- [Google Charts](https://github.com/netdata/netdata/blob/5b57fc441c40959514c4e2d0863be2e6a417e352/web/gui/dashboard.js#L2936)
319
+- [EasyPieChart](https://github.com/netdata/netdata/blob/5b57fc441c40959514c4e2d0863be2e6a417e352/web/gui/dashboard.js#L3531)
320
+- [Peity](https://github.com/netdata/netdata/blob/5b57fc441c40959514c4e2d0863be2e6a417e352/web/gui/dashboard.js#L4137)
321
+- [Sparkline](https://github.com/netdata/netdata/blob/5b57fc441c40959514c4e2d0863be2e6a417e352/web/gui/dashboard.js#L2779)
322
+- [Text-only](https://github.com/netdata/netdata/blob/5b57fc441c40959514c4e2d0863be2e6a417e352/web/gui/dashboard.js#L4200)
323
324
### Data points
325
274
-For the time-frame requested, `dashboard.js` will use the chart dimensions and the settings of the chart library to find out how many data points it can show.
326
+For the time-frame requested, `dashboard.js` will use the chart dimensions and
327
+the settings of the chart library to find out how many data points it can show.
328
276
-For example, most line chart libraries are using 3 pixels per data point. If the chart shows 10 minutes of data (600 seconds), its update frequency is 1 second, and the chart width is 1800 pixels, then `dashboard.js` will request from the Netdata server: 10 minutes of data, represented in 600 points, and the chart will be refreshed per second. If the user resizes the window so that the chart becomes 600 pixels wide, then `dashboard.js` will request the same 10 minutes of data, represented in 200 points and the chart will be refreshed once every 3 seconds.
329
+For example, most line chart libraries are using 3 pixels per data point. If the
330
+chart shows 10 minutes of data (600 seconds), its update frequency is 1 second,
331
+and the chart width is 1800 pixels, then `dashboard.js` will request from the
332
+Netdata server: 10 minutes of data, represented in 600 points, and the chart
333
+will be refreshed per second. If the user resizes the window so that the chart
334
+becomes 600 pixels wide, then `dashboard.js` will request the same 10 minutes of
335
+data, represented in 200 points and the chart will be refreshed once every 3
336
+seconds.
337
278
-If you need to have a fixed number of points in the data source retrieved from the Netdata server, you can set:
338
+If you need the chart to show a fixed number of points, you can set the `data-points` option. Replace `DATA_POINTS` with the number of points you need:
339
340
```html
341
<div data-netdata="unique.id"
282
- data-points="DATA_POINTS"
283
- ></div>
342
+ data-points="DATA_POINTS"
343
+ ></div>
344
```
345
286
-Where `DATA_POINTS` is the number of points you need.
287
-
346
You can also overwrite the pixels-per-point per chart using this:
347
348
```html
349
<div data-netdata="unique.id"
292
- data-pixels-per-point="PIXELS_PER_POINT"
293
- ></div>
350
+ data-pixels-per-point="PIXELS_PER_POINT"
351
+ ></div>
352
```
353
354
Where `PIXELS_PER_POINT` is the number of pixels each data point should occupy.
355
356
### Data grouping method
357
300
-Netdata supports **average** (the default), **sum** and **max** grouping methods. The grouping method is used when the Netdata server is requested to return fewer points for a time-frame, compared to the number of points available.
358
+Netdata supports **average** (the default), **sum** and **max** grouping
359
+methods. The grouping method is used when the Netdata server is requested to
360
+return fewer points for a time-frame, compared to the number of points
361
+available.
362
363
You can give it per chart, using:
364
365
```html
366
<div data-netdata="unique.id"
306
- data-method="max"
307
- ></div>
367
+ data-method="max"
368
+ ></div>
369
```
370
371
### Changing rates
372
312
-Netdata can change the rate of charts on the fly. So a charts that shows values **per second** can be turned to **per minute** (or any other, e.g. **per 10 seconds**), with this:
373
+Netdata can change the rate of charts on the fly. So a charts that shows values
374
+**per second** can be turned to **per minute** (or any other, e.g. **per 10
375
+seconds**), with this:
376
377
```html
378
<div data-netdata="unique.id"
316
- data-method="average"
317
- data-gtime="60"
318
- data-units="per minute"
319
- ></div>
379
+ data-method="average"
380
+ data-gtime="60"
381
+ data-units="per minute"
382
+ ></div>
383
```
384
322
-The above will provide the average rate per minute (60 seconds).
323
-Use 60 for `/minute`, 3600 for `/hour`, 86400 for `/day` (provided you have that many data).
385
+The above will provide the average rate per minute (60 seconds). Use 60 for
386
+`/minute`, 3600 for `/hour`, 86400 for `/day` (provided you have that many
387
+data).
388
325
-- The `data-gtime` setting does not change the units of the chart. You have to change them yourself with `data-units`.
389
+- The `data-gtime` setting does not change the units of the chart. You have to
390
+ change them yourself with `data-units`.
391
- This works only for `data-method="average"`.
327
-- Netdata may aggregate multiple points to satisfy the `data-points` setting. For example, you request `per minute` but the requested number of points to be returned are not enough to report every single minute. In this case Netdata will sum the `per second` raw data of the database to find the `per minute` for every single minute and then **average** them to find the **average per minute rate of every X minutes**. So, it works as if the data collection frequency was per minute.
392
+- Netdata may aggregate multiple points to satisfy the `data-points` setting.
393
+ For example, you request `per minute` but the requested number of points to
394
+ be returned are not enough to report every single minute. In this case
395
+ Netdata will sum the `per second` raw data of the database to find the `per
396
+ minute` for every single minute and then **average** them to find the
397
+ **average per minute rate of every X minutes**. So, it works as if the data
398
+ collection frequency was per minute.
399
400
### Selecting dimensions
401
331
-By default, `dashboard.js` will show all the dimensions of the chart.
332
-You can select specific dimensions using this:
402
+By default, `dashboard.js` will show all the dimensions of the chart. You can
403
+select specific dimensions using this:
404
405
```html
406
<div data-netdata="unique.id"
336
- data-dimensions="dimension1,dimension2,dimension3,..."
337
- ></div>
407
+ data-dimensions="dimension1,dimension2,dimension3,..."
408
+ ></div>
409
```
410
340
-Netdata supports coma (`,`) or pipe (`|`) separated [simple patterns](../../../libnetdata/simple_pattern/) for dimensions. By default it searches for both dimension IDs and dimension NAMEs. You can control the target of the match with: `data-append-options="match-ids"` or `data-append-options="match-names"`. Spaces in `data-dimensions=""` are matched in the dimension names and IDs.
411
+Netdata supports coma (`,`) or pipe (`|`) separated [simple
412
+patterns](../../../libnetdata/simple_pattern/) for dimensions. By default it
413
+searches for both dimension IDs and dimension NAMEs. You can control the target
414
+of the match with: `data-append-options="match-ids"` or
415
+`data-append-options="match-names"`. Spaces in `data-dimensions=""` are matched
416
+in the dimension names and IDs.
417
418
### Chart title
419
@@ -345,40 +421,44 @@ You can overwrite the title of the chart using this:
421
422
```html
423
<div data-netdata="unique.id"
348
- data-title="my super chart"
349
- ></div>
424
+ data-title="my super chart"
425
+ ></div>
426
```
427
428
### Chart units
429
354
-You can overwrite the units of measurement of the dimensions of the chart, using this:
430
+You can overwrite the units of measurement of the dimensions of the chart, using
431
+this:
432
433
```html
434
<div data-netdata="unique.id"
358
- data-units="words/second"
359
- ></div>
435
+ data-units="words/second"
436
+ ></div>
437
```
438
439
### Chart colors
440
364
-`dashboard.js` has an internal palette of colors for the dimensions of the charts.
365
-You can prepend colors to it (so that your will be used first) using this:
441
+`dashboard.js` has an internal palette of colors for the dimensions of the
442
+charts. You can prepend colors to it (so that your will be used first) using
443
+this:
444
445
```html
446
<div data-netdata="unique.id"
369
- data-colors="#AABBCC #DDEEFF ..."
370
- ></div>
447
+ data-colors="#AABBCC #DDEEFF ..."
448
+ ></div>
449
```
450
451
### Extracting dimension values
452
375
-`dashboard.js` can update the selected values of the chart at elements you specify. For example, let's assume we have a chart that measures the bandwidth of eth0, with 2 dimensions `in` and `out`. You can use this:
453
+`dashboard.js` can update the selected values of the chart at elements you
454
+specify. For example, let's assume we have a chart that measures the bandwidth
455
+of eth0, with 2 dimensions `in` and `out`. You can use this:
456
457
```html
458
<div data-netdata="net.eth0"
379
- data-show-value-of-in-at="eth0_in_value"
380
- data-show-value-of-out-at="eth0_out_value"
381
- ></div>
459
+ data-show-value-of-in-at="eth0_in_value"
460
+ data-show-value-of-out-at="eth0_out_value"
461
+ ></div>
462
463
My eth0 interface, is receiving <span id="eth0_in_value"></span>
464
and transmitting <span id="eth0_out_value"></span>.
@@ -386,12 +466,13 @@ and transmitting <span id="eth0_out_value"></span>.
466
467
### Hiding the legend of a chart
468
389
-On charts that by default have a legend managed by `dashboard.js` you can remove it, using this:
469
+On charts that by default have a legend managed by `dashboard.js` you can remove
470
+it, using this:
471
472
```html
473
<div data-netdata="unique.id"
393
- data-legend="no"
394
- ></div>
474
+ data-legend="no"
475
+ ></div>
476
```
477
478
### API options
@@ -400,69 +481,167 @@ You can append Netdata **[REST API v1](../../api)** data options, using this:
481
482
```html
483
<div data-netdata="unique.id"
403
- data-append-options="absolute,percentage"
404
- ></div>
484
+ data-append-options="absolute,percentage"
485
+ ></div>
486
```
487
488
A few useful options are:
489
409
-- `absolute` to show all values are absolute (i.e. turn negative dimensions to positive)
410
-- `percentage` to express the values as a percentage of the chart total (so, the values of the dimensions are added, and the sum of them if expressed as a percentage of the sum of all dimensions)
411
-- `unaligned` to prevent Netdata from aligning the charts (e.g. when requesting 60 seconds aggregation per point, Netdata returns chart data aligned to XX:XX:00 to XX:XX:59 - similarly for hours, days, etc - the `unaligned` option disables this feature)
412
-- `match-ids` or `match-names` is used to control what `data-dimensions=` will match.
490
+- `absolute` to show all values are absolute (i.e. turn negative dimensions to
491
+ positive)
492
+- `percentage` to express the values as a percentage of the chart total (so,
493
+ the values of the dimensions are added, and the sum of them if expressed as
494
+ a percentage of the sum of all dimensions)
495
+- `unaligned` to prevent Netdata from aligning the charts (e.g. when
496
+ requesting 60 seconds aggregation per point, Netdata returns chart data
497
+ aligned to XX:XX:00 to XX:XX:59 - similarly for hours, days, etc - the
498
+ `unaligned` option disables this feature)
499
+- `match-ids` or `match-names` is used to control what `data-dimensions=` will
500
+ match.
501
502
### Chart library performance
503
416
-`dashboard.js` measures the performance of the chart library when it renders the charts. You can specify an element ID you want this information to be visualized, using this:
504
+`dashboard.js` measures the performance of the chart library when it renders the
505
+charts. You can specify an element ID you want this information to be
506
+visualized, using this:
507
508
```html
509
<div data-netdata="unique.id"
420
- data-dt-element-name="measurement1"
421
- ></div>
510
+ data-dt-element-name="measurement1"
511
+ ></div>
512
513
refreshed in <span id="measurement1"></span> milliseconds!
514
```
515
516
### Syncing charts y-range
517
428
-If you give the same `data-common-max="NAME"` to 2+ charts, then all of them will share the same max value of their y-range. If one spikes, all of them will be aligned to have the same scale. This is done for the cpu interrupts and and cpu softnet charts at the dashboard and also for the `gauge` and `easypiecharts` of the Netdata home page.
518
+If you give the same `data-common-max="NAME"` to 2+ charts, then all of them
519
+will share the same max value of their y-range. If one spikes, all of them will
520
+be aligned to have the same scale. This is done for the cpu interrupts and and
521
+cpu softnet charts at the dashboard and also for the `gauge` and `easypiecharts`
522
+of the Netdata home page.
523
524
```html
525
<div data-netdata="chart1"
432
- data-common-max="chart-group-1"
433
- ></div>
526
+ data-common-max="chart-group-1"
527
+ ></div>
528
529
<div data-netdata="chart2"
436
- data-common-max="chart-group-1"
437
- ></div>
530
+ data-common-max="chart-group-1"
531
+ ></div>
532
```
533
534
The same functionality exists for `data-common-min`.
535
536
### Syncing chart units
537
444
-Netdata dashboards support auto-scaling of units. So, `MB` can become `KB`, `GB`, etc dynamically, based on the value to be shown.
538
+Netdata dashboards support auto-scaling of units. So, `MB` can become `KB`,
539
+`GB`, etc dynamically, based on the value to be shown.
540
446
-Giving the same `NAME` with `data-common-units="NAME"`, 2+ charts can be forced to always have the same units.
541
+Giving the same `NAME` with `data-common-units= "NAME"`, 2+ charts can be forced
542
+to always have the same units.
543
544
```html
545
<div data-netdata="chart1"
450
- data-common-units="chart-group-1"
451
- ></div>
546
+ data-common-units="chart-group-1"
547
+ ></div>
548
549
<div data-netdata="chart2"
454
- data-common-units="chart-group-1"
455
- ></div>
550
+ data-common-units="chart-group-1"
551
+ ></div>
552
```
553
554
### Setting desired units
555
460
-Charts can be scaled to specific units with `data-desired-units="UNITS"`. If the dashboard can convert the units to the desired one, it will do.
556
+Charts can be scaled to specific units with `data-desired-units=" UNITS"`. If
557
+the dashboard can convert the units to the desired one, it will do.
558
559
```html
560
<div data-netdata="chart1"
464
- data-desired-units="GB"
465
- ></div>
561
+ data-desired-units="GB"
562
+ ></div>
563
+```
564
+
565
+## Chart library settings
566
+
567
+### Dygraph
568
+
569
+You can set the min and max values of the y-axis using
570
+`data-dygraph-valuerange=" [MIN, MAX] "`.
571
+
572
+### EasyPieChart
573
+
574
+#### Value range
575
+
576
+You can set the max value of the chart using the following snippet:
577
+
578
+```html
579
+<div data-netdata="unique.id"
580
+ data-chart-library="easypiechart"
581
+ data-easypiechart-max-value="40"
582
+ ></div>
583
+```
584
+
585
+Be aware that values that exceed the max value will get expanded (e.g. "41" is
586
+still 100%). Similar for the minimum:
587
+
588
+```html
589
+<div data-netdata="unique.id"
590
+ data-chart-library="easypiechart"
591
+ data-easypiechart-min-value="20"
592
+ ></div>
593
```
594
468
-[](<>)
595
+If you specify both minimum and maximum, the rendering behavior changes. Instead
596
+of displaying the `value` based from zero, it is now based on the range that is
597
+provided by the snippet:
598
+
599
+```html
600
+<div data-netdata="unique.id"
601
+ data-chart-library="easypiechart"
602
+ data-easypiechart-min-value="20"
603
+ data-easypiechart-max-value="40"
604
+ ></div>
605
+`"
606
+In the first example, a value of `30`, without specifying the minimum, fills the chart bar to '75 %` (100% / 40 * 30). However, in this example the range is now `20` (40 - 20 = 20). The value `30` will fill the chart to ** '50 %`**, since it's in the middle between 20 and 40.
607
+
608
+This szenario is useful if you have metrics that change only within a specific range, e.g. temperatures that are very unlikely to fall out of range. In these cases it is more useful to have the chart render the values between the given min and max, to better highlight the changes within them.
609
+
610
+#### Negative values
611
+
612
+EasyPieCharts can render negative values with the following flag:
613
+```html
614
+<div data-netdata="unique.id"
615
+ data-chart-library="easypiechart"
616
+ data-override-options="signed"
617
+ ></div>
618
+```
619
+Negative values are rendered counter-clockwise.
620
+
621
+#### Full example with EasyPieChart
622
+
623
+This is a chart that displays the hotwater temperature in the given range of 40
624
+to 50.
625
+```html
626
+<div data-netdata="stiebeleltron_system.hotwater.hotwatertemp"
627
+ data-title="Hot Water Temperature"
628
+ data-decimal-digits="1"
629
+ data-chart-library="easypiechart"
630
+ data-colors="#FE3912"
631
+ data-width="55%"
632
+ data-height="50%"
633
+ data-points="1200"
634
+ data-after="-1200"
635
+ data-dimensions="actual"
636
+ data-units="°C"
637
+ data-easypiechart-max-value="50"
638
+ data-easypiechart-min-value="40"
639
+ data-common-max="netdata-hotwater-max"
640
+ data-common-min="netdata-hotwater-min"
641
+></div>
642
+```
643
+
644
+
646
+
647
+[]()