Docs: Overhaul of Getting started guide (#6811)
* Initial edits to getting started guide * Working on tutorial and getting started guide * Initial edits to getting started guide * Working on tutorial and getting started guide * Continuing work on tutorial * Finished draft of sizing tutorial * Working on getting started guide * Move getting started guide to new file, Netlify redirect * Quick fix to change nodes menu -> my nodes * Finished draft of getting started guide * Fixing broken links from file moving * More tweaks and grammar fixes * Another run through the new pages * Last changes minus screenshot * Fixes to tutorial * Moving things around and final fixes * Addressing Cosmix' comments * Clarified source terminology and added link to modules list * Initial edits to getting started guide * Initial edits to getting started guide * Working on tutorial and getting started guide * Working on tutorial and getting started guide * Continuing work on tutorial * Finished draft of sizing tutorial * Working on getting started guide * Move getting started guide to new file, Netlify redirect * Quick fix to change nodes menu -> my nodes * Finished draft of getting started guide * Fixing broken links from file moving * More tweaks and grammar fixes * Another run through the new pages * Last changes minus screenshot * Fixes to tutorial * Moving things around and final fixes * Addressing Cosmix' comments * Clarified source terminology and added link to modules list * Quick fix to browser line * Fixing one new broken link * One more grammar fix
Joel Hans committed
Sep 24, 2019 at 07:00 UTC
30563fc5eec1516d399a88b8739aea3c9089ce3d
8 files changed
+400
-190
docs/GettingStarted.md
deleted
-182
@@ -1,182 +0,0 @@
1
-# Getting Started
2
-
3
-These are your first steps **after** you have installed Netdata. If you haven't installed it already, please check the [installation page](../packaging/installer).
4
-
5
-## Accessing the dashboard
6
-
7
-To access the Netdata dashboard, navigate with your browser to:
8
-
9
-```
10
-http://your.server.ip:19999/
11
-```
12
-
13
-<details markdown="1"><summary>Click here, if it does not work.</summary>
14
-
15
-**Verify Netdata is running.**
16
-
17
-Open an ssh session to the server and execute `sudo ps -e | grep netdata`. It should respond with the PID of the Netdata daemon. If it prints nothing, Netdata is not running. Check the [installation page](../packaging/installer) to install it.
18
-
19
-**Verify Netdata responds to HTTP requests.**
20
-
21
-Using the same ssh session, execute `curl -Ss http://localhost:19999`. It should dump on your screen the `index.html` page of the dashboard. If it does not, check the [installation page](../packaging/installer) to install it.
22
-
23
-**Verify Netdata receives the HTTP requests.**
24
-
25
-On the same ssh session, execute `tail -f /var/log/netdata/access.log` (if you installed the static 64bit package, use: `tail -f /opt/netdata/var/log/netdata/access.log`). This command will print on your screen all HTTP requests Netdata receives.
26
-
27
-Next, try to access the dashboard using your web browser, using the URL posted above. If nothing is printed on your terminal, the HTTP request is not routed to your Netdata.
28
-
29
-If you are not sure about your server IP, run this for a hint: `ip route get 8.8.8.8 | grep -oP " src [0-9\.]+ "`. It should print the IP of your server.
30
-
31
-If still Netdata does not receive the requests, something is blocking them. A firewall possibly. Please check your network.
32
-
33
-</details> <br/>
34
-
35
-When you install multiple Netdata servers, all your servers will appear at the node menu at the top left of the dashboard. For this to work, you have to manually access just once, the dashboard of each of your Netdata servers.
36
-
37
-The node menu is more than just browser bookmarks. When switching Netdata servers from that menu, any settings of the current view are propagated to the other Netdata server:
38
-
39
-- the current charts panning (drag the charts left or right),
40
-- the current charts zooming (`SHIFT` + mouse wheel over a chart),
41
-- the highlighted time-frame (`ALT` + select an area on a chart),
42
-- the scrolling position of the dashboard,
43
-- the theme you use,
44
-- etc.
45
-
46
-are all sent over to other Netdata server, to allow you troubleshoot cross-server performance issues easily.
47
-
48
-## Starting and stopping Netdata
49
-
50
-Netdata installer integrates Netdata to your init / systemd environment.
51
-
52
-To start/stop Netdata, depending on your environment, you should use:
53
-
54
-- `systemctl start netdata` and `systemctl stop netdata`
55
-- `service netdata start` and `service netdata stop`
56
-- `/etc/init.d/netdata start` and `/etc/init.d/netdata stop`
57
-
58
-Once Netdata is installed, the installer configures it to start at boot and stop at shutdown.
59
-
60
-For more information about using these commands, consult your system documentation.
61
-
62
-## Sizing Netdata
63
-
64
-The default installation of Netdata is configured for a small round-robin database: just 1 hour of data. Depending on the memory your system has and the amount you can dedicate to Netdata, you should adapt this. On production systems with limited RAM, we suggest to set this to 3-4 hours. For best results you should set this to 24 or 48 hours.
65
-
66
-For every hour of data, Netdata needs about 25MB of RAM. If you can dedicate about 100MB of RAM to Netdata, you should set its database size to 4 hours.
67
-
68
-To do this, edit `/etc/netdata/netdata.conf` (or `/opt/netdata/etc/netdata/netdata.conf`) and set:
69
-
70
-```
71
-[global]
72
- history = SECONDS
73
-```
74
-
75
-Make sure the `history` line is not commented (comment lines start with `#`).
76
-
77
-1 hour is 3600 seconds, so the number you need to set is the result of `HOURS * 3600`.
78
-
79
-!!! danger
80
- Be careful when you set this on production systems. If you set it too high, your system may run out of memory. By default, Netdata is configured to be killed first when the system starves for memory, but better be careful to avoid issues.
81
-
82
-For more information about Netdata memory requirements, [check this page](../database).
83
-
84
-If your kernel supports KSM (most do), you can [enable KSM to half Netdata memory requirement](../database#ksm).
85
-
86
-## Service discovery and auto-detection
87
-
88
-Netdata supports auto-detection of data collection sources. It auto-detects almost everything: database servers, web servers, dns server, etc.
89
-
90
-This auto-detection process happens **only once**, when Netdata starts. To have Netdata re-discover data sources, you need to restart it. There are a few exceptions to this:
91
-
92
-- containers and VMs are auto-detected forever (when Netdata is running at the host).
93
-- many data sources are collected but are silenced by default, until there is useful information to collect (for example network interface dropped packet, will appear after a packet has been dropped).
94
-- services that are not optimal to collect on all systems, are disabled by default.
95
-- services we received feedback from users that caused issues when monitored, are also disabled by default (for example, `chrony` is disabled by default, because CentOS ships a version of it that uses 100% CPU when queried for statistics).
96
-
97
-Once a data collection source is detected, Netdata will never quit trying to collect data from it, until Netdata is restarted. So, if you stop your web server, Netdata will pick it up automatically when it is started again.
98
-
99
-Since Netdata is installed on all your systems (even inside containers), auto-detection is limited to `localhost`. This simplifies significantly the security model of a Netdata monitored infrastructure, since most applications allow `localhost` access by default.
100
-
101
-A few well known data collection sources that commonly need to be configured are:
102
-
103
-- [systemd services utilization](../collectors/cgroups.plugin/#monitoring-systemd-services) are not exposed by default on most systems, so `systemd` has to be configured to expose those metrics.
104
-
105
-## Configuration quick start
106
-
107
-In Netdata we have:
108
-
109
-- **internal** data collection plugins (running inside the Netdata daemon)
110
-- **external** data collection plugins (independent processes, sending data to Netdata over pipes)
111
-- modular plugin **orchestrators** (external plugins that have multiple data collection modules)
112
-
113
-You can enable and disable plugins (internal and external) via `netdata.conf` at the section `[plugins]`.
114
-
115
-All plugins have dedicated sections in `netdata.conf`, like `[plugin:XXX]` for overwriting their default data collection frequency and providing additional command line options to them.
116
-
117
-All external plugins have their own `.conf` file.
118
-
119
-All modular plugin orchestrators have a directory in `/etc/netdata` with a `.conf` file for each of their modules.
120
-
121
-It is complex. So, let's see the whole configuration tree for the `nginx` module of `python.d.plugin`:
122
-
123
-In `netdata.conf` at the `[plugins]` section, `python.d.plugin` can be enabled or disabled:
124
-
125
-```
126
-[plugins]
127
- python.d = yes
128
-```
129
-
130
-In `netdata.conf` at the `[plugin:python.d]` section, we can provide additional command line options for `python.d.plugin` and overwite its data collection frequency:
131
-
132
-```
133
-[plugin:python.d]
134
- update every = 1
135
- command options =
136
-```
137
-
138
-`python.d.plugin` has its own configuration file for enabling and disabling its modules (here you can disable `nginx` for example):
139
-
140
-```bash
141
-sudo /etc/netdata/edit-config python.d.conf
142
-```
143
-
144
-Then, `nginx` has its own configuration file for configuring its data collection jobs (most modules can collect data from multiple sources, so the `nginx` module can collect metrics from multiple, local or remote, `nginx` servers):
145
-
146
-```bash
147
-sudo /etc/netdata/edit-config python.d/nginx.conf
148
-```
149
-
150
-## Health monitoring and alarms
151
-
152
-Netdata ships hundreds of health monitoring alarms for detecting anomalies. These are optimized for production servers.
153
-
154
-Many users install Netdata on workstations and are frustrated by the default alarms shipped with Netdata. On these cases, we suggest to disable health monitoring.
155
-
156
-To disable it, edit `/etc/netdata/netdata.conf` (or `/opt/netdata/etc/netdata/netdata.conf` if you installed the static 64bit package) and set:
157
-
158
-```
159
-[health]
160
- enabled = no
161
-```
162
-
163
-The above will disable health monitoring entirely.
164
-
165
-If you want to keep health monitoring enabled for the dashboard, but you want to disable email notifications, run this:
166
-
167
-```bash
168
-sudo /etc/netdata/edit-config health_alarm_notify.conf
169
-```
170
-
171
-and set `SEND_EMAIL="NO"`.
172
-
173
-(For static 64bit installations use `sudo /opt/netdata/etc/netdata/edit-config health_alarm_notify.conf`).
174
-
175
-## What is next?
176
-
177
-- Check [Data Collection](../collectors) for configuring data collection plugins.
178
-- Check [Health Monitoring](../health) for configuring your own alarms, or setting up alarm notifications.
179
-- Check [Streaming](../streaming) for centralizing Netdata metrics.
180
-- Check [Backends](../backends) for long term archiving of Netdata metrics to time-series databases.
181
-
182
-[](<>)
docs/contributing/contributing-documentation.md
+3
-3
@@ -107,9 +107,9 @@ folder and either name it `README.md` for generic documentation, or with another
107
108
#### The `docs` folder
109
110
-At the root of the Netdata repository is a `docs/` folder. Inside this folder we place documentation that does not
111
-have a direct relationship to a specific component of Netdata. It's where we house our [getting started guide](../GettingStarted.md),
112
-guides on [running Netdata behind Nginx](../Running-behind-nginx.md), and more.
110
+At the root of the Netdata repository is a `docs/` folder. Inside this folder we place documentation that does not have
111
+a direct relationship to a specific component of Netdata. It's where we house our [getting started
112
+guide](../getting-started.md), guides on [running Netdata behind Nginx](../Running-behind-nginx.md), and more.
113
114
If the documentation you're working on doesn't have a direct relaionship to a component of Netdata,
115
it can be placed in this `docs/` folder.
docs/generator/buildyaml.sh
+1
-1
@@ -149,7 +149,7 @@ echo -ne " - 'docs/what-is-netdata.md'
149
- 'packaging/installer/UPDATE.md'
150
- 'packaging/DISTRIBUTIONS.md'
151
- 'packaging/installer/UNINSTALL.md'
152
-- 'docs/GettingStarted.md'
152
+- 'docs/getting-started.md'
153
- Running Netdata:
154
- 'daemon/README.md'
155
- 'docs/configuration-guide.md'
docs/getting-started.md
new
+233
@@ -0,0 +1,233 @@
1
+# Getting started guide
2
+
3
+Thanks for trying Netdata! In this guide, we'll quickly walk you through the first steps you should take after getting
4
+Netdata installed.
5
+
6
+Netdata can collect thousands of metrics in real-time without any configuration, but there are some valuable things to
7
+know to get the most of out Netdata based on your needs.
8
+
9
+> If you haven't installed Netdata yet, visit the [installation instructions](../packaging/installer) for details,
10
+> including our one-liner script, which automatically installs Netdata on almost all Linux distributions.
11
+
12
+## Access the dashboard
13
+
14
+Open up your web browser of choice and navigate to `http://YOUR-HOST:19999`. Welcome to Netdata!
15
+
16
+
18
+
19
+**What's next?**:
20
+
21
+- Read more about the [standard Netdata dashboard](../web/gui/).
22
+- Learn all the specifics of [using charts](../web/README.md#using-charts) or the differences between [charts,
23
+ context, and families](../web/README.md#charts-contexts-families).
24
+
25
+## Configuration basics
26
+
27
+Netdata primarily uses the `netdata.conf` file for custom configurations.
28
+
29
+On most systems, you can find that file at `/etc/netdata/netdata.conf`.
30
+
31
+> Some operating systems will place your `netdata.conf` at `/opt/netdata/etc/netdata/netdata.conf`, so check there if
32
+> you find nothing at `/etc/netdata/netdata.conf`.
33
+
34
+The `netdata.conf` file is broken up into various sections, such as `[global]`, `[web]`, `[registry]`, and more. By
35
+default, most options are commented, so you'll have to uncomment them (remove the `#`) for Netdata to recognize your
36
+change.
37
+
38
+Once you save your changes, [restart Netdata](#start-stop-and-restart-netdata) to load your new configuration.
39
+
40
+**What's next?**:
41
+
42
+- [Change how long Netdata stores metrics](#change-how-long-netdata-stores-metrics) by either increasing the `history`
43
+ option or switching to the database engine.
44
+- Move Netdata's dashboard to a [different port](https://docs.netdata.cloud/web/server/) or enable TLS/HTTPS
45
+ encryption.
46
+- See all the `netdata.conf` options in our [daemon configuration documentation](../daemon/config/).
47
+- Run your own [registry](../registry/README.md#run-your-own-registry).
48
+
49
+## Collect data from more sources
50
+
51
+When Netdata _starts_, it auto-detects dozens of **data sources**, such as database servers, web servers, and more. To
52
+auto-detect and collect metrics from a service or application you just installed, you need to [restart
53
+Netdata](#start-stop-and-restart-netdata).
54
+
55
+> There is one exception: When Netdata is running on the host (as in not in a container itself), it will always
56
+> auto-detect containers and VMs.
57
+
58
+However, auto-detection only works if you installed the source using its standard installation procedure. If Netdata
59
+isn't collecting metrics after a restart, your source probably isn't configured correctly. Look at the [external plugin
60
+documentation](../collectors/plugins.d/) to find the appropriate module for your source. Those pages will contain more
61
+information about how to configure your source for auto-detection.
62
+
63
+Some modules, like `chrony`, are disabled by default and must be enabled manually for auto-detection to work.
64
+
65
+Once Netdata detects a valid source of data, it will continue trying to collect data from it. For example, if
66
+Netdata is collecting data from an Nginx web server, and you shut Nginx down, Netdata will collect new data as soon as
67
+you start the web server back up—no restart necessary.
68
+
69
+### Configuring plugins
70
+
71
+Even if Netdata auto-detects your service/application, you might want to configure what, or how often, Netdata is
72
+collecting data.
73
+
74
+Netdata uses **internal** and **external** plugins to collect data. Internal plugins run within the Netdata dæmon, while
75
+external plugins are independent processes that send metrics to Netdata over pipes. There are also plugin
76
+**orchestrators**, which are external plugins with one or more data collection **modules**.
77
+
78
+You can configure both internal and external plugins, along with the individual modules. There are many ways to do so:
79
+
80
+- In `netdata.conf`, `[plugins]` section: Enable or disable internal or external plugins with `yes` or `no`.
81
+- In `netdata.conf`, `[plugin:XXX]` sections: Each plugin has a section for changing collection frequency or passing
82
+ options to the plugin.
83
+- In `.conf` files for each external plugin: For example, at `/etc/netdata/python.d.conf`.
84
+- In `.conf` files for each module : For example, at `/etc/netdata/python.d/nginx.conf`.
85
+
86
+It's complex, so let's walk through an example of the various `.conf` files responsible for collecting data from an
87
+Nginx web server using the `nginx` module and the `python.d` plugin orchestrator.
88
+
89
+First, you can enable or disable the `python.d` plugin entirely in `netdata.conf`.
90
+
91
+```conf
92
+[plugins]
93
+ # Enabled
94
+ python.d = yes
95
+ # Disabled
96
+ python.d = no
97
+```
98
+
99
+You can also configure the entire `python.d` external plugin via the `[plugin:python.d]` section in `netdata.conf`.
100
+Here, you can change how often Netdata uses `python.d` to collect metrics or pass other command options:
101
+
102
+```conf
103
+[plugin:python.d]
104
+ update every = 1
105
+ command options =
106
+```
107
+
108
+The `python.d` plugin has a separate configuration file at `/etc/netdata/python.d.conf` for enabling and disabling
109
+modules. You can use the `edit-config` script to edit the file, or open it with your text editor of choice:
110
+
111
+```bash
112
+sudo /etc/netdata/edit-config python.d.conf
113
+```
114
+
115
+Finally, the `nginx` module has a configuration file called `nginx.conf` in the `python.d` folder. Again, use
116
+`edit-config` or your editor of choice:
117
+
118
+```bash
119
+sudo /etc/netdata/edit-config python.d/nginx.conf
120
+```
121
+
122
+In the `nginx.conf` file, you'll find additional options. The default works in most situations, but you may need to make
123
+changes based on your particular Nginx setup.
124
+
125
+**What's next?**:
126
+
127
+- Look at the [full list of data collection modules](Add-more-charts-to-netdata.md#available-data-collection-modules)
128
+ to configure your sources for auto-detection and monitoring.
129
+- Improve the [performance](Performance.md) of Netdata on low-memory systems.
130
+- Configure `systemd` to expose [systemd services
131
+ utilization](../collectors/cgroups.plugin/README.md#monitoring-systemd-services) metrics automatically.
132
+- [Reconfigure individual charts](../daemon/config/README.md#per-chart-configuration) in `netdata.conf`.
133
+
134
+## Health monitoring and alarms
135
+
136
+Netdata comes with hundreds of health monitoring alarms for detecting anomalies on production servers. If you're running
137
+Netdata on a workstation, you might want to disable Netdata's alarms.
138
+
139
+Edit your `/etc/netdata/netdata.conf` file and set the following:
140
+
141
+```conf
142
+[health]
143
+ enabled = no
144
+```
145
+
146
+If you want to keep health monitoring enabled, but turn email notifications off, edit your `health_alarm_notify.conf`
147
+file with `edit-config`, or with your the text editor of your choice:
148
+
149
+```bash
150
+sudo /etc/netdata/edit-config health_alarm_notify.conf
151
+```
152
+
153
+Find the `SEND_EMAIL="YES"` line and change it to `SEND_EMAIL="NO"`.
154
+
155
+**What's next?**:
156
+
157
+- Write your own health alarm using the [examples](../health/README.md#examples).
158
+- Add a new notification method, like [Slack](../health/notifications/slack/).
159
+
160
+## Change how long Netdata stores metrics
161
+
162
+By default, Netdata stores 1 hour of historical metrics and uses about 25MB of RAM.
163
+
164
+If that's not enough for you, Netdata is quite adaptable to long-term storage of your system's metrics.
165
+
166
+There are two quick ways to increase the depth of historical metrics: increase the `history` value for the round-robin
167
+that's enabled by default, or switch to the database engine.
168
+
169
+We have a tutorial that walks you through both options: [**Changing how long Netdata stores
170
+metrics**](tutorials/longer-metrics-storage.md).
171
+
172
+**What's next?**:
173
+
174
+- Learn more about the [memory requirements for the database engine](../database/engine/README.md#memory-requirements)
175
+ to understand how much RAM/disk space you should commit to storing historical metrics.
176
+- Read up on the memory requirements of the [round-robin database](../database/), or figure out whether your system
177
+ has KSM enabled, which can [reduce the default database's memory usage](../database/README.md#ksm) by about 60%.
178
+
179
+## Monitoring multiple systems with Netdata
180
+
181
+If you have Netdata installed on multiple systems, you can have them all appear in the **My nodes** menu at the top-left
182
+corner of the dashboard.
183
+
184
+To show all your servers in that menu, you need to [register for or sign in](netdata-cloud/signing-in.md) to [Netdata
185
+Cloud](netdata-cloud/) from each system. Each system will then appear in the **My nodes** menu, which you can use to
186
+navigate between your systems quickly.
187
+
188
+
190
+
191
+Whenever you pan, zoom, highlight, select, or pause a chart, Netdata will synchronize those settings with any other
192
+agent you visit via the My nodes menu. Even your scroll position is synchronized, so you'll see the same charts and
193
+respective data for easy comparisons or root cause analysis.
194
+
195
+You can now seamlessly track performance anomalies across your entire infrastructure!
196
+
197
+**What's next?**:
198
+
199
+- Read up on how the [Netdata Cloud registry works](../registry/), and what kind of data it stores and sends to your
200
+ web browser.
201
+- Familiarize yourself with the [Nodes View](netdata-cloud/nodes-view.md)
202
+
203
+## Start, stop, and restart Netdata
204
+
205
+When you install Netdata, it's configured to start at boot, and stop and restart/shutdown. You shouldn't need to start
206
+or stop Netdata manually, but you will probably need to restart Netdata at some point.
207
+
208
+- To **start** Netdata, open a terminal and run `service netdata start`.
209
+- To **stop** Netdata, run `service netdata stop`.
210
+- To **restart** Netdata, run `service netdata restart`.
211
+
212
+The `service` command is a wrapper script that tries to use your system's preferred method of starting or stopping
213
+Netdata based on your system. But, if either of those commands fails, try using the equivalent commands for `systemd`
214
+and `init.d`:
215
+
216
+- **systemd**: `systemctl start netdata`, `systemctl stop netdata`, `systemctl restart netdata`
217
+- **init.d**: `/etc/init.d/netdata start`, `/etc/init.d/netdata stop`, `/etc/init.d/netdata restart`
218
+
219
+## What's next?
220
+
221
+Even after you've configured `netdata.conf`, tweaked alarms, learned the basics of performance troubleshooting, and
222
+added all your systems to the **My nodes** menu, you've just gotten started with Netdata.
223
+
224
+Take a look at some more advanced features and configurations:
225
+
226
+- Centralize Netdata metrics from many systems with [streaming](../streaming)
227
+- Enable long-term archiving of Netdata metrics via [backends](../backends) to time-series databases.
228
+- Improve security by putting Netdata behind an [Nginx proxy with SSL](Running-behind-nginx.md).
229
+
230
+Or, learn more about how you can contribute to [Netdata core](../CONTRIBUTING.md) or our
231
+[documentation](contributing/contributing-documentation.md)!
232
+
233
+[](<>)
docs/tutorials/longer-metrics-storage.md
new
+155
@@ -0,0 +1,155 @@
1
+# Change how long Netdata stores metrics
2
+
3
+Netdata helps you collect thousands of system and application metrics every second, but what about storing them for the
4
+long term?
5
+
6
+Many people think Netdata can only store about an hour's worth of real-time metrics, but that's just the default
7
+configuration today. With the right settings, Netdata is quite capable of efficiently storing hours or days worth of
8
+historical, per-second metrics without having to rely on a [backend](../../backends/).
9
+
10
+This tutorial gives two options for configuring Netdata to store more metrics. We recommend the [**database
11
+engine**](#using-the-database-engine), as it will soon be the default configuration. However, you can stick with the
12
+current default **round-robin database** if you prefer.
13
+
14
+Let's get started.
15
+
16
+## Using the database engine
17
+
18
+The database engine uses RAM to store recent metrics while also using a "spill to disk" feature that takes advantage of
19
+available disk space for long-term metrics storage.This feature of the database engine allows you to store a much larger
20
+dataset than your system's available RAM.
21
+
22
+The database engine will eventually become the default method of retaining metrics, but until then, you can switch to
23
+the database engine by changing a single option.
24
+
25
+Edit your `netdata.conf` file and change the `memory mode` setting to `dbengine`:
26
+
27
+```conf
28
+[global]
29
+ memory mode = dbengine
30
+```
31
+
32
+Next, restart Netdata. On Linux systems, we recommend running `sudo service netdata restart`. You're now using the
33
+database engine!
34
+
35
+> Learn more about how we implemented the database engine, and our vision for its future, on our blog: [_How and why
36
+> we're bringing long-term storage to Netdata_](https://blog.netdata.cloud/posts/db-engine/).
37
+
38
+What makes the database engine efficient? While it's structured like a traditional database, the database engine splits
39
+data between RAM and disk. The database engine caches and indexes data on RAM to keep memory usage low, and then
40
+compresses older metrics onto disk for long-term storage.
41
+
42
+When the Netdata dashboard queries for historical metrics, the database engine will use its cache, stored in RAM, to
43
+return relevant metrics for visualization in charts.
44
+
45
+Now, given that the database engine uses _both_ RAM and disk, there are two other settings to consider: `page cache
46
+size` and `dbengine disk space`.
47
+
48
+```conf
49
+[global]
50
+ page cache size = 32
51
+ dbengine disk space = 256
52
+```
53
+
54
+`page cache size` sets the maximum amount of RAM (in MiB) the database engine will use for caching and indexing.
55
+`dbengine disk space` sets the maximum disk space (again, in MiB) the database engine will use for storing compressed
56
+metrics.
57
+
58
+Based on our testing, these default settings will retain about two day's worth of metrics when Netdata collects 2,000
59
+metrics every second.
60
+
61
+If you'd like to change these options, read more about the [database engine's memory
62
+footprint](../../database/engine/README.md#memory-requirements).
63
+
64
+With the database engine active, you can back up your `/var/cache/netdata/dbengine/` folder to another location for
65
+redundancy.
66
+
67
+Now that you know how to switch to the database engine, let's cover the default round-robin database for those who
68
+aren't ready to make the move.
69
+
70
+## Using the round-robin database
71
+
72
+By default, Netdata uses a round-robin database to store 1 hour of per-second metrics. Here's the default setting for
73
+`history` in the `netdata.conf` file that comes pre-installed with Netdata.
74
+
75
+```conf
76
+[global]
77
+ history = 3600
78
+```
79
+
80
+One hour has 3,600 seconds, hence the `3600` value!
81
+
82
+To increase your historical metrics, you can increase `history` to the number of seconds you'd like to store:
83
+
84
+```conf
85
+[global]
86
+ # 2 hours = 2 * 60 * 60 = 7200 seconds
87
+ history = 7200
88
+ # 4 hours = 4 * 60 * 60 = 14440 seconds
89
+ history = 14440
90
+ # 24 hours = 24 * 60 * 60 = 86400 seconds
91
+ history = 86400
92
+```
93
+
94
+And so on.
95
+
96
+Next, check to see how many metrics Netdata collects on your system, and how much RAM that uses. Visit the Netdata
97
+dashboard and look at the bottom-right corner of the interface. You'll find a sentence similar to the following:
98
+
99
+> Every second, Netdata collects 1,938 metrics, presents them in 299 charts and monitors them with 81 alarms. Netdata is
100
+> using 25 MB of memory on **netdata-linux** for 1 hour, 6 minutes and 36 seconds of real-time history.
101
+
102
+On this desktop system, using a Ryzen 5 1600 and 16GB of RAM, the round-robin databases uses 25 MB of RAM to store just
103
+over an hour's worth of data for nearly 2,000 metrics.
104
+
105
+To increase the `history` option, you need to edit your `netdata.conf` file and increase the `history` setting. In most
106
+installations, you'll find it at `/etc/netdata/netdata.conf`, but some operating systems place it at
107
+`/opt/netdata/etc/netdata/netdata.conf`.
108
+
109
+Use `/etc/netdata/edit-config netdata.conf`, or your favorite text editor, to replace `3600` with the number of seconds
110
+you'd like to store.
111
+
112
+You should base this number on two things: How much history you need for your use case, and how much RAM you're willing
113
+to dedicate to Netdata.
114
+
115
+> Take care when you change the `history` option on production systems. Netdata is configured to stop its process if
116
+> your system starts running out of RAM, but you can never be too careful. Out of memory situations are very bad.
117
+
118
+How much RAM will a longer history use? Let's use a little math.
119
+
120
+The round-robin database needs 4 bytes for every value Netdata collects. If Netdata collects metrics every second,
121
+that's 4 bytes, per second, per metric.
122
+
123
+```text
124
+4 bytes * X seconds * Y metrics = RAM usage in bytes
125
+```
126
+
127
+Let's assume your system collects 1,000 metrics per second.
128
+
129
+```text
130
+4 bytes * 3600 seconds * 1,000 metrics = 14400000 bytes = 14.4 MB RAM
131
+```
132
+
133
+With that formula, you can calculate the RAM usage for much larger history settings.
134
+
135
+```conf
136
+# 2 hours at 1,000 metrics per second
137
+4 bytes * 7200 seconds * 1,000 metrics = 28800000 bytes = 28.8 MB RAM
138
+# 2 hours at 2,000 metrics per second
139
+4 bytes * 7200 seconds * 2,000 metrics = 57600000 bytes = 57.6 MB RAM
140
+# 4 hours at 2,000 metrics per second
141
+4 bytes * 14440 seconds * 2,000 metrics = 115520000 bytes = 115.52 MB RAM
142
+# 24 hours at 1,000 metrics per second
143
+4 bytes * 86400 seconds * 1,000 metrics = 345600000 bytes = 345.6 MB RAM
144
+```
145
+
146
+## What's next?
147
+
148
+Now that you have either configured database engine or round-robin database engine to store more metrics, you'll
149
+probably want to see it in action!
150
+
151
+For more information about how to pan charts to view historical metrics, see our documentation on [using
152
+charts](../../web/README.md#using-charts).
153
+
154
+And if you'd now like to reduce Netdata's resource usage, view our [performance guide](../Performance.md) for our best
155
+practices on optimization.
netlify.toml
+4
@@ -10,3 +10,7 @@
10
11
# Default build command.
12
command = "./buildhtml.sh"
13
+
14
+[[redirects]]
15
+ from = "/docs/GettingStarted/"
16
+ to = "/docs/getting-started"
\ No newline at end of file
packaging/installer/README.md
+3
-3
@@ -77,7 +77,7 @@ bash <(curl -Ss https://my-netdata.io/kickstart.sh) --dont-wait --dont-start-it
77
Note: `--stable-channel` and `--local-files` overlap, if you use the tarball override the stable channel option is not effective
78
</details>
79
80
-Once Netdata is installed, see [Getting Started](../../docs/GettingStarted.md).
80
+Once Netdata is installed, see [Getting Started](../../docs/getting-started.md).
81
82
---
83
@@ -149,7 +149,7 @@ sh /tmp/kickstart-static64.sh
149
150
</details>
151
152
-Once Netdata is installed, see [Getting Started](../../docs/GettingStarted.md).
152
+Once Netdata is installed, see [Getting Started](../../docs/getting-started.md).
153
154
---
155
@@ -585,7 +585,7 @@ bash kickstart-static64.sh --local-files /tmp/netdata-version-number-here.gz.run
585
```
586
587
Now that you're finished with your offline installation, you can move on to our
588
-[getting started guide](../../docs/GettingStarted.md)!
588
+[getting started guide](../../docs/getting-started.md)!
589
590
## Automatic updates
591
web/README.md
+1
-1
@@ -43,7 +43,7 @@ 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)!
46
+them using the [**My nodes** 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: