diff options
| author | Joel Hans <joel@netdata.cloud> | 2021-01-07 11:44:43 -0700 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2021-01-07 11:44:43 -0700 |
| commit | 46a8075c8ff6da974d1b39f5b3b9eb50385892c1 (patch) | |
| tree | 53ee29b1928ef3d13a3c941c52c9f56868bf918c /docs | |
| parent | 0bb7a429b619bc68104983691e4f957482630787 (diff) | |
Docs housekeeping for SEO and syntax, part 1 (#10388)
* First pass to get the script working right
* Finish adding analytics tags
Diffstat (limited to 'docs')
27 files changed, 223 insertions, 51 deletions
diff --git a/docs/Add-more-charts-to-netdata.md b/docs/Add-more-charts-to-netdata.md index d607111b3f..a16f2e9dbc 100644 --- a/docs/Add-more-charts-to-netdata.md +++ b/docs/Add-more-charts-to-netdata.md @@ -1,8 +1,6 @@ <!-- ---- title: "Add more charts to Netdata" custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/Add-more-charts-to-netdata.md ---- --> # Add more charts to Netdata @@ -14,3 +12,5 @@ guide](/collectors/QUICKSTART.md) for more information. See the [list of supported collectors](/collectors/COLLECTORS.md) to see all the sources Netdata can collect metrics from. + +[]() diff --git a/docs/Demo-Sites.md b/docs/Demo-Sites.md index 2fce066b37..8af1282ba4 100644 --- a/docs/Demo-Sites.md +++ b/docs/Demo-Sites.md @@ -1,9 +1,7 @@ <!-- ---- title: "Demo sites" date: 2020-03-26 custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/Demo-Sites.md ---- --> # Demo sites diff --git a/docs/Donations-netdata-has-received.md b/docs/Donations-netdata-has-received.md index 2c75b87436..df6c040bab 100644 --- a/docs/Donations-netdata-has-received.md +++ b/docs/Donations-netdata-has-received.md @@ -1,8 +1,6 @@ <!-- ---- title: "Donations" custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/Donations-netdata-has-received.md ---- --> # Donations diff --git a/docs/README.md b/docs/README.md index c483cb7ad1..47950f3889 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,8 +1,6 @@ <!-- ---- title: "Read documentation on <https://learn.netdata.cloud>" custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/README.md ---- --> # Read documentation on <https://learn.netdata.cloud> @@ -15,3 +13,5 @@ uses a few extra Markdown features that GitHub doesn't support natively. Other t perfect. Now get out there and build an exceptional infrastructure. + +[](<>) diff --git a/docs/Running-behind-apache.md b/docs/Running-behind-apache.md index 930c220fda..8a547e7b4f 100644 --- a/docs/Running-behind-apache.md +++ b/docs/Running-behind-apache.md @@ -1,8 +1,6 @@ <!-- ---- title: "Netdata via apache's mod_proxy" custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/Running-behind-apache.md ---- --> # Netdata via apache's mod_proxy diff --git a/docs/Running-behind-caddy.md b/docs/Running-behind-caddy.md index 01934b5749..c1d57504ad 100644 --- a/docs/Running-behind-caddy.md +++ b/docs/Running-behind-caddy.md @@ -1,8 +1,6 @@ <!-- ---- title: "Netdata via Caddy" custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/Running-behind-caddy.md ---- --> # Netdata via Caddy diff --git a/docs/Running-behind-haproxy.md b/docs/Running-behind-haproxy.md index 212779b4b2..d4b09f85c7 100644 --- a/docs/Running-behind-haproxy.md +++ b/docs/Running-behind-haproxy.md @@ -1,8 +1,6 @@ <!-- ---- title: "Netdata via HAProxy" custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/Running-behind-haproxy.md ---- --> # Netdata via HAProxy diff --git a/docs/Running-behind-lighttpd.md b/docs/Running-behind-lighttpd.md index 25c62cff4d..8649158002 100644 --- a/docs/Running-behind-lighttpd.md +++ b/docs/Running-behind-lighttpd.md @@ -1,8 +1,6 @@ <!-- ---- title: "Netdata via lighttpd v1.4.x" custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/Running-behind-lighttpd.md ---- --> # Netdata via lighttpd v1.4.x diff --git a/docs/Running-behind-nginx.md b/docs/Running-behind-nginx.md index 35e6c8051a..2f47447da3 100644 --- a/docs/Running-behind-nginx.md +++ b/docs/Running-behind-nginx.md @@ -1,8 +1,6 @@ <!-- ---- title: "Running Netdata behind Nginx" custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/Running-behind-nginx.md ---- --> # Running Netdata behind Nginx diff --git a/docs/a-github-star-is-important.md b/docs/a-github-star-is-important.md index 6730dfecfe..d309d3928a 100644 --- a/docs/a-github-star-is-important.md +++ b/docs/a-github-star-is-important.md @@ -1,8 +1,6 @@ <!-- ---- title: "A GitHub star is important" custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/a-github-star-is-important.md ---- --> # A GitHub star is important diff --git a/docs/agent-cloud.md b/docs/agent-cloud.md index 2a03582c2b..061b8472db 100644 --- a/docs/agent-cloud.md +++ b/docs/agent-cloud.md @@ -1,9 +1,7 @@ <!-- ---- title: "Use the Agent with Netdata Cloud" date: 2020-05-04 custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/agent-cloud.md ---- --> # Use the Agent with Netdata Cloud @@ -76,4 +74,6 @@ about how you might want to use or configure Cloud, we recommend the following: - Follow the 5-minute [get started with Cloud](https://learn.netdata.cloud/docs/cloud/get-started/) guide to finish onboarding and claim your first nodes. - Better understand how agents connect securely to the Cloud with [claiming](/claim/README.md) and [Agent-Cloud - link](/aclk/README.md) documentation.
\ No newline at end of file + link](/aclk/README.md) documentation. + +[]() diff --git a/docs/anonymous-statistics.md b/docs/anonymous-statistics.md index 71c995a519..70c502d063 100644 --- a/docs/anonymous-statistics.md +++ b/docs/anonymous-statistics.md @@ -1,8 +1,7 @@ <!-- ---- title: "Anonymous statistics" +description: "The Netdata Agent collects anonymous usage information by default and sends it to Google Analytics for quality assurance and product decisions." custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/anonymous-statistics.md ---- --> # Anonymous statistics @@ -106,3 +105,5 @@ Each of these opt-out processes does the following: - Forces the anonymous statistics script to exit immediately. - Stops the Google Tag Manager Javascript snippet, which remains on the dashboard, from firing and sending any data to Google Analytics. + +[]() diff --git a/docs/configuration-guide.md b/docs/configuration-guide.md new file mode 100644 index 0000000000..06b61d08d1 --- /dev/null +++ b/docs/configuration-guide.md @@ -0,0 +1,211 @@ +<!-- +title: "Configuration guide" +custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/configuration-guide.md +--> + +# Configuration guide + +No configuration is required to run Netdata, but you will find plenty of options to tweak, so that you can adapt it to +your particular needs. + +<details markdown="1"><summary>Configuration files are placed in `/etc/netdata`.</summary> +Depending on your installation method, Netdata will have been installed either directly under `/`, or under `/opt/netdata`. The paths mentioned here and in the documentation in general assume that your installation is under `/`. If it is not, you will find the exact same paths under `/opt/netdata` as well. (i.e. `/etc/netdata` will be `/opt/netdata/etc/netdata`).</details> + +Under that directory you will see the following: + +- `netdata.conf` is [the main configuration file](/daemon/config/README.md#daemon-configuration) +- `edit-config` is an sh script that you can use to easily and safely edit the configuration. Just run it to see its + usage. +- Other directories, initially empty, where your custom configurations for alarms and collector plugins/modules will + be copied from the stock configuration, if and when you customize them using `edit-config`. +- `orig` is a symbolic link to the directory `/usr/lib/netdata/conf.d`, which contains the stock configurations for + everything not included in `netdata.conf`: + - `health_alarm_notify.conf` is where you configure how and to who Netdata will send [alarm + notifications](/health/notifications/README.md#netdata-alarm-notifications). + - `health.d` is the directory that contains the alarm triggers for [health + monitoring](/health/README.md#health-monitoring). It contains one .conf file per collector. + - The [modular plugin orchestrators](/collectors/plugins.d/README.md#external-plugins-overview) have: + - One config file each, mainly to turn their modules on and off: `python.d.conf` for + [python](/collectors/python.d.plugin/README.md#pythondplugin), `node.d.conf` for + [nodejs](/collectors/node.d.plugin/README.md#nodedplugin) and `charts.d.conf` for + [bash](/collectors/charts.d.plugin/README.md#chartsdplugin) modules. + - One directory each, where the module-specific configuration files can be found. + - `stream.conf` is where you configure [streaming and + replication](/streaming/README.md#streaming-and-replication) + - `stats.d` is a directory under which you can add .conf files to add [synthetic + charts](/collectors/statsd.plugin/README.md#synthetic-statsd-charts). + - Individual collector plugin config files, such as `fping.conf` for the [fping + plugin](/collectors/fping.plugin/) and `apps_groups.conf` for the [apps plugin](/collectors/apps.plugin/) + +So there are many configuration files to control every aspect of Netdata's behavior. It can be overwhelming at first, +but you won't have to deal with any of them, unless you have specific things you need to change. The following HOWTO +will guide you on how to customize your Netdata, based on what you want to do. + +## How to + +### Persist my configuration + +In `http://localhost:19999/netdata.conf`, you will see the following two parameters: + +```bash + # config directory = /etc/netdata + # stock config directory = /usr/lib/netdata/conf.d +``` + +To persist your configurations, don't edit the files under the `stock config directory` directly. Use the `sudo [config +directory]/edit-config` command, or copy the stock config file to its proper place under the `config directory` and edit +it there. + +### Change what I see + +#### Increase the long-term metrics retention period + +Increase the values for the `page cache size` and `dbengine disk space` settings in the [`[global]` +section](/daemon/config/README.md#global-section-options) of `netdata.conf`. Read our guide on [increasing +long-term metrics storage](/docs/guides/longer-metrics-storage.md) and the [memory requirements for the database +engine](/database/engine/README.md#memory-requirements). + +#### Reduce the data collection frequency + +Increase `update every` in [netdata.conf \[global\]](/daemon/config/README.md#global-section-options). This is another +way to increase your metrics retention period, but at a lower resolution than the default 1s. + +#### Modify how a chart is displayed + +In `netdata.conf` under `# Per chart configuration` you will find several [\[CHART_NAME\] +sections](/daemon/config/README.md#per-chart-configuration), where you can control all aspects of a specific chart. + +#### Disable a collector + +Entire plugins can be turned off from the [netdata.conf \[plugins\]](/daemon/config/README.md#plugins-section-options) +section. To disable specific modules of a plugin orchestrator, you need to edit one of the following: + +- `python.d.conf` for [python](/collectors/python.d.plugin/README.md) +- `node.d.conf` for [nodejs](/collectors/node.d.plugin/README.md) +- `charts.d.conf` for [bash](/collectors/charts.d.plugin/README.md) + +#### 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. + +### Modify alarms and notifications + +#### Add a new alarm + +You can add a new alarm definition either by editing an existing stock alarm config file under `health.d` (e.g. +`/etc/netdata/edit-config health.d/load.conf`), or by adding a new `.conf` file under `/etc/netdata/health.d`. The +documentation on how to define an alarm is in [health monitoring](/health/README.md). It is +suggested to look at some of the stock alarm definitions, so you can ensure you understand how the various options work. + +#### Turn off all alarms and notifications + +Just set `enabled = no` in the [netdata.conf \[health\]](/daemon/config/README.md#health-section-options) section + +#### Modify or disable a specific alarm + +The `health.d` directory that contains the alarm triggers for [health monitoring](/health/README.md). It has +one .conf file per collector. You can easily find the .conf file you will need to modify, by looking for the "source" +line on the table that appears on the right side of an alarm on the Netdata gui. + +For example, if you click on Alarms and go to the tab 'All', the default Netdata installation will show you at the top +the configured alarm for `10 min cpu usage` (it's the name of the badge). Looking at the table on the right side, you +will see a row that says: `source 4@/usr/lib/netdata/conf.d/health.d/cpu.conf`. This way, you know that you will need +to run `/etc/netdata/edit-config health.d/cpu.conf` and look for alarm at line 4 of the conf file. + +As stated at the top of the .conf file, **you can disable an alarm notification by setting the 'to' line to: silent**. +To modify how the alarm gets triggered, we suggest that you go through the guide on [health +monitoring](/health/README.md#health-monitoring). + +#### Receive notifications using my preferred method + +You only need to configure `health_alarm_notify.conf`. To learn how to do it, read first [alarm +notifications](/health/notifications/README.md#netdata-alarm-notifications) and then open the submenu `Supported +Notifications` under `Alarm notifications` in the documentation to find the specific page on your preferred notification +method. + +### Make security-related customizations + +#### Change the Netdata web server access lists + +You have several options under the [netdata.conf \[web\]](/web/server/README.md#access-lists) section. + +#### 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/README.md#run-your-own-registry). + +#### Change the IP address/port Netdata listens to + +The settings are under the `[web]` section. Look at the [web server +documentation](/web/server/README.md#binding-netdata-to-multiple-ports) for more info. + +### System resource usage + +#### Reduce the resources Netdata uses + +The [Netdata performance guide](/docs/guides/configure/performance.md) outlines many ways to reduce the Netdata +CPU/disk/RAM utilization to levels suitable even for the weakest [IoT devices](/docs/netdata-for-IoT.md). + +#### Change when Netdata saves metrics to disk + +[netdata.conf \[global\]](/daemon/config/README.md#global-section-options): `memory mode` + +#### Prevent Netdata from getting immediately killed when my server runs out of memory + +You can change the Netdata [OOM score](/daemon/README.md#oom-score) in `[global]`. + +### Other + +#### Move Netdata directories + +The various directory paths are in [netdata.conf \[global\]](/daemon/config/README.md#global-section-options). + +## How Netdata configuration works + +The configuration files are `name = value` dictionaries with `[sections]`. Write whatever you like there as long as it +follows this simple format. + +Netdata loads this dictionary and then when the code needs a value from it, it just looks up the `name` in the +dictionary at the proper `section`. In all places, in the code, there are both the `names` and their `default values`, +so if something is not found in the configuration file, the default is used. The lookup is made using B-Trees and hashes +(no string comparisons), so they are super fast. Also the `names` of the settings can be `my super duper setting that +once set to yes, will turn the world upside down = no` - so goodbye to most of the documentation involved. + +Next, Netdata can generate a valid configuration for the user to edit. No need to remember anything. Just get the +configuration from the server (`/netdata.conf` on your Netdata server), edit it and save it. + +Last, what about options you believe you have set, but you misspelled?When you get the configuration file from the +server, there will be a comment above all `name = value` pairs the server does not use. So you know that whatever you +wrote there, is not used. + +## Netdata simple patterns + +Unix prefers regular expressions. But they are just too hard, too cryptic to use, write and understand. + +So, Netdata supports [simple patterns](/libnetdata/simple_pattern/README.md). + +## Netdata labels + +Beginning with 1.20, Netdata accepts user-defined **host labels**. These labels are defined in the section `[host +labels]`. + +Read more about how these labels work and why they're an effective way to organize complex infrasturctures in our +guide: [Use host labels to organize systems, metrics, and alarms](/docs/guides/using-host-labels.md). + +To define a label inside this section, some rules needs to be followed, or Netdata will reject the label. The following +restrictions are applied for 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 alarms and +templates. + +[](<>) diff --git a/docs/getting-started.md b/docs/getting-started.md index 74597c10b3..1ccab4247b 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,9 +1,7 @@ <!-- ---- title: "Get started guide" date: 2020-05-04 custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/getting-started.md ---- --> # Get started guide diff --git a/docs/guides/deploy/ansible.md b/docs/guides/deploy/ansible.md index 887ba5e07a..8298fd00c8 100644 --- a/docs/guides/deploy/ansible.md +++ b/docs/guides/deploy/ansible.md @@ -1,6 +1,6 @@ <!-- title: Deploy Netdata with Ansible -description: Deploy an infrastructure monitoring solution in minutes with the Netdata Agent and Ansible. Use and customize a simple playbook for monitoring as code. +description: "Deploy an infrastructure monitoring solution in minutes with the Netdata Agent and Ansible. Use and customize a simple playbook for monitoring as code." image: /img/seo/guides/deploy/ansible.png custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/guides/deploy/ansible.md --> diff --git a/docs/guides/export/export-netdata-metrics-graphite.md b/docs/guides/export/export-netdata-metrics-graphite.md index 4b11c3b15c..9a4a4f5ca6 100644 --- a/docs/guides/export/export-netdata-metrics-graphite.md +++ b/docs/guides/export/export-netdata-metrics-graphite.md @@ -1,6 +1,6 @@ <!-- title: Export and visualize Netdata metrics in Graphite -description: Use Netdata to collect and export thousands of metrics to Graphite for long-term storage or further analysis. +description: "Use Netdata to collect and export thousands of metrics to Graphite for long-term storage or further analysis." image: /img/seo/guides/export/export-netdata-metrics-graphite.png --> diff --git a/docs/guides/monitor/dimension-templates.md b/docs/guides/monitor/dimension-templates.md index 5fe3ae9632..da1faed8b4 100644 --- a/docs/guides/monitor/dimension-templates.md +++ b/docs/guides/monitor/dimension-templates.md @@ -1,8 +1,6 @@ <!-- ---- title: "Use dimension templates to create dynamic alarms" custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/monitor/health/dimension-templates.md ---- --> # Use dimension templates to create dynamic alarms diff --git a/docs/guides/monitor/stop-notifications-alarms.md b/docs/guides/monitor/stop-notifications-alarms.md index bf897e0f57..587880ab11 100644 --- a/docs/guides/monitor/stop-notifications-alarms.md +++ b/docs/guides/monitor/stop-notifications-alarms.md @@ -1,8 +1,6 @@ <!-- ---- title: "Stop notifications for individual alarms" custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/guides/monitor/stop-notifications-alarms.md ---- --> # Stop notifications for individual alarms diff --git a/docs/netdata-for-IoT.md b/docs/netdata-for-IoT.md index abd2d5ddda..77b95229fd 100644 --- a/docs/netdata-for-IoT.md +++ b/docs/netdata-for-IoT.md @@ -1,8 +1,6 @@ <!-- ---- title: "Netdata for IoT" custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-for-IoT.md ---- --> # Netdata for IoT diff --git a/docs/netdata-security.md b/docs/netdata-security.md index 97b9bae939..e020c0c8d2 100644 --- a/docs/netdata-security.md +++ b/docs/netdata-security.md @@ -1,8 +1,6 @@ <!-- ---- title: "Security design" custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-security.md ---- --> # Security design diff --git a/docs/privacy-policy.md b/docs/privacy-policy.md index 561803783a..0152b0e0f5 100644 --- a/docs/privacy-policy.md +++ b/docs/privacy-policy.md @@ -1,8 +1,6 @@ <!-- ---- title: "Privacy Policy" custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/privacy-policy.md ---- --> # Privacy Policy diff --git a/docs/terms-of-use.md b/docs/terms-of-use.md index 652dbc97f1..a3cbd0099c 100644 --- a/docs/terms-of-use.md +++ b/docs/terms-of-use.md @@ -1,8 +1,6 @@ <!-- ---- title: "Terms of Use" custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/terms-of-use.md ---- --> # Terms of Use diff --git a/docs/why-netdata/1s-granularity.md b/docs/why-netdata/1s-granularity.md index bd0f9624d1..a2cc65b8f4 100644 --- a/docs/why-netdata/1s-granularity.md +++ b/docs/why-netdata/1s-granularity.md @@ -1,8 +1,6 @@ <!-- ---- title: "1s granularity" custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/why-netdata/1s-granularity.md ---- --> # 1s granularity diff --git a/docs/why-netdata/README.md b/docs/why-netdata/README.md index d0c3206089..39cda51e23 100644 --- a/docs/why-netdata/README.md +++ b/docs/why-netdata/README.md @@ -1,8 +1,6 @@ <!-- ---- title: "Why Netdata" custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/why-netdata/README.md ---- --> # Why Netdata diff --git a/docs/why-netdata/immediate-results.md b/docs/why-netdata/immediate-results.md index 589f6afd1f..ba7c7d684a 100644 --- a/docs/why-netdata/immediate-results.md +++ b/docs/why-netdata/immediate-results.md @@ -1,8 +1,6 @@ <!-- ---- title: "Immediate results" custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/why-netdata/immediate-results.md ---- --> # Immediate results diff --git a/docs/why-netdata/meaningful-presentation.md b/docs/why-netdata/meaningful-presentation.md index 4236fae4c5..64d83b4f62 100644 --- a/docs/why-netdata/meaningful-presentation.md +++ b/docs/why-netdata/meaningful-presentation.md @@ -1,8 +1,6 @@ <!-- ---- title: "Meaningful presentation" custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/why-netdata/meaningful-presentation.md ---- --> # Meaningful presentation diff --git a/docs/why-netdata/unlimited-metrics.md b/docs/why-netdata/unlimited-metrics.md index 8c8e83f130..8e50062c7d 100644 --- a/docs/why-netdata/unlimited-metrics.md +++ b/docs/why-netdata/unlimited-metrics.md @@ -1,8 +1,6 @@ <!-- ---- title: "Unlimited metrics" custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/why-netdata/unlimited-metrics.md ---- --> # Unlimited metrics |