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
This commit is contained in:
Joel Hans
GitHub
parent
8ece9b0932
commit
89e71c474c
|
|
@ -143,6 +143,6 @@ External plugins that need additional configuration may support a dedicated file
|
|||
|
||||
### Per chart configuration
|
||||
|
||||
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).
|
||||
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).
|
||||
|
||||
[](<>)
|
||||
|
|
|
|||
|
|
@ -1,27 +0,0 @@
|
|||
# Charts, contexts, families
|
||||
|
||||
Before configuring an alarm or writing a collector, it's important to understand how Netdata organizes collected metrics into charts.
|
||||
|
||||
## Charts
|
||||
|
||||
Each chart that you see on the Netdata dashboard contains one or more dimensions, one for each collected or calculated metric.
|
||||
|
||||
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`.
|
||||
|
||||
## Dimensions
|
||||
|
||||
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).
|
||||
|
||||
## Families
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## Contexts
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
[](<>)
|
||||
|
|
@ -154,7 +154,6 @@ echo -ne " - 'docs/what-is-netdata.md'
|
|||
- 'daemon/README.md'
|
||||
- 'docs/configuration-guide.md'
|
||||
- 'daemon/config/README.md'
|
||||
- 'docs/Charts.md'
|
||||
"
|
||||
navpart 2 web/server "" "Web server"
|
||||
navpart 3 web/server "" "" 2 excludefirstlevel
|
||||
|
|
@ -182,6 +181,9 @@ echo -ne "
|
|||
- 'docs/netdata-cloud/nodes-view.md'
|
||||
"
|
||||
|
||||
navpart 1 web "README" "Dashboards"
|
||||
navpart 2 web/gui "" "" 3
|
||||
|
||||
navpart 1 collectors "" "Data collection" 1
|
||||
echo -ne " - 'docs/Add-more-charts-to-netdata.md'
|
||||
- Internal plugins:
|
||||
|
|
@ -261,9 +263,6 @@ navpart 1 streaming "" "" 4
|
|||
|
||||
navpart 1 backends "" "Archiving to backends" 3
|
||||
|
||||
navpart 1 web "README" "Dashboards"
|
||||
navpart 2 web/gui "" "" 3
|
||||
|
||||
navpart 1 web/api "" "HTTP API"
|
||||
navpart 2 web/api/exporters "" "Exporters" 2
|
||||
navpart 2 web/api/formatters "" "Formatters" 2
|
||||
|
|
|
|||
|
|
@ -144,7 +144,7 @@ This is useful when you centralize metrics from multiple hosts, to one Netdata.
|
|||
This line is only used in alarm templates. It filters the charts. So, if you need to create
|
||||
an alarm template for a few of a kind of chart (a few of your disks, or a few of your network
|
||||
interfaces, or a few your mysql servers, etc), you can create an alarm template that would
|
||||
normally be applied to all of them, and filter them by [family](../docs/Charts.md#families).
|
||||
normally be applied to all of them, and filter them by [family](../web/README.md#families).
|
||||
|
||||
The format is:
|
||||
|
||||
|
|
@ -446,12 +446,13 @@ You can find all the variables that can be used for a given chart, using
|
|||
`http://your.netdata.ip:19999/api/v1/alarm_variables?chart=CHART_NAME`
|
||||
Example: [variables for the `system.cpu` chart of the registry](https://registry.my-netdata.io/api/v1/alarm_variables?chart=system.cpu).
|
||||
|
||||
_Hint: If you don't know how to find the CHART_NAME, you can read about it [here](../docs/Charts.md#charts)._
|
||||
_Hint: If you don't know how to find the CHART_NAME, you can read about it [here](../web/README.md#charts)._
|
||||
|
||||
Netdata supports 3 internal indexes for variables that will be used in health monitoring.
|
||||
|
||||
<details markdown="1"><summary>The variables below can be used in both chart alarms and context templates.</summary>
|
||||
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).
|
||||
|
||||
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).
|
||||
</details>
|
||||
|
||||
- **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.
|
||||
|
|
|
|||
228
web/README.md
228
web/README.md
|
|
@ -1,28 +1,228 @@
|
|||
# Web dashboards overview
|
||||
|
||||
The default port is 19999; for example, to access the dashboard on localhost, use: <http://localhost:19999>
|
||||
Because Netdata is a health monitoring and _performance troubleshooting_ system,
|
||||
we put a lot of emphasis on real-time, meaningful, and context-aware charts.
|
||||
|
||||
To view Netdata collected data you access its **[REST API v1](api/)**.
|
||||
We bundle Netdata with a dashboard and hundreds of charts, designed by both our
|
||||
team and the community, but you can also customize them yourself.
|
||||
|
||||
For our convenience, Netdata provides 2 more layers:
|
||||
There are two primary ways to view Netdata's dashboards:
|
||||
|
||||
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/)**
|
||||
1. The [standard web dashboard](gui/) that comes pre-configured with every
|
||||
Netdata installation. You can see it at `http://SERVER-IP:19999`, or
|
||||
`http://localhost:19999` on `localhost`. You can customize the contents and
|
||||
colors of the standard dashboard [using
|
||||
JavaScript](gui/#customizing-the-standard-dashboard).
|
||||
|
||||
2. Ready to be used web dashboards that render all the charts a Netdata server maintains.
|
||||
2. The [`dashboard.js` JavaScript library](#dashboardjs), which helps you
|
||||
[customize the standard dashboards](gui/#customizing-the-standard-dashboard)
|
||||
using JavaScript, or create entirely new [custom dashboards](gui/custom/) or
|
||||
[Atlassian Confluence dashboards](gui/confluence/).
|
||||
|
||||
## Customizing the standard dashboards
|
||||
You can also view all the data Netdata collects through the [REST API v1](api/).
|
||||
|
||||
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.
|
||||
No matter where you use Netdata's charts, you'll want to know how to
|
||||
[use](#using-charts) them. You'll also want to understand how Netdata defines
|
||||
[charts](#charts), [dimensions](#dimensions), [families](#families), and
|
||||
[contexts](#contexts).
|
||||
|
||||
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).
|
||||
## Using charts
|
||||
|
||||
You have to copy the example file under a new name, so that it will not be overwritten with Netdata updates.
|
||||
Netdata's charts are far from static. They are interactive, real-time, and work
|
||||
with your mouse, touchpad, or touchscreen!
|
||||
|
||||
To configure your info file set in `netdata.conf`:
|
||||
Hover over any chart to temporarily pause it and see the exact values presented
|
||||
as different [dimensions](#dimensions). Click or tap stop the chart from automatically updating with new metrics, thereby locking it to a single timeframe.
|
||||
|
||||
```
|
||||
[web]
|
||||
custom dashboard_info.js = your_file_name.js
|
||||
|
||||
|
||||
You can change how charts show their metrics by zooming in or out, moving
|
||||
forward or backward in time, or selecting a specific timeframe for more in-depth
|
||||
analysis.
|
||||
|
||||
Whenever you use a chart in this way, Netdata synchronizes all the other charts
|
||||
to match it. Chart synchronization even works between separate Netdata agents if you connect
|
||||
them using the [node menu](../registry)!
|
||||
|
||||
You can change how charts show their metrics in a few different ways, each of
|
||||
which have a few methods:
|
||||
|
||||
| Manipulation | Method #1 | Method #2 | Method #3 |
|
||||
|--- |--- |--- |--- |
|
||||
| **Reset** charts to default auto-refreshing state | `double click` | `double tap` (touchpad/touchscreen) | |
|
||||
| **Select** a certain timeframe | `ALT` + `mouse selection` | `⌘` + `mouse selection` (macOS) | |
|
||||
| **Pan** forward or back in time | `click and drag` | `touch and drag` (touchpad/touchscreen) | |
|
||||
| **Zoom** to a specific timeframe | `SHIFT` + `mouse selection` | | |
|
||||
| **Zoom** in/out | `SHIFT`/`ALT` + `mouse scrollwheel` | `SHIFT`/`ALT` + `two-finger pinch` (touchpad/touchscreen) | `SHIFT`/`ALT` + `two-finger scroll` (touchpad/touchscreen) |
|
||||
|
||||
Here's how chart synchronization looks while zooming and panning:
|
||||
|
||||
|
||||
|
||||
You can also perform all these actions using the small
|
||||
rewind/play/fast-forward/zoom-in/zoom-out buttons that appear in the
|
||||
bottom-right corner of each chart.
|
||||
|
||||
## Charts, contexts, families
|
||||
|
||||
Before customizing the standard web dashboard, creating a custom dashboard,
|
||||
configuring an alarm, or writing a collector, it's crucial to understand how
|
||||
Netdata organizes metrics into charts, dimensions, families, and contexts.
|
||||
|
||||
### Charts
|
||||
|
||||
A **chart** is an individual, interactive, always-updating graphic displaying
|
||||
one or more collected/calculated metrics. Charts are generated by
|
||||
[collectors](../collectors/).
|
||||
|
||||
Here's the system CPU chart, the first chart displayed on the standard
|
||||
dashboard:
|
||||
|
||||
|
||||
|
||||
Netdata displays a chart's name in parentheses above the chart. For example, if
|
||||
you navigate to the system CPU chart, you'll see the label: **Total CPU
|
||||
utilization (system.cpu)**. In this case, the chart's name is `system.cpu`.
|
||||
Netdata derives the name from the chart's [context](#contexts).
|
||||
|
||||
### Dimensions
|
||||
|
||||
A **dimension** is a value that gets shown on a chart. The value can be raw data
|
||||
or calculated values, such as percentages, aggregates, and more.
|
||||
|
||||
Charts are capable of showing more than one dimension. Netdata shows these
|
||||
dimensions on the right side of the chart, beneath the date and time. Again, the
|
||||
`system.cpu` chart will serve as a good example.
|
||||
|
||||
|
||||
|
||||
Here, the `system.cpu` chart is showing many dimensions, such as `user`,
|
||||
`system`, `softirq`, `irq`, and more.
|
||||
|
||||
Note that other applications sometimes use the word _series_ instead of
|
||||
_dimension_.
|
||||
|
||||
### Families
|
||||
|
||||
A **family** is _one_ instance of a monitored hardware or software resource that
|
||||
needs to be monitored and displayed separately from similar instances.
|
||||
|
||||
For example, if your system has multiple disk drives at `sda` and `sdb`, Netdata
|
||||
will put each interface into their own family. Same goes for software resources,
|
||||
like multiple MySQL instances. We call these instances "families" because the
|
||||
charts associated with a single disk instance, for example, are often related to
|
||||
each other. Relatives, family... get it?
|
||||
|
||||
When relevant, Netdata prefers to organize charts by family. When you visit the
|
||||
**Disks** section, you will see your disk drives organized into families, and
|
||||
each family will have one or more charts: `disk`, `disk_ops`, `disk_backlog`,
|
||||
`disk_util`, `disk_await`, `disk_avgsz`, `disk_svctm`, `disk_mops`, and
|
||||
`disk_iotime`.
|
||||
|
||||
In the screenshot below, the disk family `sdb` shows a few gauges, followed by a
|
||||
few of the associated charts:
|
||||
|
||||
|
||||
|
||||
Netdata also creates separate submenu entries for each family in the right
|
||||
navigation page so you can easily navigate to the instance you're interested in.
|
||||
Here, Netdata has made several submenus under the **Disk** menu.
|
||||
|
||||
|
||||
|
||||
### Contexts
|
||||
|
||||
A **context** is a way of grouping charts by the types of metrics collected and
|
||||
dimensions displayed. Different charts with the same context will show the same
|
||||
dimensions, but for different instances (families) of hardware/software
|
||||
resources.
|
||||
|
||||
For example, the **Disks** section will often use many contexts (`disk.io`,
|
||||
`disk.ops`, `disk.backlog`, `disk.util`, and so on). Netdata then creates an
|
||||
individual chart for each context, and groups them by family.
|
||||
|
||||
Netdata names charts according to their context according to the following
|
||||
structure: `[context].[family]`. A chart with the `disk.util` context, in the
|
||||
`sdb` family, gets the name `disk_util.sdb`. Netdata shows that name in the
|
||||
top-left corner of a chart.
|
||||
|
||||
Given the four example contexts, and two families of `sdb` and `sdd`, Netdata
|
||||
will create the following charts and their names:
|
||||
|
||||
Context | `sdb` family | `sdd` family
|
||||
--- | --- | ---
|
||||
`disk.io` | `disk_io.sdb` | `disk_io.sdd`
|
||||
`disk.ops` | `disk_ops.sdb` | `disk_ops.sdd`
|
||||
`disk.backlog` | `disk_backlog.sdb` | `disk_backlog.sdd`
|
||||
`disk.util` | `disk_util.sdb` | `disk_util.sdd`
|
||||
|
||||
And here's what two of those charts in the `disk.io` context look like under
|
||||
`sdb` and `sdd` families:
|
||||
|
||||
|
||||
|
||||
|
||||
As you can see in the screenshot, you can view the context of a chart if you
|
||||
hover over the date above the list of dimensions. A tooltip will appear that
|
||||
shows you two pieces of information: the collector that produces the chart, and
|
||||
the chart's context.
|
||||
|
||||
Netdata also uses [contexts for alarm
|
||||
templates](../health/#alarm-line-on). You can create an
|
||||
alarm for the `net.packets` context to receive alerts for any chart with that
|
||||
context, no matter which family it's attached to.
|
||||
|
||||
## Positive and negative values on charts
|
||||
|
||||
To improve clarity on charts, Netdata dashboards present **positive** values for
|
||||
metrics representing `read`, `input`, `inbound`, `received` and **negative**
|
||||
values for metrics representing `write`, `output`, `outbound`, `sent`.
|
||||
|
||||
|
||||
|
||||
_Netdata charts showing the bandwidth and packets of a network interface.
|
||||
`received` is positive and `sent` is negative._
|
||||
|
||||
## Autoscaled y-axis
|
||||
|
||||
Netdata charts automatically zoom vertically, to visualize the variation of each
|
||||
metric within the visible timeframe.
|
||||
|
||||
|
||||
|
||||
_A zero-based `stacked` chart, automatically switches to an auto-scaled `area`
|
||||
chart when a single dimension is selected._
|
||||
|
||||
## dashboard.js
|
||||
|
||||
Netdata uses the `dashboards.js` file to define, configure, create, and update
|
||||
all the charts and other visualizations that appear on any Netdata dashboard.
|
||||
You need to put `dashboard.js` on any HTML page that's going to render Netdata
|
||||
charts.
|
||||
|
||||
The [custom dashboards documentation](gui/custom/) contains examples of such
|
||||
custom HTML pages.
|
||||
|
||||
### Generating dashboard.js
|
||||
|
||||
We build the `dashboards.js` file by concatenating all the source files located
|
||||
in the `web/gui/src/dashboard.js/` directory. That's done using the provided
|
||||
build script:
|
||||
|
||||
```sh
|
||||
cd web/gui
|
||||
make
|
||||
```
|
||||
|
||||
[](<>)
|
||||
If you make any changes to the `src` directory when developing Netdata, you
|
||||
should regenerate the `dashboard.js` file before you commit to the Netdata
|
||||
repository.
|
||||
|
||||
[]()
|
||||
|
|
|
|||
|
|
@ -1,118 +1,159 @@
|
|||
# Netdata agent web GUI
|
||||
# The standard web dashboard
|
||||
|
||||
## Generating dashboard.js
|
||||
The standard web dashboard is the heart of Netdata's performance troubleshooting
|
||||
toolkit. You've probably seen it before:
|
||||
|
||||
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:
|
||||
|
||||
|
||||
```sh
|
||||
cd web/gui
|
||||
make
|
||||
Learn more about how dashboards work and how they're populated using the
|
||||
`dashboards.js` file in our [web dashboards overview](../README.md).
|
||||
|
||||
By default, Netdata starts a web server for its dashboard at port `19999`. Open
|
||||
up your web browser of choice and navigate to `http://SERVER-IP:19999`, or
|
||||
`http://localhost:19999` on `localhost`.
|
||||
|
||||
Netdata uses an [internal, static-threaded web server](../server/) to host the
|
||||
HTML, CSS, and JavaScript files that make up the standard dashboard. You don't
|
||||
have to configure anything to access it, although you can adjust [your
|
||||
settings](../server/#other-netdataconf-web-section-options) in the
|
||||
`netdata.conf` file, or run Netdata behind an Nginx proxy, and so on.
|
||||
|
||||
## Navigating the standard dashboard
|
||||
|
||||
Beyond charts, the standard dashboard can be broken down into three key areas:
|
||||
|
||||
1. [**Sections**](#sections)
|
||||
2. [**Menus/submenus**](#menus)
|
||||
3. [**Nodes menu**](#nodes-menu)
|
||||
|
||||
|
||||
|
||||
### Sections
|
||||
|
||||
Netdata is broken up into multiple **sections**, such as **System Overview**,
|
||||
**CPU**, **Disk**, and more. Inside each section you'll find a number of charts,
|
||||
broken down into [contexts](../README.md#contexts) and
|
||||
[families](../README.md#families).
|
||||
|
||||
An example of the **Memory** section on a Linux desktop system.
|
||||
|
||||
|
||||
|
||||
All sections and their associated charts appear on a single "page," so all you
|
||||
need to do to view different sections is scroll up and down the page. But it's
|
||||
usually quicker to use the [menus](#menus).
|
||||
|
||||
### Menus
|
||||
|
||||
**Menus** appears on the right-hand side of the standard dashboard. Netdata
|
||||
generates a menu for each section, and menus link to the section they're
|
||||
associated with.
|
||||
|
||||
|
||||
|
||||
Most menu items will contain several **submenu** entries, which represent any
|
||||
[families](../README.md#families) from that section. Netdata automatically
|
||||
generates these submenu entries.
|
||||
|
||||
Here's a **Disks** menu with several submenu entries for each disk drive and
|
||||
partition Netdata recognizes.
|
||||
|
||||
|
||||
|
||||
### Nodes menu
|
||||
|
||||
The nodes menu appears in the top-left corner of the standard dashboard and is
|
||||
labeled with the hostname of the system Netdata is monitoring.
|
||||
|
||||
Clicking on it will display a drop-down menu of any nodes you might have
|
||||
connected via the [Netdata registry](../../registry/). By default, you'll find
|
||||
nothing under the **My nodes** heading, but you can try out any of the demo
|
||||
Netdata nodes to see how the nodes menu works.
|
||||
|
||||
|
||||
|
||||
Once you add nodes via [Netdata Cloud](../../docs/netdata-cloud/) or a [private
|
||||
registry](../../registry/#run-your-own-registry), you will see them appear under
|
||||
the **My nodes** heading.
|
||||
|
||||
|
||||
|
||||
The nodes menu will also show the master netdata node and all slave nodes
|
||||
streaming to that master, if you have [configured streaming](../../streaming).
|
||||
|
||||
|
||||
|
||||
## Customizing the standard dashboard
|
||||
|
||||
Netdata stores information about individual charts in the `dashboard_info.js`
|
||||
file. This file includes section and subsection headings, descriptions, colors,
|
||||
titles, tooltips, and other information for Netdata to render on the dashboard.
|
||||
|
||||
For example, here is how `dashboard_info.js` defines the **System Overview**
|
||||
section.
|
||||
|
||||
```javascript
|
||||
netdataDashboard.menu = {
|
||||
'system': {
|
||||
title: 'System Overview',
|
||||
icon: '<i class="fas fa-bookmark"></i>',
|
||||
info: 'Overview of the key system metrics.'
|
||||
},
|
||||
```
|
||||
|
||||
After every change in the `src` directory, the `dashboard.js` file should be regenerated and commited to the repository.
|
||||
If you want to customize this information, you should avoid editing
|
||||
`dashboard_info.js` directly. These changes are not persistent; Netdata will
|
||||
overwrite the file when it's updated. Instead, you should create a new file with
|
||||
your customizations.
|
||||
|
||||
## Custom Dashboards
|
||||
We created an example file at
|
||||
[`dashboard_info_custom_example.js`](dashboard_info_custom_example.js). You can
|
||||
copy this to a new file with a name of your choice in the `web/` directory. This
|
||||
directory changes based on your operating system and installation method. If
|
||||
you're on a Linux system, it should be at `/usr/share/netdata/web/`.
|
||||
|
||||
For information on creating custom dashboards, see **[Custom Dashboards](custom/)** and **[Atlassian Confluence Dashboards](confluence/)**
|
||||
|
||||
## Supported chart libraries
|
||||
|
||||
- Dygraph
|
||||
- jQuery Sparkline
|
||||
- Peity
|
||||
- Google Charts
|
||||
- Morris
|
||||
- EasyPieChart
|
||||
- Gauge.js
|
||||
- D3
|
||||
- C3
|
||||
|
||||
### Dygraph
|
||||
|
||||
#### Settings
|
||||
|
||||
[Example settings here](https://github.com/netdata/netdata/blob/e91f00d99f4965e985981b93fa46ef33f94dd726/web/dashboard.js#L3793)
|
||||
|
||||
#### Value Range
|
||||
|
||||
You can set the min and max values of the y-axis using `data-dygraph-valuerange="[MIN, MAX]"`
|
||||
|
||||
### EasyPieChart
|
||||
|
||||
#### Settings
|
||||
|
||||
TBD
|
||||
|
||||
#### Value Range
|
||||
|
||||
You can set the max value of the chart using the following snippet:
|
||||
|
||||
```html
|
||||
<div data-netdata="unique.id"
|
||||
data-chart-library="easypiechart"
|
||||
data-easypiechart-max-value="40"
|
||||
></div>
|
||||
```shell
|
||||
cd /usr/share/netdata/web/
|
||||
sudo cp dashboard_info_custom_example.js your_dashboard_info_file.js
|
||||
```
|
||||
|
||||
Be aware that values that exceed the max value will get expanded (e.g. "41" is still 100%). Similar for the minimum:
|
||||
Edit the file with your customizations. For example:
|
||||
|
||||
```html
|
||||
<div data-netdata="unique.id"
|
||||
data-chart-library="easypiechart"
|
||||
data-easypiechart-min-value="20"
|
||||
></div>
|
||||
```javascript
|
||||
customDashboard.menu = {
|
||||
'system': {
|
||||
title: 'Testing, testing, 1 2 3',
|
||||
icon: '<i class="fas fa-thumbs-up"></i>',
|
||||
info: 'This is overwritten info for the system overview section!'
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
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:
|
||||
Finally, tell Netdata where you placed your customization file by replacing
|
||||
`your_dashboard_info_file.js` below.
|
||||
|
||||
```html
|
||||
<div data-netdata="unique.id"
|
||||
data-chart-library="easypiechart"
|
||||
data-easypiechart-min-value="20"
|
||||
data-easypiechart-max-value="40"
|
||||
></div>
|
||||
```conf
|
||||
[web]
|
||||
custom dashboard_info.js = your_dashboard_info_file.js
|
||||
```
|
||||
|
||||
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.
|
||||
Once you restart Netdata, refresh the dashboard to find your custom
|
||||
configuration:
|
||||
|
||||
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.
|
||||
|
||||
|
||||
#### Negative Values
|
||||
## Custom dashboards
|
||||
|
||||
EasyPieCharts can render negative values with the following flag:
|
||||
|
||||
```html
|
||||
<div data-netdata="unique.id"
|
||||
data-chart-library="easypiechart"
|
||||
data-override-options="signed"
|
||||
></div>
|
||||
```
|
||||
|
||||
Negative values are rendered counter-clockwise.
|
||||
|
||||
#### Full example
|
||||
|
||||
This is a chart that displays the hotwater temperature in the given range of 40 to 50.
|
||||
|
||||
```html
|
||||
<div data-netdata="stiebeleltron_system.hotwater.hotwatertemp"
|
||||
data-title="Hot Water Temperature"
|
||||
data-decimal-digits="1"
|
||||
data-chart-library="easypiechart"
|
||||
data-colors="#FE3912"
|
||||
data-width="55%"
|
||||
data-height="50%"
|
||||
data-points="1200"
|
||||
data-after="-1200"
|
||||
data-dimensions="actual"
|
||||
data-units="°C"
|
||||
data-easypiechart-max-value="50"
|
||||
data-easypiechart-min-value="40"
|
||||
data-common-max="netdata-hotwater-max"
|
||||
data-common-min="netdata-hotwater-min"
|
||||
></div>
|
||||
```
|
||||
|
||||
|
||||
For information on creating custom dashboards from scratch, see the [custom
|
||||
dashboards](custom/) or [Atlassian Confluence dashboards](confluence/) guides.
|
||||
|
||||
[](<>)
|
||||
|
|
|
|||
|
|
@ -2,18 +2,24 @@
|
|||
|
||||
You can:
|
||||
|
||||
- create your own dashboards using simple HTML (no javascript is required for basic dashboards)
|
||||
- create your own dashboards using simple HTML (no javascript is required for
|
||||
basic dashboards)
|
||||
- utilizing any or all of the available chart libraries, on the same dashboard
|
||||
- using data from one or more Netdata servers, on the same dashboard
|
||||
- host your dashboard HTML page on any web server, anywhere
|
||||
|
||||
Netdata charts can also be added to existing web pages.
|
||||
You can also add Netdata charts to existing web pages.
|
||||
|
||||
Check this **[very simple working example of a custom dashboard](http://netdata.firehol.org/demo.html)**, and its **[html source](../demo.html)**.
|
||||
Check this **[very simple working example of a custom
|
||||
dashboard](http://netdata.firehol.org/demo.html)**, and its **[html
|
||||
source](../demo.html)**.
|
||||
|
||||
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).
|
||||
You should also look at the [custom dashboard
|
||||
template](https://my-netdata.io/dashboard.html), which contains samples of all
|
||||
supported charts. The code is [here](../dashboard.html).
|
||||
|
||||
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:
|
||||
If you plan to put the dashboard on TV, check out [tv.html](../tv.html). Here's
|
||||
is a screenshot of it, monitoring two servers on the same page:
|
||||
|
||||
|
||||
|
||||
|
|
@ -21,27 +27,32 @@ If you plan to put the dashboard on TV, check **[tv.html](../tv.html)**. This is
|
|||
|
||||
## Web directory
|
||||
|
||||
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`.\
|
||||
Note: index.html has a different syntax. Don't use it as a template for simple custom dashboards.
|
||||
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`.\
|
||||
Note: index.html has a different syntax. Don't use it as a template for simple
|
||||
custom dashboards.
|
||||
|
||||
## Example empty dashboard
|
||||
|
||||
If you need to create a new dashboard on an empty page, we suggest the following header:
|
||||
If you need to create a new dashboard on an empty page, we suggest the following
|
||||
header:
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<title>Your dashboard</title>
|
||||
<title>Your dashboard</title>
|
||||
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<meta name="apple-mobile-web-app-capable" content="yes">
|
||||
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<meta name="apple-mobile-web-app-capable" content="yes">
|
||||
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
|
||||
|
||||
<!-- here we will add dashboard.js -->
|
||||
<!-- here we will add dashboard.js -->
|
||||
|
||||
</head>
|
||||
<body>
|
||||
|
|
@ -107,73 +118,88 @@ To change the display order of your hosts, which is saved in localStorage, click
|
|||
|
||||
## dashboard.js
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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:
|
||||
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:
|
||||
|
||||
```html
|
||||
<script type="text/javascript" src="http://box:19999/dashboard.js"></script>
|
||||
```
|
||||
|
||||
### what dashboard.js does?
|
||||
### What does dashboard.js do?
|
||||
|
||||
`dashboard.js` will automatically load the following:
|
||||
|
||||
1. `dashboard.css`, required for the Netdata charts
|
||||
|
||||
2. `jquery.min.js`, (only if jquery is not already loaded for this web page)
|
||||
2. `jquery.min.js`, (only if jQuery is not already loaded for this web page)
|
||||
|
||||
3. `bootstrap.min.js` (only if bootstrap is not already loaded) and `bootstrap.min.css`.
|
||||
3. `bootstrap.min.js` (only if Bootstrap is not already loaded) and
|
||||
`bootstrap.min.css`.
|
||||
|
||||
You can disable this by adding the following before loading `dashboard.js`:
|
||||
You can disable this by adding the following before loading `dashboard.js`:
|
||||
|
||||
```html
|
||||
<script>var netdataNoBootstrap = true;</script>
|
||||
```
|
||||
|
||||
4. `jquery.nanoscroller.min.js`, required for the scrollbar of the chart legends.
|
||||
4. `jquery.nanoscroller.min.js`, required for the scrollbar of the chart
|
||||
legends.
|
||||
|
||||
5. `bootstrap-toggle.min.js` and `bootstrap-toggle.min.css`, required for the settings toggle buttons.
|
||||
5. `bootstrap-toggle.min.js` and `bootstrap-toggle.min.css`, required for the
|
||||
settings toggle buttons.
|
||||
|
||||
6. `font-awesome.min.css`, for icons.
|
||||
|
||||
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).
|
||||
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).
|
||||
|
||||
### Prevent dashboard.js from starting chart refreshes
|
||||
|
||||
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:
|
||||
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:
|
||||
|
||||
```html
|
||||
<script>var netdataDontStart = true;</script>
|
||||
```
|
||||
`"
|
||||
|
||||
The above, will inform the `dashboard.js` to load everything, but not process the web page until you tell it to.
|
||||
You can tell it to start processing the page, by running this javascript code:
|
||||
|
||||
```js
|
||||
NETDATA.start();
|
||||
```
|
||||
`"
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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`):
|
||||
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`):
|
||||
|
||||
```js
|
||||
NETDATA.pause(function() {
|
||||
// ok, it is paused
|
||||
// ok, it is paused
|
||||
|
||||
// update the DOM as you wish
|
||||
// update the DOM as you wish
|
||||
|
||||
// and then call this to let the charts refresh:
|
||||
NETDATA.unpause();
|
||||
// and then call this to let the charts refresh:
|
||||
NETDATA.unpause();
|
||||
});
|
||||
```
|
||||
|
||||
### The default Netdata server
|
||||
|
||||
`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.
|
||||
`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.
|
||||
|
||||
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`:
|
||||
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`:
|
||||
|
||||
```html
|
||||
<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
|
|||
|
||||
## Adding charts
|
||||
|
||||
To add charts, you need to add a `div` for each of them. Each of these `div` elements accept a few `data-` attributes:
|
||||
To add charts, you need to add a `div` for each of them. Each of these `div`
|
||||
elements accept a few `data-` attributes:
|
||||
|
||||
### The chart unique ID
|
||||
|
||||
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)).
|
||||
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)).
|
||||
|
||||
To specify the unique id, use this:
|
||||
|
||||
|
|
@ -195,26 +225,34 @@ To specify the unique id, use this:
|
|||
<div data-netdata="unique.id"></div>
|
||||
```
|
||||
|
||||
The above is enough for adding a chart. It most probably have the wrong visual settings though. Keep reading...
|
||||
The above is enough for adding a chart. It most probably have the wrong visual
|
||||
settings though. Keep reading...
|
||||
|
||||
### The duration of the chart
|
||||
|
||||
You can specify the duration of the chart (how much time of data it will show) using:
|
||||
You can specify the duration of the chart (how much time of data it will show)
|
||||
using:
|
||||
|
||||
```html
|
||||
<div data-netdata="unique.id"
|
||||
data-after="AFTER_SECONDS"
|
||||
data-before="BEFORE_SECONDS"
|
||||
></div>
|
||||
data-after="AFTER_SECONDS"
|
||||
data-before="BEFORE_SECONDS"
|
||||
></div>
|
||||
```
|
||||
|
||||
`AFTER_SECONDS` and `BEFORE_SECONDS` are numbers representing a time-frame in seconds.
|
||||
`AFTER_SECONDS` and `BEFORE_SECONDS` are numbers representing a time-frame in
|
||||
seconds.
|
||||
|
||||
The can be either:
|
||||
|
||||
- **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.
|
||||
- **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.
|
||||
|
||||
- **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.
|
||||
- **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.
|
||||
|
||||
### Chart sizes
|
||||
|
||||
|
|
@ -222,122 +260,160 @@ You can set the size of the chart using this:
|
|||
|
||||
```html
|
||||
<div data-netdata="unique.id"
|
||||
data-width="WIDTH"
|
||||
data-height="HEIGHT"
|
||||
></div>
|
||||
data-width="WIDTH"
|
||||
data-height="HEIGHT"
|
||||
></div>
|
||||
```
|
||||
|
||||
`WIDTH` and `HEIGHT` can be anything CSS accepts for width and height (e.g. percentages, pixels, etc).
|
||||
Keep in mind that for certain chart libraries, `dashboard.js` may apply an aspect ratio to these.
|
||||
`WIDTH` and `HEIGHT` can be anything CSS accepts for width and height (e.g.
|
||||
percentages, pixels, etc). Keep in mind that for certain chart libraries,
|
||||
`dashboard.js` may apply an aspect ratio to these.
|
||||
|
||||
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.
|
||||
If you want `dashboard.js` to permanently remember (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.
|
||||
|
||||
### Netdata server
|
||||
|
||||
Each chart can get data from a different Netdata server. You can give per chart the Netdata server using:
|
||||
Each chart can get data from a different Netdata server. You can specify the Netdata server to use for each chart using:
|
||||
|
||||
```html
|
||||
<div data-netdata="unique.id"
|
||||
data-host="http://another.netdata.server:19999/"
|
||||
></div>
|
||||
data-host="http://another.netdata.server:19999/"
|
||||
></div>
|
||||
```
|
||||
|
||||
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:
|
||||
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:
|
||||
|
||||
```html
|
||||
<div data-netdata="unique.id"
|
||||
data-host="http://yournetdata.server:19999/host/reported-hostname"
|
||||
></div>
|
||||
data-host="http://yournetdata.server:19999/host/reported-hostname"
|
||||
></div>
|
||||
```
|
||||
|
||||
### Chart library
|
||||
|
||||
The default chart library is `dygraph`. You set a different chart library per chart using this:
|
||||
Netdata supports a number of chart libraries. The default chart library is
|
||||
`dygraph`, but you can set a different chart library per chart using
|
||||
`data-chart-library`:
|
||||
|
||||
```html
|
||||
<div data-netdata="unique.id"
|
||||
data-chart-library="gauge"
|
||||
></div>
|
||||
data-chart-library="gauge"
|
||||
></div>
|
||||
```
|
||||
|
||||
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:
|
||||
Each chart library has a number of specific settings. To learn more about them,
|
||||
you should investigate the documentation of the given chart library, or visit
|
||||
the appropriate JavaScript file that defines the library's options. These files
|
||||
are concatenated into the monolithin `dashboard.js` for deployment.
|
||||
|
||||
- options `data-dygraph-XXX` [here](https://github.com/netdata/netdata/blob/643cfe20a8d8beba0ed31ec6afaade80853fd310/web/dashboard.js#L6251-L6361)
|
||||
- options `data-easypiechart-XXX` [here](https://github.com/netdata/netdata/blob/643cfe20a8d8beba0ed31ec6afaade80853fd310/web/dashboard.js#L7954-L7966)
|
||||
- options `data-gauge-XXX` [here](https://github.com/netdata/netdata/blob/643cfe20a8d8beba0ed31ec6afaade80853fd310/web/dashboard.js#L8182-L8189)
|
||||
- options `data-d3pie-XXX` [here](https://github.com/netdata/netdata/blob/643cfe20a8d8beba0ed31ec6afaade80853fd310/web/dashboard.js#L7394-L7561)
|
||||
- options `data-sparkline-XXX` [here](https://github.com/netdata/netdata/blob/643cfe20a8d8beba0ed31ec6afaade80853fd310/web/dashboard.js#L5940-L5985)
|
||||
- options `data-peity-XXX` [here](https://github.com/netdata/netdata/blob/643cfe20a8d8beba0ed31ec6afaade80853fd310/web/dashboard.js#L5892)
|
||||
- [Dygraph](https://github.com/netdata/netdata/blob/5b57fc441c40959514c4e2d0863be2e6a417e352/web/gui/dashboard.js#L2034)
|
||||
- [d3](https://github.com/netdata/netdata/blob/5b57fc441c40959514c4e2d0863be2e6a417e352/web/gui/dashboard.js#L4095)
|
||||
- [d3pie](https://github.com/netdata/netdata/blob/5b57fc441c40959514c4e2d0863be2e6a417e352/web/gui/dashboard.js#L3753)
|
||||
- [Gauge.js](https://github.com/netdata/netdata/blob/5b57fc441c40959514c4e2d0863be2e6a417e352/web/gui/dashboard.js#L3065)
|
||||
- [Google Charts](https://github.com/netdata/netdata/blob/5b57fc441c40959514c4e2d0863be2e6a417e352/web/gui/dashboard.js#L2936)
|
||||
- [EasyPieChart](https://github.com/netdata/netdata/blob/5b57fc441c40959514c4e2d0863be2e6a417e352/web/gui/dashboard.js#L3531)
|
||||
- [Peity](https://github.com/netdata/netdata/blob/5b57fc441c40959514c4e2d0863be2e6a417e352/web/gui/dashboard.js#L4137)
|
||||
- [Sparkline](https://github.com/netdata/netdata/blob/5b57fc441c40959514c4e2d0863be2e6a417e352/web/gui/dashboard.js#L2779)
|
||||
- [Text-only](https://github.com/netdata/netdata/blob/5b57fc441c40959514c4e2d0863be2e6a417e352/web/gui/dashboard.js#L4200)
|
||||
|
||||
### Data points
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
If you need to have a fixed number of points in the data source retrieved from the Netdata server, you can set:
|
||||
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:
|
||||
|
||||
```html
|
||||
<div data-netdata="unique.id"
|
||||
data-points="DATA_POINTS"
|
||||
></div>
|
||||
data-points="DATA_POINTS"
|
||||
></div>
|
||||
```
|
||||
|
||||
Where `DATA_POINTS` is the number of points you need.
|
||||
|
||||
You can also overwrite the pixels-per-point per chart using this:
|
||||
|
||||
```html
|
||||
<div data-netdata="unique.id"
|
||||
data-pixels-per-point="PIXELS_PER_POINT"
|
||||
></div>
|
||||
data-pixels-per-point="PIXELS_PER_POINT"
|
||||
></div>
|
||||
```
|
||||
|
||||
Where `PIXELS_PER_POINT` is the number of pixels each data point should occupy.
|
||||
|
||||
### Data grouping method
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
You can give it per chart, using:
|
||||
|
||||
```html
|
||||
<div data-netdata="unique.id"
|
||||
data-method="max"
|
||||
></div>
|
||||
data-method="max"
|
||||
></div>
|
||||
```
|
||||
|
||||
### Changing rates
|
||||
|
||||
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:
|
||||
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:
|
||||
|
||||
```html
|
||||
<div data-netdata="unique.id"
|
||||
data-method="average"
|
||||
data-gtime="60"
|
||||
data-units="per minute"
|
||||
></div>
|
||||
data-method="average"
|
||||
data-gtime="60"
|
||||
data-units="per minute"
|
||||
></div>
|
||||
```
|
||||
|
||||
The above will provide the average rate per minute (60 seconds).
|
||||
Use 60 for `/minute`, 3600 for `/hour`, 86400 for `/day` (provided you have that many data).
|
||||
The above will provide the average rate per minute (60 seconds). Use 60 for
|
||||
`/minute`, 3600 for `/hour`, 86400 for `/day` (provided you have that many
|
||||
data).
|
||||
|
||||
- The `data-gtime` setting does not change the units of the chart. You have to change them yourself with `data-units`.
|
||||
- The `data-gtime` setting does not change the units of the chart. You have to
|
||||
change them yourself with `data-units`.
|
||||
- This works only for `data-method="average"`.
|
||||
- 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.
|
||||
- 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.
|
||||
|
||||
### Selecting dimensions
|
||||
|
||||
By default, `dashboard.js` will show all the dimensions of the chart.
|
||||
You can select specific dimensions using this:
|
||||
By default, `dashboard.js` will show all the dimensions of the chart. You can
|
||||
select specific dimensions using this:
|
||||
|
||||
```html
|
||||
<div data-netdata="unique.id"
|
||||
data-dimensions="dimension1,dimension2,dimension3,..."
|
||||
></div>
|
||||
data-dimensions="dimension1,dimension2,dimension3,..."
|
||||
></div>
|
||||
```
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
### Chart title
|
||||
|
||||
|
|
@ -345,40 +421,44 @@ You can overwrite the title of the chart using this:
|
|||
|
||||
```html
|
||||
<div data-netdata="unique.id"
|
||||
data-title="my super chart"
|
||||
></div>
|
||||
data-title="my super chart"
|
||||
></div>
|
||||
```
|
||||
|
||||
### Chart units
|
||||
|
||||
You can overwrite the units of measurement of the dimensions of the chart, using this:
|
||||
You can overwrite the units of measurement of the dimensions of the chart, using
|
||||
this:
|
||||
|
||||
```html
|
||||
<div data-netdata="unique.id"
|
||||
data-units="words/second"
|
||||
></div>
|
||||
data-units="words/second"
|
||||
></div>
|
||||
```
|
||||
|
||||
### Chart colors
|
||||
|
||||
`dashboard.js` has an internal palette of colors for the dimensions of the charts.
|
||||
You can prepend colors to it (so that your will be used first) using this:
|
||||
`dashboard.js` has an internal palette of colors for the dimensions of the
|
||||
charts. You can prepend colors to it (so that your will be used first) using
|
||||
this:
|
||||
|
||||
```html
|
||||
<div data-netdata="unique.id"
|
||||
data-colors="#AABBCC #DDEEFF ..."
|
||||
></div>
|
||||
data-colors="#AABBCC #DDEEFF ..."
|
||||
></div>
|
||||
```
|
||||
|
||||
### Extracting dimension values
|
||||
|
||||
`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:
|
||||
`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:
|
||||
|
||||
```html
|
||||
<div data-netdata="net.eth0"
|
||||
data-show-value-of-in-at="eth0_in_value"
|
||||
data-show-value-of-out-at="eth0_out_value"
|
||||
></div>
|
||||
data-show-value-of-in-at="eth0_in_value"
|
||||
data-show-value-of-out-at="eth0_out_value"
|
||||
></div>
|
||||
|
||||
My eth0 interface, is receiving <span id="eth0_in_value"></span>
|
||||
and transmitting <span id="eth0_out_value"></span>.
|
||||
|
|
@ -386,12 +466,13 @@ and transmitting <span id="eth0_out_value"></span>.
|
|||
|
||||
### Hiding the legend of a chart
|
||||
|
||||
On charts that by default have a legend managed by `dashboard.js` you can remove it, using this:
|
||||
On charts that by default have a legend managed by `dashboard.js` you can remove
|
||||
it, using this:
|
||||
|
||||
```html
|
||||
<div data-netdata="unique.id"
|
||||
data-legend="no"
|
||||
></div>
|
||||
data-legend="no"
|
||||
></div>
|
||||
```
|
||||
|
||||
### API options
|
||||
|
|
@ -400,69 +481,167 @@ You can append Netdata **[REST API v1](../../api)** data options, using this:
|
|||
|
||||
```html
|
||||
<div data-netdata="unique.id"
|
||||
data-append-options="absolute,percentage"
|
||||
></div>
|
||||
data-append-options="absolute,percentage"
|
||||
></div>
|
||||
```
|
||||
|
||||
A few useful options are:
|
||||
|
||||
- `absolute` to show all values are absolute (i.e. turn negative dimensions to positive)
|
||||
- `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)
|
||||
- `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)
|
||||
- `match-ids` or `match-names` is used to control what `data-dimensions=` will match.
|
||||
- `absolute` to show all values are absolute (i.e. turn negative dimensions to
|
||||
positive)
|
||||
- `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)
|
||||
- `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)
|
||||
- `match-ids` or `match-names` is used to control what `data-dimensions=` will
|
||||
match.
|
||||
|
||||
### Chart library performance
|
||||
|
||||
`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:
|
||||
`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:
|
||||
|
||||
```html
|
||||
<div data-netdata="unique.id"
|
||||
data-dt-element-name="measurement1"
|
||||
></div>
|
||||
data-dt-element-name="measurement1"
|
||||
></div>
|
||||
|
||||
refreshed in <span id="measurement1"></span> milliseconds!
|
||||
```
|
||||
|
||||
### Syncing charts y-range
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
```html
|
||||
<div data-netdata="chart1"
|
||||
data-common-max="chart-group-1"
|
||||
></div>
|
||||
data-common-max="chart-group-1"
|
||||
></div>
|
||||
|
||||
<div data-netdata="chart2"
|
||||
data-common-max="chart-group-1"
|
||||
></div>
|
||||
data-common-max="chart-group-1"
|
||||
></div>
|
||||
```
|
||||
|
||||
The same functionality exists for `data-common-min`.
|
||||
|
||||
### Syncing chart units
|
||||
|
||||
Netdata dashboards support auto-scaling of units. So, `MB` can become `KB`, `GB`, etc dynamically, based on the value to be shown.
|
||||
Netdata dashboards support auto-scaling of units. So, `MB` can become `KB`,
|
||||
`GB`, etc dynamically, based on the value to be shown.
|
||||
|
||||
Giving the same `NAME` with `data-common-units="NAME"`, 2+ charts can be forced to always have the same units.
|
||||
Giving the same `NAME` with `data-common-units= "NAME"`, 2+ charts can be forced
|
||||
to always have the same units.
|
||||
|
||||
```html
|
||||
<div data-netdata="chart1"
|
||||
data-common-units="chart-group-1"
|
||||
></div>
|
||||
data-common-units="chart-group-1"
|
||||
></div>
|
||||
|
||||
<div data-netdata="chart2"
|
||||
data-common-units="chart-group-1"
|
||||
></div>
|
||||
data-common-units="chart-group-1"
|
||||
></div>
|
||||
```
|
||||
|
||||
### Setting desired units
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
```html
|
||||
<div data-netdata="chart1"
|
||||
data-desired-units="GB"
|
||||
></div>
|
||||
data-desired-units="GB"
|
||||
></div>
|
||||
```
|
||||
|
||||
[](<>)
|
||||
## Chart library settings
|
||||
|
||||
### Dygraph
|
||||
|
||||
You can set the min and max values of the y-axis using
|
||||
`data-dygraph-valuerange=" [MIN, MAX] "`.
|
||||
|
||||
### EasyPieChart
|
||||
|
||||
#### Value range
|
||||
|
||||
You can set the max value of the chart using the following snippet:
|
||||
|
||||
```html
|
||||
<div data-netdata="unique.id"
|
||||
data-chart-library="easypiechart"
|
||||
data-easypiechart-max-value="40"
|
||||
></div>
|
||||
```
|
||||
|
||||
Be aware that values that exceed the max value will get expanded (e.g. "41" is
|
||||
still 100%). Similar for the minimum:
|
||||
|
||||
```html
|
||||
<div data-netdata="unique.id"
|
||||
data-chart-library="easypiechart"
|
||||
data-easypiechart-min-value="20"
|
||||
></div>
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```html
|
||||
<div data-netdata="unique.id"
|
||||
data-chart-library="easypiechart"
|
||||
data-easypiechart-min-value="20"
|
||||
data-easypiechart-max-value="40"
|
||||
></div>
|
||||
`"
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
#### Negative values
|
||||
|
||||
EasyPieCharts can render negative values with the following flag:
|
||||
```html
|
||||
<div data-netdata="unique.id"
|
||||
data-chart-library="easypiechart"
|
||||
data-override-options="signed"
|
||||
></div>
|
||||
```
|
||||
Negative values are rendered counter-clockwise.
|
||||
|
||||
#### Full example with EasyPieChart
|
||||
|
||||
This is a chart that displays the hotwater temperature in the given range of 40
|
||||
to 50.
|
||||
```html
|
||||
<div data-netdata="stiebeleltron_system.hotwater.hotwatertemp"
|
||||
data-title="Hot Water Temperature"
|
||||
data-decimal-digits="1"
|
||||
data-chart-library="easypiechart"
|
||||
data-colors="#FE3912"
|
||||
data-width="55%"
|
||||
data-height="50%"
|
||||
data-points="1200"
|
||||
data-after="-1200"
|
||||
data-dimensions="actual"
|
||||
data-units="°C"
|
||||
data-easypiechart-max-value="50"
|
||||
data-easypiechart-min-value="40"
|
||||
data-common-max="netdata-hotwater-max"
|
||||
data-common-min="netdata-hotwater-min"
|
||||
></div>
|
||||
```
|
||||
|
||||
|
||||
|
||||
[]()
|
||||
|
|
|
|||
Loading…
Reference in New Issue