diff options
Diffstat (limited to '')
| -rw-r--r-- | docs/configure/common-changes.md | 159 | ||||
| -rw-r--r-- | docs/configure/nodes.md | 139 |
2 files changed, 0 insertions, 298 deletions
diff --git a/docs/configure/common-changes.md b/docs/configure/common-changes.md deleted file mode 100644 index 2d1757fe9..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](https://github.com/netdata/netdata/blob/master/docs/netdata-cloud/README.md) -for infrastructure monitoring, 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/src/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/src/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/src/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/src/health/REFERENCE.md) to -get started, and see -the [health monitoring reference](https://github.com/netdata/netdata/blob/master/src/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/src/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/security-and-privacy-design/README.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 99e00223c..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/src/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/src/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/src/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/src/collectors/apps.plugin/README.md) or - [`ebpf.plugin`](https://github.com/netdata/netdata/blob/master/src/collectors/ebpf.plugin/README.md). -- `health.d/` is a directory that contains [health configuration files](https://github.com/netdata/netdata/blob/master/src/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/src/collectors/statsd.plugin/README.md). -- `stream.conf` configures [parent-child streaming](https://github.com/netdata/netdata/blob/master/src/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/packaging/installer/README.md#maintaining-a-netdata-agent-installation) 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 -``` |