Minor README file updates (#4548)
* Minor changes in registy/README.md * Minor improvements to README files within web/ directory * Minor * Added minor comments * Improved web_client_api_request_v1_registry() comment * Minor * Minor formatting
George Moschovitis committed
Nov 2, 2018 at 17:17 UTC
72bad7923056317307257326aa886074635af194
5 files changed
+55
-41
registry/README.md
+16
-16
@@ -1,32 +1,32 @@
1
-# netdata registry
1
+# Netdata registry
2
3
Netdata registry implements the `my-netdata` menu on netdata dashboards.
4
The `my-netdata` menu lists the netdata servers you have visited.
5
6
## Why?
7
8
-netdata provides distributed monitoring.
8
+Netdata provides distributed monitoring.
9
10
Traditional monitoring solutions centralize all the data to provide unified dashboards across all servers. Before netdata, this was the standard practice. However it has a few issues:
11
12
1. due to the resources required, the number of metrics collected is limited.
13
-2. for the same reason, the data collection frequency is not that high, at best it will be once every 10 or 15 seconds, at worst every 5 or 10 mins.
14
-2. the central monitoring solution needs dedicated resources, thus becoming "another bottleneck" in the whole ecosystem. It also requires maintenance, administration, etc.
15
-3. most centralized monitoring solutions are usually only good for presenting *statistics of past performance* (i.e. cannot be used for real-time performance troubleshooting).
13
+1. for the same reason, the data collection frequency is not that high, at best it will be once every 10 or 15 seconds, at worst every 5 or 10 mins.
14
+1. the central monitoring solution needs dedicated resources, thus becoming "another bottleneck" in the whole ecosystem. It also requires maintenance, administration, etc.
15
+1. most centralized monitoring solutions are usually only good for presenting *statistics of past performance* (i.e. cannot be used for real-time performance troubleshooting).
16
17
-Netdata has a different approach:
17
+Netdata follows a different approach:
18
19
1. data collection happens per second
20
-2. thousands of metrics per server are collected
21
-3. data do not leave the server where they are collected
22
-4. netdata servers do not talk to each other
23
-5. your browser connects all the netdata servers
20
+1. thousands of metrics per server are collected
21
+1. data do not leave the server where they are collected
22
+1. netdata servers do not talk to each other
23
+1. your browser connects all the netdata servers
24
25
-Using netdata, your monitoring infrastructure is embedded on each server, limiting significantly the need of additional resources. netdata is blazingly fast, very resource efficient and utilizes server resources that already exist and are spare (on each server). This allows **scaling out** the monitoring infrastructure.
25
+Using netdata, your monitoring infrastructure is embedded on each server, limiting significantly the need of additional resources. Netdata is blazingly fast, very resource efficient and utilizes server resources that already exist and are spare (on each server). This allows **scaling out** the monitoring infrastructure.
26
27
However, the netdata approach introduces a few new issues that need to be addressed, one being **the list of netdata we have installed**, i.e. the URLs our netdata servers are listening.
28
29
-To solve this, netdata utilizes a **central registry**. This registry, together with certain browser features, allow netdata to provide unified cross server dashboards. For example, when you jump from server to server using the `my-netdata` menu, several session settings (like the currently viewed charts, the current zoom and pan operations on the charts, etc) are propagated to the new server, so that the new dashboard will come with exactly the same view.
29
+To solve this, netdata utilizes a **central registry**. This registry, together with certain browser features, allow netdata to provide unified cross-server dashboards. For example, when you jump from server to server using the `my-netdata` menu, several session settings (like the currently viewed charts, the current zoom and pan operations on the charts, etc.) are propagated to the new server, so that the new dashboard will come with exactly the same view.
30
31
## What is the registry?
32
@@ -66,7 +66,7 @@ For *persons* and *machines*, the registry keeps links to *URLs*, each link with
66
67
`https://registry.my-netdata.io`, which is currently served by `https://london.my-netdata.io`. This registry listens to both HTTP and HTTPS requests but the default is HTTPS.
68
69
-#### Can this registry handle the global load of netdata installations?
69
+### Can this registry handle the global load of netdata installations?
70
71
Yeap! The registry can handle 50.000 - 100.000 requests **per second per core** (depending on the type of CPU, the computer's memory bandwidth, etc). 50.000 is on J1900 (celeron 2Ghz).
72
@@ -107,7 +107,7 @@ You may also want to give your server different names under the **my-netdata** m
107
108
So this server will appear in **my-netdata** as `Group1 - Master DB`. The max name length is 50 characters.
109
110
-#### limiting access to the registry
110
+### Limiting access to the registry
111
112
netdata v1.9+ support limiting access to the registry from given IPs, like this:
113
```
@@ -119,7 +119,7 @@ netdata v1.9+ support limiting access to the registry from given IPs, like this:
119
120
Keep in mind that connections to netdata API ports are filtered by `[web].allow connections from`. So, IPs allowed by `[registry].allow from` should also be allowed by `[web].allow connection from`.
121
122
-#### Where is the registry database stored?
122
+### Where is the registry database stored?
123
124
`/var/lib/netdata/registry/*.db`
125
@@ -149,4 +149,4 @@ To use the registry, your web browser needs to support **third party cookies**,
149
ERROR 409: Cannot ACCESS netdata registry: https://registry.my-netdata.io responded with: {"status":"redirect","registry":"https://registry.my-netdata.io"}
150
```
151
152
-This error is printed on your web browser console (press F12 on your browser to show it).
152
+This error is printed on your web browser console (press F12 on your browser to see it).
web/api/README.md
+4
-3
@@ -1,10 +1,12 @@
1
-# netdata REST API
1
+# API
2
+
3
+## Netdata REST API
4
5
The complete documentation of the netdata API is available at the **[Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/netdata/netdata/master/web/api/netdata-swagger.yaml)**.
6
7
If your prefer it over the Swagger Editor, you can also use **[Swagger UI](https://registry.my-netdata.io/swagger/#!/default/get_data)**. This however does not provide all the information available.
8
7
-## google charts
9
+## Google charts API
10
11
netdata is a [Google Visualization API datatable and datasource provider](https://developers.google.com/chart/interactive/docs/reference), so it can directly be used with [Google Charts](https://developers.google.com/chart/interactive/docs/).
12
@@ -15,4 +17,3 @@ Check this [single chart, jsfiddle example](https://jsfiddle.net/ktsaou/ensu4uws
17
and this [multi chart, jsfiddle example](https://jsfiddle.net/ktsaou/L5y2eqp2/):
18
19
18
-
web/api/web_api_v1.c
+14
@@ -429,6 +429,20 @@ inline int web_client_api_request_v1_data(RRDHOST *host, struct web_client *w, c
429
return ret;
430
}
431
432
+// Pings a netdata server:
433
+// /api/v1/registry?action=hello
434
+//
435
+// Access to a netdata registry:
436
+// /api/v1/registry?action=access&machine=${machine_guid}&name=${hostname}&url=${url}
437
+//
438
+// Delete from a netdata registry:
439
+// /api/v1/registry?action=delete&machine=${machine_guid}&name=${hostname}&url=${url}&delete_url=${delete_url}
440
+//
441
+// Search for the URLs of a machine:
442
+// /api/v1/registry?action=search&machine=${machine_guid}&name=${hostname}&url=${url}&for=${machine_guid}
443
+//
444
+// Impersonate:
445
+// /api/v1/registry?action=switch&machine=${machine_guid}&name=${hostname}&url=${url}&to=${new_person_guid}
446
inline int web_client_api_request_v1_registry(RRDHOST *host, struct web_client *w, char *url) {
447
static uint32_t hash_action = 0, hash_access = 0, hash_hello = 0, hash_delete = 0, hash_search = 0,
448
hash_switch = 0, hash_machine = 0, hash_url = 0, hash_name = 0, hash_delete_url = 0, hash_for = 0,
web/gui/README.md
+3
@@ -0,0 +1,3 @@
1
+# Web GUI
2
+
3
+A Graphical User Interface for visualizing data collected by Netdata.
web/server/README.md
+18
-22
@@ -1,6 +1,6 @@
1
-# netdata web server
1
+# Netdata web server
2
3
-netdata supports 3 implementation of its internal web server:
3
+Netdata supports 3 implementations of its internal web server:
4
5
- `static-threaded` is a web server with a fix (configured number of threads)
6
- `single-threaded` is a simple web server running with a single thread
@@ -13,10 +13,9 @@ All versions of the web servers use non-blocking I/O.
13
14
All web servers respect the `keep-alive` HTTP header to serve multiple HTTP requests via the same connection.
15
16
-
16
## Configuration
17
19
-#### selecting the web server
18
+### Selecting the web server
19
20
You can select the web server implementation by editing `netdata.conf` and setting:
21
@@ -36,35 +35,33 @@ The `static` web server supports also these settings:
35
36
The default number of processor threads is `min(cpu cores, 6)`.
37
39
-The `web server max sockets` setting is automatically adjusted to 50% of the max number of open files
40
-netdata is allowed to use (via `/etc/security/limits.conf` or systemd), to allow enough file descriptors
41
-to be available for data collection.
38
+The `web server max sockets` setting is automatically adjusted to 50% of the max number of open files netdata is allowed to use (via `/etc/security/limits.conf` or systemd), to allow enough file descriptors to be available for data collection.
39
43
-#### binding netdata to multiple ports
40
+### Binding netdata to multiple ports
41
45
-netdata can bind to multiple IPs and ports. Up to 100 sockets can be used
46
-(you can increase it at compile time with `CFLAGS="-DMAX_LISTEN_FDS=200" ./netdata-installer.sh ...`).
42
+Netdata can bind to multiple IPs and ports. Up to 100 sockets can be used (you can increase it at compile time with `CFLAGS="-DMAX_LISTEN_FDS=200" ./netdata-installer.sh ...`).
43
44
The ports to bind are controlled via `[web].bind to`, like this:
49
-
45
+
46
```
47
[web]
48
default port = 19999
49
bind to = 127.0.0.1 10.1.1.1:19998 hostname:19997 [::]:19996 localhost:19995 *:http unix:/tmp/netdata.sock
50
```
55
-
51
+
52
Using the above, netdata will bind to:
57
- - IPv4 127.0.0.1 at port 19999 (port was used from `default port`)
58
- - IPv4 10.1.1.1 at port 19998
59
- - All the IPs `hostname` resolves to (both IPv4 and IPv6 depending on the resolved IPs) at port 19997
60
- - All IPv6 IPs at port 19996
61
- - All the IPs `localhost` resolves to (both IPv4 and IPv6 depending the resolved IPs) at port 19996
62
- - All IPv4 and IPv6 IPs at port `http` as set in `/etc/services`
63
- - Unix domain socket `/tmp/netdata.sock`
64
-
53
+
54
+- IPv4 127.0.0.1 at port 19999 (port was used from `default port`)
55
+- IPv4 10.1.1.1 at port 19998
56
+- All the IPs `hostname` resolves to (both IPv4 and IPv6 depending on the resolved IPs) at port 19997
57
+- All IPv6 IPs at port 19996
58
+- All the IPs `localhost` resolves to (both IPv4 and IPv6 depending the resolved IPs) at port 19996
59
+- All IPv4 and IPv6 IPs at port `http` as set in `/etc/services`
60
+- Unix domain socket `/tmp/netdata.sock`
61
+
62
The option `[web].default port` is used when an entries in `[web].bind to` do not specify a port.
63
67
-#### access lists
64
+### Access lists
65
66
Netdata supports access lists in `netdata.conf`:
67
@@ -104,4 +101,3 @@ If you publish your netdata to the internet, you may want to apply some protecti
101
3. Don't use all your cpu cores for netdata (lower `[web].web server threads`)
102
4. Run netdata with a low process scheduling priority (the default is the lowest)
103
5. If possible, proxy netdata via a full featured web server (nginx, apache, etc)
107
-