| 1 | # Configuration Examples |
| 2 | |
| 3 | These practical examples will help you optimize Netdata for various real-world deployment scenarios. |
| 4 | |
| 5 | ## Single Agent Configuration |
| 6 | |
| 7 | Single Agents work great out of the box with sensible defaults. |
| 8 | |
| 9 | :::tip |
| 10 | |
| 11 | Check out our [configuration documentation](/docs/netdata-agent/configuration/README.md) for all available options. |
| 12 | |
| 13 | ::: |
| 14 | |
| 15 | ## Parent-Child Configuration Examples |
| 16 | |
| 17 | ### Lightweight Child Configuration |
| 18 | |
| 19 | This example helps you make Children super lightweight by offloading work to Parents, minimizing resource usage on production systems. |
| 20 | |
| 21 | **Why minimize Child footprint?** |
| 22 | We don't recommend connecting Children to Cloud directly. This reduces the Netdata Agent footprint on your production systems, as some capabilities can be switched OFF for the Child and kept ON for the Parent. |
| 23 | |
| 24 | **What this does:** |
| 25 | |
| 26 | - Stores metrics in RAM only (zero disk I/O) |
| 27 | - Disables machine learning (Parent handles it) |
| 28 | - Disables alerts (Parent handles them) |
| 29 | - Keeps only 20 minutes of data locally |
| 30 | - Restricts dashboard to localhost only |
| 31 | |
| 32 | Edit `netdata.conf` on the Child using the [edit-config](/docs/netdata-agent/configuration/README.md#locate-your-config-directory) script: |
| 33 | |
| 34 | ```ini |
| 35 | [db] |
| 36 | # https://github.com/netdata/netdata/blob/master/src/database/README.md |
| 37 | # none = no retention, ram = some retention in ram |
| 38 | mode = ram |
| 39 | # The retention in seconds. |
| 40 | # This provides some tolerance to the time the child has to find a parent |
| 41 | # to transfer the data. For IoT, this can be lowered to 120. |
| 42 | retention = 1200 |
| 43 | # The granularity of metrics, in seconds. |
| 44 | # You may increase this to lower CPU resources. |
| 45 | update every = 1 |
| 46 | [ml] |
| 47 | # Disable Machine Learning |
| 48 | enabled = no |
| 49 | [health] |
| 50 | # Disable Health Checks (Alerting) |
| 51 | enabled = no |
| 52 | [web] |
| 53 | # Disable remote access to the local dashboard |
| 54 | bind to = localhost |
| 55 | [plugins] |
| 56 | # Uncomment the following line to disable all external plugins on extreme IoT cases by default. |
| 57 | # enable running new plugins = no |
| 58 | ``` |
| 59 | |
| 60 | Edit `stream.conf` on the Child using the [edit-config](/docs/netdata-agent/configuration/README.md#locate-your-config-directory) script: |
| 61 | |
| 62 | ```ini |
| 63 | [stream] |
| 64 | # Stream metrics to another Netdata |
| 65 | enabled = yes |
| 66 | # The IP and PORT of the parent |
| 67 | destination = PARENT_IP_ADDRESS:19999 |
| 68 | # The shared API key, generated by uuidgen |
| 69 | api key = API_KEY |
| 70 | ``` |
| 71 | |
| 72 | **Perfect for:** IoT devices, containers, or any resource-constrained system. |
| 73 | |
| 74 | |
| 75 | ### Parent with Tiered Storage |
| 76 | |
| 77 | This example helps you configure a Parent with multiple [tiers of metrics storage](/src/database/README.md#tiers) to store different time ranges at different resolutions, for 10 Children with about 2k metrics each. Retention in each tier is restricted both in time and storage space, whichever is met first. See [retention settings](/src/database/CONFIGURATION.md#retention-settings) for fine-tuning retention. |
| 78 | |
| 79 | **What this gives you:** |
| 80 | |
| 81 | - 1-second resolution for 1 week (recent data at full detail) |
| 82 | - 1-minute resolution for 1 month (medium-term trends) |
| 83 | - 1-hour resolution for 1 year (long-term patterns) |
| 84 | |
| 85 | **Resource requirements:** |
| 86 | |
| 87 | - Disk space: 25GB total |
| 88 | - RAM usage: 3.5GB typical (2.5GB under memory pressure) |
| 89 | |
| 90 | Edit `netdata.conf` on the Parent using the [edit-config](/docs/netdata-agent/configuration/README.md#locate-your-config-directory) script: |
| 91 | |
| 92 | ```ini |
| 93 | [db] |
| 94 | mode = dbengine |
| 95 | dbengine tier backfill = new |
| 96 | storage tiers = 3 |
| 97 | dbengine page cache size = 1.4GiB |
| 98 | |
| 99 | # storage tier 0, 1 second resolution |
| 100 | update every = 1 |
| 101 | dbengine tier 0 retention size = 12GiB |
| 102 | dbengine tier 0 retention time = 7d |
| 103 | |
| 104 | # storage tier 1, 60 seconds = 1 minute resolution |
| 105 | dbengine tier 1 update every iterations = 60 |
| 106 | dbengine tier 1 retention size = 4GiB |
| 107 | dbengine tier 1 retention time = 1mo |
| 108 | |
| 109 | # storage tier 2, 60 * 60 seconds = 1 hour resolution |
| 110 | dbengine tier 2 update every iterations = 60 |
| 111 | dbengine tier 2 retention size = 2GiB |
| 112 | dbengine tier 2 retention time = 1y |
| 113 | |
| 114 | [ml] |
| 115 | # Enabled by default |
| 116 | # enabled = yes |
| 117 | [health] |
| 118 | # Enabled by default |
| 119 | # enabled = yes |
| 120 | [web] |
| 121 | # Enabled by default |
| 122 | # bind to = * |
| 123 | ``` |
| 124 | |
| 125 | Edit `stream.conf` on the Parent using the [edit-config](/docs/netdata-agent/configuration/README.md#locate-your-config-directory) script: |
| 126 | |
| 127 | ```ini |
| 128 | [API_KEY] |
| 129 | # Accept metrics streaming from other Agents with the specified API key |
| 130 | enabled = yes |
| 131 | ``` |
| 132 | |
| 133 | **Perfect for:** Central monitoring servers with enough storage for historical data. |
| 134 | |
| 135 | |
| 136 | ### Active-Active Parents |
| 137 | |
| 138 | This example guides you through setting up active-active Parents that sync with each other for high availability. |
| 139 | |
| 140 | :::info |
| 141 | |
| 142 | - To set up active-active streaming between Parent 1 and Parent 2, Parent 1 needs to be instructed to stream data to Parent 2 and Parent 2 to stream data to Parent 1. |
| 143 | |
| 144 | - The Child Agents need to be configured with the addresses of both Parent Agents. An Agent will only connect to one Parent at a time, falling back to the next upon failure. |
| 145 | |
| 146 | ::: |
| 147 | |
| 148 | **Parent 1 stream.conf:** |
| 149 | |
| 150 | ```ini |
| 151 | [stream] |
| 152 | # Stream metrics to another Netdata |
| 153 | enabled = yes |
| 154 | # The IP and PORT of Parent 2 |
| 155 | destination = PARENT_2_IP_ADDRESS:19999 |
| 156 | # This is the API key for the outgoing connection to Parent 2 |
| 157 | api key = API_KEY |
| 158 | [API_KEY] |
| 159 | # Accept metrics streams from Parent 2 and Child Agents |
| 160 | enabled = yes |
| 161 | ``` |
| 162 | |
| 163 | **Parent 2 stream.conf:** |
| 164 | |
| 165 | ```ini |
| 166 | [stream] |
| 167 | # Stream metrics to another Netdata |
| 168 | enabled = yes |
| 169 | # The IP and PORT of Parent 1 |
| 170 | destination = PARENT_1_IP_ADDRESS:19999 |
| 171 | api key = API_KEY |
| 172 | [API_KEY] |
| 173 | # Accept metrics streams from Parent 1 and Child Agents |
| 174 | enabled = yes |
| 175 | ``` |
| 176 | |
| 177 | **Children stream.conf:** |
| 178 | |
| 179 | ```ini |
| 180 | [stream] |
| 181 | # Stream metrics to another Netdata |
| 182 | enabled = yes |
| 183 | # The IP and PORT of the parent |
| 184 | destination = PARENT_1_IP_ADDRESS:19999 PARENT_2_IP_ADDRESS:19999 |
| 185 | # The shared API key, generated by uuidgen |
| 186 | api key = API_KEY |
| 187 | ``` |
| 188 | |
| 189 | |
| 190 | ## Further Reading |
| 191 | |
| 192 | We strongly recommend the following configuration changes for production deployments: |
| 193 | |
| 194 | 1. Understand Netdata's [security and privacy design](/docs/security-and-privacy-design/README.md) and [secure your nodes](/docs/netdata-agent/securing-netdata-agents.md) |
| 195 | |
| 196 | To safeguard your infrastructure and comply with your organization's security policies. |
| 197 | |
| 198 | 2. [Optimize the Netdata Agents system utilization and performance](/docs/netdata-agent/configuration/optimize-the-netdata-agents-performance.md) |
| 199 | |
| 200 | To save valuable system resources, especially when running on weak IoT devices. |
| 201 | |
| 202 | We also suggest that you: |
| 203 | |
| 204 | 1. [Use Netdata Cloud to access the dashboards](/docs/netdata-cloud/README.md) |
| 205 | |
| 206 | For increased security, user management and access to our latest features, tools and troubleshooting solutions. |
| 207 | |
| 208 | 2. [Change how long Netdata stores metrics](/src/database/CONFIGURATION.md#tiers) |
| 209 | |
| 210 | To control Netdata's memory use, when you have a lot of ephemeral metrics. |
| 211 | |
| 212 | 3. [Use host labels](/docs/netdata-agent/configuration/organize-systems-metrics-and-alerts.md) |
| 213 | |
| 214 | To organize systems, metrics, and alerts. |