requests|warning|critical The column `minimum requests` state the minimum number of requests required for the alarm to be evaluated. We found that when the site is receiving requests above this rate, these alarms are pretty accurate (i.e. no false-positives). -[**netdata**](https://my-netdata.io/) alarms are user configurable. Sample config files can be found under directory `health/health.d` of the netdata github repository. So, even [`web_log` alarms can be adapted to your needs](../../../health/health.d/web_log.conf). +[**netdata**](https://my-netdata.io/) alarms are user configurable. Sample config files can be found under directory `health/health.d` of the [Netdata GitHub repository](https://github.com/netdata/netdata/). So, even [`web_log` alarms can be adapted to your needs](../../../health/health.d/web_log.conf). []() diff --git a/collectors/statsd.plugin/README.md b/collectors/statsd.plugin/README.md index 399918dc94..4df9860048 100644 --- a/collectors/statsd.plugin/README.md +++ b/collectors/statsd.plugin/README.md @@ -4,7 +4,7 @@ statsd is a system to collect data from any application. Applications are sendin There is a [plethora of client libraries](https://github.com/etsy/statsd/wiki#client-implementations) for embedding statsd metrics to any application framework. This makes statsd quite popular for custom application metrics. -netdata is a fully featured statsd server. It can collect statsd formatted metrics, visualize them on its dashboards, stream them to other netdata servers or archive them to backend time-series databases. +Netdata is a fully featured statsd server. It can collect statsd formatted metrics, visualize them on its dashboards, stream them to other Netdata servers or archive them to backend time-series databases. Netdata statsd is inside Netdata (an internal plugin, running inside the Netdata daemon), it is configured via `netdata.conf` and by-default listens on standard statsd ports (tcp and udp 8125 - yes, Netdata statsd server supports both tcp and udp at the same time). @@ -62,19 +62,19 @@ The application may append `|@sampling_rate`, where `sampling_rate` is a number #### Overlapping metrics -netdata statsd maintains different indexes for each of the types supported. This means the same metric `name` may exist under different types concurrently. +Netdata's statsd server maintains different indexes for each of the types supported. This means the same metric `name` may exist under different types concurrently. #### Multiple metrics per packet -netdata accepts multiple metrics per packet if each is terminated with `\n`. +Netdata accepts multiple metrics per packet if each is terminated with `\n`. #### TCP packets -netdata listens for both TCP and UDP packets. For TCP though, is it important to always append `\n` on each metric. netdata uses this to detect if a metric is split into multiple TCP packets. On disconnect, even the remaining (non terminated with `\n`) buffer, is processed. +Netdata listens for both TCP and UDP packets. For TCP though, is it important to always append `\n` on each metric. Netdata uses this to detect if a metric is split into multiple TCP packets. On disconnect, even the remaining (non terminated with `\n`) buffer, is processed. #### UDP packets -When sending multiple packets over UDP, it is important not to exceed the network MTU (usually 1500 bytes minus a few bytes for the headers). netdata will accept UDP packets up to 9000 bytes, but the underlying network will not exceed MTU. +When sending multiple packets over UDP, it is important not to exceed the network MTU (usually 1500 bytes minus a few bytes for the headers). Netdata will accept UDP packets up to 9000 bytes, but the underlying network will not exceed MTU. ## configuration @@ -107,7 +107,7 @@ This is the statsd configuration at `/etc/netdata/netdata.conf`: ### statsd main config options - `enabled = yes|no` - controls if statsd will be enabled for this netdata. The default is enabled. + controls if statsd will be enabled for this Netdata. The default is enabled. - `default port = 8125` @@ -117,15 +117,15 @@ This is the statsd configuration at `/etc/netdata/netdata.conf`: is a space separated list of IPs and ports to listen to. The format is `PROTOCOL:IP:PORT` - if `PORT` is omitted, the `default port` will be used. If `IP` is IPv6, it needs to be enclosed in `[]`. `IP` can also be ` * ` (to listen on all IPs) or even a hostname. -- `update every (flushInterval) = 1` seconds, controls the frequency statsd will push the collected metrics to netdata charts. +- `update every (flushInterval) = 1` seconds, controls the frequency statsd will push the collected metrics to Netdata charts. -- `decimal detail = 1000` controls the number of fractional digits in gauges and histograms. netdata collects metrics using signed 64 bit integers and their fractional detail is controlled using multipliers and divisors. This setting is used to multiply all collected values to convert them to integers and is also set as the divisors, so that the final data will be a floating point number with this fractional detail (1000 = X.0 - X.999, 10000 = X.0 - X.9999, etc). +- `decimal detail = 1000` controls the number of fractional digits in gauges and histograms. Netdata collects metrics using signed 64 bit integers and their fractional detail is controlled using multipliers and divisors. This setting is used to multiply all collected values to convert them to integers and is also set as the divisors, so that the final data will be a floating point number with this fractional detail (1000 = X.0 - X.999, 10000 = X.0 - X.9999, etc). The rest of the settings are discussed below. ## statsd charts -netdata can visualize statsd collected metrics in 2 ways: +Netdata can visualize statsd collected metrics in 2 ways: 1. Each metric gets its own **private chart**. This is the default and does not require any configuration (although there are a few options to tweak). @@ -143,11 +143,11 @@ create private charts for metrics matching = !myapp.*.badmetric myapp.* The default is to render private charts for all metrics. -The `memory mode` of the round robin database and the `history` of private metric charts are controlled with `private charts memory mode` and `private charts history`. The defaults for both settings is to use the global netdata settings. So, you need to edit them only when you want statsd to use different settings compared to the global ones. +The `memory mode` of the round robin database and the `history` of private metric charts are controlled with `private charts memory mode` and `private charts history`. The defaults for both settings is to use the global Netdata settings. So, you need to edit them only when you want statsd to use different settings compared to the global ones. -If you have thousands of metrics, each with its own private chart, you may notice that your web browser becomes slow when you view the netdata dashboard (this is a web browser issue we need to address at the netdata UI). So, netdata has a protection to stop creating charts when `max private charts allowed = 200` (soft limit) is reached. +If you have thousands of metrics, each with its own private chart, you may notice that your web browser becomes slow when you view the Netdata dashboard (this is a web browser issue we need to address at the Netdata UI). So, Netdata has a protection to stop creating charts when `max private charts allowed = 200` (soft limit) is reached. -The metrics above this soft limit are still processed by netdata and will be available to be sent to backend time-series databases, up to `max private charts hard limit = 1000`. So, between 200 and 1000 charts, netdata will still generate charts, but they will automatically be created with `memory mode = none` (netdata will not maintain a database for them). These metrics will be sent to backend time series databases, if the backend configuration is set to `as collected`. +The metrics above this soft limit are still processed by Netdata and will be available to be sent to backend time-series databases, up to `max private charts hard limit = 1000`. So, between 200 and 1000 charts, Netdata will still generate charts, but they will automatically be created with `memory mode = none` (Netdata will not maintain a database for them). These metrics will be sent to backend time series databases, if the backend configuration is set to `as collected`. Metrics above the hard limit are still collected, but they can only be used in synthetic charts (once a metric is added to chart, it will be sent to backend servers too). @@ -217,7 +217,7 @@ Using synthetic charts, you can create dedicated sections on the dashboard to re Synthetic charts are organized in -- **applications** (i.e. entries at the main menu of the netdata dashboard) +- **applications** (i.e. entries at the main menu of the Netdata dashboard) - **charts for each application** (grouped in families - i.e. submenus at the dashboard menu) - **statsd metrics for each chart** (i.e. dimensions of the charts) @@ -257,11 +257,11 @@ Using the above configuration `myapp` should get its own section on the dashboar `[app]` starts a new application definition. The supported settings in this section are: - `name` defines the name of the app. -- `metrics` is a netdata simple pattern (space separated patterns, using `*` for wildcard, possibly starting with `!` for negative match). This pattern should match all the possible statsd metrics that will be participating in the application `myapp`. +- `metrics` is a Netdata simple pattern (space separated patterns, using `*` for wildcard, possibly starting with `!` for negative match). This pattern should match all the possible statsd metrics that will be participating in the application `myapp`. - `private charts = yes|no`, enables or disables private charts for the metrics matched. - `gaps when not collected = yes|no`, enables or disables gaps on the charts of the application, when metrics are not collected. -- `memory mode` sets the memory mode for all charts of the application. The default is the global default for netdata (not the global default for statsd private charts). -- `history` sets the size of the round robin database for this application. The default is the global default for netdata (not the global default for statsd private charts). +- `memory mode` sets the memory mode for all charts of the application. The default is the global default for Netdata (not the global default for statsd private charts). +- `history` sets the size of the round robin database for this application. The default is the global default for Netdata (not the global default for statsd private charts). `[dictionary]` defines name-value associations. These are used to renaming metrics, when added to synthetic charts. Metric names are also defined at each `dimension` line. However, using the dictionary dimension names can be declared globally, for each app and is the only way to rename dimensions when using patterns. Of course the dictionary can be empty or missing. @@ -281,7 +281,7 @@ So, the format is this: dimension = [pattern] METRIC NAME TYPE MULTIPLIER DIVIDER OPTIONS ``` -`pattern` is a keyword. When set, `METRIC` is expected to be a netdata simple pattern that will be used to match all the statsd metrics to be added to the chart. So, `pattern` automatically matches any number of statsd metrics, all of which will be added as separate chart dimensions. +`pattern` is a keyword. When set, `METRIC` is expected to be a Netdata simple pattern that will be used to match all the statsd metrics to be added to the chart. So, `pattern` automatically matches any number of statsd metrics, all of which will be added as separate chart dimensions. `TYPE`, `MUTLIPLIER`, `DIVIDER` and `OPTIONS` are optional. @@ -336,13 +336,13 @@ and this synthetic chart: The `[dictionary]` section accepts any number of `name = value` pairs. -netdata uses this dictionary as follows: +Netdata uses this dictionary as follows: 1. When a `dimension` has a non-empty `NAME`, that name is looked up at the dictionary. 2. If the above lookup gives nothing, or the `dimension` has an empty `NAME`, the original statsd metric name is looked up at the dictionary. -3. If any of the above succeeds, netdata uses the `value` of the dictionary, to set the name of the dimension. The dimensions will have as ID the original statsd metric name, and as name, the dictionary value. +3. If any of the above succeeds, Netdata uses the `value` of the dictionary, to set the name of the dimension. The dimensions will have as ID the original statsd metric name, and as name, the dictionary value. So, you can use the dictionary in 2 ways: @@ -351,11 +351,11 @@ So, you can use the dictionary in 2 ways: In both cases, the dimension will be added with ID `myapp.metric1` and will be named `metric1 name`. So, in alarms you can use either of the 2 as `${myapp.metric1}` or `${metric1 name}`. -> keep in mind that if you add multiple times the same statsd metric to a chart, netdata will append `TYPE` to the dimension ID, so `myapp.metric1` will be added as `myapp.metric1_last` or `myapp.metric1_events`, etc. If you add multiple times the same metric with the same `TYPE` to a chart, netdata will also append an incremental counter to the dimension ID, i.e. `myapp.metric1_last1`, `myapp.metric1_last2`, etc. +> keep in mind that if you add multiple times the same statsd metric to a chart, Netdata will append `TYPE` to the dimension ID, so `myapp.metric1` will be added as `myapp.metric1_last` or `myapp.metric1_events`, etc. If you add multiple times the same metric with the same `TYPE` to a chart, Netdata will also append an incremental counter to the dimension ID, i.e. `myapp.metric1_last1`, `myapp.metric1_last2`, etc. #### dimension patterns -netdata allows adding multiple dimensions to a chart, by matching the statsd metrics with a netdata simple pattern. +Netdata allows adding multiple dimensions to a chart, by matching the statsd metrics with a Netdata simple pattern. Assume we have an API that provides statsd metrics for each response code per method it supports, like these: @@ -382,7 +382,7 @@ To add all response codes of `myapp.api.get` to a chart use this: dimension = pattern 'myapp.api.get.* '' last 1 1 ``` -The above will add dimension named `200`, `400` and `500` (yes, netdata extracts the wildcarded part of the metric name - so the dimensions will be named with whatever the `*` matched). You can rename the dimensions with this: +The above will add dimension named `200`, `400` and `500` (yes, Netdata extracts the wildcarded part of the metric name - so the dimensions will be named with whatever the `*` matched). You can rename the dimensions with this: ``` [dictionary] @@ -435,17 +435,17 @@ Using the above, the dimensions will be added as `GET`, `ADD` and `DELETE`. ## interpolation -~~If you send just one value to statsd, you will notice that the chart is created but no value is shown. The reason is that netdata interpolates all values at second boundaries. For incremental values (`counters` and `meters` in statsd terminology), if you send 10 at 00:00:00.500, 20 at 00:00:01.500 and 30 at 00:00:02.500, netdata will show 15 at 00:00:01 and 25 at 00:00:02.~~ +~~If you send just one value to statsd, you will notice that the chart is created but no value is shown. The reason is that Netdata interpolates all values at second boundaries. For incremental values (`counters` and `meters` in statsd terminology), if you send 10 at 00:00:00.500, 20 at 00:00:01.500 and 30 at 00:00:02.500, Netdata will show 15 at 00:00:01 and 25 at 00:00:02.~~ -~~This interpolation is automatic and global in netdata for all charts, for incremental values. This means that for the chart to start showing values you need to send 2 values across 2 flush intervals.~~ +~~This interpolation is automatic and global in Netdata for all charts, for incremental values. This means that for the chart to start showing values you need to send 2 values across 2 flush intervals.~~ -~~(although this is required for incremental values, netdata allows mixing incremental and absolute values on the same charts, so this little limitation [i.e. 2 values to start visualization], is applied on all netdata dimensions).~~ +~~(although this is required for incremental values, Netdata allows mixing incremental and absolute values on the same charts, so this little limitation [i.e. 2 values to start visualization], is applied on all Netdata dimensions).~~ (statsd metrics do not loose their first data collection due to interpolation anymore - fixed with [PR #2411](https://github.com/netdata/netdata/pull/2411)) ## sending statsd metrics from shell scripts -You can send/update statsd metrics from shell scripts. You can use this feature, to visualize in netdata automated jobs you run on your servers. +You can send/update statsd metrics from shell scripts. You can use this feature, to visualize in Netdata automated jobs you run on your servers. The command you need to run is: diff --git a/collectors/tc.plugin/README.md b/collectors/tc.plugin/README.md index 4133b4f8db..170c5e9526 100644 --- a/collectors/tc.plugin/README.md +++ b/collectors/tc.plugin/README.md @@ -42,7 +42,7 @@ QoS is about 2 features: 1. **Monitoring the bandwidth used by services** - netdata provides wonderful real-time charts, like this one (wait to see the orange `rsync` part): + Netdata provides wonderful real-time charts, like this one (wait to see the orange `rsync` part):  @@ -62,7 +62,7 @@ QoS is about 2 features: When your system is under a DDoS attack, it will get a lot more bandwidth compared to the one it can handle and probably your applications will crash. Setting a limit on the inbound traffic using QoS, will protect your servers (throttle the requests) and depending on the size of the attack may allow your legitimate users to access the server, while the attack is taking place. - Using QoS together with a [SYNPROXY](../proc.plugin/README.md#linux-anti-ddos) will provide a great degree of protection against most DDoS attacks. Actually when I wrote that article, a few folks tried to DDoS the netdata demo site to see in real-time the SYNPROXY operation. They did not do it right, but anyway a great deal of requests reached the netdata server. What saved netdata was QoS. The netdata demo server has QoS installed, so the requests were throttled and the server did not even reach the point of resource starvation. Read about it [here](../proc.plugin/README.md#linux-anti-ddos). + Using QoS together with a [SYNPROXY](../proc.plugin/README.md#linux-anti-ddos) will provide a great degree of protection against most DDoS attacks. Actually when I wrote that article, a few folks tried to DDoS the Netdata demo site to see in real-time the SYNPROXY operation. They did not do it right, but anyway a great deal of requests reached the Netdata server. What saved Netdata was QoS. The Netdata demo server has QoS installed, so the requests were throttled and the server did not even reach the point of resource starvation. Read about it [here](../proc.plugin/README.md#linux-anti-ddos). On top of all these, QoS is extremely light. You will configure it once, and this is it. It will not bother you again and it will not use any noticeable CPU resources, especially on application and database servers. @@ -72,7 +72,7 @@ On top of all these, QoS is extremely light. You will configure it once, and thi - ensure each end-user connection will get a fair cut of the available bandwidth. -Once **traffic classification** is applied, we can use **[netdata](https://github.com/netdata/netdata)** to visualize the bandwidth consumption per class in real-time (no configuration is needed for netdata - it will figure it out). +Once **traffic classification** is applied, we can use **[netdata](https://github.com/netdata/netdata)** to visualize the bandwidth consumption per class in real-time (no configuration is needed for Netdata - it will figure it out). QoS, is extremely light. You will configure it once, and this is it. It will not bother you again and it will not use any noticeable CPU resources, especially on application and database servers. @@ -115,10 +115,10 @@ To do it the hard way, you can go through the [tc configuration steps](#qos-conf The **[FireHOL](https://firehol.org/)** package already distributes **[FireQOS](https://firehol.org/tutorial/fireqos-new-user/)**. Check the **[FireQOS tutorial](https://firehol.org/tutorial/fireqos-new-user/)** to learn how to write your own QoS configuration. -With **[FireQOS](https://firehol.org/tutorial/fireqos-new-user/)**, it is **really simple for everyone to use QoS in Linux**. Just install the package `firehol`. It should already be available for your distribution. If not, check the **[FireHOL Installation Guide](https://firehol.org/installing/)**. After that, you will have the `fireqos` command which uses a configuration like the following `/etc/firehol/fireqos.conf`, used at the netdata demo site: +With **[FireQOS](https://firehol.org/tutorial/fireqos-new-user/)**, it is **really simple for everyone to use QoS in Linux**. Just install the package `firehol`. It should already be available for your distribution. If not, check the **[FireHOL Installation Guide](https://firehol.org/installing/)**. After that, you will have the `fireqos` command which uses a configuration like the following `/etc/firehol/fireqos.conf`, used at the Netdata demo site: ```sh - # configure the netdata ports + # configure the Netdata ports server_netdata_ports="tcp/19999" interface eth0 world bidirectional ethernet balanced rate 50Mbit @@ -155,7 +155,7 @@ With **[FireQOS](https://firehol.org/tutorial/fireqos-new-user/)**, it is **real match input src 10.2.3.5 ``` -Nothing more is needed. You just run `fireqos start` to apply this configuration, restart netdata and you have real-time visualization of the bandwidth consumption of your applications. FireQOS is not a daemon. It will just convert the configuration to `tc` commands. It will run them and it will exit. +Nothing more is needed. You just run `fireqos start` to apply this configuration, restart Netdata and you have real-time visualization of the bandwidth consumption of your applications. FireQOS is not a daemon. It will just convert the configuration to `tc` commands. It will run them and it will exit. **IMPORTANT**: If you copy this configuration to apply it to your system, please adapt the speeds - experiment in non-production environments to learn the tool, before applying it on your servers. @@ -191,7 +191,7 @@ Add the following configuration option in `/etc/netdata.conf`: Finally, create `/etc/netdata/tc-qos-helper.conf` with this content: ```tc_show="class"``` -Please note, that by default Netdata will enable monitoring metrics only when they are not zero. If they are constantly zero they are ignored. Metrics that will start having values, after netdata is started, will be detected and charts will be automatically added to the dashboard (a refresh of the dashboard is needed for them to appear though). Set `yes` for a chart instead of `auto` to enable it permanently. You can also set the `enable zero metrics` option to `yes` in the `[global]` section which enables charts with zero metrics for all internal Netdata plugins. +Please note, that by default Netdata will enable monitoring metrics only when they are not zero. If they are constantly zero they are ignored. Metrics that will start having values, after Netdata is started, will be detected and charts will be automatically added to the dashboard (a refresh of the dashboard is needed for them to appear though). Set `yes` for a chart instead of `auto` to enable it permanently. You can also set the `enable zero metrics` option to `yes` in the `[global]` section which enables charts with zero metrics for all internal Netdata plugins. []() diff --git a/collectors/xenstat.plugin/README.md b/collectors/xenstat.plugin/README.md index f803dbf36c..b52757a6b8 100644 --- a/collectors/xenstat.plugin/README.md +++ b/collectors/xenstat.plugin/README.md @@ -6,7 +6,7 @@ 1. install `xen-dom0-libs-devel` and `yajl-devel` using the package manager of your system. -2. re-install netdata from source. The installer will detect that the required libraries are now available and will also build xenstat.plugin. +2. re-install Netdata from source. The installer will detect that the required libraries are now available and will also build xenstat.plugin. Keep in mind that `libxenstat` requires root access, so the plugin is setuid to root. @@ -25,7 +25,7 @@ Domain: ## Configuration -If you need to disable xenstat for netdata, edit /etc/netdata/netdata.conf and set: +If you need to disable xenstat for Netdata, edit /etc/netdata/netdata.conf and set: ``` [plugins] diff --git a/contrib/README.md b/contrib/README.md index c5ce873a77..a5dafa01bc 100644 --- a/contrib/README.md +++ b/contrib/README.md @@ -1,4 +1,4 @@ -# netdata contrib +# Netdata contrib ## Building .deb packages @@ -7,8 +7,8 @@ Debian package. It has been tested on Debian Jessie and Wheezy, but should work, possibly with minor changes, if you have other dpkg-based systems such as Ubuntu or Mint. -To build netdata for a Debian Jessie system, the debian directory -has to be available in the root of the netdata source. The easiest +To build Netdata for a Debian Jessie system, the debian directory +has to be available in the root of the Netdata source. The easiest way to do this is with a symlink: ~/netdata$ ln -s contrib/debian @@ -50,9 +50,9 @@ updates first. Then proceed as the main instructions above. -### Reinstalling netdata +### Reinstalling Netdata -The recommended way to upgrade netdata packages built from this +The recommended way to upgrade Netdata packages built from this source is to remove the current package from your system, then install the new package. Upgrading on wheezy is known to not work cleanly; Jessie may behave as expected. diff --git a/contrib/sles11/README.md b/contrib/sles11/README.md index d052b9454a..fb584bbec3 100644 --- a/contrib/sles11/README.md +++ b/contrib/sles11/README.md @@ -1,10 +1,10 @@ -# spec to build netdata RPM for sles 11 +# Spec to build Netdata RPM for sles 11 Based on [opensuse rpm spec](https://build.opensuse.org/package/show/network/netdata) with some changes and additions for sles 11 backport, namely: - init.d script - run-time dependency on python ordereddict backport -- patch for netdata python.d plugin to work with older python +- patch for Netdata python.d plugin to work with older python - crude hack of notification script to work with bash 3 (email and syslog only, one destination, see comments at the top) diff --git a/daemon/README.md b/daemon/README.md index 62cc8c3b2b..26d19b66de 100644 --- a/daemon/README.md +++ b/daemon/README.md @@ -2,10 +2,10 @@ ## Starting netdata -- You can start netdata by executing it with `/usr/sbin/netdata` (the installer will also start it). +- You can start Netdata by executing it with `/usr/sbin/netdata` (the installer will also start it). -- You can stop netdata by killing it with `killall netdata`. - You can stop and start netdata at any point. Netdata saves on exit its round robbin +- You can stop Netdata by killing it with `killall netdata`. + You can stop and start Netdata at any point. Netdata saves on exit its round robbin database to `/var/cache/netdata` so that it will continue from where it stopped the last time. Access to the web site, for all graphs, is by default on port `19999`, so go to: @@ -16,7 +16,7 @@ Access to the web site, for all graphs, is by default on port `19999`, so go to: You can get the running config file at any time, by accessing `http://127.0.0.1:19999/netdata.conf`. -### Starting netdata at boot +### Starting Netdata at boot In the `system` directory you can find scripts and configurations for the various distros. @@ -27,7 +27,7 @@ The installer already installs `netdata.service` if it detects a systemd system. To install `netdata.service` by hand, run: ```sh -# stop netdata +# stop Netdata killall netdata # copy netdata.service to systemd @@ -36,10 +36,10 @@ cp system/netdata.service /etc/systemd/system/ # let systemd know there is a new service systemctl daemon-reload -# enable netdata at boot +# enable Netdata at boot systemctl enable netdata -# start netdata +# start Netdata systemctl start netdata ``` @@ -48,7 +48,7 @@ systemctl start netdata In the system directory you can find `netdata-lsb`. Copy it to the proper place according to your distribution documentation. For Ubuntu, this can be done via running the following commands as root. ```sh -# copy the netdata startup file to /etc/init.d +# copy the Netdata startup file to /etc/init.d cp system/netdata-lsb /etc/init.d/netdata # make sure it is executable @@ -67,7 +67,7 @@ In the `system` directory you can find `netdata-openrc`. Copy it to the proper p For older versions of RHEL/CentOS that don't have systemd, an init script is included in the system directory. This can be installed by running the following commands as root. ```sh -# copy the netdata startup file to /etc/init.d +# copy the Netdata startup file to /etc/init.d cp system/netdata-init-d /etc/init.d/netdata # make sure it is executable @@ -81,7 +81,7 @@ _There have been some recent work on the init script, see PR https://github.com/ #### other systems -You can start netdata by running it from `/etc/rc.local` or equivalent. +You can start Netdata by running it from `/etc/rc.local` or equivalent. ## Command line options @@ -97,7 +97,7 @@ netdata -h The program will print the supported command line parameters. -The command line options of the netdata 1.10.0 version are the following: +The command line options of the Netdata 1.10.0 version are the following: ``` ^ @@ -182,7 +182,7 @@ The command line options of the netdata 1.10.0 version are the following: ## Log files -netdata uses 3 log files: +Netdata uses 3 log files: 1. `error.log` 2. `access.log` @@ -190,18 +190,18 @@ netdata uses 3 log files: Any of them can be disabled by setting it to `/dev/null` or `none` in `netdata.conf`. By default `error.log` and `access.log` are enabled. `debug.log` is only enabled if -debugging/tracing is also enabled (netdata needs to be compiled with debugging enabled). +debugging/tracing is also enabled (Netdata needs to be compiled with debugging enabled). Log files are stored in `/var/log/netdata/` by default. #### error.log -The `error.log` is the `stderr` of the netdata daemon and all external plugins run by netdata. +The `error.log` is the `stderr` of the `netdata` daemon and all external plugins run by netdata. -So if any process, in the netdata process tree, writes anything to its standard error, +So if any process, in the Netdata process tree, writes anything to its standard error, it will appear in `error.log`. -For most netdata programs (including standard external plugins shipped by netdata), the +For most Netdata programs (including standard external plugins shipped by netdata), the following lines may appear: tag|description @@ -213,7 +213,7 @@ tag|description So, when auto-detection of data collection fail, `ERROR` lines are logged and the relevant modules are disabled, but the program continues to run. -When a netdata program cannot run at all, a `FATAL` line is logged. +When a Netdata program cannot run at all, a `FATAL` line is logged. #### access.log @@ -231,7 +231,7 @@ where: - `PERCENT_COMPRESSION` is the percentage of traffic saved due to compression. - `PREP_TIME` is the time in milliseconds needed to prepared the response. - `SENT_TIME` is the time in milliseconds needed to sent the response to the client. - - `TOTAL_TIME` is the total time the request was inside netdata (from the first byte of the request to the last byte of the response). + - `TOTAL_TIME` is the total time the request was inside Netdata (from the first byte of the request to the last byte of the response). - `ACTION` can be `filecopy`, `options` (used in CORS), `data` (API call). @@ -242,17 +242,17 @@ See [debugging](#debugging). ## OOM Score -netdata runs with `OOMScore = 1000`. This means netdata will be the first to be killed when your +Netdata runs with `OOMScore = 1000`. This means Netdata will be the first to be killed when your server runs out of memory. -You can set netdata OOMScore in `netdata.conf`, like this: +You can set Netdata OOMScore in `netdata.conf`, like this: ``` [global] OOM score = 1000 ``` -netdata logs its OOM score when it starts: +Netdata logs its OOM score when it starts: ```sh # grep OOM /var/log/netdata/error.log @@ -261,16 +261,16 @@ netdata logs its OOM score when it starts: #### OOM score and systemd -netdata will not be able to lower its OOM Score below zero, when it is started as the `netdata` +Netdata will not be able to lower its OOM Score below zero, when it is started as the `netdata` user (systemd case). -To allow netdata control its OOM Score in such cases, you will need to edit +To allow Netdata control its OOM Score in such cases, you will need to edit `netdata.service` and set: ``` [Service] -# The minimum netdata Out-Of-Memory (OOM) score. -# netdata (via [global].OOM score in netdata.conf) can only increase the value set here. +# The minimum Netdata Out-Of-Memory (OOM) score. +# Netdata (via [global].OOM score in netdata.conf) can only increase the value set here. # To decrease it, set the minimum here and set the same or a higher value in netdata.conf. # Valid values: -1000 (never kill netdata) to 1000 (always kill netdata). OOMScoreAdjust=-1000 @@ -278,7 +278,7 @@ OOMScoreAdjust=-1000 Run `systemctl daemon-reload` to reload these changes. -The above, sets and OOMScore for netdata to `-1000`, so that netdata can increase it via +The above, sets and OOMScore for Netdata to `-1000`, so that Netdata can increase it via `netdata.conf`. If you want to control it entirely via systemd, you can set in `netdata.conf`: @@ -293,9 +293,9 @@ Using the above, whatever OOM Score you have set at `netdata.service` will be ma ## Netdata process scheduling policy -By default netdata runs with the `idle` process scheduling policy, so that it uses CPU resources, only when there is idle CPU to spare. On very busy servers (or weak servers), this can lead to gaps on the charts. +By default Netdata runs with the `idle` process scheduling policy, so that it uses CPU resources, only when there is idle CPU to spare. On very busy servers (or weak servers), this can lead to gaps on the charts. -You can set netdata scheduling policy in `netdata.conf`, like this: +You can set Netdata scheduling policy in `netdata.conf`, like this: ``` [global] @@ -306,7 +306,7 @@ You can use the following: policy|description :-----:|:-------- -`idle`|use CPU only when there is spare - this is lower than nice 19 - it is the default for netdata and it is so low that netdata will run in "slow motion" under extreme system load, resulting in short (1-2 seconds) gaps at the charts. +`idle`|use CPU only when there is spare - this is lower than nice 19 - it is the default for Netdata and it is so low that Netdata will run in "slow motion" under extreme system load, resulting in short (1-2 seconds) gaps at the charts. `other`
or
`nice`|this is the default policy for all processes under Linux. It provides dynamic priorities based on the `nice` level of each process. Check below for setting this `nice` level for netdata. `batch`|This policy is similar to `other` in that it schedules the thread according to its dynamic priority (based on the `nice` value). The difference is that this policy will cause the scheduler to always assume that the thread is CPU-intensive. Consequently, the scheduler will apply a small scheduling penalty with respect to wake-up behavior, so that this thread is mildly disfavored in scheduling decisions. `fifo`|`fifo` can be used only with static priorities higher than 0, which means that when a `fifo` threads becomes runnable, it will always immediately preempt any currently running `other`, `batch`, or `idle` thread. `fifo` is a simple scheduling algorithm without time slicing. @@ -337,30 +337,30 @@ When the policy is set to `other`, `nice`, or `batch`, the following will appear ## scheduling settings and systemd -netdata will not be able to set its scheduling policy and priority to more important values when it is started as the `netdata` user (systemd case). +Netdata will not be able to set its scheduling policy and priority to more important values when it is started as the `netdata` user (systemd case). You can set these settings at `/etc/systemd/system/netdata.service`: ``` [Service] -# By default netdata switches to scheduling policy idle, which makes it use CPU, only +# By default Netdata switches to scheduling policy idle, which makes it use CPU, only # when there is spare available. # Valid policies: other (the system default) | batch | idle | fifo | rr #CPUSchedulingPolicy=other -# This sets the maximum scheduling priority netdata can set (for policies: rr and fifo). -# netdata (via [global].process scheduling priority in netdata.conf) can only lower this value. +# This sets the maximum scheduling priority Netdata can set (for policies: rr and fifo). +# Netdata (via [global].process scheduling priority in netdata.conf) can only lower this value. # Priority gets values 1 (lowest) to 99 (highest). #CPUSchedulingPriority=1 # For scheduling policy 'other' and 'batch', this sets the lowest niceness of netdata. -# netdata (via [global].process nice level in netdata.conf) can only increase the value set here. +# Netdata (via [global].process nice level in netdata.conf) can only increase the value set here. #Nice=0 ``` Run `systemctl daemon-reload` to reload these changes. -Now, tell netdata to keep these settings, as set by systemd, by editing `netdata.conf` and setting: +Now, tell Netdata to keep these settings, as set by systemd, by editing `netdata.conf` and setting: ``` [global] @@ -370,9 +370,9 @@ Now, tell netdata to keep these settings, as set by systemd, by editing `netdata Using the above, whatever scheduling settings you have set at `netdata.service` will be maintained by netdata. -#### Example 1: netdata with nice -1 on non-systemd systems +#### Example 1: Netdata with nice -1 on non-systemd systems -On a system that is not based on systemd, to make netdata run with nice level -1 (a little bit higher to the default for all programs), edit netdata.conf and set: +On a system that is not based on systemd, to make Netdata run with nice level -1 (a little bit higher to the default for all programs), edit `netdata.conf` and set: ``` [global] @@ -387,9 +387,9 @@ sudo service netdata restart ``` -#### Example 2: netdata with nice -1 on systemd systems +#### Example 2: Netdata with nice -1 on systemd systems -On a system that is based on systemd, to make netdata run with nice level -1 (a little bit higher to the default for all programs), edit netdata.conf and set: +On a system that is based on systemd, to make Netdata run with nice level -1 (a little bit higher to the default for all programs), edit `netdata.conf` and set: ``` [global] @@ -415,9 +415,9 @@ sudo systemctl restart netdata You may notice that netdata's virtual memory size, as reported by `ps` or `/proc/pid/status` (or even netdata's applications virtual memory chart) is unrealistically high. -For example, it may be reported to be 150+MB, even if the resident memory size is just 25MB. Similar values may be reported for netdata plugins too. +For example, it may be reported to be 150+MB, even if the resident memory size is just 25MB. Similar values may be reported for Netdata plugins too. -Check this for example: A netdata installation with default settings on Ubuntu 16.04LTS. The top chart is **real memory used**, while the bottom one is **virtual memory**: +Check this for example: A Netdata installation with default settings on Ubuntu 16.04LTS. The top chart is **real memory used**, while the bottom one is **virtual memory**:  @@ -431,19 +431,18 @@ number of threads running. The system does this for speed. Having a separate memory arena for each thread, allows the threads to run in parallel in multi-core systems, without any locks between them. -This behaviour is system specific. For example, the chart above when running netdata on alpine -linux (that uses **musl** instead of **glibc**) is this: +This behaviour is system specific. For example, the chart above when running Netdata on Alpine Linux (that uses **musl** instead of **glibc**) is this:  **Can we do anything to lower it?** -Since netdata already uses minimal memory allocations while it runs (i.e. it adapts its memory on start, so that while repeatedly collects data it does not do memory allocations), it already instructs the system memory allocator to minimize the memory arenas for each thread. We have also added [2 configuration options](https://github.com/netdata/netdata/blob/5645b1ee35248d94e6931b64a8688f7f0d865ec6/src/main.c#L410-L418) +Since Netdata already uses minimal memory allocations while it runs (i.e. it adapts its memory on start, so that while repeatedly collects data it does not do memory allocations), it already instructs the system memory allocator to minimize the memory arenas for each thread. We have also added [2 configuration options](https://github.com/netdata/netdata/blob/5645b1ee35248d94e6931b64a8688f7f0d865ec6/src/main.c#L410-L418) to allow you tweak these settings: `glibc malloc arena max for plugins` and `glibc malloc arena max for netdata`. However, even if we instructed the memory allocator to use just one arena, it seems it allocates an arena per thread. -netdata also supports `jemalloc` and `tcmalloc`, however both behave exactly the same to the glibc memory allocator in this aspect. +Netdata also supports `jemalloc` and `tcmalloc`, however both behave exactly the same to the glibc memory allocator in this aspect. **Is this a problem?** @@ -452,53 +451,53 @@ No, it is not. Linux reserves real memory (physical RAM) in pages (on x86 machines pages are 4KB each). So even if the system memory allocator is allocating huge amounts of virtual memory, only the 4KB pages that are actually used are reserving physical RAM. The **real memory** chart -on netdata application section, shows the amount of physical memory these pages occupy(it +on Netdata application section, shows the amount of physical memory these pages occupy(it accounts the whole pages, even if parts of them are actually used). ## Debugging -When you compile netdata with debugging: +When you compile Netdata with debugging: -1. compiler optimizations for your CPU are disabled (netdata will run somewhat slower) +1. compiler optimizations for your CPU are disabled (Netdata will run somewhat slower) -2. a lot of code is added all over netdata, to log debug messages to `/var/log/netdata/debug.log`. However, nothing is printed by default. netdata allows you to select which sections of netdata you want to trace. Tracing is activated via the config option `debug flags`. It accepts a hex number, to enable or disable specific sections. You can find the options supported at [log.h](../libnetdata/log/log.h). They are the `D_*` defines. The value `0xffffffffffffffff` will enable all possible debug flags. +2. a lot of code is added all over netdata, to log debug messages to `/var/log/netdata/debug.log`. However, nothing is printed by default. Netdata allows you to select which sections of Netdata you want to trace. Tracing is activated via the config option `debug flags`. It accepts a hex number, to enable or disable specific sections. You can find the options supported at [log.h](../libnetdata/log/log.h). They are the `D_*` defines. The value `0xffffffffffffffff` will enable all possible debug flags. -Once netdata is compiled with debugging and tracing is enabled for a few sections, the file `/var/log/netdata/debug.log` will contain the messages. +Once Netdata is compiled with debugging and tracing is enabled for a few sections, the file `/var/log/netdata/debug.log` will contain the messages. > Do not forget to disable tracing (`debug flags = 0`) when you are done tracing. The file `debug.log` can grow too fast. -#### compiling netdata with debugging +#### compiling Netdata with debugging -To compile netdata with debugging, use this: +To compile Netdata with debugging, use this: ```sh -# step into the netdata source directory +# step into the Netdata source directory cd /usr/src/netdata.git # run the installer with debugging enabled CFLAGS="-O1 -ggdb -DNETDATA_INTERNAL_CHECKS=1" ./netdata-installer.sh ``` -The above will compile and install netdata with debugging info embedded. You can now use `debug flags` to set the section(s) you need to trace. +The above will compile and install Netdata with debugging info embedded. You can now use `debug flags` to set the section(s) you need to trace. #### debugging crashes -We have made the most to make netdata crash free. If however, netdata crashes on your system, it would be very helpful to provide stack traces of the crash. Without them, is will be almost impossible to find the issue (the code base is quite large to find such an issue by just objerving it). +We have made the most to make Netdata crash free. If however, Netdata crashes on your system, it would be very helpful to provide stack traces of the crash. Without them, is will be almost impossible to find the issue (the code base is quite large to find such an issue by just objerving it). -To provide stack traces, **you need to have netdata compiled with debugging**. There is no need to enable any tracing (`debug flags`). +To provide stack traces, **you need to have Netdata compiled with debugging**. There is no need to enable any tracing (`debug flags`). Then you need to be in one of the following 2 cases: -1. netdata crashes and you have a core dump +1. Netdata crashes and you have a core dump 2. you can reproduce the crash If you are not on these cases, you need to find a way to be (i.e. if your system does not produce core dumps, check your distro documentation to enable them). -#### netdata crashes and you have a core dump +#### Netdata crashes and you have a core dump -> you need to have netdata compiled with debugging info for this to work (check above) +> you need to have Netdata compiled with debugging info for this to work (check above) Run the following command and post the output on a github issue. @@ -506,9 +505,9 @@ Run the following command and post the output on a github issue. gdb $(which netdata) /path/to/core/dump ``` -#### you can reproduce a netdata crash on your system +#### you can reproduce a Netdata crash on your system -> you need to have netdata compiled with debugging info for this to work (check above) +> you need to have Netdata compiled with debugging info for this to work (check above) Install the package `valgrind` and run: @@ -516,7 +515,7 @@ Install the package `valgrind` and run: valgrind $(which netdata) -D ``` -netdata will start and it will be a lot slower. Now reproduce the crash and `valgrind` will dump on your console the stack trace. Open a new github issue and post the output. +Netdata will start and it will be a lot slower. Now reproduce the crash and `valgrind` will dump on your console the stack trace. Open a new github issue and post the output. []() diff --git a/daemon/config/README.md b/daemon/config/README.md index c36a5b6db2..207602a4c7 100644 --- a/daemon/config/README.md +++ b/daemon/config/README.md @@ -8,21 +8,21 @@ This config file **is not needed by default**. Netdata works fine out of the box `netdata.conf` has sections stated with `[section]`. You will see the following sections: -1. `[global]` to [configure](#global-section-options) the [netdata daemon](../). +1. `[global]` to [configure](#global-section-options) the [Netdata daemon](../). 2. `[web]` to [configure the web server](../../web/server). 3. `[plugins]` to [configure](#plugins-section-options) which [collectors](../../collectors) to use and PATH settings. 4. `[health]` to [configure](#health-section-options) general settings for [health monitoring](../../health) -5. `[registry]` for the [netdata registry](../../registry). +5. `[registry]` for the [Netdata registry](../../registry). 6. `[backend]` to set up [streaming and replication](../../streaming) options. 7. `[statsd]` for the general settings of the [stats.d.plugin](../../collectors/statsd.plugin). 8. `[plugin:NAME]` sections for each collector plugin, under the comment [Per plugin configuration](#per-plugin-configuration). 9. `[CHART_NAME]` sections for each chart defined, under the comment [Per chart configuration](#per-chart-configuration). -The configuration file is a `name = value` dictionary. Netdata will not complain if you set options unknown to it. When you check the running configuration by accessing the URL `/netdata.conf` on your netdata server, netdata will add a comment on settings it does not currently use. +The configuration file is a `name = value` dictionary. Netdata will not complain if you set options unknown to it. When you check the running configuration by accessing the URL `/netdata.conf` on your Netdata server, Netdata will add a comment on settings it does not currently use. ## Applying changes -After `netdata.conf` has been modified, netdata needs to be restarted for changes to apply: +After `netdata.conf` has been modified, Netdata needs to be restarted for changes to apply: ```bash sudo service netdata restart @@ -42,36 +42,36 @@ Please note that your data history will be lost if you have modified `history` p setting | default | info :------:|:-------:|:---- -process scheduling policy | `keep` | See [netdata process scheduling policy](../#netdata-process-scheduling-policy) +process scheduling policy | `keep` | See [Netdata process scheduling policy](../#netdata-process-scheduling-policy) OOM score | `1000` | See [OOM score](../#oom-score) glibc malloc arena max for plugins | `1` | See [Virtual memory](../#virtual-memory). -glibc malloc arena max for netdata | `1` | See [Virtual memory](../#virtual-memory). -hostname | auto-detected | The hostname of the computer running netdata. -history | `3996` | The number of entries the netdata daemon will by default keep in memory for each chart dimension. This setting can also be configured per chart. Check [Memory Requirements](../../database/#database) for more information. +glibc malloc arena max for Netdata | `1` | See [Virtual memory](../#virtual-memory). +hostname | auto-detected | The hostname of the computer running Netdata. +history | `3996` | The number of entries the `netdata` daemon will by default keep in memory for each chart dimension. This setting can also be configured per chart. Check [Memory Requirements](../../database/#database) for more information. update every | `1` | The frequency in seconds, for data collection. For more information see [Performance](../../docs/Performance.md#performance). config directory | `/etc/netdata` | The directory configuration files are kept. stock config directory | `/usr/lib/netdata/conf.d` | log directory | `/var/log/netdata` | The directory in which the [log files](../#log-files) are kept. web files directory | `/usr/share/netdata/web` | The directory the web static files are kept. -cache directory | `/var/cache/netdata` | The directory the memory database will be stored if and when netdata exits. Netdata will re-read the database when it will start again, to continue from the same point. -lib directory | `/var/lib/netdata` | Contains the alarm log and the netdata instance guid. +cache directory | `/var/cache/netdata` | The directory the memory database will be stored if and when Netdata exits. Netdata will re-read the database when it will start again, to continue from the same point. +lib directory | `/var/lib/netdata` | Contains the alarm log and the Netdata instance guid. home directory | `/var/cache/netdata` | Contains the db files for the collected metrics plugins directory | `"/usr/libexec/netdata/plugins.d" "/etc/netdata/custom-plugins.d"` | The directory plugin programs are kept. This setting supports multiple directories, space separated. If any directory path contains spaces, enclose it in single or double quotes. -memory mode | `save` | When set to `save` netdata will save its round robin database on exit and load it on startup. When set to `map` the cache files will be updated in real time (check `man mmap` - do not set this on systems with heavy load or slow disks - the disks will continuously sync the in-memory database of netdata). When set to `dbengine` it behaves similarly to `map` but with much better disk and memory efficiency, however, with higher overhead. When set to `ram` the round robin database will be temporary and it will be lost when netdata exits. `none` disables the database at this host. This also disables health monitoring (there cannot be health monitoring without a database). host access prefix | | This is used in docker environments where /proc, /sys, etc have to be accessed via another path. You may also have to set SYS_PTRACE capability on the docker for this work. Check [issue 43](https://github.com/netdata/netdata/issues/43). -memory deduplication (ksm) | `yes` | When set to `yes`, netdata will offer its in-memory round robin database to kernel same page merging (KSM) for deduplication. For more information check [Memory Deduplication - Kernel Same Page Merging - KSM](../../database/#ksm) +memory mode | `save` | When set to `save` Netdata will save its round robin database on exit and load it on startup. When set to `map` the cache files will be updated in real time (check `man mmap` - do not set this on systems with heavy load or slow disks - the disks will continuously sync the in-memory database of Netdata). When set to `dbengine` it behaves similarly to `map` but with much better disk and memory efficiency, however, with higher overhead. When set to `ram` the round robin database will be temporary and it will be lost when Netdata exits. `none` disables the database at this host. This also disables health monitoring (there cannot be health monitoring without a database). host access prefix | | This is used in docker environments where /proc, /sys, etc have to be accessed via another path. You may also have to set SYS_PTRACE capability on the docker for this work. Check [issue 43](https://github.com/netdata/netdata/issues/43). +memory deduplication (ksm) | `yes` | When set to `yes`, Netdata will offer its in-memory round robin database to kernel same page merging (KSM) for deduplication. For more information check [Memory Deduplication - Kernel Same Page Merging - KSM](../../database/#ksm) TZ environment variable | `:/etc/localtime` | Where to find the timezone timezone | auto-detected | The timezone retrieved from the environment variable debug flags | `0x0000000000000000` | Bitmap of debug options to enable. For more information check [Tracing Options](../#debugging). debug log | `/var/log/netdata/debug.log` | The filename to save debug information. This file will not be created if debugging is not enabled. You can also set it to `syslog` to send the debug messages to syslog, or `none` to disable this log. For more information check [Tracing Options](../#debugging). -error log | `/var/log/netdata/error.log` | The filename to save error messages for netdata daemon and all plugins (`stderr` is sent here for all netdata programs, including the plugins). You can also set it to `syslog` to send the errors to syslog, or `none` to disable this log. -access log | `/var/log/netdata/access.log` | The filename to save the log of web clients accessing netdata charts. You can also set it to `syslog` to send the access log to syslog, or `none` to disable this log. +error log | `/var/log/netdata/error.log` | The filename to save error messages for Netdata daemon and all plugins (`stderr` is sent here for all Netdata programs, including the plugins). You can also set it to `syslog` to send the errors to syslog, or `none` to disable this log. +access log | `/var/log/netdata/access.log` | The filename to save the log of web clients accessing Netdata charts. You can also set it to `syslog` to send the access log to syslog, or `none` to disable this log. errors flood protection period | `1200` | UNUSED - Length of period (in sec) during which the number of errors should not exceed the `errors to trigger flood protection`. errors to trigger flood protection | `200` | UNUSED - Number of errors written to the log in `errors flood protection period` sec before flood protection is activated. -run as user | `netdata` | The user netdata will run as. +run as user | `netdata` | The user Netdata will run as. pthread stack size | auto-detected | cleanup obsolete charts after seconds | `3600` | See [monitoring ephemeral containers](../../collectors/cgroups.plugin/#monitoring-ephemeral-containers), also sets the timeout for cleaning up obsolete dimensions gap when lost iterations above | `1` | -cleanup orphan hosts after seconds | `3600` | How long to wait until automatically removing from the DB a remote netdata host (slave) that is no longer sending data. +cleanup orphan hosts after seconds | `3600` | How long to wait until automatically removing from the DB a remote Netdata host (slave) that is no longer sending data. delete obsolete charts files | `yes` | See [monitoring ephemeral containers](../../collectors/cgroups.plugin/#monitoring-ephemeral-containers), also affects the deletion of files for obsolete dimensions delete orphan hosts files | `yes` | Set to `no` to disable non-responsive host removal. enable zero metrics | `no` | Set to `yes` to show charts when all their metrics are zero. @@ -90,8 +90,8 @@ setting | default | info :------:|:-------:|:---- PATH environment variable | `auto-detected` | PYTHONPATH environment variable | | Used to set a custom python path -enable running new plugins | `yes` | When set to `yes`, netdata will enable detected plugins, even if they are not configured explicitly. Setting this to `no` will only enable plugins explicitly configirued in this file with a `yes` -check for new plugins every | 60 | The time in seconds to check for new plugins in the plugins directory. This allows having other applications dynamically creating plugins for netdata. +enable running new plugins | `yes` | When set to `yes`, Netdata will enable detected plugins, even if they are not configured explicitly. Setting this to `no` will only enable plugins explicitly configirued in this file with a `yes` +check for new plugins every | 60 | The time in seconds to check for new plugins in the plugins directory. This allows having other applications dynamically creating plugins for Netdata. checks | `no` | This is a debugging plugin for the internal latency ### [health] section options @@ -129,7 +129,7 @@ The configuration options for plugins appear in sections following the pattern ` Most internal plugins will provide additional options. Check [Internal Plugins](../../collectors/) for more information. -Please note, that by default Netdata will enable monitoring metrics for disks, memory, and network only when they are not zero. If they are constantly zero they are ignored. Metrics that will start having values, after netdata is started, will be detected and charts will be automatically added to the dashboard (a refresh of the dashboard is needed for them to appear though). Use `yes` instead of `auto` in plugin configuration sections to enable these charts permanently. You can also set the `enable zero metrics` option to `yes` in the `[global]` section which enables charts with zero metrics for all internal Netdata plugins. +Please note, that by default Netdata will enable monitoring metrics for disks, memory, and network only when they are not zero. If they are constantly zero they are ignored. Metrics that will start having values, after Netdata is started, will be detected and charts will be automatically added to the dashboard (a refresh of the dashboard is needed for them to appear though). Use `yes` instead of `auto` in plugin configuration sections to enable these charts permanently. You can also set the `enable zero metrics` option to `yes` in the `[global]` section which enables charts with zero metrics for all internal Netdata plugins. #### External plugins diff --git a/database/README.md b/database/README.md index de0aa9b53b..c7f5463ad3 100644 --- a/database/README.md +++ b/database/README.md @@ -3,7 +3,7 @@ Although `netdata` does all its calculations using `long double`, it stores all values using a [custom-made 32-bit number](../libnetdata/storage_number/). -So, for each dimension of a chart, netdata will need: `4 bytes for the value * the entries +So, for each dimension of a chart, Netdata will need: `4 bytes for the value * the entries of its history`. It will not store any other data for each value in the time series database. Since all its values are stored in a time series with fixed step, the time each value corresponds can be calculated at run time, using the position of a value in the round robin database. @@ -23,22 +23,22 @@ use the **[Database Engine](engine/)**. ## Memory modes -Currently netdata supports 6 memory modes: +Currently Netdata supports 6 memory modes: 1. `ram`, data are purely in memory. Data are never saved on disk. This mode uses `mmap()` and supports [KSM](#ksm). -2. `save`, (the default) data are only in RAM while netdata runs and are saved to / loaded from - disk on netdata restart. It also uses `mmap()` and supports [KSM](#ksm). +2. `save`, (the default) data are only in RAM while Netdata runs and are saved to / loaded from + disk on Netdata restart. It also uses `mmap()` and supports [KSM](#ksm). 3. `map`, data are in memory mapped files. This works like the swap. Keep in mind though, this - will have a constant write on your disk. When netdata writes data on its memory, the Linux kernel + will have a constant write on your disk. When Netdata writes data on its memory, the Linux kernel marks the related memory pages as dirty and automatically starts updating them on disk. Unfortunately we cannot control how frequently this works. The Linux kernel uses exactly the same algorithm it uses for its swap memory. Check below for additional information on running a - dedicated central netdata server. This mode uses `mmap()` but does not support [KSM](#ksm). + dedicated central Netdata server. This mode uses `mmap()` but does not support [KSM](#ksm). -4. `none`, without a database (collected metrics can only be streamed to another netdata). +4. `none`, without a database (collected metrics can only be streamed to another Netdata). 5. `alloc`, like `ram` but it uses `calloc()` and does not support [KSM](#ksm). This mode is the fallback for all others except `none`. @@ -49,7 +49,7 @@ Currently netdata supports 6 memory modes: but depends on the configured disk space and the effective compression ratio of the data stored. For more details see [here](engine/). -You can select the memory mode by editing netdata.conf and setting: +You can select the memory mode by editing `netdata.conf` and setting: ``` [global] @@ -60,7 +60,7 @@ You can select the memory mode by editing netdata.conf and setting: cache directory = /var/cache/netdata ``` -## Running netdata in embedded devices +## Running Netdata in embedded devices Embedded devices usually have very limited RAM resources available. @@ -74,36 +74,36 @@ second updates. If you set `update every = 2` and `history = 1800`, you will still have an hour of data, but collected once every 2 seconds. This will **cut in half** both CPU and RAM resources consumed -by netdata. Of course experiment a bit. On very weak devices you might have to use +by Netdata. Of course experiment a bit. On very weak devices you might have to use `update every = 5` and `history = 720` (still 1 hour of data, but 1/5 of the CPU and RAM resources). You can also disable [data collection plugins](../collectors) you don't need. Disabling such plugins will also free both CPU and RAM resources. -## Running a dedicated central netdata server +## Running a dedicated central Netdata server -Netdata allows streaming data between netdata nodes. This allows us to have a central netdata +Netdata allows streaming data between Netdata nodes. This allows us to have a central Netdata server that will maintain the entire database for all nodes, and will also run health checks/alarms for all nodes. -For this central netdata, memory size can be a problem. Fortunately, netdata supports several +For this central Netdata, memory size can be a problem. Fortunately, Netdata supports several memory modes. **One interesting option** for this setup is `memory mode = map`. ### map -In this mode, the database of netdata is stored in memory mapped files. netdata continues to read +In this mode, the database of Netdata is stored in memory mapped files. Netdata continues to read and write the database in memory, but the kernel automatically loads and saves memory pages from/to disk. **We suggest _not_ to use this mode on nodes that run other applications.** There will always be dirty memory to be synced and this syncing process may influence the way other applications work. -This mode however is useful when we need a central netdata server that would normally need huge +This mode however is useful when we need a central Netdata server that would normally need huge amounts of memory. Using memory mode `map` we can overcome all memory restrictions. There are a few kernel options that provide finer control on the way this syncing works. But before -explaining them, a brief introduction of how netdata database works is needed. +explaining them, a brief introduction of how Netdata database works is needed. -For each chart, netdata maps the following files: +For each chart, Netdata maps the following files: 1. `chart/main.db`, this is the file that maintains chart information. Every time data are collected for a chart, this is updated. @@ -111,7 +111,7 @@ For each chart, netdata maps the following files: 2. `chart/dimension_name.db`, this is the file for each dimension. At its beginning there is a header, followed by the round robin database where metrics are stored. -So, every time netdata collects data, the following pages will become dirty: +So, every time Netdata collects data, the following pages will become dirty: 1. the chart file 2. the header part of all dimension files @@ -147,8 +147,8 @@ There are 2 more options to tweak: 2. `dirty_ratio`, by default `20`. These control the amount of memory that should be dirty for disk syncing to be triggered. -On dedicated netdata servers, you can use: `80` and `90` respectively, so that all RAM is given -to netdata. +On dedicated Netdata servers, you can use: `80` and `90` respectively, so that all RAM is given +to Netdata. With these settings, you can expect a little `iowait` spike once every 10 minutes and in case of system crash, data on disk will be up to 10 minutes old. @@ -169,7 +169,7 @@ for this setup** is `memory mode = dbengine`. ### dbengine -In this mode, the database of netdata is stored in database files. The [Database Engine](engine/) +In this mode, the database of Netdata is stored in database files. The [Database Engine](engine/) works like a traditional database. There is some amount of RAM dedicated to data caching and indexing and the rest of the data reside compressed on disk. The number of history entries is not fixed in this case, but depends on the configured disk space and the effective compression ratio @@ -187,10 +187,10 @@ Netdata offers all its round robin database to kernel for deduplication In the past KSM has been criticized for consuming a lot of CPU resources. Although this is true when KSM is used for deduplicating certain applications, it is not true with -netdata, since the netdata memory is written very infrequently (if you have 24 hours of metrics in +netdata, since the Netdata memory is written very infrequently (if you have 24 hours of metrics in netdata, each byte at the in-memory database will be updated just once per day). -KSM is a solution that will provide 60+% memory savings to netdata. +KSM is a solution that will provide 60+% memory savings to Netdata. ### Enable KSM in kernel diff --git a/database/engine/README.md b/database/engine/README.md index adc69ffd72..441a3eea05 100644 --- a/database/engine/README.md +++ b/database/engine/README.md @@ -23,13 +23,13 @@ journalfile-1-0000000003.njf They are located under their host's cache directory in the directory `./dbengine` (e.g. for localhost the default location is `/var/cache/netdata/dbengine/*`). The higher numbered filenames contain more recent metric data. The user can safely delete some pairs -of files when netdata is stopped to manually free up some space. +of files when Netdata is stopped to manually free up some space. *Users should* **back up** *their `./dbengine` folders if they consider this data to be important.* ## Configuration -There is one DB engine instance per netdata host/node. That is, there is one `./dbengine` folder +There is one DB engine instance per Netdata host/node. That is, there is one `./dbengine` folder per node, and all charts of `dbengine` memory mode in such a host share the same storage space and DB engine instance memory state. You can select the memory mode for localhost by editing netdata.conf and setting: @@ -59,10 +59,10 @@ quota. Both numbers are in **MiB**. All DB engine instances will allocate the co separately. The `page cache size` option determines the amount of RAM in **MiB** that is dedicated to caching -netdata metric values themselves. +Netdata metric values themselves. The `dbengine disk space` option determines the amount of disk space in **MiB** that is dedicated -to storing netdata metric values and all related metadata describing them. +to storing Netdata metric values and all related metadata describing them. ## Operation @@ -72,7 +72,7 @@ the **Page Cache**. When those pages fill up they are slowly compressed and flushed to disk. It can take `4096 / 4 = 1024 seconds = 17 minutes`, for a chart dimension that is being collected -every 1 second, to fill a page. Pages can be cut short when we stop netdata or the DB engine +every 1 second, to fill a page. Pages can be cut short when we stop Netdata or the DB engine instance so as to not lose the data. When we query the DB engine for data we trigger disk read I/O requests that fill the Page Cache with the requested pages and potentially evict cold (not recently used) pages. @@ -91,7 +91,7 @@ applications. Using memory mode `dbengine` we can overcome most memory restrictions and store a dataset that is much larger than the available memory. -There are explicit memory requirements **per** DB engine **instance**, meaning **per** netdata +There are explicit memory requirements **per** DB engine **instance**, meaning **per** Netdata **node** (e.g. localhost and streaming recipient nodes): - `page cache size` must be at least `#dimensions-being-collected x 4096 x 2` bytes. @@ -115,11 +115,11 @@ file descriptors available per `dbengine` instance. Netdata allocates 25% of the available file descriptors to its Database Engine instances. This means that only 25% of the file descriptors that are available to the Netdata service are accessible by dbengine instances. You should take that into account when configuring your service -or system-wide file descriptor limits. You can roughly estimate that the netdata service needs 2048 file +or system-wide file descriptor limits. You can roughly estimate that the Netdata service needs 2048 file descriptors for every 10 streaming slave hosts when streaming is configured to use `memory mode = dbengine`. -If for example one wants to allocate 65536 file descriptors to the netdata service on a systemd system -one needs to override the netdata service by running `sudo systemctl edit netdata` and creating a +If for example one wants to allocate 65536 file descriptors to the Netdata service on a systemd system +one needs to override the Netdata service by running `sudo systemctl edit netdata` and creating a file with contents: ``` diff --git a/docs/Add-more-charts-to-netdata.md b/docs/Add-more-charts-to-netdata.md index 285713b028..4d62cd64a9 100644 --- a/docs/Add-more-charts-to-netdata.md +++ b/docs/Add-more-charts-to-netdata.md @@ -187,7 +187,7 @@ rethinkdb|python
v2 or v3|Connects to multiple rethinkdb servers (local or r application|language|notes| :---------:|:------:|:----| -retroshare|python
v2 or v3|Connects to multiple retroshare servers (local or remote) to collect real-time performance metrics.
netdata plugin: [python.d.plugin](../collectors/python.d.plugin)
plugin module: [retroshare.chart.py](../collectors/python.d.plugin/retroshare)
configuration file: [python.d/retroshare.conf](../collectors/python.d.plugin/retroshare)| +retroshare|python
v2 or v3|Connects to multiple retroshare servers (local or remote) to collect real-time performance metrics.
Netdata plugin: [python.d.plugin](../collectors/python.d.plugin)
plugin module: [retroshare.chart.py](../collectors/python.d.plugin/retroshare)
configuration file: [python.d/retroshare.conf](../collectors/python.d.plugin/retroshare)| --- @@ -196,7 +196,7 @@ retroshare|python
v2 or v3|Connects to multiple retroshare servers (local or application|language|notes| :---------:|:------:|:----| -squid|python
v2 or v3|Connects to multiple squid servers (local or remote) to collect real-time performance metrics.
netdata plugin: [python.d.plugin](../collectors/python.d.plugin)
plugin module: [squid.chart.py](../collectors/python.d.plugin/squid)
configuration file: [python.d/squid.conf](../collectors/python.d.plugin/squid)| +squid|python
v2 or v3|Connects to multiple squid servers (local or remote) to collect real-time performance metrics.
Netdata plugin: [python.d.plugin](../collectors/python.d.plugin)
plugin module: [squid.chart.py](../collectors/python.d.plugin/squid)
configuration file: [python.d/squid.conf](../collectors/python.d.plugin/squid)| squid|BASH
Shell Script|Connects to a squid server (local or remote) to collect real-time performance metrics.
DEPRECATED IN FAVOR OF THE PYTHON ONE. It is still supplied only as an example module to shell scripting plugins.
Netdata plugin: [charts.d.plugin](../collectors/charts.d.plugin#chartsdplugin)
plugin module: [squid.chart.sh](../collectors/charts.d.plugin/squid)
configuration file: [charts.d/squid.conf](../collectors/charts.d.plugin/squid)| @@ -298,8 +298,8 @@ postfix|BASH
Shell Script|Charts the postfix queue size.
DEPRECATED application|language|notes| :---------:|:------:|:----| NFS Client|`C`|This is handled entirely by the Netdata daemon.
Configuration: `netdata.conf`, section `[plugin:proc:/proc/net/rpc/nfs]`. -NFS Server|`C`|This is handled entirely by the netdata daemon.
Configuration: `netdata.conf`, section `[plugin:proc:/proc/net/rpc/nfsd]`. -samba|python
v2 or v3|Performance metrics of Samba SMB2 file sharing.
documentation page: [python.d.plugin module samba](../collectors/python.d.plugin/samba)
netdata plugin: [python.d.plugin](../collectors/python.d.plugin)
plugin module: [samba.chart.py](../collectors/python.d.plugin/samba)
configuration file: [python.d/samba.conf](../collectors/python.d.plugin/samba)| +NFS Server|`C`|This is handled entirely by the `netdata` daemon.
Configuration: `netdata.conf`, section `[plugin:proc:/proc/net/rpc/nfsd]`. +samba|python
v2 or v3|Performance metrics of Samba SMB2 file sharing.
documentation page: [python.d.plugin module samba](../collectors/python.d.plugin/samba)
Netdata plugin: [python.d.plugin](../collectors/python.d.plugin)
plugin module: [samba.chart.py](../collectors/python.d.plugin/samba)
configuration file: [python.d/samba.conf](../collectors/python.d.plugin/samba)| --- @@ -307,7 +307,7 @@ samba|python
v2 or v3|Performance metrics of Samba SMB2 file sharing.
&n application|language|notes| :---------:|:------:|:----| -CUPS|C|Charts metrics of printers, jobs and other cups destinations.
netdata plugin: [cups.plugin](../collectors/cups.plugin) +CUPS|C|Charts metrics of printers, jobs and other cups destinations.
Netdata plugin: [cups.plugin](../collectors/cups.plugin) --- @@ -315,7 +315,7 @@ CUPS|C|Charts metrics of printers, jobs and other cups destinations.
< application|language|notes| :---------:|:------:|:----| -xenstat|C|Collects host and domain statistics for XenServer or XCP-ng hypervisors.
netdata plugin: [xenstat.plugin](../collectors/xenstat.plugin) +xenstat|C|Collects host and domain statistics for XenServer or XCP-ng hypervisors.
Netdata plugin: [xenstat.plugin](../collectors/xenstat.plugin) --- diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md index 3ddf4c388d..792eb1f298 100644 --- a/docs/GettingStarted.md +++ b/docs/GettingStarted.md @@ -32,9 +32,9 @@ If still Netdata does not receive the requests, something is blocking them. A fi
-When you install multiple Netdata servers, all your servers will appear at the node menu at the top left of the dashboard. For this to work, you have to manually access just once, the dashboard of each of your netdata servers. +When you install multiple Netdata servers, all your servers will appear at the node menu at the top left of the dashboard. For this to work, you have to manually access just once, the dashboard of each of your Netdata servers. -The node menu is more than just browser bookmarks. When switching Netdata servers from that menu, any settings of the current view are propagated to the other netdata server: +The node menu is more than just browser bookmarks. When switching Netdata servers from that menu, any settings of the current view are propagated to the other Netdata server: - the current charts panning (drag the charts left or right), - the current charts zooming (`SHIFT` + mouse wheel over a chart), diff --git a/docs/Running-behind-nginx.md b/docs/Running-behind-nginx.md index 81ebc1a756..5479118cb3 100644 --- a/docs/Running-behind-nginx.md +++ b/docs/Running-behind-nginx.md @@ -14,7 +14,7 @@ The software is known for its low impact on memory resources, high scalability, - Password-protect access to Netdata, until distributed authentication is implemented via the Netdata cloud Sign In mechanism. -- A proxy was necessary to encrypt the communication to netdata, until v1.16.0, which provided TLS (HTTPS) support. +- A proxy was necessary to encrypt the communication to Netdata, until v1.16.0, which provided TLS (HTTPS) support. ## Nginx configuration file diff --git a/docs/anonymous-statistics.md b/docs/anonymous-statistics.md index 376a2c4aaa..689b692f14 100644 --- a/docs/anonymous-statistics.md +++ b/docs/anonymous-statistics.md @@ -26,7 +26,7 @@ To ensure anonymity of the stored information, we have configured GTM's GA varia |page|netdata-dashboard |hostname|dashboard.my-netdata.io |anonymizeIp|true -|title|netdata dashboard +|title|Netdata dashboard |campaignSource|{{machine_guid}} |campaignMedium|web |referrer|http://dashboard.my-netdata.io @@ -35,7 +35,7 @@ To ensure anonymity of the stored information, we have configured GTM's GA varia |Page Path|/netdata-dashboard |location|http://dashboard.my-netdata.io -In addition, the netdata-generated unique machine guid is sent to GA via a custom dimension. +In addition, the Netdata-generated unique machine guid is sent to GA via a custom dimension. You can verify the effect of these settings by examining the GA `collect` request parameters. The only thing that's impossible for us to prevent from being **sent** is the URL in the "Referrer" Header of the browser request to GA. However, the settings above ensure that all **stored** URLs and host names are anonymized. diff --git a/docs/configuration-guide.md b/docs/configuration-guide.md index 1c79e02769..26ebb9119e 100644 --- a/docs/configuration-guide.md +++ b/docs/configuration-guide.md @@ -59,7 +59,7 @@ Entire plugins can be turned off from the [netdata.conf [plugins]](../daemon/con ##### Show charts with zero metrics -By default, Netdata will enable monitoring metrics for disks, memory, and network only when they are not zero. If they are constantly zero they are ignored. Metrics that will start having values, after netdata is started, will be detected and charts will be automatically added to the dashboard (a refresh of the dashboard is needed for them to appear though). Use `yes` instead of `auto` in plugin configuration sections to enable these charts permanently. You can also set the `enable zero metrics` option to `yes` in the `[global]` section which enables charts with zero metrics for all internal Netdata plugins. +By default, Netdata will enable monitoring metrics for disks, memory, and network only when they are not zero. If they are constantly zero they are ignored. Metrics that will start having values, after Netdata is started, will be detected and charts will be automatically added to the dashboard (a refresh of the dashboard is needed for them to appear though). Use `yes` instead of `auto` in plugin configuration sections to enable these charts permanently. You can also set the `enable zero metrics` option to `yes` in the `[global]` section which enables charts with zero metrics for all internal Netdata plugins. ### Modify alarms and notifications @@ -92,11 +92,11 @@ You have several options under the [netdata.conf [web]](../web/server/#access-li ##### Stop sending info to registry.my-netdata.io -You will need to configure the [registry] section in netdata.conf. First read the [registry documentation](../registry/). In it, are instructions on how to [run your own registry](../registry/#run-your-own-registry). +You will need to configure the [registry] section in `netdata.conf`. First read the [registry documentation](../registry/). In it, are instructions on how to [run your own registry](../registry/#run-your-own-registry). ##### Change the IP address/port Netdata listens to -The settings are under netdata.conf [web]. Look at the [web server documentation](../web/server/#binding-netdata-to-multiple-ports) for more info. +The settings are under `netdata.conf` [web]. Look at the [web server documentation](../web/server/#binding-netdata-to-multiple-ports) for more info. ### System resource usage @@ -110,7 +110,7 @@ The page on [Netdata performance](Performance.md) has an excellent guide on how ##### Prevent Netdata from getting immediately killed when my server runs out of memory -You can change the Netdata [OOM score](../daemon/#oom-score) in netdata.conf [global]. +You can change the Netdata [OOM score](../daemon/#oom-score) in `netdata.conf` [global]. ### Other diff --git a/docs/netdata-security.md b/docs/netdata-security.md index a905717d93..afbb32775e 100644 --- a/docs/netdata-security.md +++ b/docs/netdata-security.md @@ -132,7 +132,7 @@ iptables -t filter -A netdata -j DROP iptables -t filter -D INPUT -p tcp --dport ${NETDATA_PORT} -m conntrack --ctstate NEW -j netdata 2>/dev/null # add the input chain hook (again) -# to send all new netdata connections to our filtering chain +# to send all new Netdata connections to our filtering chain iptables -t filter -I INPUT -p tcp --dport ${NETDATA_PORT} -m conntrack --ctstate NEW -j netdata ``` _script to allow access to Netdata only from a number of hosts_ diff --git a/docs/privacy-policy.md b/docs/privacy-policy.md index e46d783ed2..4d7a7e526e 100644 --- a/docs/privacy-policy.md +++ b/docs/privacy-policy.md @@ -37,22 +37,22 @@ The menu lists the Netdata servers you have visited. For example, when you jump (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. The global registry keeps track of 4 entities: -1. **machines**: i.e. the netdata installations (a random GUID generated by each netdata the first time it starts; we call this **machine_guid**) +1. **machines**: i.e. the Netdata installations (a random GUID generated by each Netdata the first time it starts; we call this **machine_guid**) - For each netdata installation (each `machine_guid`) the registry keeps track of the different URLs it is accessed. + For each Netdata installation (each `machine_guid`) the registry keeps track of the different URLs it is accessed. -2. **persons**: i.e. the web browsers accessing the netdata installations (a random GUID generated by the registry the first time it sees a new web browser; we call this **person_guid**) +2. **persons**: i.e. the web browsers accessing the Netdata installations (a random GUID generated by the registry the first time it sees a new web browser; we call this **person_guid**) - For each person, the registry keeps track of the netdata installations it has accessed and their URLs. + For each person, the registry keeps track of the Netdata installations it has accessed and their URLs. -3. **URLs** of netdata installations (as seen by the web browsers) +3. **URLs** of Netdata installations (as seen by the web browsers) For each URL, the registry keeps the URL and nothing more. Each URL is linked to *persons* and *machines*. The only way to find a URL is to know its **machine_guid** or have a **person_guid** it is linked to it. 4. **accounts**: i.e. the information used to sign-in via one of the available sign-in methods. Depending on the method, this may include an email, an email and a profile picture. For *persons*/*accounts* and *machines*, the registry keeps links to *URLs*, each link with 2 timestamps (first time seen, last time seen) and a counter (number of times it has been seen). -*machines*, *persons*, and timestamps are stored in the netdata registry regardless of whether you sign in or not. +*machines*, *persons*, and timestamps are stored in the Netdata registry regardless of whether you sign in or not. If sending this information is against your policies, you can [run your own registry](../registry/#run-your-own-registry). Note that ND versions with the 'Sign in' feature of the ND Cloud do not use the global registry. diff --git a/health/README.md b/health/README.md index 345f7fc70d..a03c7eec7e 100644 --- a/health/README.md +++ b/health/README.md @@ -1,9 +1,9 @@ # Health monitoring -Each netdata node runs an independent thread evaluating health monitoring checks. +Each Netdata node runs an independent thread evaluating health monitoring checks. This thread has lock free access to the database, so that it can operate as a watchdog. -Health checks (alarms) are attached to netdata charts, allowing netdata to automatically +Health checks (alarms) are attached to Netdata charts, allowing Netdata to automatically activate an alarm as soon as a chart is created. This is very important for netdata, since many charts are dynamically created during runtime (for example, the chart tracking network interface packet drops, is automatically created on the first @@ -20,15 +20,15 @@ use expressions combining the latest value of any number of metrics. ## Health configuration reference -Stock netdata health configuration is in `/usr/lib/netdata/conf.d/health.d`. +Stock Netdata health configuration is in `/usr/lib/netdata/conf.d/health.d`. These files can be overwritten by copying them and editing them in `/etc/netdata/health.d` (run `/etc/netdata/edit-config` to edit them). In `/etc/netdata/health.d` you can also put any number of files (in any number of sub-directories) -with a suffix `.conf` to have them processed by netdata. +with a suffix `.conf` to have them processed by Netdata. -Health configuration can be reloaded at any time, without restarting netdata. -Just send netdata the SIGUSR2 signal, like this: +Health configuration can be reloaded at any time, without restarting Netdata. +Just send Netdata the SIGUSR2 signal, like this: ```sh killall -USR2 netdata @@ -50,7 +50,7 @@ The only difference is the label `alarm` or `template`. Netdata supports overriding **templates** with **alarms**. For example, when a template is defined for a set of charts, an alarm with exactly the same name attached to the same chart the template matches, will have higher precedence -(i.e. netdata will use the alarm on this chart and prevent the template from being applied +(i.e. Netdata will use the alarm on this chart and prevent the template from being applied to it). ### The format @@ -135,7 +135,7 @@ hosts: server1 server2 database* !redis3 redis* The above says: use this alarm on all hosts named `server1`, `server2`, `database*`, and all `redis*` except `redis3`. -This is useful when you centralize metrics from multiple hosts, to one netdata. +This is useful when you centralize metrics from multiple hosts, to one Netdata. --- @@ -187,7 +187,7 @@ Everything is the same with [badges](../web/api/badges/). In short: - `of DIMENSIONS` is optional and has to be the last parameter. Dimensions have to be separated by `,` or `|`. The space characters found in dimensions will be kept as-is (a few dimensions - have spaces in their names). This accepts netdata simple patterns and the `match-ids` and + have spaces in their names). This accepts Netdata simple patterns and the `match-ids` and `match-names` options affect the searches for dimensions. The result of the lookup will be available as `$this` and `$NAME` in expressions. @@ -289,8 +289,8 @@ Format: exec: SCRIPT ``` -The default `SCRIPT` is netdata's `alarm-notify.sh`, which supports all the notifications -methods netdata supports, including custom hooks. +The default `SCRIPT` is Netdata's `alarm-notify.sh`, which supports all the notifications +methods Netdata supports, including custom hooks. --- @@ -373,19 +373,17 @@ For some alarms we need compare two time-frames, to detect anomalies. For exampl ### Expressions -netdata has an internal [infix expression parser](../libnetdata/eval). +Netdata has an internal [infix expression parser](../libnetdata/eval). This parses expressions and creates an internal structure that allows fast execution of them. These operators are supported `+`, `-`, `*`, `/`, `<`, `<=`, `<>`, `!=`, `>`, `>=`, `&&`, `||`, `!`, `AND`, `OR`, `NOT`. Boolean operators result in either `1` (true) or `0` (false). -The conditional evaluation operator `?` is supported too. Using this operator IF-THEN-ELSE -conditional statements can be specified. The format is: `(condition) ? (true expression) : -(false expression)`. So, netdata will first evaluate the `condition` and based on the result -will either evaluate `true expression` or `false expression`. +The conditional evaluation operator `?` is supported too. Using this operator IF-THEN-ELSE conditional statements can be specified. The format is: `(condition) ? (true expression) :(false expression)`. So, Netdata will first evaluate the `condition` and based on the result will either evaluate `true expression` or `false expression`. + Example: `($this > 0) ? ($avail * 2) : ($used / 2)`. -Nested such expressions are also supported (i.e. `true expression` and `false expression` can -contain conditional evaluations). + +Nested such expressions are also supported (i.e. `true expression` and `false expression` can contain conditional evaluations). Expressions also support the `abs()` function. @@ -407,7 +405,7 @@ or warning thresholds. This usage helps to avoid bogus messages resulting from variations in the value when it is varying regularly but staying close to the threshold value, without needing to delay sending messages at all. -An example of such usage from the default CPU usage alarms bundled with netdata is: +An example of such usage from the default CPU usage alarms bundled with Netdata is: ``` warn: $this > (($status >= $WARNING) ? (75) : (85)) @@ -491,7 +489,7 @@ Although the `alarm_variables` link shows you variables for a particular chart, Alarms can have the following statuses: - - `REMOVED` - the alarm has been deleted (this happens when a SIGUSR2 is sent to netdata + - `REMOVED` - the alarm has been deleted (this happens when a SIGUSR2 is sent to Netdata to reload health configuration) - `UNINITIALIZED` - the alarm is not initialized yet @@ -509,7 +507,7 @@ The external script will be called for all status changes. ## Examples -Check the `health/health.d/` directory for all alarms shipped with netdata. +Check the `health/health.d/` directory for all alarms shipped with Netdata. Here are a few examples: @@ -526,7 +524,7 @@ template: apache_last_collected_secs crit: $this > (10 * $update_every) ``` -The above checks that netdata is able to collect data from apache. In detail: +The above checks that Netdata is able to collect data from apache. In detail: ``` template: apache_last_collected_secs @@ -653,12 +651,12 @@ The `lookup` line will calculate the sum of the all dropped packets in the last The `crit` line will issue a critical alarm if even a single packet has been dropped. Note that the drops chart does not exist if a network interface has never dropped a single packet. -When netdata detects a dropped packet, it will add the chart and it will automatically attach this +When Netdata detects a dropped packet, it will add the chart and it will automatically attach this alarm to it. ## Troubleshooting -You can compile netdata with [debugging](../daemon#debugging) and then set in `netdata.conf`: +You can compile Netdata with [debugging](../daemon#debugging) and then set in `netdata.conf`: ``` [global] @@ -671,7 +669,7 @@ Important: this will generate a lot of output in debug.log. You can find the context of charts by looking up the chart in either `http://your.netdata:19999/netdata.conf` or `http://your.netdata:19999/api/v1/charts`. -You can find how netdata interpreted the expressions by examining the alarm at `http://your.netdata:19999/api/v1/alarms?all`. For each expression, netdata will return the expression as given in its config file, and the same expression with additional parentheses added to indicate the evaluation flow of the expression. +You can find how Netdata interpreted the expressions by examining the alarm at `http://your.netdata:19999/api/v1/alarms?all`. For each expression, Netdata will return the expression as given in its config file, and the same expression with additional parentheses added to indicate the evaluation flow of the expression. ## Disabling health checks or silencing notifications at runtime diff --git a/health/notifications/awssns/README.md b/health/notifications/awssns/README.md index 82c7ef7a0a..7bb3487143 100644 --- a/health/notifications/awssns/README.md +++ b/health/notifications/awssns/README.md @@ -14,9 +14,9 @@ To get this working, you will need: * The Amazon Web Services CLI tools. Most distributions provide these with the package name `awscli`. * An actual home directory for the user you run Netdata as, instead of just using `/` as a home directory. Setup of this is distribution specific. `/var/lib/netdata` is the recommended directory (because the permissions will already be correct) if you are using a dedicated user (which is how most distributions work). * An Amazon SNS topic to send notifications to with one or more subscribers. The [Getting Started](https://docs.aws.amazon.com/sns/latest/dg/GettingStarted.html) section of the Amazon SNS documentation covers the basics of how to set this up. Make note of the Topic ARN when you create the topic. -* While not mandatory, it is highly recommended to create a dedicated IAM user on your account for netdata to send notifications. This user needs to have programmatic access, and should only allow access to SNS. If you're really paranoid, you can create one for each system or group of systems. +* While not mandatory, it is highly recommended to create a dedicated IAM user on your account for Netdata to send notifications. This user needs to have programmatic access, and should only allow access to SNS. If you're really paranoid, you can create one for each system or group of systems. -Once you have all the above, run the following command as the user netdata runs under: +Once you have all the above, run the following command as the user Netdata runs under: aws configure @@ -28,6 +28,6 @@ Notes: * Netdata's native email notification support is far better in almost all respects than it's support through Amazon SNS. If you want email notifications, use the native support, not SNS. * If you need to change the notification format for SNS notifications, you can do so by specifying the format in `AWSSNS_MESSAGE_FORMAT` in the configuration. This variable supports all the same vairiables you can use in custom notifications. - * While Amazon SNS supports sending differently formatted messages for different delivery methods, netdata does not currently support this functionality. + * While Amazon SNS supports sending differently formatted messages for different delivery methods, Netdata does not currently support this functionality. []() diff --git a/health/notifications/custom/README.md b/health/notifications/custom/README.md index eeaad8a606..80210572b2 100644 --- a/health/notifications/custom/README.md +++ b/health/notifications/custom/README.md @@ -46,7 +46,7 @@ Variables available to the custom_sender: - `${alarm_id}` the unique id of the alarm that generated this event - `${event_id}` the incremental id of the event, for this alarm id - `${when}` the timestamp this event occurred - - `${name}` the name of the alarm, as given in netdata health.d entries + - `${name}` the name of the alarm, as given in Netdata health.d entries - `${url_name}` same as `${name}` but URL encoded - `${chart}` the name of the chart (type.id) - `${url_chart}` same as `${chart}` but URL encoded @@ -67,7 +67,7 @@ Variables available to the custom_sender: - `${old_value_string}` friendly old value (with units) - `${image}` the URL of an image to represent the status of the alarm - `${color}` a color in #AABBCC format for the alarm - - `${goto_url}` the URL the user can click to see the netdata dashboard + - `${goto_url}` the URL the user can click to see the Netdata dashboard - `${calc_expression}` the expression evaluated to provide the value for the alarm - `${calc_param_values}` the value of the variables in the evaluated expression - `${total_warnings}` the total number of alarms in WARNING state on the host diff --git a/health/notifications/discord/README.md b/health/notifications/discord/README.md index 7694fef4b9..7b43f4e229 100644 --- a/health/notifications/discord/README.md +++ b/health/notifications/discord/README.md @@ -6,7 +6,7 @@ This is what you will get: You need: -1. The **incoming webhook URL** as given by Discord. Create a webhook by following the official [Discord documentation](https://support.discordapp.com/hc/en-us/articles/228383668-Intro-to-Webhooks). You can use the same on all your netdata servers (or you can have multiple if you like - your decision). +1. The **incoming webhook URL** as given by Discord. Create a webhook by following the official [Discord documentation](https://support.discordapp.com/hc/en-us/articles/228383668-Intro-to-Webhooks). You can use the same on all your Netdata servers (or you can have multiple if you like - your decision). 2. One or more Discord channels to post the messages to. Set them in `/etc/netdata/health_alarm_notify.conf` (to edit it on your system run `/etc/netdata/edit-config health_alarm_notify.conf`), like this: diff --git a/health/notifications/email/README.md b/health/notifications/email/README.md index 84a9e0ce71..ebe72f6d86 100644 --- a/health/notifications/email/README.md +++ b/health/notifications/email/README.md @@ -2,7 +2,7 @@ You need a working `sendmail` command for email alerts to work. Almost all MTAs provide a `sendmail` interface. -netdata sends all emails as user `netdata`, so make sure your `sendmail` works for local users. +Netdata sends all emails as user `netdata`, so make sure your `sendmail` works for local users. email notifications look like this: @@ -16,7 +16,7 @@ You can configure recipients in [`/etc/netdata/health_alarm_notify.conf`](https: You can also configure per role recipients [in the same file, a few lines below](https://github.com/netdata/netdata/blob/99d44b7d0c4e006b11318a28ba4a7e7d3f9b3bae/conf.d/health_alarm_notify.conf#L313). -Changes to this file do not require netdata restart. +Changes to this file do not require a Netdata restart. You can test your configuration by issuing the commands: diff --git a/health/notifications/flock/README.md b/health/notifications/flock/README.md index 0d679ce6b3..70a850376e 100644 --- a/health/notifications/flock/README.md +++ b/health/notifications/flock/README.md @@ -7,7 +7,7 @@ This is what you will get: You need: -The **incoming webhook URL** as given by flock.com. You can use the same on all your netdata servers (or you can have multiple if you like - your decision). +The **incoming webhook URL** as given by flock.com. You can use the same on all your Netdata servers (or you can have multiple if you like - your decision). Get them here: https://admin.flock.com/webhooks @@ -21,8 +21,8 @@ Set them in `/etc/netdata/health_alarm_notify.conf` (to edit it on your system r SEND_FLOCK="YES" # Login to flock.com and create an incoming webhook. -# You need only one for all your netdata servers. -# Without it, netdata cannot send flock notifications. +# You need only one for all your Netdata servers. +# Without it, Netdata cannot send flock notifications. FLOCK_WEBHOOK_URL="https://api.flock.com/hooks/sendMessage/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" # if a role recipient is not configured, no notification will be sent diff --git a/health/notifications/irc/README.md b/health/notifications/irc/README.md index 9ea86e92d0..804ff6041b 100644 --- a/health/notifications/irc/README.md +++ b/health/notifications/irc/README.md @@ -10,7 +10,7 @@ Irssi terminal client: You need: -1. The `nc` utility. If you do not set the path, netdata will search for it in your system `$PATH`. +1. The `nc` utility. If you do not set the path, Netdata will search for it in your system `$PATH`. Set the path for `nc` in `/etc/netdata/health_alarm_notify.conf` (to edit it on your system run `/etc/netdata/edit-config health_alarm_notify.conf`), like this: diff --git a/health/notifications/kavenegar/README.md b/health/notifications/kavenegar/README.md index d833eef82e..b8026b89a4 100644 --- a/health/notifications/kavenegar/README.md +++ b/health/notifications/kavenegar/README.md @@ -32,7 +32,7 @@ SEND_KAVENEGAR="YES" # copy your api key. You can generate new API Key too. # You can find and select kevenegar sender number from this place. -# Without an API key, netdata cannot send KAVENEGAR text messages. +# Without an API key, Netdata cannot send KAVENEGAR text messages. KAVENEGAR_API_KEY="" KAVENEGAR_SENDER="" DEFAULT_RECIPIENT_KAVENEGAR="" diff --git a/health/notifications/messagebird/README.md b/health/notifications/messagebird/README.md index cdb3e8dc11..62b8b2eaa3 100644 --- a/health/notifications/messagebird/README.md +++ b/health/notifications/messagebird/README.md @@ -31,7 +31,7 @@ SEND_MESSAGEBIRD="YES" # to get the API key, click on 'API' in the sidebar, then 'API Access (REST)' # click 'Add access key' and fill in data (you want a live key to send SMS) -# Without an access key, netdata cannot send Messagebird text messages. +# Without an access key, Netdata cannot send Messagebird text messages. MESSAGEBIRD_ACCESS_KEY="XXXXXXXX" MESSAGEBIRD_NUMBER="XXXXXXX" DEFAULT_RECIPIENT_MESSAGEBIRD="XXXXXXX" diff --git a/health/notifications/pagerduty/README.md b/health/notifications/pagerduty/README.md index 884b979235..8f03a0695e 100644 --- a/health/notifications/pagerduty/README.md +++ b/health/notifications/pagerduty/README.md @@ -2,11 +2,11 @@ [PagerDuty](https://www.pagerduty.com/company/) is the enterprise incident resolution service that integrates with ITOps and DevOps monitoring stacks to improve operational reliability and agility. From enriching and aggregating events to correlating them into incidents, PagerDuty streamlines the incident management process by reducing alert noise and resolution times. -Here is an example of a PagerDuty dashboard with netdata notifications: +Here is an example of a PagerDuty dashboard with Netdata notifications: - + -To have netdata send notifications to PagerDuty, you'll first need to set up a PagerDuty `Generic API` service and install the PagerDuty agent on the host running netdata. See the following guide for details: +To have Netdata send notifications to PagerDuty, you'll first need to set up a PagerDuty `Generic API` service and install the PagerDuty agent on the host running Netdata. See the following guide for details: https://www.pagerduty.com/docs/guides/agent-install-guide/ diff --git a/health/notifications/pushbullet/README.md b/health/notifications/pushbullet/README.md index 42b343e457..0c0b9a3224 100644 --- a/health/notifications/pushbullet/README.md +++ b/health/notifications/pushbullet/README.md @@ -36,7 +36,7 @@ SEND_PUSHBULLET="YES" # not have a pushbullet account, the pushbullet service will send an email # to that address instead -# Without an access token, netdata cannot send pushbullet notifications. +# Without an access token, Netdata cannot send pushbullet notifications. PUSHBULLET_ACCESS_TOKEN="o.Sometokenhere" DEFAULT_RECIPIENT_PUSHBULLET="admin1@example.com admin3@somemail.com" ``` diff --git a/health/notifications/pushover/README.md b/health/notifications/pushover/README.md index 1debf5dcd4..90e2646a9b 100644 --- a/health/notifications/pushover/README.md +++ b/health/notifications/pushover/README.md @@ -2,11 +2,11 @@ pushover.net allows you to receive push notifications on your mobile phone. The service seems free for up to 7.500 messages per month. -netdata will send warning messages with priority `0` and critical messages with priority `1`. pushover.net allows you to select do-not-disturb hours. The way this is configured, critical notifications will ring and vibrate your phone, even during the do-not-disturb-hours. All other notifications will be delivered silently. +Netdata will send warning messages with priority `0` and critical messages with priority `1`. pushover.net allows you to select do-not-disturb hours. The way this is configured, critical notifications will ring and vibrate your phone, even during the do-not-disturb-hours. All other notifications will be delivered silently. You need: -1. APP TOKEN. You can use the same on all your netdata servers. +1. APP TOKEN. You can use the same on all your Netdata servers. 2. USER TOKEN for each user you are going to send notifications to. This is the actual recipient of the notification. The configuration is like above (slack messages). diff --git a/health/notifications/rocketchat/README.md b/health/notifications/rocketchat/README.md index f05e73f08b..f2650aedbd 100644 --- a/health/notifications/rocketchat/README.md +++ b/health/notifications/rocketchat/README.md @@ -4,7 +4,7 @@ This is what you will get:  You need: -1. The **incoming webhook URL** as given by RocketChat. You can use the same on all your netdata servers (or you can have multiple if you like - your decision). +1. The **incoming webhook URL** as given by RocketChat. You can use the same on all your Netdata servers (or you can have multiple if you like - your decision). 2. One or more channels to post the messages to. Get them here: https://rocket.chat/docs/administrator-guides/integrations/index.html#how-to-create-a-new-incoming-webhook @@ -22,8 +22,8 @@ Set them in `/etc/netdata/health_alarm_notify.conf` (to edit it on your system r SEND_ROCKETCHAT="YES" # Login to rocket.chat and create an incoming webhook. You need only one for all -# your netdata servers (or you can have one for each of your netdata). -# Without it, netdata cannot send rocketchat notifications. +# your Netdata servers (or you can have one for each of your Netdata). +# Without it, Netdata cannot send rocketchat notifications. ROCKETCHAT_WEBHOOK_URL="
-You need a netdata `master`. This node should not be ephemeral. It will be the node where all ephemeral nodes (let's call them `slaves`) will be sending their metrics.
+You need a Netdata `master`. This node should not be ephemeral. It will be the node where all ephemeral nodes (let's call them `slaves`) will be sending their metrics.
The master will need to authorize the slaves for accepting their metrics. This is done with an API key.
@@ -393,11 +392,11 @@ On the master, edit `/etc/netdata/stream.conf` (to edit it on your system run `/
If you used many API keys, you can add one such section for each API key.
-When done, restart netdata on the `master` node. It is now ready to receive metrics.
+When done, restart Netdata on the `master` node. It is now ready to receive metrics.
-Note that `health enabled by default = auto` will still trigger `last_collected` alarms, if a connected slave does not exit gracefully. If the netdata running on the slave is
+Note that `health enabled by default = auto` will still trigger `last_collected` alarms, if a connected slave does not exit gracefully. If the `netdata` process running on the slave is
stopped, it will close the connection to the master, ensuring that no `last_collected` alarms are triggered. For example, a proper container restart would first terminate
-the netdata process, but a system power issue would leave the connection open on the master side. In the second case, you will still receive alarms.
+the `netdata` process, but a system power issue would leave the connection open on the master side. In the second case, you will still receive alarms.
#### Configuring the `slaves`
@@ -405,7 +404,7 @@ On each of the slaves, edit `/etc/netdata/stream.conf` (to edit it on your syste
```bash
[stream]
- # stream metrics to another netdata
+ # stream metrics to another Netdata
enabled = yes
# the IP and PORT of the master
@@ -416,7 +415,7 @@ On each of the slaves, edit `/etc/netdata/stream.conf` (to edit it on your syste
```
*`stream.conf` on slaves, to enable pushing metrics to master at `10.11.12.13:19999`.*
-Using just the above configuration, the `slaves` will be pushing their metrics to the `master` netdata, but they will still maintain a local database of the metrics and run health checks. To disable them, edit `/etc/netdata/netdata.conf` and set:
+Using just the above configuration, the `slaves` will be pushing their metrics to the `master` Netdata, but they will still maintain a local database of the metrics and run health checks. To disable them, edit `/etc/netdata/netdata.conf` and set:
```bash
[global]
@@ -431,9 +430,9 @@ Using just the above configuration, the `slaves` will be pushing their metrics t
Keep in mind that setting `memory mode = none` will also force `[health].enabled = no` (health checks require access to a local database). But you can keep the database and disable health checks if you need to. You are however sending all the metrics to the master server, which can handle the health checking (`[health].enabled = yes`)
-#### netdata unique id
+#### Netdata unique id
-The file `/var/lib/netdata/registry/netdata.public.unique.id` contains a random GUID that **uniquely identifies each netdata**. This file is automatically generated, by netdata, the first time it is started and remains unaltered forever.
+The file `/var/lib/netdata/registry/netdata.public.unique.id` contains a random GUID that **uniquely identifies each Netdata**. This file is automatically generated, by Netdata, the first time it is started and remains unaltered forever.
> If you are building an image to be used for automated provisioning of autoscaled VMs, it important to delete that file from the image, so that each instance of your image will generate its own.
@@ -469,7 +468,7 @@ and something like this on the slave:
### Archiving to a time-series database
-The `master` netdata node can also archive metrics, for all `slaves`, to a time-series database. At the time of this writing, netdata supports:
+The `master` Netdata node can also archive metrics, for all `slaves`, to a time-series database. At the time of this writing, Netdata supports:
- graphite
- opentsdb
@@ -477,7 +476,7 @@ The `master` netdata node can also archive metrics, for all `slaves`, to a time-
- json document DBs
- all the compatibles to the above (e.g. kairosdb, influxdb, etc)
-Check the netdata [backends documentation](../backends) for configuring this.
+Check the Netdata [backends documentation](../backends) for configuring this.
This is how such a solution will work:
@@ -487,7 +486,7 @@ This is how such a solution will work:
### An advanced setup
-netdata also supports `proxies` with and without a local database, and data retention can be different between all nodes.
+Netdata also supports `proxies` with and without a local database, and data retention can be different between all nodes.
This means a setup like the following is also possible:
@@ -498,16 +497,16 @@ This means a setup like the following is also possible:
## proxies
-A proxy is a netdata that is receiving metrics from a netdata, and streams them to another netdata.
+A proxy is a Netdata instance that is receiving metrics from a Netdata, and streams them to another Netdata.
-netdata proxies may or may not maintain a database for the metrics passing through them.
+Netdata proxies may or may not maintain a database for the metrics passing through them.
When they maintain a database, they can also run health checks (alarms and notifications)
for the remote host that is streaming the metrics.
-To configure a proxy, configure it as a receiving and a sending netdata at the same time,
+To configure a proxy, configure it as a receiving and a sending Netdata at the same time,
using [stream.conf](stream.conf).
-The sending side of a netdata proxy, connects and disconnects to the final destination of the
+The sending side of a Netdata proxy, connects and disconnects to the final destination of the
metrics, following the same pattern of the receiving side.
For a practical example see [Monitoring ephemeral nodes](#monitoring-ephemeral-nodes).
diff --git a/web/README.md b/web/README.md
index 5c1a06f59b..66f3ce2788 100644
--- a/web/README.md
+++ b/web/README.md
@@ -18,7 +18,7 @@ If you change that file, your changes will be overwritten when Netdata is update
You have to copy the example file under a new name, so that it will not be overwritten with Netdata updates.
-To configure your info file set in netdata.conf:
+To configure your info file set in `netdata.conf`:
```
[web]
diff --git a/web/api/README.md b/web/api/README.md
index 44afbc90d1..21cebdfa17 100644
--- a/web/api/README.md
+++ b/web/api/README.md
@@ -2,13 +2,13 @@
## Netdata REST API
-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)**.
+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)**.
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.
## Google charts API
-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/).
+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/).
Check this [single chart, jsfiddle example](https://jsfiddle.net/ktsaou/ensu4uws/9/):
diff --git a/web/api/badges/README.md b/web/api/badges/README.md
index 6884cc11ad..60f12e545d 100644
--- a/web/api/badges/README.md
+++ b/web/api/badges/README.md
@@ -6,11 +6,11 @@ Netdata can generate badges for any chart and any dimension at any time-frame. B
**Netdata badges are powerful**!
-Given that netdata collects from **1.000** to **5.000** metrics per server (depending on the number of network interfaces, disks, cpu cores, applications running, users logged in, containers running, etc) and that netdata already has data reduction/aggregation functions embedded, the badges can be quite powerful.
+Given that Netdata collects from **1.000** to **5.000** metrics per server (depending on the number of network interfaces, disks, cpu cores, applications running, users logged in, containers running, etc) and that Netdata already has data reduction/aggregation functions embedded, the badges can be quite powerful.
For each metric/dimension and for arbitrary time-frames badges can show **min**, **max** or **average** value, but also **sum** or **incremental-sum** to have their **volume**.
-For example, there is [a chart in netdata that shows the current requests/s of nginx](http://london.my-netdata.io/#nginx_local_nginx). Using this chart alone we can show the following badges (we could add more time-frames, like **today**, **yesterday**, etc):
+For example, there is [a chart in Netdata that shows the current requests/s of nginx](http://london.my-netdata.io/#nginx_local_nginx). Using this chart alone we can show the following badges (we could add more time-frames, like **today**, **yesterday**, etc):
@@ -18,9 +18,9 @@ Similarly, there is [a chart that shows outbound bandwidth per class](http://lon
-The right one is a **volume** calculation. Netdata calculated the total of the last 86.400 seconds (a day) which gives `kilobits`, then divided it by 8 to make it KB, then by 1024 to make it MB and then by 1024 to make it GB. Calculations like this are quite accurate, since for every value collected, every second, netdata interpolates it to second boundary using microsecond calculations.
+The right one is a **volume** calculation. Netdata calculated the total of the last 86.400 seconds (a day) which gives `kilobits`, then divided it by 8 to make it KB, then by 1024 to make it MB and then by 1024 to make it GB. Calculations like this are quite accurate, since for every value collected, every second, Netdata interpolates it to second boundary using microsecond calculations.
-Let's see a few more badge examples (they come from the [netdata registry](../../../registry/)):
+Let's see a few more badge examples (they come from the [Netdata registry](../../../registry/)):
- **cpu usage of user `root`** (you can pick any user; 100% = 1 core). This will be `green <10%`, `yellow <20%`, `orange <50%`, `blue <100%` (1 core), `red` otherwise (you define thresholds and colors on the URL).
@@ -36,7 +36,7 @@ Let's see a few more badge examples (they come from the [netdata registry](../..
---
-> So, every single line on the charts of a [netdata dashboard](http://london.my-netdata.io/), can become a badge and this badge can calculate **average**, **min**, **max**, or **volume** for any time-frame! And you can also vary the badge color using conditions on the calculated value.
+> So, every single line on the charts of a [Netdata dashboard](http://london.my-netdata.io/), can become a badge and this badge can calculate **average**, **min**, **max**, or **volume** for any time-frame! And you can also vary the badge color using conditions on the calculated value.
---
@@ -44,13 +44,13 @@ Let's see a few more badge examples (they come from the [netdata registry](../..
The basic URL is `http://your.netdata:19999/api/v1/badge.svg?option1&option2&option3&...`.
-Here is what you can put for `options` (these are standard netdata API options):
+Here is what you can put for `options` (these are standard Netdata API options):
- `chart=CHART.NAME`
The chart to get the values from.
- **This is the only parameter required** and with just this parameter, netdata will return the sum of the latest values of all chart dimensions.
+ **This is the only parameter required** and with just this parameter, Netdata will return the sum of the latest values of all chart dimensions.
Example:
@@ -76,7 +76,7 @@ Here is what you can put for `options` (these are standard netdata API options):
- `dimensions=DIMENSION1|DIMENSION2|...`
- The dimensions of the chart to use. If you don't set any dimension, all will be used. When multiple dimensions are used, netdata will sum their values. You can append `options=absolute` if you want this sum to convert all values to positive before adding them.
+ The dimensions of the chart to use. If you don't set any dimension, all will be used. When multiple dimensions are used, Netdata will sum their values. You can append `options=absolute` if you want this sum to convert all values to positive before adding them.
Pipes in HTML have to escaped with `%7C`.
@@ -132,7 +132,7 @@ Here is what you can put for `options` (these are standard netdata API options):
- `group=min` or `group=max` or `group=average` (the default) or `group=sum` or `group=incremental-sum`
- If netdata will have to reduce (aggregate) the data to calculate the value, which aggregation method to use.
+ If Netdata will have to reduce (aggregate) the data to calculate the value, which aggregation method to use.
- `max` will find the max value for the timeframe. This works on both positive and negative dimensions. It will find the most extreme value.
@@ -156,7 +156,7 @@ Here is what you can put for `options` (these are standard netdata API options):
- `min2max`, when multiple dimensions are given, do not sum them, but take their `max - min`.
- - `unaligned`, when data are reduced / aggregated (e.g. the request is about the average of the last minute, or hour), netdata by default aligns them so that the charts will have a constant shape (so average per minute returns always XX:XX:00 - XX:XX:59). Setting the `unaligned` option, netdata will aggregate data without any alignment, so if the request is for 60 seconds, it will aggregate the latest 60 seconds of collected data.
+ - `unaligned`, when data are reduced / aggregated (e.g. the request is about the average of the last minute, or hour), Netdata by default aligns them so that the charts will have a constant shape (so average per minute returns always XX:XX:00 - XX:XX:59). Setting the `unaligned` option, Netdata will aggregate data without any alignment, so if the request is for 60 seconds, it will aggregate the latest 60 seconds of collected data.
These are options dedicated to badges:
@@ -166,9 +166,9 @@ These are options dedicated to badges:
- `units=TEXT`
- The units of the badge. If you want to put a `/`, please put a `\`. This is because netdata allows badges parameters to be given as path in URL, instead of query string. You can also use `null` or `empty` to show it without any units.
+ The units of the badge. If you want to put a `/`, please put a `\`. This is because Netdata allows badges parameters to be given as path in URL, instead of query string. You can also use `null` or `empty` to show it without any units.
- The units `seconds`, `minutes` and `hours` trigger special formatting. The value has to be in this unit, and netdata will automatically change it to show a more pretty duration.
+ The units `seconds`, `minutes` and `hours` trigger special formatting. The value has to be in this unit, and Netdata will automatically change it to show a more pretty duration.
- `multiply=NUMBER`
@@ -180,7 +180,7 @@ These are options dedicated to badges:
- `label_color=COLOR`
- The color of the label (the left part). You can use any HTML color, include `#NNN` and `#NNNNNN`. The following colors are defined in netdata (and you can use them by name): `green`, `brightgreen`, `yellow`, `yellowgreen`, `orange`, `red`, `blue`, `grey`, `gray`, `lightgrey`, `lightgray`. These are taken from https://github.com/badges/shields so they are compatible with standard badges.
+ The color of the label (the left part). You can use any HTML color, include `#NNN` and `#NNNNNN`. The following colors are defined in Netdata (and you can use them by name): `green`, `brightgreen`, `yellow`, `yellowgreen`, `orange`, `red`, `blue`, `grey`, `gray`, `lightgrey`, `lightgray`. These are taken from https://github.com/badges/shields so they are compatible with standard badges.
- `value_color=COLOR:null|COLOR milliseconds!
### Syncing charts y-range
-If you give the same `data-common-max="NAME"` to 2+ charts, then all of them will share the same max value of their y-range. If one spikes, all of them will be aligned to have the same scale. This is done for the cpu interrupts and and cpu softnet charts at the dashboard and also for the `gauge` and `easypiecharts` of the netdata home page.
+If you give the same `data-common-max="NAME"` to 2+ charts, then all of them will share the same max value of their y-range. If one spikes, all of them will be aligned to have the same scale. This is done for the cpu interrupts and and cpu softnet charts at the dashboard and also for the `gauge` and `easypiecharts` of the Netdata home page.
```html