The step-by-step Netdata tutorial (#7489)
* Initial add * Parts to steps * Lots of fixes to tutorial steps, integration with docs * Fixing broken links * checklinks fix * Add to sidebar * Initial add * Parts to steps * Lots of fixes to tutorial steps, integration with docs * Fixing broken links * checklinks fix * Add to sidebar * Fixed link * Added tutorial to homepage with styling * Cleanup * Few more fixes and improvements * Final tweaks to last few steps * Let nav items wrap * Fixes for Austin and Andy * Linter error * Add text for Austin * Text about charts not showing up
Joel Hans committed
Dec 20, 2019 at 14:58 UTC
9d754e8ac3530d68dd6a54a2b39668551d5d9956
17 files changed
+2261
-28
DOCUMENTATION.md
+47
-13
@@ -1,26 +1,60 @@
1
# Netdata Documentation
2
3
-**Netdata is real-time health monitoring and performance troubleshooting for systems and applications.** It helps you instantly diagnose slowdowns and anomalies in your infrastructure with thousands of metrics, interactive visualizations, and insightful health alarms.
3
+**Netdata is real-time health monitoring and performance troubleshooting for systems and applications.** It helps you
4
+instantly diagnose slowdowns and anomalies in your infrastructure with thousands of metrics, interactive visualizations,
5
+and insightful health alarms.
6
7
## Navigating the Netdata documentation
8
7
-Welcome! You've arrived at the documentation for Netdata. Use the links below to find answers to the most common questions about Netdata, such as how to install it, getting started guides, basic configuration, and adding more charts. Or, explore all of Netdata's documentation using the table of contents to your left.
9
+Welcome! You've arrived at the documentation for Netdata. Use the links below to find answers to the most common
10
+questions about Netdata, such as how to install it, getting started guides, basic configuration, and adding more charts.
11
+Or, explore all of Netdata's documentation using the table of contents to your left.
12
13
<div class="homepage-nav">
14
11
- <div class="nav-install">
12
- <a class="nav-button" href="packaging/installer/#one-line-installation">One-line installation</a>
13
- <p>Use our completely automated one-line installation process to get Netdata on all Linux distributions. Or, find detailed instructions for binary packages, Kubernetes, macOS, and more.</p>
14
-
15
+ <div class="nav-page">
16
+ <a href="packaging/installer/">
17
+ <div class="button-header">
18
+ <h3>Installation guide</h3>
19
+ <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 448 512" height="1em" width="1em" xmlns="http://www.w3.org/2000/svg"><path d="M224.3 273l-136 136c-9.4 9.4-24.6 9.4-33.9 0l-22.6-22.6c-9.4-9.4-9.4-24.6 0-33.9l96.4-96.4-96.4-96.4c-9.4-9.4-9.4-24.6 0-33.9L54.3 103c9.4-9.4 24.6-9.4 33.9 0l136 136c9.5 9.4 9.5 24.6.1 34zm192-34l-136-136c-9.4-9.4-24.6-9.4-33.9 0l-22.6 22.6c-9.4 9.4-9.4 24.6 0 33.9l96.4 96.4-96.4 96.4c-9.4 9.4-9.4 24.6 0 33.9l22.6 22.6c9.4 9.4 24.6 9.4 33.9 0l136-136c9.4-9.2 9.4-24.4 0-33.8z"></path></svg>
20
+ </div>
21
+ <div class="button-text">
22
+ <p>Use our automated one-line installation script to install Netdata on Linux systems or find detailed instructions for binary packages, Kubernetes, Docker, macOS, and more.</p>
23
+ </div>
24
+ </a>
25
</div>
16
- <div class="nav-getting-started">
17
- <a class="nav-button" href="docs/getting-started/">Getting started guide</a>
18
- <p>The perfect place for Netdata beginners to start. Learn how to access Netdata's dashboard, start and stop the service, basic configuration, and more.</p>
19
-
26
+ <div class="nav-page">
27
+ <a href="docs/step-by-step/step-00/">
28
+ <div class="button-header">
29
+ <h3>Step-by-step tutorial</h3>
30
+ <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 448 512" height="1em" width="1em" xmlns="http://www.w3.org/2000/svg"><path d="M224.3 273l-136 136c-9.4 9.4-24.6 9.4-33.9 0l-22.6-22.6c-9.4-9.4-9.4-24.6 0-33.9l96.4-96.4-96.4-96.4c-9.4-9.4-9.4-24.6 0-33.9L54.3 103c9.4-9.4 24.6-9.4 33.9 0l136 136c9.5 9.4 9.5 24.6.1 34zm192-34l-136-136c-9.4-9.4-24.6-9.4-33.9 0l-22.6 22.6c-9.4 9.4-9.4 24.6 0 33.9l96.4 96.4-96.4 96.4c-9.4 9.4-9.4 24.6 0 33.9l22.6 22.6c9.4 9.4 24.6 9.4 33.9 0l136-136c9.4-9.2 9.4-24.4 0-33.8z"></path></svg>
31
+ </div>
32
+ <div class="button-text">
33
+ <p>Take a guided tour through each of Netdata's core features—perfect for beginners. Follow detailed instructions to monitor your systems and apps, and start your journey into performance troubleshooting.</p>
34
+ </div>
35
+ </a>
36
+ </div>
37
+ <div class="nav-page">
38
+ <a href="docs/getting-started/">
39
+ <div class="button-header">
40
+ <h3>Getting started guide</h3>
41
+ <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 448 512" height="1em" width="1em" xmlns="http://www.w3.org/2000/svg"><path d="M224.3 273l-136 136c-9.4 9.4-24.6 9.4-33.9 0l-22.6-22.6c-9.4-9.4-9.4-24.6 0-33.9l96.4-96.4-96.4-96.4c-9.4-9.4-9.4-24.6 0-33.9L54.3 103c9.4-9.4 24.6-9.4 33.9 0l136 136c9.5 9.4 9.5 24.6.1 34zm192-34l-136-136c-9.4-9.4-24.6-9.4-33.9 0l-22.6 22.6c-9.4 9.4-9.4 24.6 0 33.9l96.4 96.4-96.4 96.4c-9.4 9.4-9.4 24.6 0 33.9l22.6 22.6c9.4 9.4 24.6 9.4 33.9 0l136-136c9.4-9.2 9.4-24.4 0-33.8z"></path></svg>
42
+ </div>
43
+ <div class="button-text">
44
+ <p>Have some monitoring and system administration experience? Dive right into configuring Netdata, accessing the dashboard, working with the daemon, and changing how Netdata stores metrics.</p>
45
+ </div>
46
+ </a>
47
</div>
21
- <div class="nav-configuration">
22
- <a class="nav-button" href="docs/configuration-guide/">Configuration guide</a>
23
- <p>Take your configuration options from the <em>getting started guide</em> to the next level. Increase metrics retention, modify how charts are displayed, disable collectors, and modify alarms.</p>
48
+ <div class="nav-page">
49
+ <a href="docs/configuration-guide/">
50
+ <div class="button-header">
51
+ <h3>Configuration guide</h3>
52
+ <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 448 512" height="1em" width="1em" xmlns="http://www.w3.org/2000/svg"><path d="M224.3 273l-136 136c-9.4 9.4-24.6 9.4-33.9 0l-22.6-22.6c-9.4-9.4-9.4-24.6 0-33.9l96.4-96.4-96.4-96.4c-9.4-9.4-9.4-24.6 0-33.9L54.3 103c9.4-9.4 24.6-9.4 33.9 0l136 136c9.5 9.4 9.5 24.6.1 34zm192-34l-136-136c-9.4-9.4-24.6-9.4-33.9 0l-22.6 22.6c-9.4 9.4-9.4 24.6 0 33.9l96.4 96.4-96.4 96.4c-9.4 9.4-9.4 24.6 0 33.9l22.6 22.6c9.4 9.4 24.6 9.4 33.9 0l136-136c9.4-9.2 9.4-24.4 0-33.8z"></path></svg>
53
+ </div>
54
+ <div class="button-text">
55
+ <p>Take your configuration options from the <em>getting started guide</em> to the next level. Increase metrics retention, modify how charts are displayed, disable collectors, and modify alarms.</p>
56
+ </div>
57
+ </a>
58
</div>
59
60
</div>
docs/generator/buildyaml.sh
+4
@@ -150,6 +150,10 @@ echo -ne " - 'docs/what-is-netdata.md'
150
- 'packaging/DISTRIBUTIONS.md'
151
- 'packaging/installer/UNINSTALL.md'
152
- 'docs/getting-started.md'
153
+"
154
+navpart 1 docs/step-by-step "" "Step-by-step tutorial" 1
155
+# navpart 1 health README "Alarms and notifications"
156
+echo -ne "
157
- Running Netdata:
158
- 'daemon/README.md'
159
- 'docs/configuration-guide.md'
docs/generator/custom/css/netdata.css
+42
-9
@@ -1,6 +1,6 @@
1
-.md-nav__link {
1
+/* .md-nav__link {
2
white-space: nowrap;
3
-}
3
+} */
4
5
.md-typeset {
6
font-size: .75rem
@@ -15,20 +15,53 @@
15
/* Custom styling for the new documentation homepage.
16
In particular, the three buttons for install/getting started/configuration. */
17
.homepage-nav {
18
- display: flex;
18
+ display: grid;
19
+ grid-template-columns: repeat(4,[col-start] 1fr);
20
+ grid-gap: 2rem;
21
margin-top: 1.4rem;
22
+ margin-bottom: 2rem;
23
}
24
22
-.homepage-nav div {
23
- flex: 1;
25
+.nav-page {
26
+ grid-column: span 2;
27
+ border-radius: 3px;
28
+ border: 1px solid #EFEFEF;
29
+ box-shadow: 0 8px 48px 4px rgba(86,91,115,0.15);
30
}
31
26
-.homepage-nav .nav-install {
27
- margin-right: 1rem;
32
+.button-header {
33
+ padding: 1rem 1.4rem;
34
+ display: flex;
35
+ align-items: center;
36
+ justify-content: space-between;
37
+ background: linear-gradient( to right, #306BAC, #56B2FF 140%);
38
+ border-radius: 3px 3px 0 0;
39
}
40
30
-.homepage-nav .nav-configuration {
31
- margin-left: 1rem;
41
+.button-header h3 {
42
+ color: white;
43
+ margin: 0;
44
+}
45
+
46
+.button-header svg {
47
+ color: white;
48
+ position: relative;
49
+ transition-property: left;
50
+ transition-timing-function: ease-in-out;
51
+ transition-duration: 200ms;
52
+}
53
+
54
+.nav-page:hover svg {
55
+ left: 4px;
56
+}
57
+
58
+.button-text {
59
+ color: #35414A;
60
+ padding: 1rem 1.4rem;
61
+}
62
+
63
+.button-text p {
64
+ margin: 0;
65
}
66
67
.nav-button {
docs/getting-started.md
+5
-2
@@ -1,11 +1,14 @@
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.
3
+Thanks for trying Netdata! In this getting started guide, we'll quickly walk you through the first steps you should take
4
+after getting 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
+We'll skip right into some technical details, so if you're brand-new to monitoring the health and performance of systems
10
+and applications, our [**step-by-step tutorial**](step-by-step/step-00.md) might be a better fit.
11
+
12
> If you haven't installed Netdata yet, visit the [installation instructions](../packaging/installer) for details,
13
> including our one-liner script, which automatically installs Netdata on almost all Linux distributions.
14
docs/step-by-step/step-00.md
new
+106
@@ -0,0 +1,106 @@
1
+# The step-by-step Netdata tutorial
2
+
3
+Welcome to Netdata! We're glad you're interested in our health monitoring and performance troubleshooting system.
4
+
5
+Because Netdata is entirely open-source software, you can use it free of charge, whether you want to monitor one or ten
6
+thousand systems! All our code is hosted on [GitHub](https://github.com/netdata/netdata).
7
+
8
+This tutorial is designed to help you understand what Netdata is, what it's capable of, and how it'll help you make
9
+faster and more informed decisions about the health and performance of your systems and applications. If you're
10
+completely new to Netdata, or have never tried health monitoring/performance troubleshooting systems before, this
11
+tutorial is perfect for you.
12
+
13
+If you have monitoring experience, or would rather get straight into configuring Netdata to your needs, you can jump
14
+straight into code and configurations with our [getting started guide](../getting-started.md).
15
+
16
+> This tutorial contains instructions for Netdata installed on a Linux system. Many of the instructions will work on
17
+> other supported operating systems, like FreeBSD and MacOS, but we can't make any guarantees.
18
+
19
+## Where to go if you need help
20
+
21
+No matter where you are in this Netdata tutorial, if you need help, head over to our [GitHub
22
+repository](https://github.com/netdata/netdata/). That's where we collect questions from users, help fix their bugs, and
23
+point people toward documentation that explains what they're having trouble with.
24
+
25
+Click on the **issues** tab to see all the conversations we're having with Netdata users. Use the search bar to find
26
+previously-written advice for your specific problem, and if you don't see any results, hit the **New issue** button to
27
+send us a question.
28
+
29
+Or, if that's too complicated, feel free to send this tutorial's author [an email](mailto:joel@netdata.cloud).
30
+
31
+## Before we get started
32
+
33
+Let's make sure you have Netdata installed on your system!
34
+
35
+> If you already installed Netdata, feel free to skip to [Step 1: Netdata's building blocks](step-01.md).
36
+
37
+The easiest way to install Netdata on a Linux system is our `kickstart.sh` one-line installer. Run this on your system
38
+and let it take care of the rest.
39
+
40
+This script will install Netdata from source, keep it up to date with nightly releases, connects to the Netdata
41
+[registry](../../registry/README.md), and sends [_anonymous statistics_](../anonymous-statistics.md) about how you use
42
+Netdata. We use this information to better understand how we can improve the Netdata experience for all our users.
43
+
44
+```bash
45
+bash <(curl -Ss https://my-netdata.io/kickstart.sh)
46
+```
47
+
48
+Once finished, you'll have Netdata installed, and you'll be set up to get _nightly updates_ to get the latest features,
49
+improvements, and bugfixes.
50
+
51
+If this method doesn't work for you, or you want to use a different process, visit our [installation
52
+documentation](../../packaging/installer/README.md) for details.
53
+
54
+## Netdata fundamentals
55
+
56
+[Step 1. Netdata's building blocks](step-01.md)
57
+
58
+In this introductory step, we'll talk about the fundamental ideas, philosophies, and UX decisions behind Netdata.
59
+
60
+[Step 2. Get to know Netdata's dashboard](step-02.md)
61
+
62
+Visit Netdata's dashboard to explore, manipulate charts, and check out alarms. Get your first taste of visual anomaly
63
+detection.
64
+
65
+[Step 3. Monitor more than one system with Netdata](step-03.md)
66
+
67
+While the dashboard lets you quickly move from one agent to another, Netdata Cloud is our SaaS solution for monitoring
68
+the health of many systems. We'll cover its features and the benefits of using Netdata Cloud on top of the dashboard.
69
+
70
+[Step 4. The basics of configuring Netdata](step-04.md)
71
+
72
+While Netdata can monitor thousands of metrics in real-time without any configuration, you may _want_ to tweak some
73
+settings based on your system's resources.
74
+
75
+## Intermediate steps
76
+
77
+[Step 5. Health monitoring alarms and notifications](step-05.md)
78
+
79
+Learn how to tune, silence, and write custom alarms. Then enable notifications so you never miss a change in health
80
+status or performance anomaly.
81
+
82
+[Step 6. Collect metrics from more services and apps](step-06.md)
83
+
84
+Learn how to enable/disable collection plugins and configure a collection plugin job to add more charts to your Netdata
85
+dashboard and begin monitoring more apps and services, like MySQL, Nginx, MongoDB, and hundreds more.
86
+
87
+[Step 7. Netdata's dashboard in depth](step-07.md)
88
+
89
+Now that you configured your Netdata monitoring agent to your exact needs, you'll dive back into metrics snapshots,
90
+updates, and the dashboard's settings.
91
+
92
+## Advanced steps
93
+
94
+[Step 8. Building your first custom dashboard](step-08.md)
95
+
96
+Using simple HTML, CSS, and JavaScript, we'll build a custom dashboard that displays essential information in any format
97
+you choose. You can even monitor many systems from a single HTML file.
98
+
99
+[Step 9. Long-term metrics storage](step-09.md)
100
+
101
+Want to store lots of real-time metrics from Netdata? Tweak our custom database to your heart's content. Want to take
102
+your Netdata metrics elsewhere? We're happy to help you archive data to Prometheus, MongoDB, TimescaleDB, and others.
103
+
104
+[Step 10. Set up a proxy](step-10.md)
105
+
106
+Run Netdata behind an Nginx proxy to improve performance, and enable TLS/HTTPS for better security.
docs/step-by-step/step-01.md
new
+148
@@ -0,0 +1,148 @@
1
+# Step 1. Netdata's building blocks
2
+
3
+Netdata is a distributed and real-time _health monitoring and performance troubleshooting toolkit_ for monitoring your
4
+systems and applications.
5
+
6
+Because the monitoring agent is highly-optimized, you can install it all your physical systems, containers, IoT devices,
7
+and edge devices without disrupting their core function.
8
+
9
+By default, and without configuration, Netdata delivers real-time insights into everything happening on the system, from
10
+CPU utilization to packet loss on every network device. Netdata can also auto-detect metrics from hundreds of your
11
+favorite services and applications, like MySQL/MariaDB, Docker, Nginx, Apache, MongoDB, and more.
12
+
13
+All metrics are automatically-updated, providing interactive dashboards that allow you to dive in, discover anomalies,
14
+and figure out the root cause analysis of any issue.
15
+
16
+Best of all, Netdata is entirely free, open-source software! Solo developers and enterprises with thousands of systems
17
+can both use it free of charge. We're hosted on [GitHub](https://github.com/netdata/netdata).
18
+
19
+Want to learn about the history of Netdata, and what inspired our CEO to build it in the first place, and where we're
20
+headed? Read Costa's comprehensive blog post: _[Redefining monitoring with Netdata (and how it came to
21
+be)](https://blog.netdata.cloud/posts/redefining-monitoring-netdata/)_.
22
+
23
+## What you'll learn in this step
24
+
25
+In the first step of the Netdata guide, you'll learn about:
26
+
27
+- [Netdata's core features](#netdatas-core-features)
28
+- [Why you should use Netdata](#why-you-should-use-netdata)
29
+- [How Netdata has complementary systems, not competitors](#how-netdata-has-complementary-systems-not-competitors)
30
+
31
+Let's get started!
32
+
33
+## Netdata's core features
34
+
35
+Netdata has only been around for a few years, but it's a complex piece of software. Here are just some of the features
36
+we'll cover throughout this tutorial.
37
+
38
+- A sophisticated **dashboard**, which we'll cover in [step 2](step-02.md). The real-time, highly-granular dashboard,
39
+ with hundreds of charts, is your main source of information about the health and performance of your systems/
40
+ applications. We designed the dashboard with anomaly detection and quick analysis in mind. We'll return to
41
+ dashboard-related topics in both [step 7](step-07.md) and [step 8](step-08.md).
42
+- **Netdata Cloud** is our SaaS toolkit that helps Netdata users monitor the health and performance of entire
43
+ infrastructures, whether they are two or two thousand (or more!) systems. We'll cover Netdata Cloud in [step
44
+ 3](step-03.md).
45
+- **No configuration necessary**. Without any configuration, you'll get thousands of real-time metrics and hundreds of
46
+ alarms designed by our community of sysadmin experts. But you _can_ configure Netdata in a lot of ways, some of
47
+ which we'll cover in [step 4](step-04.md).
48
+- **Distributed, per-system installation**. Instead of centralizing metrics in one location, you install Netdata on
49
+ _every_ system, and each system is responsible for its metrics. Having distributed agents reduces cost and lets
50
+ Netdata run on devices with little available resources, such as IoT and edge devices, without affecting their core
51
+ purpose.
52
+- **Sophisticated health monitoring** to ensure you always know when an anomaly hits. In [step 5](step-05.md), we dive
53
+ into how you can tune alarms, write your own alarm, and enable two types of notifications.
54
+- **High-speed, low-resource collectors** that allow you to collect thousands of metrics every second while using only
55
+ a fraction of your system's CPU resources and a few MiB of RAM.
56
+- **Long-term metrics storage**. With our new database engine, you can store days, weeks, or months of per-second
57
+ historical metrics. Or you can archive metrics to another database, like MongoDB or Prometheus. We'll cover all
58
+ these options in [step 9](step-09.md).
59
+
60
+## Why you should use Netdata
61
+
62
+Because you care about the health and performance of your systems and applications, and all of the awesome features we
63
+just mentioned. And it's free!
64
+
65
+All these may be valid reasons, but let's step back and talk about Netdata's _principles_ for health monitoring and
66
+performance troubleshooting. We have a lot of [complementary
67
+systems](#how-netdata-has-complementary-systems-not-competitors), and we think there's a good reason why Netdata should
68
+always be your first choice when troubleshooting an anomaly.
69
+
70
+We built Netdata on four principles.
71
+
72
+### Per-second data collection
73
+
74
+Our first principle is per-second data collection for all metrics.
75
+
76
+That matters because you can't monitor a 2-second service-level agreement (SLA) with 10-second metrics. You can't detect
77
+quick anomalies if your metrics don't show them.
78
+
79
+How do we solve this? By decentralizing monitoring. Each node is responsible for collecting metrics, triggering alamrs,
80
+and building dashboards locally, and we work hard to ensure it does each step (and others) with remarkable efficiency.
81
+For example, Netdata can [collect 100,000 metrics](https://github.com/netdata/netdata/issues/1323) every second while
82
+using only 9% of a single server-grade CPU core!
83
+
84
+By decentralizing monitoring and emphasizing speed at every turn, Netdata helps you scale your health monitoring and
85
+performance troubleshooting to an infrastructure of every size. _And_ you get to keep per-second metrics.
86
+
87
+### Unlimited metrics
88
+
89
+We believe all metrics are fundamentally important, and all metrics should be available to the user.
90
+
91
+If you don't collect _all_ the metrics a system creates, you're only seeing part of the story. It's like saying you've
92
+read a book after skipping all but the last ten pages. You only know the ending, not everything that leads to it.
93
+
94
+Most monitoring solutions exist to poke you when there's a problem, and then tell you to use a dozen different console
95
+tools to find the root cause. Netdata prefers to give you every piece of information you might need to understand why an
96
+anomaly happened.
97
+
98
+### Meaningful presentation
99
+
100
+We want every piece of Netdata's dashboard not only to look good and update every second, but also provide context as to
101
+what you're looking at and why it matters.
102
+
103
+The principle of meaningful presentation is fundamental to our dashboard's user experience (UX). We could have put
104
+charts in a grid or hidden some behind tabs or buttons. We instead chose to stack them vertically, on a single page, so
105
+you can visually see how, for example, a jump in disk usage can also increase system load.
106
+
107
+Here's an example of a system undergoing a disk stress test:
108
+
109
+
111
+
112
+> For the curious, here's the command: `stress-ng --fallocate 4 --fallocate-bytes 4g --timeout 1m --metrics --verify
113
+> --times`!
114
+
115
+### Immediate results
116
+
117
+Finally, Netdata should be usable from the moment you install it.
118
+
119
+As we've talked about, and as you'll learn in the following nine steps, Netdata comes installed with:
120
+
121
+- Auto-detected metrics
122
+- Human-readable units
123
+- Metrics that are structured into charts, families, and contexts
124
+- Automatically generated dashboards
125
+- Charts designed for visual anomaly detection
126
+- Hundreds of pre-configured alarms
127
+
128
+By standardizing your monitoring infrastructure, Netdata tries to make at least one part of your administrative tasks
129
+easy!
130
+
131
+## How Netdata has complementary systems, not competitors
132
+
133
+We'll cover this quickly, as you're probably eager to get on with using Netdata itself.
134
+
135
+We don't want to lock you in to using Netdata by itself, and forever. By supporting [archiving to
136
+backends](../../backends/README.md) like Graphite, Prometheus, OpenTSDB, MongoDB, and others, you can use Netdata _in
137
+conjunction_ with software that might seem like our competitors.
138
+
139
+We don't want to "wage war" with another monitoring solution, whether it's commercial, open-source, or anything in
140
+between. We just want to give you all the metrics every second, and what you do with them next is your business, not
141
+ours. Our mission is helping people create more extraordinary infrastructures!
142
+
143
+## What's next?
144
+
145
+We think it's imperative you understand why we built Netdata the way we did. But now that we have that behind us, let's
146
+get right into that dashboard you've heard so much about.
147
+
148
+[Next: Get to know Netdata's dashboard →](step-02.md)
docs/step-by-step/step-02.md
new
+210
@@ -0,0 +1,210 @@
1
+# Step 2. Get to know Netdata's dashboard
2
+
3
+Welcome to Netdata proper! Now that you understand how Netdata works, how it's built, and why we built it, you can start
4
+working with the dashboard directly.
5
+
6
+This step-by-step guide assumes you've already installed Netdata on a system of yours. If you haven't yet, hop back over
7
+to ["step 0"](step-00.md#before-we-get-started) for information about our one-line installer script. Or, view the
8
+[installation docs](../../packaging/installer) to learn more. Once you have Netdata installed, you can hop back over
9
+here and dig in.
10
+
11
+## What you'll learn in this step
12
+
13
+In this step of the Netdata guide, you'll learn how to:
14
+
15
+- [Visit and explore the dashboard](#visit-and-explore-the-dashboard)
16
+- [Explore available charts using menus](#explore-available-charts-using-menus)
17
+- [Read the descriptions accompanying charts](#read-the-descriptions-accompanying-charts)
18
+- [Interact with charts](#interact-with-charts)
19
+- [See raised alarms and the alarm log](#see-raised-alarms-and-the-alarm-log)
20
+
21
+Let's get started!
22
+
23
+## Visit and explore the dashboard
24
+
25
+Netdata's dashboard is where you interact with your system's metrics. Time to open it up and start exploring. Open up
26
+your browser of choice.
27
+
28
+If you installed Netdata on the same system you're using to open your browser, navigate to `http://localhost:19999/`.
29
+
30
+If you installed Netdata on a remote system, navigate to `http://HOST:19999/` after replacing `HOST` with the IP address
31
+of that system. To connect to a virtual private server (VPS), for example, you might navigate to
32
+`http://203.0.113.0:19999`. We'll learn more on monitoring remote systems and [multiple systems](step-03.md)
33
+later on.
34
+
35
+> From here on out in this tutorial, we'll refer to the address you use to view your dashboard as `HOST`. Be sure to
36
+> replace it with either `localhost` or the IP address as needed.
37
+
38
+Hit `Enter`. Welcome to Netdata!
39
+
40
+
42
+
43
+## Explore available charts using menus
44
+
45
+**Menus** are located on the right-hand side of the Netdata dashboard. You can use these to navigate to the
46
+charts you're interested in.
47
+
48
+
50
+
51
+Netdata shows all its charts on a single page, so you can also scroll up and down using the mouse wheel, your
52
+touchscreen/touchpad, or the scrollbar.
53
+
54
+Both menus and the items displayed beneath them, called **submenus**, are populated automatically by Netdata based on
55
+what it's collecting. If you run Netdata on many different systems using different OS types or versions, the
56
+menus and submenus may look a little different for each one.
57
+
58
+To learn more about menus, see our documentation about [navigating the standard
59
+dashboard](../../web/gui/README.md#menus).
60
+
61
+> ❗ By default, Netdata only creates and displays charts if the metrics are _not zero_. So, you may be missing some
62
+> charts, menus, and submenus if those charts have zero metrics. You can change this by changing the **Which dimensions
63
+> to show?** setting to **All**. In addition, if you start Netdata and immediately load the dashboard, not all
64
+> charts/menus/submenus may be displayed, as some collectors can take a while to initialize.
65
+
66
+## Read the descriptions accompanying charts
67
+
68
+Many charts come with a short description of what dimensions the chart is displaying and why they matter.
69
+
70
+For example, here's the description that accompanies the **swap** chart.
71
+
72
+
74
+
75
+If you're new to health monitoring and performance troubleshooting, we recommend you spend some time reading these
76
+descriptions and learning more at the pages linked above.
77
+
78
+## Understand charts, dimensions, families, and contexts
79
+
80
+A **chart** is an interactive visualization of one or more collected/calculated metrics. You can see the name (also
81
+known as its unique ID) of a chart by looking at the top-left corner of a chart and finding the parenthesized text. On a
82
+Linux system, one of the first charts on the dashboard will be the system CPU chart, with the name `system.cpu`:
83
+
84
+
86
+
87
+A **dimension** is any value that gets shown on a chart. The value can be raw data or calculated values, such as
88
+percentages, aggregates, and more. Most charts will have more than one dimension, in which case it will display each in
89
+a different color. Here, a `system.cpu` chart is showing many dimensions, such as `user`, `system`, `softirq`, `irq`,
90
+and more.
91
+
92
+
94
+
95
+A **family** is _one_ instance of a monitored hardware or software resource that needs to be monitored and displayed
96
+separately from similar instances. For example, if your system has multiple partitions, Netdata will create different
97
+families for `/`, `/boot`, `/home`, and so on. Same goes for entire disks, network devices, and more.
98
+
99
+
100
+
101
+A **context** groups several charts based on the types of metrics being collected and displayed. For example, the
102
+**Disk** section often has many contexts: `disk.io`, `disk.ops`, `disk.backlog`, `disk.util`, and so on. Netdata uses
103
+this context to create individual charts and then groups them by family. You can always see the context of any chart by
104
+looking at its name or hovering over the chart's date.
105
+
106
+It's important to understand these differences, as Netdata uses charts, dimensions, families, and contexts to create
107
+health alarms and configure collectors. To read even more about the differences between all these elements of the
108
+dashboard, and how they affect other parts of Netdata, read our [dashboards
109
+documentation](../../web/README.md#charts-contexts-families).
110
+
111
+## Interact with charts
112
+
113
+We built Netdata to be a big sandbox for learning more about your systems and applications. Time to play!
114
+
115
+Netdata's charts are fully interactive. You can pan through historical metrics, zoom in and out, select specific
116
+timeframes for further analysis, resize charts, and more.
117
+
118
+Best of all, Whenever you use a chart in this way, Netdata synchronizes all the other charts to match it. This even
119
+applies across different Netdata agents if you connect them using the [**My nodes** menu](../../registry/README.md)!
120
+
121
+
123
+
124
+### Pan, zoom, highlight, and reset charts
125
+
126
+You can change how charts show their metrics in a few different ways, each of which have a few methods:
127
+
128
+| Change | Method #1 | Method #2 | Method #3 |
129
+| ------------------------------------------------- | ----------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------- |
130
+| **Reset** charts to default auto-refreshing state | `double click` | `double tap` (touchpad/touchscreen) | |
131
+| **Select** a certain timeframe | `ALT` + `mouse selection` | `⌘` + `mouse selection` (macOS) | |
132
+| **Pan** forward or back in time | `click and drag` | `touch and drag` (touchpad/touchscreen) | |
133
+| **Zoom** to a specific timeframe | `SHIFT` + `mouse selection` | | |
134
+| **Zoom** in/out | `SHIFT`/`ALT` + `mouse scrollwheel` | `SHIFT`/`ALT` + `two-finger pinch` (touchpad/touchscreen) | `SHIFT`/`ALT` + `two-finger scroll` (touchpad/touchscreen) |
135
+
136
+These interactions can also be triggered using the icons on the bottom-right corner of every chart. They are,
137
+respectively, `Pan Left`, `Reset`, `Pan Right`, `Zoom In`, and `Zoom Out`.
138
+
139
+
141
+
142
+### Show and hide dimensions
143
+
144
+Each dimension can be hidden by clicking on it. Hiding dimensions simplifies the chart and can help you better discover
145
+exactly which aspect of your system is behaving strangely.
146
+
147
+### Resize charts
148
+
149
+Additionally, resize charts by clicking-and-dragging the icon on the bottom-right corner of any chart. To restore the
150
+chart to its original height, double-click the same icon.
151
+
152
+
154
+
155
+To learn more about other options and chart interactivity, read our [dashboard documentation](../../web/README.md).
156
+
157
+## See raised alarms and the alarm log
158
+
159
+Aside from performance troubleshooting, Netdata is designed to help you monitor the health of your systems and
160
+applications. That's why every Netdata installation comes with dozens of pre-configured alarms that trigger alerts when
161
+your system starts acting strangely.
162
+
163
+Find the **Alarms** button in the top navigation bring up a modal that shows currently raised alarms, all running
164
+alarms, and the alarms log.
165
+
166
+Here is an example of raised `disk_space._` and `disk_space._home` alarms, followed by the full list and alarm log:
167
+
168
+
170
+
171
+Let's look at one of those raised alarms a little more in-depth. Here is a static screenshot:
172
+
173
+
175
+
176
+The alarm itself is named **disk - /**, and its context is `disk_space._`. Beneath that is an auto-updating badge that
177
+shows the latest metric: 28.4% disk space usage.
178
+
179
+With the three icons beneath that and the **role** designation, you can **1)** scroll to the chart associated with this
180
+raised alarm, **2)** copy a link to the badge to your clipboard, and **3)** copy the code to embed the badge onto
181
+another web page using an `<embed>` element.
182
+
183
+The table on the right-hand side displays information about the alarm's configuration.
184
+
185
+In this example, Netdata triggers a warning alarm when any disk on the system is more than 20% full. Netdata triggers a
186
+critical alarm when the disk is more than 30% full.
187
+
188
+The `calculation` field is the equation used to calculate those percentages, and the `check every` field specifies how
189
+often Netdata should be calculating these metrics to see if the alarm should remain triggered.
190
+
191
+The `execute` field tells Netdata how to notify you about this alarm, and the `source` field lets you know where you can
192
+find the configuration file, if you'd like to edit its configuration.
193
+
194
+We'll cover alarm configuration in more detail later in the tutorial, so don't worry about it too much for now! Right
195
+now, it's most important that you understand how to see alarms, and parse their details, if and when they appear on your
196
+system.
197
+
198
+## What's next?
199
+
200
+In this step of the Netdata tutorial, you learned how to:
201
+
202
+- Visit the dashboard
203
+- Explore available charts (using the right-side menu)
204
+- Read the descriptions accompanying charts
205
+- Interact with charts
206
+- See raised alarms and the alarm log
207
+
208
+Next, you'll learn how to monitor multiple nodes through the dashboard.
209
+
210
+[Next: Monitor more than one system with Netdata →](step-03.md)
docs/step-by-step/step-03.md
new
+168
@@ -0,0 +1,168 @@
1
+# Step 3. Monitor more than one system with Netdata
2
+
3
+The Netdata agent is _distributed_ by design. That means each agent operates independently from any other, collecting
4
+and creating charts only for the system you installed it on. We made this decision a long time ago to [improve security
5
+and performance](step-01.md).
6
+
7
+You might be thinking, "So, now I have to remember all these IP addresses, and type them into my browser
8
+manually, to move from one system to another? Maybe I should just make a bunch of bookmarks. What's a few more tabs
9
+on top of the hundred I have already? 🤬"
10
+
11
+We get it. That's why we built [Netdata Cloud](../netdata-cloud/README.md), which connects many distributed agents
12
+together for a seamless experience when monitoring multiple systems.
13
+
14
+All without remembering IPs or making a bunch of bookmarks.
15
+
16
+> If you're interested in streaming the metrics from one Netdata agent to another, that's unfortunately not part of this
17
+> tutorial. You'll want to reference our [streaming documentation](../../streaming/README.md) when you're finished with
18
+> these steps.
19
+
20
+Even if you don't have multiple systems right now, keep reading. The instructions to follow will show you how to test
21
+out these features with Netdata demo servers. That way, you'll be able to experience one of Netdata's defining features
22
+right away.
23
+
24
+## What you'll learn in this step
25
+
26
+In this step of the Netdata guid, we'll talk about the following:
27
+
28
+- [Why you should use Netdata Cloud](#why-use-netdata-cloud)
29
+- [Add nodes to your Netdata Cloud account](#add-nodes-to-your-netdata-cloud-account)
30
+- [Navigate between your nodes via the **My nodes** menu](#navigate-between-your-nodes-via-the-my-nodes-menu)
31
+- [Try out the Nodes View](#try-out-the-nodes-view)
32
+
33
+## Why use Netdata Cloud?
34
+
35
+We built Netdata Cloud to give users a way to bridge the gap between many distributed agents running concurrently, all
36
+without creating a centralized database for all your systems' metrics.
37
+
38
+> Read more: [_Introducing Netdata Cloud: our vision for distributed health and performance
39
+> monitoring_](https://blog.netdata.cloud/posts/netdata-cloud-announcement/).
40
+
41
+Netdata Cloud gives you a better way to observe and take action on slowdowns, anomalies, or outages in your systems and
42
+applications. It connects all your Netdata agents through your _web browser_, allowing you to move between different
43
+nodes quickly and use the Nodes View to see a handful or hundreds of Netdata-monitored nodes on a single screen.
44
+
45
+If you're keeping tabs on multiple systems with Netdata, Netdata Cloud gives you all the benefits of a centralized
46
+monitoring solution while distributing the workload to each agent.
47
+
48
+That makes Netdata Cloud both comprehensive and lightweight. The best of both worlds!
49
+
50
+And, better yet, Netdata Cloud doesn't store any of your system's metrics. It stores _metadata_ about the system's IP,
51
+hostname, and a randomly-created GUID, and nothing else. Metrics are streamed from your systems directly to your _web
52
+browser_.
53
+
54
+Essentially, your web browser hosts a SaaS application with all of Netdata Cloud's features embedded right into the
55
+dashboard itself.
56
+
57
+## Add nodes to your Netdata Cloud account
58
+
59
+The best way to add nodes to your Netdata Cloud account is to click on the **Sign in** button on the top-right corner of
60
+your Netdata dashboard.
61
+
62
+That button will open a new tab in for Netdata Cloud, and will prompt you to log-in using email or authentication via
63
+Google or GitHub.
64
+
65
+If you chose email, Netdata Cloud will send you a "magic link" via email. Once you click on the link, that node will be
66
+connected to your Netdata Cloud account and you'll be redirected back to your dashboard. If you chose Google or GitHub,
67
+you'll be redirected back to your dashboard as soon as authentication is finished.
68
+
69
+Here's what authentication via Google looks like:
70
+
71
+
73
+
74
+Depending on your authentication method, your email address or name will appear in the top right of your dashboard
75
+instead of the **Sign in** button.
76
+
77
+At this point, you've successfully added a single Netdata agent to your Netdata Cloud account. _What about the rest?_
78
+
79
+Well, all you have to do is visit another node and repeat the sign-in process.
80
+
81
+Let's use a demo system as an example.
82
+
83
+Visit the [Netdata website](https://www.netdata.cloud/#live-demo) and click on any of the gauge charts displayed
84
+underneath the **Live Demo** header.
85
+
86
+Once the dashboard loads, repeat the Netdata Cloud sign-in process. The demo server is now associated with your Netdata
87
+Cloud account, and will appear in your **My nodes** menu.
88
+
89
+Here's how the process looks in action:
90
+
91
+
93
+
94
+## Navigate between your nodes via the My nodes menu
95
+
96
+Once you have multiple nodes added to Netdata Cloud, they will populate your **My nodes** menu. You can use this menu to
97
+navigate between your systems quickly.
98
+
99
+
101
+
102
+Whenever you pan, zoom, highlight, select, or pause a chart, Netdata will synchronize those settings with any other
103
+agent you visit via the My nodes menu. Even your scroll position is synchronized, so you'll see the same charts and
104
+respective data for easy comparisons or root cause analysis.
105
+
106
+You can now seamlessly track performance anomalies across your entire infrastructure!
107
+
108
+## Try out the Nodes View
109
+
110
+Next, let's try out the Nodes View.
111
+
112
+Nodes View is a feature built in to Netdata Cloud that offers a different interface for viewing the health status of
113
+multiple nodes.
114
+
115
+> Learn more about all the features within Nodes View and what charts/metrics are represented there in our
116
+> [documentation](../netdata-cloud/nodes-view.md).
117
+
118
+You can visit Nodes View by navigating to `https://netdata.cloud/console` in your browser. Or, you can click on the
119
+**Nodes View** button in any Netdata dashboard. If you're not logged in to Netdata Cloud yet, you'll be asked to log in
120
+first.
121
+
122
+
124
+
125
+The Nodes View shows an aggregated list of the nodes you connected to Netdata Cloud, and shows at-a-glance health status
126
+for each.
127
+
128
+Click on any of the boxes representing your nodes to see real-time, per-second charts of essential metrics in the **Node
129
+overview** sidebar.
130
+
131
+
133
+
134
+You can also view raised alarms and see real-time metrics from a [select number of
135
+services/applications](../netdata-cloud/nodes-view.md#services-available-in-the-nodes-view) using the various tabs
136
+available in the node overview sidebar.
137
+
138
+If you add a large number of nodes to the Nodes View, you may want to look into the different view and sorting options.
139
+You can choose between **full**, **compact**, and **detailed** view modes.
140
+
141
+
143
+
144
+You can also sort between grouping nodes by hostname, recently viewed, or most frequestly visited. Or, group them by
145
+alarm status, their services, or whether they're online or unreachable.
146
+
147
+
149
+
150
+Play around until you find the right settings for you and your infrastructure.
151
+
152
+### Remove a node from Nodes View
153
+
154
+If you want to clean up your Nodes View a bit, you can remove them from your Netdata Cloud account.
155
+
156
+Click on the node in question, and then scroll to the bottom of the Node overiew sidebar. You'll see a URL under the
157
+**Node URLs** heading. Hover over the URL and click on the garbage bin icon. Click **Confirm** on the modal window.
158
+Then, click the **Forget** button that appears in the sidebar, and hit **Confirm** once again.
159
+
160
+
161
+
162
+## What's next?
163
+
164
+Now that you know how to add multiple nodes to your Netdata Cloud agent and navigate between them, it's time to learn
165
+more about how you can configure Netdata to your liking. From there, you'll be able to customize your Netdata experience
166
+to your exact infrastructure and the information you need.
167
+
168
+[Next: The basics of configuring Netdata →](step-04.md)
docs/step-by-step/step-04.md
new
+134
@@ -0,0 +1,134 @@
1
+# Step 4. The basics of configuring Netdata
2
+
3
+Welcome to the fourth step of the Netdata tutorial.
4
+
5
+Since the beginning, we've covered the building blocks of Netdata, dashboard basics, and how you can monitor many
6
+individual systems using many distributed Netdata agents.
7
+
8
+Next up: configuration.
9
+
10
+## What you'll learn in this step
11
+
12
+We'll talk about Netdata's default configuration, and then you'll learn how to do the following:
13
+
14
+- [Find your `netdata.conf` file](#find-your-netdataconf-file)
15
+- [Use edit-config to open `netdata.conf`](#use-edit-config-to-open-netdataconf)
16
+- [Navigate the structure of `netdata.conf`](#the-structure-of-netdataconf)
17
+- [Edit your `netdata.conf` file](#edit-your-netdataconf-file)
18
+
19
+## Find your `netdata.conf` file
20
+
21
+Netdata primarily uses the `netdata.conf` file to configure its core functionality. `netdata.conf` resides within your
22
+**Netdata config directory**.
23
+
24
+The location of that directory and `netdata.conf` depends on your operating system and the method you used to install
25
+Netdata.
26
+
27
+The most reliable method of finding your Netdata config directory is loading your `netdata.conf` on your browser. Open a
28
+tab and navigate to `http://HOST:19999/netdata.conf`. Your browser will load a text document that looks like this:
29
+
30
+
32
+
33
+Look for the line that begins with `# config directory = `. The text after that will be the path to your Netdata config
34
+directory.
35
+
36
+In the system represented by the screenshot, the line reads: `config directory = /etc/netdata`. That means
37
+`netdata.conf`, and all the other configuration files, can be found at `/etc/netdata`.
38
+
39
+> For more details on where your Netdata config directory is, take a look at our [installation
40
+> instructions](../../packaging/installer/).
41
+
42
+For the rest of this tutorial, we'll assume you're editing files or running scripts from _within_ your **Netdata
43
+configuration directory**.
44
+
45
+## Use edit-config to open `netdata.conf`
46
+
47
+Inside your Netdata config directory, there is a helper scripted called `edit-config`. This script will open existing
48
+Netdata configuration files using a text editor. Or, if the configuration file doesn't yet exist, the script will copy
49
+an example file to your Netdata config directory and then allow you to edit it before saving it.
50
+
51
+> `edit-config` will use the `EDITOR` environment variable on your system to edit the file. On many systems, that is
52
+> defaulted to `vim` or `nano`. We highly recommend `nano` for beginners. To change this variable for the current
53
+> session (it will revert to the default when you reboot), export a new value: `export EDITOR=nano`. Or, [make the
54
+> change permanent](https://stackoverflow.com/questions/13046624/how-to-permanently-export-a-variable-in-linux).
55
+
56
+Let's give it a shot. Navigate to your Netdata config directory. To use `edit-config` on `netdata.conf`, you need to
57
+have permissions to edit the file. On Linux/MacOS systems, you can usually use `sudo` to elevate your permissions.
58
+
59
+```bash
60
+cd /etc/netdata # Replace this path with your Netdata config directory as found in the steps above
61
+sudo ./edit-config netdata.conf
62
+```
63
+
64
+You should now see `netdata.conf` your editor! Let's walk through how the file is structured.
65
+
66
+## The structure of `netdata.conf`
67
+
68
+There are two main parts of the file to note: **sections** and **options**.
69
+
70
+The `netdata.conf` file is broken up into various **sections**, such as `[global]`, `[web]`, and `[registry]`. Each
71
+section contains the configuration options for some core component of Netdata.
72
+
73
+Each section also contains many **options**. Options have a name and a value. With the option `config directory =
74
+/etc/netdata`, `config directory` is the name, and `/etc/netdata` is the value.
75
+
76
+Most lines are **commented**, in that they start with a hash symbol (`#`), and the value is set to a sane default. To
77
+tell Netdata that you'd like to change any option from its default value, you must **uncomment** it by removing that
78
+hash.
79
+
80
+### Edit your `netdata.conf` file
81
+
82
+Let's try editing the options in `netdata.conf` to see how the process works.
83
+
84
+First, add a fake option to show you how Netdata loads its configuration files. Add a `test` option under the `[global]`
85
+section and give it the value of `1`.
86
+
87
+```conf
88
+[global]
89
+ test = 1
90
+```
91
+
92
+Restart Netdata with `service restart netdata` or the [appropriate
93
+alternative](../getting-started.md#start-stop-and-restart-netdata) for your system.
94
+
95
+Now, open up your browser and navigate to `http://HOST:19999/netdata.conf`. You'll see that Netdata has recognized
96
+that our fake option isn't valid and added a notice that Netdata will ignore it.
97
+
98
+Here's the process in GIF form!
99
+
100
+
102
+
103
+Now, let's make a slightly more substantial edit to `netdata.conf`—change the agent's name.
104
+
105
+If you edit the value of the `hostname` option, you can change the name of your Netdata agent on the dashboard and a
106
+handful of other places, like the **My nodes** menu.
107
+
108
+Use `edit-config` to change the `hostname` option to a name like `hello-world`. Be sure to uncomment it!
109
+
110
+```conf
111
+[global]
112
+ hostname = hello-world
113
+```
114
+
115
+Once you're done, restart Netdata and refresh the dashboard. Say hello to your renamed agent!
116
+
117
+
119
+
120
+Netdata has dozens upon dozens of options you can change. To see them all, read our [daemon configuration](../../daemon/config/).
121
+
122
+## What's next?
123
+
124
+At this point, you should be comfortable with getting to your Netdata directory, opening and editing `netdata.conf`, and
125
+seeing your changes reflected in the dashboard.
126
+
127
+Netdata has many more configuration files that you might want to change, but we'll cover those in the following steps of
128
+this tutorial.
129
+
130
+In the next step, we're going to cover one of Netdata's core functions: monitoring the health of your systems via alarms
131
+and notifications. You'll learn how to disable alarms, create new ones, and push notifications to the system of your
132
+choosing.
133
+
134
+[Next: Health monitoring alarms and notifications →](step-05.md)
docs/step-by-step/step-05.md
new
+341
@@ -0,0 +1,341 @@
1
+# Step 5. Health monitoring alarms and notifications
2
+
3
+In the fifth step of the Netdata tutorial, we're introducing you to one of our core features: **health monitoring**.
4
+
5
+To accurately monitor the health of your systems and applications, you need to know _immediately_ when there's something
6
+strange going on. Netdata's alarm and notification systems are essential to keeping you informed.
7
+
8
+Netdata comes with hundreds of pre-configured alarms that don't require configuration. They were designed by our
9
+community of system adminstrators to cover the most important parts of production systems, so, in many cases, you won't
10
+need to edit them.
11
+
12
+Luckily, Netdata's alarm and notification system are incredibly adaptable to your infrastructure's unique needs.
13
+
14
+## What you'll learn in this step
15
+
16
+We'll talk about Netdata's default configuration, and then you'll learn how to do the following:
17
+
18
+- [Tune Netdata's pre-configured alarms](#tune-netdatas-pre-configured-alarms)
19
+- [Write your first health entity](#write-your-first-health-entity)
20
+- [Enable Netdata's notification systems](#enable-netdatas-notification-systems)
21
+
22
+## Tune Netdata's pre-configured alarms
23
+
24
+First, let's tune an alarm that came pre-configured with your Netdata installation.
25
+
26
+The first chart you see on any Netdata dashboard is the `system.cpu` chart, which shows the system's CPU utilization
27
+across all cores. To figure out which file you need to edit to tune this alarm, click the **Alarms** button at the top
28
+of the dashboard, click on the **All** tab, and find the **system - cpu** alarm entity.
29
+
30
+
32
+
33
+Look at the `source` row in the table. This means the `system.cpu` chart sources its health alarms from
34
+`4@/usr/lib/netdata/conf.d/health.d/cpu.conf`. To tune these alarms, you'll need to edit the alarm file at
35
+`health.d/cpu.conf`. Go to your [Netdata config directory](step-04.md#find-your-netdataconf-file) and use the
36
+`edit-config` script.
37
+
38
+```bash
39
+sudo ./edit-config health.d/cpu.conf
40
+```
41
+
42
+The first **health entity** in that file looks like this:
43
+
44
+```yaml
45
+template: 10min_cpu_usage
46
+ on: system.cpu
47
+ os: linux
48
+ hosts: *
49
+ lookup: average -10m unaligned of user,system,softirq,irq,guest
50
+ units: %
51
+ every: 1m
52
+ warn: $this > (($status >= $WARNING) ? (75) : (85))
53
+ crit: $this > (($status == $CRITICAL) ? (85) : (95))
54
+ delay: down 15m multiplier 1.5 max 1h
55
+ info: average cpu utilization for the last 10 minutes (excluding iowait, nice and steal)
56
+ to: sysadmin
57
+```
58
+
59
+Let's say you want to tune this alarm to trigger warning and critical alarms at a lower CPU utilization. You can change
60
+the `warn` and `crit` lines to the values of your choosing. For example:
61
+
62
+```yaml
63
+ warn: $this > (($status >= $WARNING) ? (60) : (75))
64
+ crit: $this > (($status == $CRITICAL) ? (75) : (85))
65
+```
66
+
67
+You _can_ [restart Netdata](../getting-started.md#start-stop-and-restart-netdata) to enable your tune, but you can also
68
+send a signal to Netdata to reload _only_ the health monitoring component.
69
+
70
+```bash
71
+killall -USR2 netdata
72
+```
73
+
74
+You can also tune any other aspect of the default alarms. To better understand how each line in a health entity works,
75
+read our [health documentation](../../health/).
76
+
77
+### Silence an individual alarm
78
+
79
+Many Netdata users don't need all the default alarms enabled. Instead of disabling any given alarm, or even _all_
80
+alarms, you can silence individual alarms by changing one line in a given health entity. Let's look at that
81
+`health/cpu.conf` file again.
82
+
83
+```yaml
84
+template: 10min_cpu_usage
85
+ on: system.cpu
86
+ os: linux
87
+ hosts: *
88
+ lookup: average -10m unaligned of user,system,softirq,irq,guest
89
+ units: %
90
+ every: 1m
91
+ warn: $this > (($status >= $WARNING) ? (75) : (85))
92
+ crit: $this > (($status == $CRITICAL) ? (85) : (95))
93
+ delay: down 15m multiplier 1.5 max 1h
94
+ info: average cpu utilization for the last 10 minutes (excluding iowait, nice and steal)
95
+ to: sysadmin
96
+```
97
+
98
+To silence this alarm, change `sysadmin` to `silent`.
99
+
100
+```yaml
101
+ to: silent
102
+```
103
+
104
+Use `killall -USR2 netdata` to reload your health configuration. You can add `to: silence` to any alarm you'd rather not
105
+bother you with notifications.
106
+
107
+## Write your first health entity
108
+
109
+The best way to understand how health entities work is building your own and experimenting with the options. To start,
110
+let's build a health entity that triggers an alarm when system RAM usage goes above 80%.
111
+
112
+The first line in a health entity will be `alarm:`. This is how you name your entity. You can give it any name you
113
+choose, but the only symbols allowed are `.` and `_`. Let's call the alarm `ram_usage`.
114
+
115
+```yaml
116
+ alarm: ram_usage
117
+```
118
+
119
+> You'll see some funky indentation in the lines coming up. Don't worry about it too much! Indentation is not important
120
+> to how Netdata processes entities, and it will make sense when you're done.
121
+
122
+Next, you need to specify which chart this entity listens via the `on:` line. You're declaring that you want this alarm
123
+to check metrics on the `system.ram` chart.
124
+
125
+```yaml
126
+ on: system.ram
127
+```
128
+
129
+Now comes the `lookup`. This line specifies what metrics the alarm is looking for, what duration of time it's looking
130
+at, and how to process the metrics into a more usable format.
131
+
132
+```yaml
133
+lookup: average -1m percentage of used
134
+```
135
+
136
+Let's take a moment to break this line down.
137
+
138
+- `average`: Calculate the average of all the metrics collected.
139
+- `-1m`: Use metrics from 1 minute ago until now to calculate that average.
140
+- `percentage`: Clarify that you want to calculate a percentage of RAM usage.
141
+- `of used`: Specify which dimension (`used`) on the `system.ram` chart you want to monitor with this entity.
142
+
143
+In other words, you're taking 1 minute's worth of metrics from the `used` dimension on the `system.ram` chart,
144
+calculating their average, and returning it as a percentage.
145
+
146
+You can move on to the `units` line, which lets Netdata know that we're working with a percentage and not an absolute
147
+unit.
148
+
149
+```yaml
150
+ units: %
151
+```
152
+
153
+Next, the `every` line tells Netdata how often to perform the calculation you specified in the `lookup` line. For
154
+certain alarms, you might want to use a shorter duration, which you can specify using values like `10s`.
155
+
156
+```yaml
157
+ every: 1m
158
+```
159
+
160
+We'll put the next two lines—`warn` and `crit`—together. In these lines, you declare at which percentage you want to
161
+trigger a warning or critical alarm. Notice the variable `$this`, which is the value calculated by the `lookup` line.
162
+These lines will trigger a warning if that average RAM usage goes above 80%, and a critical alert if it's above 90%.
163
+
164
+```yaml
165
+ warn: $this > 80
166
+ crit: $this > 90
167
+```
168
+
169
+> ❗ Most default Netdata alarms come with more complicated `warn` and `crit` lines. You may have noticed the line `warn:
170
+> $this > (($status >= $WARNING) ? (75) : (85))` in one of the health entity examples above, which is an example of
171
+> using the [conditional operator for
172
+> hysteresis](https://docs.netdata.cloud/health/reference/#special-use-of-the-conditional-operator). Hysteresis is used
173
+> to keep Netdata from triggering a ton of alerts if the metric being tracked quickly goes above and then falls below
174
+> the threshold. For this very simple example, we'll skip hysteresis, but recommend implementing it in your future
175
+> health entities.
176
+
177
+Finish off with the `info` line, which creates a description of the alarm that will then appear in any
178
+[notification](#enable-netdatas-notification-systems) you set up. This line is optional, but it has value—think of it as
179
+documentation for a health entity!
180
+
181
+```yaml
182
+ info: The percentage of RAM being used by the system.
183
+```
184
+
185
+Here's what the entity looks like in full. Now you can see why we indented the lines, too.
186
+
187
+```yaml
188
+ alarm: ram_usage
189
+ on: system.ram
190
+lookup: average -1m percentage of used
191
+ units: %
192
+ every: 1m
193
+ warn: $this > 80
194
+ crit: $this > 90
195
+ info: The percentage of RAM being used by the system.
196
+```
197
+
198
+What about what it looks like on the Netdata dashboard?
199
+
200
+
201
+
202
+If you'd like to try this alarm on your system, you can install a small program called
203
+[stress](http://manpages.ubuntu.com/manpages/disco/en/man1/stress.1.html) to create a synthetic load. Use the command
204
+below, and change the `8G` value to a number that's appropriate for the amount of RAM on your system.
205
+
206
+```bash
207
+stress -m 1 --vm-bytes 8G --vm-keep
208
+```
209
+
210
+Netdata is capable of understanding much more complicated entities. To better understand how they work, read the [health
211
+documentation](../../health/README.md), look at some [examples](../../health/REFERENCE.md#example-alarms), and open the
212
+files containing the default entities on your system.
213
+
214
+## Enable Netdata's notification systems
215
+
216
+Health alarms, while great on their own, are pretty useless without some way of you knowing they've been triggered.
217
+That's why Netdata comes with a notification system that supports more than a dozen services, such as email, Slack,
218
+Discord, PagerDuty, Twilio, Amazon SNS, and much more.
219
+
220
+To see all the supported systems, visit our [notifications documentation](../../health/notifications/).
221
+
222
+We'll cover email and Slack notifications here, but with this knowledge you should be able to enable any other type of
223
+notifications instead of or in addition to these.
224
+
225
+### Email notifications
226
+
227
+To use email notifications, you need `sendmail` or an equivalent installed on your system. Linux systems use `sendmail`
228
+or similar programs to, unsurprisingly, send emails to any inbox.
229
+
230
+> Learn more about `sendmail` via its [documentation](http://www.postfix.org/sendmail.1.html).
231
+
232
+Edit the `health_alarm_notify.conf` file, which resides in your Netdata directory.
233
+
234
+```bash
235
+sudo ./edit-config health_alarm_notify.conf
236
+```
237
+
238
+Look for the following lines:
239
+
240
+```conf
241
+# if a role recipient is not configured, an email will be send to:
242
+DEFAULT_RECIPIENT_EMAIL="root"
243
+# to receive only critical alarms, set it to "root|critical"
244
+```
245
+
246
+Change the value of `DEFAULT_RECIPIENT_EMAIL` to the email address at which you'd like to receive notifications.
247
+
248
+```conf
249
+# if a role recipient is not configured, an email will be sent to:
250
+DEFAULT_RECIPIENT_EMAIL="me@example.com"
251
+# to receive only critical alarms, set it to "root|critical"
252
+```
253
+
254
+Test email notifications system by first becoming the Netdata user and then asking Netdata to send a test alarm:
255
+
256
+```bash
257
+sudo su -s /bin/bash netdata
258
+/usr/libexec/netdata/plugins.d/alarm-notify.sh test
259
+```
260
+
261
+You should see output similar to this:
262
+
263
+```bash
264
+# SENDING TEST WARNING ALARM TO ROLE: sysadmin
265
+2019-10-17 18:23:38: alarm-notify.sh: INFO: sent email notification for: hostname test.chart.test_alarm is WARNING to 'me@example.com'
266
+# OK
267
+
268
+# SENDING TEST CRITICAL ALARM TO ROLE: sysadmin
269
+2019-10-17 18:23:38: alarm-notify.sh: INFO: sent email notification for: hostname test.chart.test_alarm is CRITICAL to 'me@example.com'
270
+# OK
271
+
272
+# SENDING TEST CLEAR ALARM TO ROLE: sysadmin
273
+2019-10-17 18:23:39: alarm-notify.sh: INFO: sent email notification for: hostname test.chart.test_alarm is CLEAR to 'me@example.com'
274
+# OK
275
+```
276
+
277
+... and you should get three separate emails, one for each test alarm, in your inbox! (Be sure to check your spam
278
+folder.)
279
+
280
+## Enable Slack notifications
281
+
282
+If you're one of the many who spend their workday getting pinged with GIFs by your colleagues, why not add Netdata
283
+notifications to the mix? It's a great way to immediately see, collaborate around, and respond to anomalies in your
284
+infrastructure.
285
+
286
+To get Slack notifications working, you first need to add an [incoming
287
+webhook](https://slack.com/apps/A0F7XDUAZ-incoming-webhooks) to the channel of your choice. Click the green **Add to
288
+Slack** button, choose the channel, and click the **Add Incoming WebHooks Integration** button.
289
+
290
+On the following page, you'll receive a **Webhook URL**. That's what you'll need to configure Netdata, so keep it handy.
291
+
292
+Time to dive back into your `health_alarm_notify.conf` file:
293
+
294
+```bash
295
+sudo ./edit-config health_alarm_notify.conf
296
+```
297
+
298
+Look for the `SLACK_WEBHOOK_URL=" "` line and add the incoming webhook URL you got from Slack:
299
+
300
+```conf
301
+SLACK_WEBHOOK_URL="https://hooks.slack.com/services/XXXXXXXXX/XXXXXXXXX/XXXXXXXXXXXX"
302
+```
303
+
304
+A few lines down, edit the `DEFAULT_RECIPIENT_SLACK` line to contain a single hash `#` character. This instructs Netdata
305
+to send a notification to the channel you configured with the incoming webhook.
306
+
307
+```conf
308
+DEFAULT_RECIPIENT_SLACK="#"
309
+```
310
+
311
+Time to test the notifications again!
312
+
313
+```bash
314
+sudo su -s /bin/bash netdata
315
+/usr/libexec/netdata/plugins.d/alarm-notify.sh test
316
+```
317
+
318
+You should receive three notifications in your Slack channel.
319
+
320
+Congratulations! You're set up with two awesome ways to get notified about any change in the health of your systems or
321
+applications.
322
+
323
+To further configure your email or Slack notification setup, or to enable other notification systems, check out the
324
+following documentation:
325
+
326
+- [Email notifications](../../health/notifications/email/)
327
+- [Slack notifications](../../health/notifications/slack/)
328
+- [Netdata's notification system](../../health/notifications/)
329
+
330
+## What's next?
331
+
332
+In this step, you learned the fundamentals of Netdata's health monitoring tools: alarms and notifications. You should be
333
+able to tune default alarms, silence them, and understand some of the basics of writing health entities. And, if you so
334
+chose, you'll now have both email and Slack notifications enabled.
335
+
336
+You're coming along quick!
337
+
338
+Next up, we're going to cover how Netdata collects its metrics, and how you can get Netdata to collect real-time metrics
339
+from hundreds of services with almost no configuration on your part. Onward!
340
+
341
+[Next: Collect metrics from more services and apps →](step-06.md)
docs/step-by-step/step-06.md
new
+114
@@ -0,0 +1,114 @@
1
+# Step 6. Collect metrics from more services and apps
2
+
3
+When Netdata _starts_, it auto-detects dozens of **data sources**, such as database servers, web servers, and more.
4
+
5
+To auto-detect and collect metrics from a source you just installed, you need to [restart
6
+Netdata](../getting-started.md#start-stop-and-restart-netdata).
7
+
8
+However, auto-detection only works if you installed the source using its standard installation
9
+procedure. If Netdata isn't collecting metrics after a restart, your source probably isn't configured
10
+correctly.
11
+
12
+Check out the [available data collection modulues](../Add-more-charts-to-netdata.md#available-data-collection-modules)
13
+to find the module for the source you want to monitor.
14
+
15
+## What you'll learn in this step
16
+
17
+We'll begin with an overview on Netdata's plugin architecture, and then dive into the following:
18
+
19
+- [Netdata's plugin architecture](#netdatas-plugin-architecture)
20
+- [Enable and disable plugins](#enable-and-disable-plugins)
21
+- [Enable the Nginx module as an example](#example-enable-the-nginx-module)
22
+
23
+## Netdata's plugin architecture
24
+
25
+Many Netdata users never have to configure plugins or worry about which plugin orchestrator they want to use.
26
+
27
+But, if you want to configure plugins or write a collector module for your custom source, it's important to understand
28
+the underlying plugin architecture.
29
+
30
+By default, Netdata collects a lot of metrics every second using a lot of plugins. **Internal** plugins collect system
31
+metrics, **external** plugins collect non-system metrics, and **orchestrator** plugins support data collection modules.
32
+
33
+These modules are primarily written in [Go](../../collectors/go.d.plugin/) (`go.d`) and
34
+[Python](../../collectors/python.d.plugin/), although some use [Bash](../../collectors/charts.d.plugin/) (`charts.d`) or
35
+[Node.js](../../collectors/node.d.plugin/) (`node.d`).
36
+
37
+## Enable and disable plugins
38
+
39
+You don't need to explicitly enable plugins to auto-detect properly configured sources, but it's useful to know how to
40
+enable or disable them.
41
+
42
+One reason you might want to _disable_ plugins is to improve Netdata's performance on low-resource systems, like
43
+ephemeral nodes or edge devices. Disabling orchestrator plugins like `python.d` can save significant resources—if you're
44
+not using any of its data collector modules.
45
+
46
+You can enable or disable plugins in the `[plugin]` section of `netdata.conf`. This section features a list of all the
47
+plugins with a boolean setting (`yes` or `no`) to enable or disable them. Be sure to uncomment the line by removing the
48
+hash (`#`)!
49
+
50
+Enabled:
51
+
52
+```conf
53
+[plugins]
54
+ # node.d = yes
55
+```
56
+
57
+Disabled:
58
+
59
+```conf
60
+[plugins]
61
+ node.d = no
62
+```
63
+
64
+When you explicitly disable a plugin this way, it won't auto-collect metrics using its modules.
65
+
66
+## Example: Enable the Nginx module
67
+
68
+To help explain how the auto-dectection process works, let's use an Nginx web server as an example.
69
+
70
+Even if you don't have Nginx installed on your system, we recommend you read through the following section so you can
71
+apply the process to other data sources, such as Apache, Redis, Memcached, and more.
72
+
73
+The Nginx module, which helps Netdata collect metrics from a running Nginx web server, is part of the `python.d.plugin`
74
+external plugin _orchestrator_.
75
+
76
+In order for Netdata to auto-detect an Nginx web server, you need to enable `ngx_http_stub_status_module` and pass the
77
+`stub_status` directive in the `location` block of your Nginx configuration file.
78
+
79
+You can confirm if the module is already enabled or not by using following command:
80
+
81
+```sh
82
+nginx -V 2>&1 | grep -o with-http_stub_status_module
83
+```
84
+
85
+If this command returns nothing, you'll need to [enable this module](https://www.nginx.com/blog/monitoring-nginx/).
86
+
87
+Next, edit your `/etc/nginx/sites-enabled/default` file to include a `location` block with the following:
88
+
89
+```conf
90
+ location /stub_status {
91
+ stub_status;
92
+ }
93
+```
94
+
95
+Restart Netdata using `service netdata restart` or the [correct
96
+alternative](../getting-started.md#start-stop-and-restart-netdata) for your system, and Netdata will auto-detect
97
+metrics from your Nginx web server!
98
+
99
+While not necessary for most auto-detection and collection purposes, you can also configure the Nginx collection module
100
+itself by editing its configuration file:
101
+
102
+```sh
103
+./edit-config python.d/nginx.conf
104
+```
105
+
106
+After configuring any source, or changing the configration files for their respective modules, always
107
+restart Netdata.
108
+
109
+## What's next?
110
+
111
+Now that you've learned the fundamentals behind configuring data sources for auto-detection, it's time to move back to
112
+the dashboard to learn more about some of its more advanced features.
113
+
114
+[Next: Netdata's dashboard in depth →](step-07.md)
docs/step-by-step/step-07.md
new
+113
@@ -0,0 +1,113 @@
1
+# Step 7. Netdata's dashboard in depth
2
+
3
+Welcome to the seventh step of the Netdata guide!
4
+
5
+This step of the guide aims to get you more familiar with the features of the dashboard not previously mentioned in
6
+[step 2](step-02.md).
7
+
8
+## What you'll learn in this step
9
+
10
+In this step of the Netdata guide, you'll learn how to:
11
+
12
+- [Change the dashboard's settings](#change-the-dashboards-settings)
13
+- [Check if there's an update to Netdata](#check-if-theres-an-update-to-netdata)
14
+- [Export and import a snapshot](#export-and-import-a-snapshot)
15
+
16
+Let's get started!
17
+
18
+## Change the dashboard's settings
19
+
20
+The settings area at the top of your Netdata dashboard houses browser settings. These settings do not affect the
21
+operation of your Netdata server/daemon. They take effect immediately and are permanently saved to browser local storage
22
+(except the refresh on focus / always option).
23
+
24
+You can see the **Performance**, **Synchronization**, **Visual**, and **Locale** tabs on the dashboard settings modal.
25
+
26
+
28
+
29
+To change any setting, click on the toggle button.
30
+
31
+
33
+
34
+We recommend you spend some time reading the descriptions for each setting to understand them before making changes.
35
+
36
+Pay particular attention to the following settings, as they have dramatic impacts on the performance and appearance of
37
+your Netdata dashboard:
38
+
39
+- When to refresh the charts?
40
+- How to handle hidden charts?
41
+- Which chart refresh policy to use?
42
+- Which theme to use?
43
+- Do you need help?
44
+
45
+Some settings are applied immediately, and others are only reflected after you refresh the page.
46
+
47
+## Check if there's an update to Netdata
48
+
49
+You can always check if there is an update available from the **Update** area of your Netdata dashboard.
50
+
51
+
53
+
54
+If an update is available, you'll see a modal similar to the one above.
55
+
56
+When you use the [automatic one-line installer script](../../packaging/installer/README.md#one-line-installation),
57
+Netdata will automatically attempt to update every day. If you choose to update it manually, there are [several
58
+well-documented methods](../../packaging/installer/UPDATE.md) to achieve that. However, it is best practice for you to
59
+first go over the [changelog](../../CHANGELOG.md).
60
+
61
+## Export and import a snapshot
62
+
63
+Netdata can export and import snapshots of the contents of your dashboard at a given time. Any Netdata agent can import
64
+a snapshot created by any other Netdata agent.
65
+
66
+Snapshot files include all the information of the dashboard, including the URL of the origin server, its unique ID, and
67
+chart data queries for the visible timeframe. While snapshots are not in real-time, and thus won't update with new
68
+metrics, you can still pan, zoom, and highlight charts as you see fit.
69
+
70
+Snapshots can be incredibly useful for diagnosing anomalies after they've already happened. Let's say Netdata triggered
71
+an alarm while you were sleeping. In the morning, you can look up the exact moment the alarm was raised, export a
72
+snapshot, and send it to a colleague for further analysis.
73
+
74
+> ❗ Know how you shouldn't go around downloading software from suspicious-looking websites? Same policy goes for loading
75
+> snapshots from untrusted or anonymous sources. Importing a snapshot loads quite a bit of data into your web browser,
76
+> and so you should always err on the side of protecting your system.
77
+
78
+To export a snapshot, click on the **export** icon.
79
+
80
+
82
+
83
+Edit the snapshot file name and select your desired compression method. Click on **Export**.
84
+
85
+When the export is complete, your browser will prompt you to save the `.snapshot` file to your machine. You can now
86
+share this file with any other Netdata user via email, Slack, or even to help describe your Netdata experience when
87
+[filing an issue](https://github.com/netdata/netdata/issues/new/choose) on GitHub.
88
+
89
+To import a snapshot, click on the **import** icon.
90
+
91
+
93
+
94
+Select the Netdata snapshot file to import. Once the file is loaded, the dashboard will update with critical information
95
+about the snapshot and the system from which it was taken. Click **import** to render it.
96
+
97
+Your Netdata dashboard will load data contained in the snapshot into charts. Because the snapshot only covers a certain
98
+period, it won't update with new metrics.
99
+
100
+An imported snapshot is also temporary. If you reload your browser tab, Netdata will remove the snapshot data and
101
+restore your real-time dashboard for your machine.
102
+
103
+## What's next?
104
+
105
+In this step of the Netdata tutorial, you learned how to:
106
+
107
+- Change the dashboard's settings
108
+- Check if there's an update to Netdata
109
+- Export or import a snapshot
110
+
111
+Next, you'll learn how to build your first custom dashboard!
112
+
113
+[Next: Build your first custom dashboard →](step-08.md)
docs/step-by-step/step-08.md
new
+388
@@ -0,0 +1,388 @@
1
+# Step 8. Build your first custom dashboard
2
+
3
+In previous steps of the tutorial, you have learned how several sections of the Netdata dashboard worked.
4
+
5
+This step will show you how to set up a custom dashboard to fit your unique needs. If nothing else, Netdata is really,
6
+really flexible. 🤸
7
+
8
+## What you'll learn in this step
9
+
10
+In this step of the Netdata guide, you'll learn:
11
+
12
+- [Why you might want a custom dashboard](#why-should-i-create-a-custom-dashboard)
13
+- [How to create and prepare your `custom-dashboard.html` file](#create-and-prepare-your-custom-dashboardhtml-file)
14
+- [Where to add `dashboard.js` to your custom dashboard file](#add-dashboardjs-to-your-custom-dashboard-file)
15
+- [How to add basic styling](#add-some-basic-styling)
16
+- [How to add charts of different types, shapes, and sizes](#creating-your-dashboards-charts)
17
+
18
+Let's get on with it!
19
+
20
+## Why should I create a custom dashboard?
21
+
22
+Because it's cool!
23
+
24
+But there are way more reasons than that, most of which will prove more valuable to you.
25
+
26
+You could use custom dashboards to aggregate real-time data from multiple Netdata agents in one place. Or, you could put
27
+all the charts with metrics collected from your custom application via `statsd` and perform application performance
28
+monitoring from a single dashboard. You could even use a custom dashboard and a standalone web server to create an
29
+enriched public status page for your service, and give your users something fun to look at while they're waiting for the
30
+503 errors to clear up!
31
+
32
+Netdata's custom dashboarding capability is meant to be as flexible as your ideas. We hope you can take these
33
+fundamental ideas and turn them into something amazing.
34
+
35
+## Create and prepare your `custom-dashboard.html` file
36
+
37
+By default, Netdata stores its web server files at `/usr/share/netdata/web`. As with finding the location of your
38
+`netdata.conf` file, you can double-check this location by loading up `http://HOST:19999/netdata.conf` in your browser
39
+and finding the value of the `web files directory` option.
40
+
41
+To create your custom dashboard, create a file at `/usr/share/netdata/web/custom-dashboard.html` and copy in the
42
+following:
43
+
44
+```html
45
+<!DOCTYPE html>
46
+<html lang="en">
47
+<head>
48
+ <title>My custom dashboard</title>
49
+
50
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
51
+ <meta charset="utf-8">
52
+ <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
53
+ <meta name="viewport" content="width=device-width, initial-scale=1">
54
+ <meta name="apple-mobile-web-app-capable" content="yes">
55
+ <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
56
+
57
+ <!-- Add dashboard.js here! -->
58
+
59
+</head>
60
+<body>
61
+
62
+ <main class="container">
63
+
64
+ <h1>My custom dashboard</h1>
65
+
66
+ <!-- Add charts here! -->
67
+
68
+ </main>
69
+
70
+</body>
71
+</html>
72
+```
73
+
74
+Try visiting `http://HOST:19999/custom-dashbord.html` in your browser.
75
+
76
+If you get a blank page with this text: `Access to file is not permitted: /usr/share/netdata/web/custom-dashboard.html`.
77
+You can fix this error by changing the dashboard file's permissions to make it owned by the `netdata` user.
78
+
79
+```bash
80
+sudo chown netdata:netdata /usr/share/netdata/web/custom-dashboard.html
81
+```
82
+
83
+Reload your browser, and you should see a blank page with the title: **Your custom dashboard**!
84
+
85
+## Add `dashboard.js` to your custom dashboard file
86
+
87
+You need to include the `dashboard.js` file of a Netdata agent to add Netdata charts. Add the following to the `<head>`
88
+of your custom dashboard page and change `HOST` according to your setup.
89
+
90
+```html
91
+ <!-- Add dashboard.js here! -->
92
+ <script type="text/javascript" src="http://HOST:19999/dashboard.js"></script>
93
+```
94
+
95
+When you add `dashboard.js` to any web page, it loads several JavaScript and CSS files to create and style charts. It
96
+also scans the page for elements that define charts, builds them, and refreshes with new metrics.
97
+
98
+> If you enabled SSL on your Netdata dashboard already, you'll need to use `https://` to grab the `dashboard.js` file.
99
+
100
+## Add some basic styling
101
+
102
+While not necessary, let's add some basic styling to make our dashboard look a little nicer. We're putting some
103
+basic CSS into a `<style>` tag inside of the page's `<head>` element.
104
+
105
+```html
106
+ <!-- Add dashboard.js here! -->
107
+ <script type="text/javascript" src="http://HOST:19999/dashboard.js"></script>
108
+
109
+ <style>
110
+ .wrap {
111
+ max-width: 1280px;
112
+ margin: 0 auto;
113
+ }
114
+
115
+ h1 {
116
+ margin-bottom: 30px;
117
+ text-align: center;
118
+ }
119
+
120
+ .charts {
121
+ display: flex;
122
+ flex-flow: row wrap;
123
+ justify-content: space-around;
124
+ }
125
+ </style>
126
+
127
+</head>
128
+```
129
+
130
+## Creating your dashboard's charts
131
+
132
+Time to create a chart!
133
+
134
+You need to create a `<div>` for each new chart. Each `<div>` element accepts a few `data-` attributes, some of which
135
+are required and some of which are optional.
136
+
137
+Let's cover a few important ones. And while we do it, we'll create a custom dashboard that shows a few CPU-related
138
+charts on a single page.
139
+
140
+### The chart unique ID (required)
141
+
142
+You need to specify the unique ID of a chart to show it on your custom dashboard. If you forgot how to find the unique
143
+ID, head back over to [step 2](step-02.md#understand-charts-dimensions-families-and-contexts) for a
144
+re-introduction.
145
+
146
+You can then put this unique ID into a `<div>` element with the `data-netdata` attribute. Put this in the `<body>` of
147
+your custom dashboard file beneath the helpful comment.
148
+
149
+```html
150
+<body>
151
+
152
+ <main class="wrap">
153
+
154
+ <h1>My custom dashboard</h1>
155
+
156
+ <div class="charts">
157
+
158
+ <!-- Add charts here! -->
159
+ <div data-netdata="system.cpu"></div>
160
+
161
+ </div>
162
+
163
+ </main>
164
+
165
+</body>
166
+```
167
+
168
+Reload the page, and you should see a real-time `system.cpu` chart!
169
+
170
+... and a whole lot of white space. Let's fix that by adding a few more charts.
171
+
172
+```html
173
+ <!-- Add charts here! -->
174
+ <div data-netdata="system.cpu"></div>
175
+ <div data-netdata="apps.cpu"></div>
176
+ <div data-netdata="groups.cpu"></div>
177
+ <div data-netdata="users.cpu"></div>
178
+```
179
+
180
+
182
+
183
+### Set chart duration
184
+
185
+By default, these charts visualize 10 minutes of Netdata metrics. Let's get a little more granular on this dashboard. To
186
+do so, add a new `data-after=""` attribute to each chart.
187
+
188
+`data-after` takes a _relative_ number of seconds from _now_. So, by putting `-300` as the value, you're asking the
189
+custom dashboard to display the _last 5 minutes_ (`5m * 60s = 300s`) of data.
190
+
191
+```html
192
+ <!-- Add charts here! -->
193
+ <div data-netdata="system.cpu"
194
+ data-after="-300">
195
+ </div>
196
+ <div data-netdata="apps.cpu"
197
+ data-after="-300">
198
+ </div>
199
+ <div data-netdata="groups.cpu"
200
+ data-after="-300">
201
+ </div>
202
+ <div data-netdata="users.cpu"
203
+ data-after="-300">
204
+ </div>
205
+```
206
+
207
+### Set chart size
208
+
209
+You can set the size of any chart using the `data-height=""` and `data-width=""` attributes. These attributes can be
210
+anything CSS accepts for width and height (e.g. percentages, pixels, em/rem, calc, and so on).
211
+
212
+Let's make the charts a little taller and allow them to fit side-by-side for a more compact view. Add
213
+`data-height="200px"` and `data-width="50%"` to each chart.
214
+
215
+```html
216
+ <div data-netdata="system.cpu"
217
+ data-after="-300"
218
+ data-height="250px"
219
+ data-width="50%"></div>
220
+ <div data-netdata="apps.cpu"
221
+ data-after="-300"
222
+ data-height="250px"
223
+ data-width="50%"></div>
224
+ <div data-netdata="groups.cpu"
225
+ data-after="-300"
226
+ data-height="250px"
227
+ data-width="50%"></div>
228
+ <div data-netdata="users.cpu"
229
+ data-after="-300"
230
+ data-height="250px"
231
+ data-width="50%"></div>
232
+```
233
+
234
+Now we're getting somewhere!
235
+
236
+
238
+
239
+## Final touches
240
+
241
+While we already have a perfectly workable dashboard, let's add some final touches to make it a little more pleasant on
242
+the eyes.
243
+
244
+First, add some extra CSS to create some vertical whitespace between the top and bottom row of charts.
245
+
246
+```html
247
+ <style>
248
+ ...
249
+
250
+ .charts > div {
251
+ margin-bottom: 6rem;
252
+ }
253
+ </style>
254
+```
255
+
256
+To create horizontal whitespace, change the value of `data-width="50%"` to `data-width="calc(50% - 2rem)"`.
257
+
258
+```html
259
+ <div data-netdata="system.cpu"
260
+ data-after="-300"
261
+ data-height="250px"
262
+ data-width="calc(50% - 2rem)"></div>
263
+ <div data-netdata="apps.cpu"
264
+ data-after="-300"
265
+ data-height="250px"
266
+ data-width="calc(50% - 2rem)"></div>
267
+ <div data-netdata="groups.cpu"
268
+ data-after="-300"
269
+ data-height="250px"
270
+ data-width="calc(50% - 2rem)"></div>
271
+ <div data-netdata="users.cpu"
272
+ data-after="-300"
273
+ data-height="250px"
274
+ data-width="calc(50% - 2rem)"></div>
275
+```
276
+
277
+Told you the `data-width` and `data-height` attributes can take any CSS values!
278
+
279
+Prefer a dark theme? Add this to your `<head>` _above_ where you added `dashboard.js`:
280
+
281
+```html
282
+ <script>
283
+ var netdataTheme = 'slate';
284
+ </script>
285
+
286
+ <!-- Add dashboard.js here! -->
287
+ <script type="text/javascript" src="https://HOST/dashboard.js"></script>
288
+```
289
+
290
+Refresh the dashboard to give your eyes a break from all that blue light!
291
+
292
+
294
+
295
+## The final `custom-dashboard.html`
296
+
297
+In case you got lost along the way, here's the final version of the `custom-dashboard.html` file:
298
+
299
+```html
300
+<!DOCTYPE html>
301
+<html lang="en">
302
+<head>
303
+ <title>My custom dashboard</title>
304
+
305
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
306
+ <meta charset="utf-8">
307
+ <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
308
+ <meta name="viewport" content="width=device-width, initial-scale=1">
309
+ <meta name="apple-mobile-web-app-capable" content="yes">
310
+ <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
311
+
312
+ <script>
313
+ var netdataTheme = 'slate';
314
+ </script>
315
+
316
+ <!-- Add dashboard.js here! -->
317
+ <script type="text/javascript" src="http://localhost:19999/dashboard.js"></script>
318
+
319
+ <style>
320
+ .wrap {
321
+ max-width: 1280px;
322
+ margin: 0 auto;
323
+ }
324
+
325
+ h1 {
326
+ margin-bottom: 30px;
327
+ text-align: center;
328
+ }
329
+
330
+ .charts {
331
+ display: flex;
332
+ flex-flow: row wrap;
333
+ justify-content: space-around;
334
+ }
335
+
336
+ .charts > div {
337
+ margin-bottom: 6rem;
338
+ position: relative;
339
+ }
340
+ </style>
341
+
342
+</head>
343
+<body>
344
+
345
+ <main class="wrap">
346
+
347
+ <h1>My custom dashboard</h1>
348
+
349
+ <div class="charts">
350
+
351
+ <!-- Add charts here! -->
352
+ <div data-netdata="system.cpu"
353
+ data-after="-300"
354
+ data-height="250px"
355
+ data-width="calc(50% - 2rem)"></div>
356
+ <div data-netdata="apps.cpu"
357
+ data-after="-300"
358
+ data-height="250px"
359
+ data-width="calc(50% - 2rem)"></div>
360
+ <div data-netdata="groups.cpu"
361
+ data-after="-300"
362
+ data-height="250px"
363
+ data-width="calc(50% - 2rem)"></div>
364
+ <div data-netdata="users.cpu"
365
+ data-after="-300"
366
+ data-height="250px"
367
+ data-width="calc(50% - 2rem)"></div>
368
+
369
+ </div>
370
+
371
+ </main>
372
+
373
+</body>
374
+</html>
375
+```
376
+
377
+## What's next?
378
+
379
+In this guide, you learned the fundamentals of building a custom Netdata dashboard. You should now be able to add more
380
+charts to your `custom-dashboard.html`, change the charts that are already there, and size them according to your needs.
381
+
382
+Of course, the custom dashboarding features covered here are just the beginning. Be sure to read up on our [custom
383
+dashboard documentation](../../web/gui/custom/) for details on how you can use other chart libraries, pull metrics from
384
+multiple Netdata agents, and choose which dimensions a given chart shows.
385
+
386
+Next, you'll learn how to store long-term historical metrics in Netdata!
387
+
388
+[Next: Long-term metrics storage →](step-09.md)
docs/step-by-step/step-09.md
new
+174
@@ -0,0 +1,174 @@
1
+# Step 9. Long-term metrics storage
2
+
3
+By default, Netdata stores metrics in a custom database we call the [database engine](../../database/engine/), which
4
+stores recent metrics in your system's RAM and "spills" historical metrics to disk. By using both RAM and disk, the
5
+database engine helps you store a much larger dataset than the amount of RAM your system has.
6
+
7
+On a system that's collecting 2,000 metrics every second, the database engine's default configuration will store about
8
+two day's worth of metrics in RAM and on disk.
9
+
10
+That's a lot of metrics. We're talking 345,600,000 individual data points. And the database engine does it with a tiny
11
+a portion of the RAM available on most systems.
12
+
13
+To store _even more_ metrics, you have two options. First, you can tweak the database engine's options to expand the RAM
14
+or disk it uses. Second, you can archive metrics to a different backend. For that, we'll use MongoDB and Prometheus as
15
+examples.
16
+
17
+## What you'll learn in this step
18
+
19
+In this step of the Netdata guide, you'll learn how to:
20
+
21
+- [Tweak the database engine's settings](#tweak-the-database-engines-settings)
22
+- [Archive metrics to a backend](#archive-metrics-to-a-backend)
23
+ - [Use the MongoDB backend](#archive-metrics-via-the-mongodb-backend)
24
+
25
+Let's get started!
26
+
27
+## Tweak the database engine's settings
28
+
29
+If you're using Netdata v1.18.0 or higher, and you haven't changed your `memory mode` settings before following this
30
+tutorial, your Netdata agent is already using the database engine.
31
+
32
+Let's look at your `netdata.conf` file again. Under the `[global]` section, you'll find three connected options.
33
+
34
+```conf
35
+[global]
36
+ # memory mode = dbengine
37
+ # page cache size = 32
38
+ # dbengine disk space = 256
39
+```
40
+
41
+The `memory mode` option is set, by default, to `dbengine`. `page cache size` determines the amount of RAM, in MiB, that
42
+the database engine dedicates to caching the metrics it's collecting. `dbengine disk space` determines the amount of
43
+disk space, in MiB, that the database engine will use to store these metrics once they've been "spilled" to disk..
44
+
45
+You can uncomment and change either `page cache size` or `dbengine disk space` based on how much RAM and disk you want
46
+the database engine to use. The higher those values, the more metrics Netdata will store. If you change them to 64 and
47
+512, respectively, the database engine should store about four day's worth of data on a system collecting 2,000 metrics
48
+every second.
49
+
50
+> Before you make changes, we recommended you read up on the [database
51
+> engine's](../../database/engine/README.md#memory-requirements) to ensure you don't overwhelm your system. Out of
52
+> memory errors are no fun!
53
+
54
+```conf
55
+[global]
56
+ memory mode = dbengine
57
+ page cache size = 64
58
+ dbengine disk space = 512
59
+```
60
+
61
+After you've made your changes, [restart Netdata](../getting-started.md#start-stop-and-restart-netdata).
62
+
63
+To confirm the database engine is working, go to your Netdata dashboard and click on the **Netdata Monitoring** menu on
64
+the right-hand side. You can find `dbengine` metrics after `queries`.
65
+
66
+
68
+
69
+## Archive metrics to a backend
70
+
71
+You can archive all the metrics collected by Netdata to what we call **backends**. The supported backends include
72
+Graphite, OpenTSDB, Prometheus, AWS Kinesis Data Streams, MongoDB, and the list is always growing.
73
+
74
+As we said in [step 1](step-01.md), we have only complimentary systems, not competitors! We're happy to support these
75
+archiving methods and are always working to improve them.
76
+
77
+A lot of Netdata users archive their metrics to one of these backends for long-term storage or further analysis. Since
78
+Netdata collects so many metrics every second, they can quickly overload small devices or even big servers that are
79
+aggregating metrics streaming in from other Netdata agents.
80
+
81
+We even support resampling metrics during archiving. With resampling enabled, Netdata will archive only the average or
82
+sum of every X seconds of metrics. This reduces the sheer amount of data, albeit with a little less accuracy.
83
+
84
+How you archive metrics, or if you archive metrics at all, is entirely up to you! But let's cover two easy archiving
85
+methods, MongoDB and Prometheus remote write, to get you started.
86
+
87
+> Currently, Netdata can only use a single backend at a time. We are currently working on a new archiving solution,
88
+> which we call "exporters," that simplifies the configuration process and allows you to archive to multiple backends.
89
+> We'll update this tutorial as soon as exporters are enabled.
90
+
91
+### Archive metrics via the MongoDB backend
92
+
93
+Begin by installing MongoDB its dependencies via the correct package manager for your system.
94
+
95
+```bash
96
+sudo apt-get install mongodb # Debian/Ubuntu
97
+sudo dnf install mongodb # Fedora
98
+sudo yum install mongodb # CentOS
99
+```
100
+
101
+Next, install the one essential dependency: v1.7.0 or higher of
102
+[libmongoc](http://mongoc.org/libmongoc/current/installing.html).
103
+
104
+```bash
105
+sudo apt-get install libmongoc-1.0-0 libmongoc-dev # Debian/Ubuntu
106
+sudo dnf install mongo-c-driver mongo-c-driver-devel # Fedora
107
+sudo yum install mongo-c-driver mongo-c-driver-devel # CentOS
108
+```
109
+
110
+Next, create a new MongoDB database and collection to store all these archived metrics. Use the `mongo` command to start
111
+the MongoDB shell, and then execute the following command:
112
+
113
+```mongodb
114
+use netdata
115
+db.createCollection("netdata_metrics")
116
+```
117
+
118
+Next, Netdata needs to be reinstalled in order to detect that the required libraries to make this backend connection
119
+exist. Since you most likely installed Netdata using the one-line installer script, all you have to do is run that
120
+script again. Don't worry—any configuration changes you made along the way will be retained!
121
+
122
+```bash
123
+bash <(curl -Ss https://my-netdata.io/kickstart.sh)
124
+```
125
+
126
+Now, from your Netdata config directory, edit your `netdata.conf` file and set these options in the `[backend]` section:
127
+
128
+```conf
129
+[backend]
130
+ enabled = yes
131
+ type = mongodb
132
+```
133
+
134
+You now need to initialize and edit a `mongodb.conf` file to tell Netdata where to find the database you just created.
135
+
136
+```sh
137
+./edit-config mongodb.conf
138
+```
139
+
140
+Add the following values to the file:
141
+
142
+```yaml
143
+# MongoDB backend configuration
144
+#
145
+# All options in this file are mandatory
146
+
147
+# URI
148
+uri = mongodb://localhost
149
+
150
+# database name
151
+database = netdata
152
+
153
+# collection name
154
+collection = netdata_metrics
155
+```
156
+
157
+[Restart](../getting-started.md#start-stop-and-restart-netdata) Netdata to enable the MongoDB backend. Click on the
158
+**Netdata Montioring** menu and check out the **backend** sub-menu. You should start seeing these charts fill up with
159
+data about your MongoDB backend!
160
+
161
+
162
+
163
+If you'd like to try connecting Netdata to another backend, such as Prometheus or OpenTSDB, read our [backends
164
+documentation](../../backends/README.md).
165
+
166
+## What's next?
167
+
168
+You're getting close to the end! In this step, you learned how to make the most of the database engine, or archive
169
+metrics to MongoDB for long-term storage.
170
+
171
+In the last step of this step-by-step tutorial, we'll put our sysadmin hat on and use Nginx to proxy traffic to and from
172
+our Netdata dashboard.
173
+
174
+[Next: Set up a proxy →](step-10.md)
docs/step-by-step/step-10.md
new
+213
@@ -0,0 +1,213 @@
1
+# Step 10. Set up a proxy
2
+
3
+You're almost through! At this point, you should be pretty familiar with now Netdata works and how to configure it to
4
+your liking.
5
+
6
+In this step of the tutorial, we're going to add a proxy in front of Netdata. We're doing this for both improved
7
+performance and security, so we highly recommend following these steps. Doubly so if you installed Netdata on a
8
+publicly-accessible remote server.
9
+
10
+> ❗ If you installed Netdata on the machine you're currently using (e.g. on `localhost`), and have been accessing
11
+> Netdata at `http://localhost:19999`, you can skip this step of the tutorial. In most cases, there is no benefit to
12
+> setting up a proxy for a service running locally.
13
+
14
+> ❗❗ This tutorial requires more advanced administration skills than previous parts. If you're still working on your
15
+> Linux administration skills, and would rather get back to Netdata, you might want to [skip this
16
+> step](step-99.md) for now and return to it later.
17
+
18
+## What you'll learn in this step
19
+
20
+In this step of the Netdata guide, you'll learn:
21
+
22
+- [What a proxy is and the benefits of using one](#wait-whats-a-proxy)
23
+- [How to connect Netdata to Nginx](#connect-netdata-to-nginx)
24
+- [How to enable HTTPS in Nginx](#enable-https-in-nginx)
25
+- [How to secure your Netdata dashboard with a password](#secure-your-netdata-dashboard-with-a-password)
26
+
27
+Let's dive in!
28
+
29
+## Wait. What's a proxy?
30
+
31
+A proxy is a middleman between the internet and a service you're running on your system. Traffic from the internet at
32
+large enters your system through the proxy, which then routes it to the service.
33
+
34
+A proxy is often used to enable encrypted HTTPS connections with your browser, but they're also useful for load
35
+balancing, performance, and password-protection.
36
+
37
+We'll use [Nginx](https://nginx.org/en/) for this step of the tutorial, but you can also use
38
+[Caddy](https://caddyserver.com/) as a simple proxy if you prefer.
39
+
40
+## Required before you start
41
+
42
+You need three things to run a proxy using Nginx:
43
+
44
+- Nginx and Certbot installed on your system
45
+- A fully qualified domain name
46
+- A subdomain for Netdata that points to your system
47
+
48
+### Nginx and Certbot
49
+
50
+This step of the tutorial assumes you can install Nginx on your system. Here are the easiest methods to do so on Debian,
51
+Ubuntu, Fedora, and CentOS systems.
52
+
53
+```bash
54
+sudo apt-get install nginx # Debian/Ubuntu
55
+sudo dnf install nginx # Fedora
56
+sudo yum install nginx # CentOS
57
+```
58
+
59
+Check out [Nginx's installation
60
+instructions](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/) for details on
61
+other Linux distributions.
62
+
63
+Certbot is a tool to help you create and renew certiciate+key pairs for your domain. Visit their
64
+[instructions](https://certbot.eff.org/instructions) to get a detailed installation process for your operating system.
65
+
66
+### Fully qualified domain name
67
+
68
+The only other true prerequisite of using a proxy is a **fully qualified domain name** (FQDN). In other words, a domain
69
+name like `example.com`, `netdata.cloud`, or `github.com`.
70
+
71
+If you don't have a domain name, you won't be able to use a proxy the way we'll describe here.
72
+
73
+Because we strongly recommend running Netdata behind a proxy, the cost of a domain name is worth the benefit. If you
74
+don't have a preferred domain registrar, try [Google Domains](https://domains.google/),
75
+[Cloudflare](https://www.cloudflare.com/products/registrar/), or [Namecheap](https://www.namecheap.com/).
76
+
77
+### Subdomain for Netdata
78
+
79
+Any of the three domain registrars mentioned above, and most registrars in general, will allow you to create new DNS
80
+entries for your domain.
81
+
82
+To create a subdomain for Netdata, use your registrar's DNS settings to create an A record for a `netdata` subdomain.
83
+Point the A record to the IP address of your system.
84
+
85
+Once finished with the steps below, you'll be able to access your dashboard at `http://netdata.example.com`.
86
+
87
+## Connect Netdata to Nginx
88
+
89
+The first part of enabling the proxy is to create a new server for Nginx.
90
+
91
+Use your favorite text editor to create a file at `/etc/nginx/sites-available/netdata`, copy in the following
92
+configuration, and change the `server_name` line to match your domain.
93
+
94
+```nginx
95
+upstream backend {
96
+ server 127.0.0.1:19999;
97
+ keepalive 64;
98
+}
99
+
100
+server {
101
+ listen 80;
102
+
103
+ # Change `example.com` to match your domain name.
104
+ server_name netdata.example.com;
105
+
106
+ location / {
107
+ proxy_set_header X-Forwarded-Host $host;
108
+ proxy_set_header X-Forwarded-Server $host;
109
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
110
+ proxy_pass http://backend;
111
+ proxy_http_version 1.1;
112
+ proxy_pass_request_headers on;
113
+ proxy_set_header Connection "keep-alive";
114
+ proxy_store off;
115
+ }
116
+}
117
+```
118
+
119
+Save and close the file.
120
+
121
+Test your configuration file by running `sudo nginx -t`.
122
+
123
+If that returns no errors, it's time to make your server available. Run the command to create a symbolic link in the
124
+`sites-enabled` directory.
125
+
126
+```bash
127
+sudo ln -s /etc/nginx/sites-available/netdata /etc/nginx/sites-enabled/netdata
128
+```
129
+
130
+Finally, restart Nginx to make your changes live. Open your browser and head to `http://netdata.example.com`. You should
131
+see your proxied Netdata dashboard!
132
+
133
+## Enable HTTPS in Nginx
134
+
135
+All this proxying doesn't mean much if we can't take advantage of one of the biggest benefits: encrypted HTTPS
136
+connections! Let's fix that.
137
+
138
+Certbot will automatically get a certificate, edit your Nginx configuration, and get HTTPS running in a single step. Run
139
+the following:
140
+
141
+```bash
142
+sudo certbot --nginx
143
+```
144
+
145
+You'll be prompted with a few questions. At the `Which names would you like to activate HTTPS for?` question, hit
146
+`Enter`. Next comes this question:
147
+
148
+```bash
149
+Please choose whether or not to redirect HTTP traffic to HTTPS, removing HTTP access.
150
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
151
+1: No redirect - Make no further changes to the webserver configuration.
152
+2: Redirect - Make all requests redirect to secure HTTPS access. Choose this for
153
+new sites, or if you're confident your site works on HTTPS. You can undo this
154
+change by editing your web server's configuration.
155
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
156
+```
157
+
158
+You _do_ want to force HTTPS, so hit `2` and then `Enter`. Nginx will now ensure all attempts to access
159
+`netdata.example.com` use HTTPS.
160
+
161
+Certbot will automatically renew your certificate whenever it's needed, so you're done configuring your proxy. Open your
162
+browser again and navigate to `https://netdata.example.com`, and you'll land on an encrypted, proxied Netdata dashboard!
163
+
164
+## Secure your Netdata dashboard with a password
165
+
166
+Finally, let's take a moment to put your Netdata dashboard behind a password. This step is optional, but you might not
167
+want _anyone_ to access the metrics in your proxied dashboard.
168
+
169
+Run the below command after changing `user` to the username you want to use to log in to your dashboard.
170
+
171
+```bash
172
+sudo sh -c "echo -n 'user:' >> /etc/nginx/.htpasswd"
173
+```
174
+
175
+Then run this command to create a password:
176
+
177
+```bash
178
+sudo sh -c "openssl passwd -apr1 >> /etc/nginx/.htpasswd"
179
+```
180
+
181
+You'll be prompted to create a password. Next, open your Nginx configuration file at
182
+`/etc/nginx/sites-available/netdata` and add these two lines under `location / {`:
183
+
184
+```nginx
185
+ location / {
186
+ auth_basic "Restricted Content";
187
+ auth_basic_user_file /etc/nginx/.htpasswd;
188
+ ...
189
+```
190
+
191
+Save, exit, and restart Nginx. Then try visiting your dashboard one last time. You'll see a prompt for the username and
192
+password you just created.
193
+
194
+
196
+
197
+Your Netdata dashboard is now a touch more secure.
198
+
199
+## What's next?
200
+
201
+You're a real sysadmin now!
202
+
203
+If you want to configure your Nginx proxy further, check out the following:
204
+
205
+- [Running Netdata behind Nginx](../Running-behind-nginx.md)
206
+- [High-performance Netdata](../high-performance-netdata.md)
207
+- [Enabling TLS on Netdata's dashboard](../../web/server/README.md#enabling-tls-support)
208
+
209
+And... you're _almost_ done with the Netdata tutorial.
210
+
211
+For some celebratory emoji and a clap on the back, head on over to our final step.
212
+
213
+[Next: The end. →](step-99.md)
docs/step-by-step/step-99.md
new
+44
@@ -0,0 +1,44 @@
1
+# Step ∞. You're finished!
2
+
3
+Congratulations. 🎉
4
+
5
+You've completed the step-by-step Netdata tutorial. That means you're well on your way to becoming an expert in using
6
+our toolkit for health monitoring and performance troubleshooting.
7
+
8
+But, perhaps more importantly, also that much closer to being an expert in the _fundamental skills behind health
9
+monitoring and performance troubleshooting_, which you can take with you to any job or project.
10
+
11
+And that is the entire point of this tutorial, and Netdata's [documentation](https://docs.netdata.cloud) as a whole—give
12
+you every resource possible to help you build faster, more resilient systems, services, and applications.
13
+
14
+Along the way, you learned how to:
15
+
16
+- Navigate Netdata's dashboard and visually detect anomalies using its charts.
17
+- Monitor multiple systems using Netdata agents connected together with your browser and Netdata Cloud.
18
+- Edit your `netdata.conf` file to tweak Netdata to your liking.
19
+- Tune existing alarms and create entirely new ones, plus get notifications about alarms on your favorite services.
20
+- Take advantage of Netdata's auto-detection capabilities to ensure your applications/services are monitored with
21
+ little to no configuration.
22
+- Use advanced features within Netdata's dashboard.
23
+- Build a custom dashboard using `dashboard.js`.
24
+- Save more historical metrics with the database engine or archive metrics to MongoDB.
25
+- Put Netdata behind a proxy to enable HTTPS and improve performance.
26
+
27
+Seems like a lot, right? Well, we hope it felt manageable and, yes, even _fun_.
28
+
29
+## What's next?
30
+
31
+Now that you're at the end of our step-by-step Netdata tutorial, the next steps are entirely up to you. In fact, you're
32
+just at the beginning of your journey into health monitoring and performance troubleshooting.
33
+
34
+Our documentation exists to put every Netdata resource in front of you as easily and coherently as we possibly can.
35
+Click around, search, and find new mountains to climb.
36
+
37
+If that feels like too much possibility to you, why not one of these options:
38
+
39
+- Share your experience with Netdata and this tutorial. Be sure to [@mention](https://twitter.com/linuxnetdata) us on
40
+ Twitter!
41
+- Contribute to what we do. Browse our [open issues](https://github.com/netdata/netdata/issues) and check out out
42
+ [contributions doc](../../CONTRIBUTING.md) for ideas of how you can pitch in.
43
+
44
+We can't wait to see what you monitor next! Bon voyage! ⛵
packaging/installer/README.md
+10
-4
@@ -77,7 +77,9 @@ 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/getting-started.md).
80
+Now that Netdata is installed, be sure to visit our [getting started guide](../../docs/getting-started.md) for a quick
81
+overview of configuring Netdata, enabling plugins, and controlling Netdata's daemon. Or, get the full guided tour of
82
+Netdata's capabilities with our [step-by-step tutorial](../../docs/step-by-step/step-00.md)!
83
84
---
85
@@ -146,7 +148,9 @@ sh /tmp/kickstart-static64.sh
148
149
</details>
150
149
-Once Netdata is installed, see [Getting Started](../../docs/getting-started.md).
151
+Now that Netdata is installed, be sure to visit our [getting started guide](../../docs/getting-started.md) for a quick
152
+overview of configuring Netdata, enabling plugins, and controlling Netdata's daemon. Or, get the full guided tour of
153
+Netdata's capabilities with our [step-by-step tutorial](../../docs/step-by-step/step-00.md)!
154
155
---
156
@@ -583,8 +587,10 @@ bash kickstart.sh --local-files /tmp/netdata-version-number-here.tar.gz /tmp/sha
587
bash kickstart-static64.sh --local-files /tmp/netdata-version-number-here.gz.run /tmp/sha256sums.txt
588
```
589
586
-Now that you're finished with your offline installation, you can move on to our
587
-[getting started guide](../../docs/getting-started.md)!
590
+Now that you're finished with your offline installation, you can move on to our [getting started
591
+guide](../../docs/getting-started.md) for a quick overview of configuring Netdata, enabling plugins, and controlling
592
+Netdata's daemon. Or, get the full guided tour of Netdata's capabilities with our [step-by-step
593
+tutorial](../../docs/step-by-step/step-00.md)!
594
595
## Automatic updates
596