diff options
Diffstat (limited to 'docs/configure')
| -rw-r--r-- | docs/configure/common-changes.md | 159 | ||||
| -rw-r--r-- | docs/configure/nodes.md | 139 | ||||
| -rw-r--r-- | docs/configure/start-stop-restart.md | 154 |
3 files changed, 0 insertions, 452 deletions
diff --git a/docs/configure/common-changes.md b/docs/configure/common-changes.md deleted file mode 100644 index 1c6f6f5a7..000000000 --- a/docs/configure/common-changes.md +++ /dev/null @@ -1,159 +0,0 @@ -<!-- -title: "Common configuration changes" -description: "See the most popular configuration changes to make to the Netdata Agent, including longer metrics retention, reduce sampling, and more." -custom_edit_url: "https://github.com/netdata/netdata/edit/master/docs/configure/common-changes.md" -sidebar_label: "Common configuration changes" -learn_status: "Published" -learn_topic_type: "Tasks" -learn_rel_path: "Configuration" ---> - -# Common configuration changes - -The Netdata Agent requires no configuration upon installation to collect thousands of per-second metrics from most -systems, containers, and applications, but there are hundreds of settings to tweak if you want to exercise more control -over your monitoring platform. - -This document assumes familiarity with -using [`edit-config`](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md) from the Netdata config -directory. - -## Change dashboards and visualizations - -The Netdata Agent's [local dashboard](https://github.com/netdata/netdata/blob/master/docs/category-overview-pages/accessing-netdata-dashboards.md), accessible -at `http://NODE:19999` is highly configurable. If -you use Netdata Cloud -for [infrastructure monitoring](https://github.com/netdata/netdata/blob/master/docs/quickstart/infrastructure.md), you -will see many of these -changes reflected in those visualizations due to the way Netdata Cloud proxies metric data and metadata to your browser. - -### Increase the long-term metrics retention period - -Read our doc -on [increasing long-term metrics storage](https://github.com/netdata/netdata/blob/master/docs/store/change-metrics-storage.md) -for details, including a -[calculator](https://github.com/netdata/netdata/blob/master/docs/store/change-metrics-storage.md#calculate-the-system-resources-ram-disk-space-needed-to-store-metrics) -to help you determine the exact settings for your desired retention period. - -### Reduce the data collection frequency - -Change `update every` in -the [`[global]` section](https://github.com/netdata/netdata/blob/master/daemon/config/README.md#global-section-options) -of `netdata.conf` so -that it is greater than `1`. An `update every` of `5` means the Netdata Agent enforces a _minimum_ collection frequency -of 5 seconds. - -```conf -[global] - update every = 5 -``` - -Every collector and plugin has its own `update every` setting, which you can also change in the `go.d.conf`, -`python.d.conf` or `charts.d.conf` files, or in individual collector configuration files. If the `update -every` for an individual collector is less than the global, the Netdata Agent uses the global setting. See -the [enable or configure a collector](https://github.com/netdata/netdata/blob/master/collectors/REFERENCE.md#enable-and-disable-a-specific-collection-module) -doc for details. - -### Disable a collector or plugin - -Turn off entire plugins in -the [`[plugins]` section](https://github.com/netdata/netdata/blob/master/daemon/config/README.md#plugins-section-options) -of -`netdata.conf`. - -To disable specific collectors, open `go.d.conf`, `python.d.conf` or `charts.d.conf` and find the line -for that specific module. Uncomment the line and change its value to `no`. - -## Modify alerts and notifications - -Netdata's health monitoring watchdog uses hundreds of preconfigured health entities, with intelligent thresholds, to -generate warning and critical alerts for most production systems and their applications without configuration. However, -each alert and notification method is completely customizable. - -### Add a new alert - -To create a new alert configuration file, initiate an empty file, with a filename that ends in `.conf`, in the -`health.d/` directory. The Netdata Agent loads any valid alert configuration file ending in `.conf` in that directory. -Next, edit the new file with `edit-config`. For example, with a file called `example-alert.conf`. - -```bash -sudo touch health.d/example-alert.conf -sudo ./edit-config health.d/example-alert.conf -``` - -Or, append your new alert to an existing file by editing a relevant existing file in the `health.d/` directory. - -Read more about [configuring alerts](https://github.com/netdata/netdata/blob/master/health/REFERENCE.md) to -get started, and see -the [health monitoring reference](https://github.com/netdata/netdata/blob/master/health/REFERENCE.md) for a full listing -of options available in health entities. - -### Configure a specific alert - -Tweak existing alerts by editing files in the `health.d/` directory. For example, edit `health.d/cpu.conf` to change how -the Agent responds to anomalies related to CPU utilization. - -To see which configuration file you need to edit to configure a specific -alert, [view your active alerts](https://github.com/netdata/netdata/blob/master/docs/monitor/view-active-alerts.md) in -Netdata Cloud or the local Agent dashboard and look for the **source** line. For example, it might -read `source 4@/usr/lib/netdata/conf.d/health.d/cpu.conf`. - -Because the source path contains `health.d/cpu.conf`, run `sudo edit-config health.d/cpu.conf` to configure that alert. - -### Disable a specific alert - -Open the configuration file for that alert and set the `to` line to `silent`. - -```conf -template: disk_fill_rate - on: disk.space - lookup: max -1s at -30m unaligned of avail - calc: ($this - $avail) / (30 * 60) - every: 15s - to: silent -``` - -### Turn of all alerts and notifications - -Set `enabled` to `no` in -the [`[health]`](https://github.com/netdata/netdata/blob/master/daemon/config/README.md#health-section-options) -section of `netdata.conf`. - -### Enable alert notifications - -Open `health_alarm_notify.conf` for editing. First, read the [enabling -notifications](https://github.com/netdata/netdata/blob/master/docs/monitor/enable-notifications.md#netdata-agent) doc -for an example of the process using Slack, then -click on the link to your preferred notification method to find documentation for that specific endpoint. - -## Improve node security - -While the Netdata Agent is both [open and secure by design](https://www.netdata.cloud/blog/netdata-agent-dashboard/), we -recommend every user take some action to administer and secure their nodes. - -Learn more about the available options in the [security design documentation](https://github.com/netdata/netdata/blob/master/docs/netdata-security.md). - -## Reduce resource usage - -Read -our [performance optimization guide](https://github.com/netdata/netdata/blob/master/docs/guides/configure/performance.md) -for a long list of specific changes -that can reduce the Netdata Agent's CPU/memory footprint and IO requirements. - -## Organize nodes with host labels - -Beginning with v1.20, Netdata accepts user-defined **host labels**. These labels are sent during streaming, exporting, -and as metadata to Netdata Cloud, and help you organize the metrics coming from complex infrastructure. Host labels are -defined in the section `[host labels]`. - -For a quick introduction, read -the [host label guide](https://github.com/netdata/netdata/blob/master/docs/guides/using-host-labels.md). - -The following restrictions apply to host label names: - -- Names cannot start with `_`, but it can be present in other parts of the name. -- Names only accept alphabet letters, numbers, dots, and dashes. - -The policy for values is more flexible, but you can not use exclamation marks (`!`), whitespaces (` `), single quotes -(`'`), double quotes (`"`), or asterisks (`*`), because they are used to compare label values in health alerts and -templates. diff --git a/docs/configure/nodes.md b/docs/configure/nodes.md deleted file mode 100644 index 8fdd1070c..000000000 --- a/docs/configure/nodes.md +++ /dev/null @@ -1,139 +0,0 @@ -# Configure the Netdata Agent - -Netdata's zero-configuration collection, storage, and visualization features work for many users, infrastructures, and -use cases, but there are some situations where you might want to configure the Netdata Agent running on your node(s), -which can be a physical or virtual machine (VM), container, cloud deployment, or edge/IoT device. - -For example, you might want to increase metrics retention, configure a collector based on your infrastructure's unique -setup, or secure the local dashboard by restricting it to only connections from `localhost`. - -Whatever the reason, Netdata users should know how to configure individual nodes to act decisively if an incident, -anomaly, or change in infrastructure affects how their Agents should perform. - -## The Netdata config directory - -On most Linux systems, using our [recommended one-line -installation](https://github.com/netdata/netdata/blob/master/packaging/installer/README.md#install-on-linux-with-one-line-installer), the **Netdata config -directory** is `/etc/netdata/`. The config directory contains several configuration files with the `.conf` extension, a -few directories, and a shell script named `edit-config`. - -> Some operating systems will use `/opt/netdata/etc/netdata/` as the config directory. If you're not sure where yours -> is, navigate to `http://NODE:19999/netdata.conf` in your browser, replacing `NODE` with the IP address or hostname of -> your node, and find the `# config directory = ` setting. The value listed is the config directory for your system. - -All of Netdata's documentation assumes that your config directory is at `/etc/netdata`, and that you're running any -scripts from inside that directory. - -## Netdata's configuration files - -Upon installation, the Netdata config directory contains a few files and directories. It's okay if you don't see all -these files in your own Netdata config directory, as the next section describes how to edit any that might not already -exist. - -- `netdata.conf` is the main configuration file. This is where you'll find most configuration options. Read descriptions - for each in the [daemon config](https://github.com/netdata/netdata/blob/master/daemon/config/README.md) doc. -- `edit-config` is a shell script used for [editing configuration files](#use-edit-config-to-edit-configuration-files). -- Various configuration files ending in `.conf` for [configuring plugins or - collectors](https://github.com/netdata/netdata/blob/master/collectors/REFERENCE.md) behave. Examples: `go.d.conf`, - `python.d.conf`, and `ebpf.d.conf`. -- Various directories ending in `.d`, which contain other configuration files, each ending in `.conf`, for [configuring - specific collectors](https://github.com/netdata/netdata/blob/master/collectors/REFERENCE.md). -- `apps_groups.conf` is a configuration file for changing how applications/processes are grouped when viewing the - **Application** charts from [`apps.plugin`](https://github.com/netdata/netdata/blob/master/collectors/apps.plugin/README.md) or - [`ebpf.plugin`](https://github.com/netdata/netdata/blob/master/collectors/ebpf.plugin/README.md). -- `health.d/` is a directory that contains [health configuration files](https://github.com/netdata/netdata/blob/master/health/REFERENCE.md). -- `health_alarm_notify.conf` enables and configures [alert notifications](https://github.com/netdata/netdata/blob/master/docs/monitor/enable-notifications.md). -- `statsd.d/` is a directory for configuring Netdata's [statsd collector](https://github.com/netdata/netdata/blob/master/collectors/statsd.plugin/README.md). -- `stream.conf` configures [parent-child streaming](https://github.com/netdata/netdata/blob/master/streaming/README.md) between separate nodes running the Agent. -- `.environment` is a hidden file that describes the environment in which the Netdata Agent is installed, including the - `PATH` and any installation options. Useful for [reinstalling](https://github.com/netdata/netdata/blob/master/packaging/installer/REINSTALL.md) or - [uninstalling](https://github.com/netdata/netdata/blob/master/packaging/installer/UNINSTALL.md) the Agent. - -The Netdata config directory also contains one symlink: - -- `orig` is a symbolic link to the directory `/usr/lib/netdata/conf.d`, which contains stock configuration files. Stock - versions are copied into the config directory when opened with `edit-config`. _Do not edit the files in - `/usr/lib/netdata/conf.d`, as they are overwritten by updates to the Netdata Agent._ - -## Configure a Netdata docker container - -See [configure agent containers](https://github.com/netdata/netdata/blob/master/packaging/docker/README.md#configure-agent-containers). - -## Use `edit-config` to edit configuration files - -The **recommended way to easily and safely edit Netdata's configuration** is with the `edit-config` script. This script -opens existing Netdata configuration files using your system's `$EDITOR`. If the file doesn't yet exist in your config -directory, the script copies the stock version from `/usr/lib/netdata/conf.d` (or wherever the symlink `orig` under the config directory leads to) -to the proper place in the config directory and opens the copy for editing. - -If you have trouble running the script, you can manually copy the file and edit the copy. - -e.g. `cp /usr/lib/netdata/conf.d/go.d/bind.conf /etc/netdata/go.d/bind.conf; vi /etc/netdata/go.d/bind.conf` - -Run `edit-config` without options, to see details on its usage, or `edit-config --list` to see a list of all the configuration -files you can edit. - -```bash -USAGE: - ./edit-config [options] FILENAME - - Copy and edit the stock config file named: FILENAME - if FILENAME is already copied, it will be edited as-is. - - Stock config files at: '/etc/netdata/../../usr/lib/netdata/conf.d' - User config files at: '/etc/netdata' - - The editor to use can be specified either by setting the EDITOR - environment variable, or by using the --editor option. - - The file to edit can also be specified using the --file option. - - For a list of known config files, run './edit-config --list' -``` - -To edit `netdata.conf`, run `./edit-config netdata.conf`. You may need to elevate your privileges with `sudo` or another -method for `edit-config` to write into the config directory. Use your `$EDITOR`, make your changes, and save the file. - -> `edit-config` uses the `EDITOR` environment variable on your system to edit the file. On many systems, that is -> defaulted to `vim` or `nano`. Use `export EDITOR=` to change this temporarily, or edit your shell configuration file -> to change to permanently. - -After you make your changes, you need to [restart the Agent](https://github.com/netdata/netdata/blob/master/docs/configure/start-stop-restart.md) with `sudo systemctl -restart netdata` or the appropriate method for your system. - -Here's an example of editing the node's hostname, which appears in both the local dashboard and in Netdata Cloud. - - - -### Other configuration files - -You can edit any Netdata configuration file using `edit-config`. A few examples: - -```bash -./edit-config apps_groups.conf -./edit-config ebpf.d.conf -./edit-config health.d/load.conf -./edit-config go.d/prometheus.conf -``` - -The documentation for each of Netdata's components explains which file(s) to edit to achieve the desired behavior. - -## See an Agent's running configuration - -On start, the Netdata Agent daemon attempts to load `netdata.conf`. If that file is missing, incomplete, or contains -invalid settings, the daemon attempts to run sane defaults instead. In other words, the state of `netdata.conf` on your -filesystem may be different from the state of the Netdata Agent itself. - -To see the _running configuration_, navigate to `http://NODE:19999/netdata.conf` in your browser, replacing `NODE` with -the IP address or hostname of your node. The file displayed here is exactly the settings running live in the Netdata -Agent. - -If you're having issues with configuring the Agent, apply the running configuration to `netdata.conf` by downloading the -file to the Netdata config directory. Use `sudo` to elevate privileges. - -```bash -wget -O /etc/netdata/netdata.conf http://localhost:19999/netdata.conf -# or -curl -o /etc/netdata/netdata.conf http://NODE:19999/netdata.conf -``` diff --git a/docs/configure/start-stop-restart.md b/docs/configure/start-stop-restart.md deleted file mode 100644 index 45691bc94..000000000 --- a/docs/configure/start-stop-restart.md +++ /dev/null @@ -1,154 +0,0 @@ -# Start, stop, or restart the Netdata Agent - -When you install the Netdata Agent, the [daemon](https://github.com/netdata/netdata/blob/master/daemon/README.md) is -configured to start at boot and stop and restart/shutdown. - -You will most often need to _restart_ the Agent to load new or editing configuration files. -[Health configuration](#reload-health-configuration) files are the only exception, as they can be reloaded without restarting -the entire Agent. - -Stopping or restarting the Netdata Agent will cause gaps in stored metrics until the `netdata` process initiates -collectors and the database engine. - -## Using `systemctl`, `service`, or `init.d` - -This is the recommended way to start, stop, or restart the Netdata daemon. - -- To **start** Netdata, run `sudo systemctl start netdata`. -- To **stop** Netdata, run `sudo systemctl stop netdata`. -- To **restart** Netdata, run `sudo systemctl restart netdata`. - -If the above commands fail, or you know that you're using a non-systemd system, try using the `service` command: - -- **service**: `sudo service netdata start`, `sudo service netdata stop`, `sudo service netdata restart` - -## Using `netdata` - -Use the `netdata` command, typically located at `/usr/sbin/netdata`, to start the Netdata daemon. - -```bash -sudo netdata -``` - -If you start the daemon this way, close it with `sudo killall netdata`. - -## Using `netdatacli` - -The Netdata Agent also comes with a [CLI tool](https://github.com/netdata/netdata/blob/master/cli/README.md) capable of performing shutdowns. Start the Agent back up -using your preferred method listed above. - -```bash -sudo netdatacli shutdown-agent -``` - -## Netdata MSI installations - -Netdata provides an installer for Windows using WSL, on those installations by using a Windows terminal (e.g. the Command prompt or Windows Powershell) you can: - -- Start Netdata, by running `start-netdata` -- Stop Netdata, by running `stop-netdata` -- Restart Netdata, by running `restart-netdata` - -## Reload health configuration - -You do not need to restart the Netdata Agent between changes to health configuration files, such as specific health -entities. Instead, use [`netdatacli`](#using-netdatacli) and the `reload-health` option to prevent gaps in metrics -collection. - -```bash -sudo netdatacli reload-health -``` - -If `netdatacli` doesn't work on your system, send a `SIGUSR2` signal to the daemon, which reloads health configuration -without restarting the entire process. - -```bash -killall -USR2 netdata -``` - -## Force stop stalled or unresponsive `netdata` processes - -In rare cases, the Netdata Agent may stall or not properly close sockets, preventing a new process from starting. In -these cases, try the following three commands: - -```bash -sudo systemctl stop netdata -sudo killall netdata -ps aux| grep netdata -``` - -The output of `ps aux` should show no `netdata` or associated processes running. You can now start the Netdata Agent -again with `service netdata start`, or the appropriate method for your system. - -## Starting Netdata at boot - -In the `system` directory you can find scripts and configurations for the -various distros. - -### systemd - -The installer already installs `netdata.service` if it detects a systemd system. - -To install `netdata.service` by hand, run: - -```sh -# stop Netdata -killall netdata - -# copy netdata.service to systemd -cp system/netdata.service /etc/systemd/system/ - -# let systemd know there is a new service -systemctl daemon-reload - -# enable Netdata at boot -systemctl enable netdata - -# start Netdata -systemctl start netdata -``` - -### init.d - -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 -cp system/netdata-lsb /etc/init.d/netdata - -# make sure it is executable -chmod +x /etc/init.d/netdata - -# enable it -update-rc.d netdata defaults -``` - -### openrc (gentoo) - -In the `system` directory you can find `netdata-openrc`. Copy it to the proper -place according to your distribution documentation. - -### CentOS / Red Hat Enterprise Linux - -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 -cp system/netdata-init-d /etc/init.d/netdata - -# make sure it is executable -chmod +x /etc/init.d/netdata - -# enable it -chkconfig --add netdata -``` - -_There have been some recent work on the init script, see PR -<https://github.com/netdata/netdata/pull/403>_ - -### other systems - -You can start Netdata by running it from `/etc/rc.local` or equivalent. - |