# Netdata — User Guide

Real-time infrastructure monitoring with per-second granularity, zero-configuration auto-discovery, machine learning anomaly detection, and 800+ integrations — all running on your own hardware.

---

## 1. Quick Start

Netdata is a real-time infrastructure monitoring tool that collects thousands of metrics per second from systems, containers, and applications with zero configuration. It ships with a built-in web dashboard, machine learning anomaly detection on every metric, and over 800 integrations that auto-discover services the moment they appear.

**Key features at a glance:**

- **Per-second metric collection** — one-second granularity by default, not 15-second or 60-second averages
- **800+ integrations** — auto-discovers and monitors services, containers, and hardware without manual setup
- **ML anomaly detection** — trains per-metric models on the fly; flags unusual behavior automatically
- **Built-in web dashboard** — accessible at `http://localhost:19999` immediately after install
- **Parent-Child streaming** — centralize metrics from hundreds of nodes to a single parent
- **Alerts with 30+ notification methods** — Slack, Discord, PagerDuty, email, Telegram, and more, out of the box
- **MCP for AI assistants** — query your infrastructure from Claude, ChatGPT, or any MCP-compatible tool
- **Low resource footprint** — runs comfortably on Raspberry Pis and VPS instances alike

### Prerequisites

Netdata runs on Linux, macOS, FreeBSD, and Windows. No special hardware is required — a machine with 256 MB of free RAM is sufficient for a standalone agent.

### Install in One Command

```bash
bash <(curl -Ss https://my-netdata.io/kickstart.sh)
```

### Verify It Works

Open your browser to:

```
http://localhost:19999
```

You should see the Netdata dashboard with live charts updating every second.

> [!TIP]
> After the dashboard loads, spend two minutes watching the CPU, memory, and disk charts. This is exactly what Netdata does best: instant, zero-config visibility into what your system is doing right now.

### What to Try Next

- **Customize your setup** — see the Configuration section below
- **Monitor containers** — see Container Monitoring in the Core Usage section
- **Set up alerts** — see Alerts and Notifications in the Core Usage section
- **Centralize multiple nodes** — see Streaming (Parent-Child) in the Core Usage section
- **Connect an AI assistant** — see MCP (AI Integration) in the Core Usage section

---

## 2. Installation

### System Requirements

| Component | Minimum | Recommended |
|-----------|---------|-------------|
| Linux kernel | 4.14+ | 5.4+ |
| RAM (standalone) | 256 MB free | 1 GB+ |
| RAM (parent, 10+ children) | 1 GB free | 4 GB+ |
| Disk (dbengine) | 256 MB | 2 GB+ for longer retention |
| CPU | Any x86_64 or ARM64 | Multi-core for large collector count |
| Network | Loopback only (standalone) | Outbound for Cloud/streaming |

> [!NOTE]
> Netdata also runs on macOS (Intel and Apple Silicon), FreeBSD, and Windows. The resource requirements above apply primarily to Linux; other platforms have similar footprints.

### Installation Methods

#### One-Line Install (kickstart.sh) — Recommended

The kickstart script auto-detects your OS, installs dependencies, and configures Netdata:

```bash
bash <(curl -Ss https://my-netdata.io/kickstart.sh)
```

Expected output (abbreviated):

```
 --- Netdata Agent Installer ---
 --- Detecting system ...
 --- Installing required packages ...
 --- Downloading Netdata ...
 --- Installing Netdata ...
 --- Starting Netdata ...
 --- Netdata is running on http://localhost:19999
```

Common kickstart flags:

| Flag | Purpose |
|------|---------|
| `--dont-start-it` | Install without starting the daemon |
| `--stable-channel` | Use stable releases only (default) |
| `--nightly-channel` | Use nightly builds |
| `--no-updates` | Disable automatic updates |
| `--claim-token TOKEN` | Claim node to Netdata Cloud during install |
| `--claim-rooms ROOM_ID` | Assign node to a War Room |

```bash
# Example: install stable, claim to Cloud, assign to a room
bash <(curl -Ss https://my-netdata.io/kickstart.sh) \
  --stable-channel \
  --claim-token YOUR_CLAIM_TOKEN \
  --claim-rooms YOUR_ROOM_ID
```

#### Docker

```bash
docker run -d --name=netdata \
  --pid=host --network=host \
  -v netdataconfig:/etc/netdata \
  -v netdatalib:/var/lib/netdata \
  -v netdatacache:/var/cache/netdata \
  -v /:/host/root:ro,rslave \
  -v /etc/passwd:/host/etc/passwd:ro \
  -v /etc/group:/host/etc/group:ro \
  -v /etc/localtime:/host/etc/localtime:ro \
  -v /proc:/host/proc:ro \
  -v /sys:/host/sys:ro \
  -v /etc/os-release:/host/etc/os-release:ro \
  --restart unless-stopped \
  --cap-add SYS_PTRACE \
  --cap-add SYS_ADMIN \
  --security-opt apparmor=unconfined \
  netdata/netdata
```

> [!IMPORTANT]
> The `--pid=host` and `--network=host` flags are required for Netdata to monitor host-level processes and network interfaces from inside the container. Without them, you only see container-internal metrics.

The named volumes (`netdataconfig`, `netdatalib`, `netdatacache`) persist configuration, database, and cache across container restarts.

**Docker Compose equivalent:**

```yaml
version: '3'
services:
  netdata:
    image: netdata/netdata
    container_name: netdata
    pid: host
    network_mode: host
    restart: unless-stopped
    cap_add:
      - SYS_PTRACE
      - SYS_ADMIN
    security_opt:
      - apparmor=unconfined
    volumes:
      - netdataconfig:/etc/netdata
      - netdatalib:/var/lib/netdata
      - netdatacache:/var/cache/netdata
      - /:/host/root:ro,rslave
      - /etc/passwd:/host/etc/passwd:ro
      - /etc/group:/host/etc/group:ro
      - /etc/localtime:/host/etc/localtime:ro
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
      - /etc/os-release:/host/etc/os-release:ro

volumes:
  netdataconfig:
  netdatalib:
  netdatacache:
```

#### Native Packages (DEB/RPM)

**Debian / Ubuntu:**

```bash
# Add the Netdata repository
curl -s https://packagecloud.io/install/repositories/netdata/netdata/script.deb.sh | sudo bash

# Install
sudo apt-get install netdata
```

**RHEL / CentOS / Fedora / Amazon Linux:**

```bash
# Add the Netdata repository
curl -s https://packagecloud.io/install/repositories/netdata/netdata/script.rpm.sh | sudo bash

# Install
sudo yum install netdata
# or on newer Fedora:
sudo dnf install netdata
```

After package install, start and enable the service:

```bash
sudo systemctl start netdata
sudo systemctl enable netdata
```

#### Source Build (CMake)

For users who need custom build options or run on unsupported platforms:

```bash
# Install build dependencies (Debian/Ubuntu example)
sudo apt-get install -y git cmake build-essential pkg-config \
  libssl-dev libjson-c-dev libyaml-dev libz-dev libuv1-dev \
  libprotobuf-dev protobuf-compiler

# Clone the repository
git clone https://github.com/netdata/netdata.git --depth=1
cd netdata

# Configure and build
mkdir build && cd build
cmake ..
make -j$(nproc)

# Install
sudo make install
```

> [!NOTE]
> Source builds place configuration in `/opt/netdata/etc/netdata/` rather than the standard `/etc/netdata/`. Adjust paths in the rest of this guide accordingly.

#### Windows

Netdata provides a native Windows agent (windows.plugin) for monitoring Windows systems. Install via the kickstart script in WSL, or deploy the Windows MSI installer from the Netdata releases page. The Windows plugin collects performance counters, event logs, and system metrics natively.

#### macOS

```bash
# Using Homebrew
brew install netdata

# Start the service
brew services start netdata
```

Alternatively, the kickstart script works on macOS:

```bash
bash <(curl -Ss https://my-netdata.io/kickstart.sh)
```

The macOS plugin (`macos.plugin`) collects system metrics using macOS-native APIs (IOKit, sysctl).

### Post-Install Verification

After installation, verify Netdata is running:

```bash
# Check the service status
sudo systemctl status netdata
```

Expected output:

```
● netdata.service - Real time performance monitoring
     Loaded: loaded
     Active: active (running)
```

Then confirm the dashboard is accessible:

```bash
curl -s http://localhost:19999/api/v1/info | head -5
```

You should see JSON output with version information.

### Install Troubleshooting

| Problem | Cause | Solution |
|---------|-------|----------|
| `curl: command not found` | curl not installed | `sudo apt-get install curl` or `sudo yum install curl` |
| Permission denied on kickstart | Script needs root for package install | Run with `sudo` or use `--dont-wait` flag |
| Port 19999 already in use | Another service occupies the port | Change port in `netdata.conf` `[web]` section or stop the conflicting service |
| Dashboard shows "connection refused" | Firewall blocking port 19999 | `sudo ufw allow 19999/tcp` or equivalent for your firewall |
| Docker container exits immediately | Missing required capabilities | Ensure `SYS_PTRACE` and `SYS_ADMIN` caps are added |
| No data in Docker container | Missing host volume mounts | Verify `/proc`, `/sys`, and root filesystem are mounted read-only |
| SELinux blocking Netdata | SELinux enforcing mode | Run `sudo setsebool -P httpd_can_network_connect 1` or set appropriate contexts |
| Package conflicts on RHEL | EPEL repository conflicts | Disable conflicting repos: `--disablerepo=epel` |
| Build fails: missing protobuf | protobuf-compiler not installed | Install `protobuf-compiler` and `libprotobuf-dev` |
| Kickstart fails behind proxy | HTTP proxy not configured | Set `http_proxy` and `https_proxy` environment variables before running |
| Old kernel (< 4.14) | Missing kernel features | Upgrade kernel or use Docker with a newer host |
| ARM install fails | Wrong architecture package | Use `--architecture` flag with kickstart or build from source |

---

## 3. Configuration

Netdata uses INI-style configuration files. The primary file is `netdata.conf`, but each subsystem has its own config file (alerts in `health.d/`, streaming in `stream.conf`, collectors in `go.d.conf`, etc.).

### The edit-config Script

Always use the `edit-config` script to modify configuration — it creates a copy from the stock defaults if one does not already exist, ensuring you only override what you change:

```bash
cd /etc/netdata
sudo ./edit-config netdata.conf
```

> [!WARNING]
> Do not edit stock configuration files directly. The `edit-config` script creates user overrides that survive updates. Direct edits to stock files will be overwritten on the next Netdata upgrade.

### Configuration Directories

| Install Method | Config Directory |
|---------------|-----------------|
| Packages / kickstart | `/etc/netdata/` |
| Static build / source | `/opt/netdata/etc/netdata/` |
| Docker | `/etc/netdata/` (inside container, mapped to `netdataconfig` volume) |

### Download Your Running Configuration

Netdata serves its current running configuration through the web interface. This is the easiest way to see all active settings, including defaults:

```bash
curl -o /tmp/netdata.conf http://localhost:19999/netdata.conf
```

The downloaded file contains every setting with its current value, commented out where defaults apply.

### Key Configuration Sections

#### Database Settings — `[db]`

```ini
[db]
    # Collection frequency (seconds)
    update every = 1

    # Storage engine: dbengine (default), ram, alloc, none
    db = dbengine

    # Retention settings (dbengine tiers)
    # Tier 0: per-second, default 14 days
    # Tier 1: per-minute, default 90 days
    # Tier 2: per-hour, default 2 years
    dbengine tier 0 retention days = 14
    dbengine tier 1 retention days = 90
    dbengine tier 2 retention days = 730
```

Netdata's dbengine uses gorilla compression, achieving approximately 0.6 bytes per sample at tier 0. Three tiers are enabled by default, giving you 14 days of per-second data, 90 days of per-minute data, and 2 years of per-hour data.

> [!TIP]
> To estimate disk usage: multiply metric count by retention days by ~0.6 bytes/sample. A typical server with 2,000 metrics at 14 days of tier-0 retention uses about 1.5 GB of disk.

#### Web Dashboard — `[web]`

```ini
[web]
    # Interface to bind (use = * for all interfaces)
    bind to = *

    # Dashboard port
    default port = 19999

    # Restrict access by IP
    allow connections from = localhost *
```

#### Machine Learning — `[ml]`

```ini
[ml]
    # Enable ML anomaly detection (on by default)
    enabled = yes
```

#### Plugins — `[plugins]`

```ini
[plugins]
    # Disable a specific plugin
    # proc = no
    # apps = no
    # go.d = no
    # python.d = no
    # charts.d = no
```

### Environment Variables

Netdata recognizes several environment variables that override configuration file settings. These are especially useful in Docker and containerized deployments:

| Variable | Purpose | Default |
|----------|---------|---------|
| `NETDATA_USER_CONFIG_DIR` | Override user configuration directory | `/etc/netdata` |
| `NETDATA_STOCK_CONFIG_DIR` | Override stock configuration directory | `/usr/lib/netdata/conf.d` |
| `NETDATA_HOST_PREFIX` | Prefix for host filesystem paths (Docker) | (none) |
| `NETDATA_UPDATE_EVERY` | Override default collection interval | `1` |
| `NETDATA_CLAIM_TOKEN` | Cloud claim token | (none) |
| `NETDATA_CLAIM_ROOMS` | Cloud War Room ID(s) | (none) |
| `NETDATA_EXTRA_DEB_PACKAGES` | Additional packages to install (kickstart) | (none) |

> [!NOTE]
> The Rust-based plugins (systemd-journal, OpenTelemetry) use their own environment variables for runtime configuration. These are internal plugin variables and are documented in the Admin Guide's full configuration reference.

### Dynamic Configuration Manager

When connected to Netdata Cloud, you can manage collector and alert configurations directly from the Cloud UI without SSH access. Changes made through Dynamic Configuration are pushed to the agent and persisted locally. This is available for go.d plugin collectors and alert definitions.

For the full configuration reference — including every section, every key, and advanced tuning — see the Admin Guide.

---

## 4. Core Usage

### 4.1 The Dashboard

Netdata's built-in web dashboard is available immediately at `http://localhost:19999`. It renders real-time, interactive charts that update every second.

**Dashboard navigation:**

- **Menu sidebar** — browse metric categories (System, CPU, Memory, Disks, Network, Applications, etc.)
- **Time controls** — pan and zoom on any chart; all charts synchronize their time window
- **Chart interactions** — hover for values, click-drag to zoom, double-click to reset
- **Composite charts** — group related metrics into a single view

The dashboard is a single-page application served directly by the Netdata agent. No external dependencies, no database queries — charts render from the in-memory/on-disk dbengine.

### 4.2 System Metrics

Out of the box, Netdata monitors every system metric available through the Linux `/proc` and `/sys` filesystems via `proc.plugin`:

**CPU:**
- Per-core utilization (user, system, iowait, steal, idle)
- CPU frequency scaling
- Interrupts, context switches, softirqs

**Memory:**
- RAM usage (used, cached, buffers, free)
- Swap usage and I/O
- Huge pages, kernel memory slabs
- NUMA node statistics

**Disk:**
- Per-disk I/O (reads, writes, in progress)
- I/O latency distribution
- Disk space usage per mount point
- MDRAID, bcache, ZFS, Btrfs

**Network:**
- Per-interface bandwidth (in/out)
- Packet rates, errors, drops
- TCP/UDP connection states
- IPv4/IPv6 statistics
- Netfilter/iptables connection tracking

All of this is automatic. No configuration required. Netdata detects hardware and virtual interfaces, disk devices, and filesystems at startup and creates charts for each.

> [!TIP]
> On FreeBSD, the `freebsd.plugin` provides equivalent system metrics using FreeBSD-native sysctl and devstat APIs. On macOS, `macos.plugin` uses IOKit and sysctl.

### 4.3 Container Monitoring

Netdata automatically discovers and monitors containers through `cgroups.plugin`:

**Docker containers:**
- CPU, memory, I/O, and network per container
- Container names resolved from Docker API
- Charts appear under the "Containers" section

**Kubernetes pods:**
- Per-pod resource usage
- Kubelet metrics via the go.d collector
- kube-proxy, kube-state-metrics integration

**LXC/LXD:**
- Per-container metrics from cgroup hierarchy

For Docker, Netdata reads cgroup data from the kernel. When running Netdata inside Docker, mount the host's root filesystem, `/proc`, and `/sys` as shown in the Docker installation section above.

### 4.4 Application Monitoring

`apps.plugin` monitors every running process and groups them by application. It reads `/proc/<pid>/stat`, `/proc/<pid>/status`, and `/proc/<pid>/io` for every process at every collection cycle.

**What it tracks per application group:**
- CPU usage (user + system)
- Real memory (RSS) and proportional memory (PSS, requires Linux 4.14+)
- Swap usage
- Disk I/O (logical and physical reads/writes)
- Open file descriptors
- Process count (running, sleeping, zombie)
- Uptime of the oldest process in the group

**Custom application groups** are defined in `apps_groups.conf`:

```bash
sudo ./edit-config apps_groups.conf
```

Example entries:

```ini
# Group name: pattern(s)
webservers: nginx apache2 httpd lighttpd
databases: mysqld postgres mongod redis-server
docker: dockerd containerd
java_apps: java
python_apps: python python3

# Prefix with 'managers:' or 'interpreters:' for special handling
interpreters: python python3 ruby node
```

Pattern matching rules:
- **Exact match:** `nginx` matches processes named exactly "nginx"
- **Prefix match:** `python*` matches "python", "python3", "python3.11"
- **Suffix match:** `*server` matches "redis-server", "dhcp-server"
- **Substring match:** `*sql*` matches "mysqld", "postgresql"

> [!NOTE]
> PSS (Proportional Set Size) memory estimation requires Linux kernel 4.14 or newer. On older kernels, Netdata falls back to RSS, which over-counts shared memory. PSS divides shared pages proportionally among processes sharing them, giving a more accurate picture of actual memory usage per application.

### 4.5 Service Monitoring

The **go.d plugin** is Netdata's primary collector framework, providing 100+ collectors written in Go. Collectors auto-discover services running on standard ports and begin monitoring immediately.

**Commonly used collectors:**

| Service | Collector | Auto-detected |
|---------|-----------|---------------|
| Nginx | `nginx` | Yes (port 80/443) |
| Apache | `apache` | Yes (port 80/443) |
| MySQL/MariaDB | `mysql` | Yes (port 3306) |
| PostgreSQL | `postgres` | Yes (port 5432) |
| Redis | `redis` | Yes (port 6379) |
| MongoDB | `mongodb` | Yes (port 27017) |
| Elasticsearch | `elasticsearch` | Yes (port 9200) |
| Docker Engine | `docker_engine` | Yes (socket) |
| HAProxy | `haproxy` | Yes (stats socket) |
| RabbitMQ | `rabbitmq` | Yes (port 15672) |
| Prometheus endpoints | `prometheus` | Manual config |
| SNMP devices | `snmp` | Manual config |
| DNS servers (BIND, PowerDNS) | `bind`, `powerdns` | Yes |
| Certificates (X.509) | `x509check` | Manual config |
| HTTP endpoints | `httpcheck` | Manual config |
| TCP ports | `portcheck` | Manual config |

To configure a collector that is not auto-detected:

```bash
cd /etc/netdata
sudo ./edit-config go.d/nginx.conf
```

Example `nginx.conf` for a non-standard port:

```yaml
jobs:
  - name: my_nginx
    url: http://127.0.0.1:8080/stub_status
```

**Python.d collectors** (`python.d.plugin`) handle services not yet ported to Go. **Charts.d collectors** (`charts.d.plugin`) are Bash-based scripts for simple metric sources.

Restart Netdata after collector configuration changes:

```bash
sudo systemctl restart netdata
```

### 4.6 Alerts and Notifications

Netdata ships with hundreds of pre-configured alerts covering CPU, memory, disk, network, and common services.

**Severity levels:**

| Level | Meaning |
|-------|---------|
| CLEAR | Condition resolved, back to normal |
| WARNING | Threshold crossed, attention needed |
| CRITICAL | Severe condition, immediate action required |

**Alert configuration files** live in `health.d/` within the config directory:

```bash
cd /etc/netdata
sudo ./edit-config health.d/cpu.conf
```

Example custom alert — warn at 80% CPU, critical at 95%:

```
alarm: cpu_usage_high
    on: system.cpu
lookup: average -1m unaligned of user,system
 units: %
 every: 10s
  warn: $this > 80
  crit: $this > 95
 delay: down 5m
  info: CPU usage averaged over the last minute
    to: sysadmin
```

**Notification methods** — Netdata supports 30+ channels:

| Channel | Config File |
|---------|-------------|
| Slack | `health_alarm_notify.conf` |
| Discord | `health_alarm_notify.conf` |
| PagerDuty | `health_alarm_notify.conf` |
| Email | `health_alarm_notify.conf` |
| Telegram | `health_alarm_notify.conf` |
| Microsoft Teams | `health_alarm_notify.conf` |
| Opsgenie | `health_alarm_notify.conf` |
| Pushover | `health_alarm_notify.conf` |
| Twilio (SMS) | `health_alarm_notify.conf` |
| Amazon SNS | `health_alarm_notify.conf` |
| Gotify | `health_alarm_notify.conf` |
| Matrix | `health_alarm_notify.conf` |
| Rocket.Chat | `health_alarm_notify.conf` |
| IRC | `health_alarm_notify.conf` |
| Flock | `health_alarm_notify.conf` |
| Custom webhook | `health_alarm_notify.conf` |

Configure notifications:

```bash
cd /etc/netdata
sudo ./edit-config health_alarm_notify.conf
```

Example — Slack notifications:

```bash
SEND_SLACK="YES"
SLACK_WEBHOOK_URL="https://hooks.slack.com/services/XXXXXXXXX/XXXXXXXXX/XXXXXXXXXXXXXXXXXXXXXXXX"
DEFAULT_RECIPIENT_SLACK="#alerts"
```

Test your notification configuration:

```bash
sudo -u netdata /usr/libexec/netdata/plugins.d/alarm-notify.sh test
```

> [!IMPORTANT]
> Netdata supports two notification paths: **Agent notifications** (configured locally in `health_alarm_notify.conf`) and **Cloud notifications** (configured in Netdata Cloud UI, requires a claimed node). Cloud notifications provide centralized management across all nodes and support additional integrations. Both can run simultaneously.

### 4.7 Machine Learning

Netdata trains a machine learning model on every single metric it collects. This is not a separate product — it runs inside the agent with minimal overhead.

**How it works:**

1. Each metric trains its own model based on recent behavior patterns
2. Every sample is scored for anomaly probability (0-100%)
3. Anomaly rates are computed per metric, per node, and globally
4. The anomaly rate itself becomes a metric you can alert on

**Viewing anomaly information:**

- In the dashboard, anomaly rates appear as an overlay on each chart
- The "Anomaly Advisor" in Netdata Cloud highlights the most anomalous metrics across all nodes
- The global anomaly rate chart shows overall system health

**Configuration:**

```bash
cd /etc/netdata
sudo ./edit-config netdata.conf
```

```ini
[ml]
    enabled = yes
    # Training window (seconds of data to train on)
    maximum num samples to train = 21600
    # Minimum training samples before predictions begin
    minimum num samples to train = 900
    # Number of models to keep per metric
    number of models per dimension = 18
```

> [!TIP]
> ML runs with negligible overhead on modern hardware. Disable it only if you are running on an extremely constrained device (Raspberry Pi Zero, for example) with `enabled = no` in the `[ml]` section.

### 4.8 MCP (AI Integration)

Netdata provides Model Context Protocol (MCP) endpoints that let AI assistants query your infrastructure metrics, alerts, and anomalies directly.

**Two MCP endpoints:**

| Endpoint | URL | Requirements |
|----------|-----|-------------|
| Cloud MCP | `https://app.netdata.cloud/api/v1/mcp` | Business plan, scope:mcp API token |
| Agent MCP | `http://<IP>:19999/mcp` | Netdata v2.6.0+ |

**Supported transports:**

| Transport | Available Since |
|-----------|----------------|
| WebSocket | v2.6.0 |
| HTTP Streamable | v2.7.2 |
| SSE (Server-Sent Events) | v2.7.2 |

**Claude Code one-liner setup (Agent MCP):**

```bash
claude mcp add netdata-agent -- curl http://localhost:19999/mcp
```

**Agent MCP API key** is auto-generated at:

```
/var/lib/netdata/mcp_dev_preview_api_key
```

Read it with:

```bash
sudo cat /var/lib/netdata/mcp_dev_preview_api_key
```

**nd-mcp bridge:** For advanced setups, the `nd-mcp` bridge (available in Go, Node.js, and Python implementations) provides a standalone MCP server that proxies requests to Netdata agents or Cloud.

> [!NOTE]
> The Agent MCP endpoint runs directly on the Netdata daemon, so it has access to all local metrics without network overhead. The Cloud MCP endpoint aggregates data from all claimed nodes, making it ideal for fleet-wide queries from a single AI assistant connection.

### 4.9 Streaming (Parent-Child)

Streaming lets you centralize metrics from many nodes (children) to one or more central nodes (parents). Children collect metrics and stream them in real time; parents store, visualize, and alert on the combined data.

**Why streaming?**

- Centralize dashboards and alerts for your fleet
- Reduce disk usage on children (thin mode stores nothing locally)
- Build hierarchies: children -> regional parents -> global parent
- High availability: cluster mode with multiple parents

**Setup overview:**

On the **parent** node, edit `stream.conf`:

```bash
cd /etc/netdata
sudo ./edit-config stream.conf
```

```ini
[API_KEY_HERE]
    enabled = yes
    allow from = *
    default memory mode = dbengine
```

Replace `API_KEY_HERE` with a UUID. Generate one with `uuidgen`.

On each **child** node, edit `stream.conf`:

```bash
cd /etc/netdata
sudo ./edit-config stream.conf
```

```ini
[stream]
    enabled = yes
    destination = PARENT_IP:19999
    api key = API_KEY_HERE
```

**Child modes:**

| Mode | Behavior |
|------|----------|
| Full (default) | Child stores data locally AND streams to parent |
| Thin | Child streams only, no local storage — minimal resource usage |

To enable thin mode on a child, set `db = none` in `netdata.conf`:

```ini
[db]
    db = none
```

Restart both parent and child after configuration:

```bash
sudo systemctl restart netdata
```

> [!WARNING]
> In thin mode, the child stores no data locally. If the parent is unreachable, metrics are lost until the connection is restored. Use full mode if you need local fallback storage on children.

### 4.10 Exporting

Netdata can export metrics to external time-series databases for long-term retention or integration with existing monitoring stacks.

**Supported backends:**

| Backend | Protocol |
|---------|----------|
| Prometheus | Remote write / scrape endpoint |
| Graphite | Line protocol |
| OpenTSDB | HTTP / Telnet |
| MongoDB | Native |
| AWS Kinesis | Kinesis Data Streams |
| JSON | HTTP POST |

**Prometheus scrape endpoint** — Netdata exposes Prometheus-compatible metrics at:

```
http://localhost:19999/api/v1/allmetrics?format=prometheus
```

Add to your `prometheus.yml`:

```yaml
scrape_configs:
  - job_name: 'netdata'
    metrics_path: '/api/v1/allmetrics'
    params:
      format: ['prometheus']
    static_configs:
      - targets: ['localhost:19999']
```

**Graphite export** — configure in `exporting.conf`:

```bash
cd /etc/netdata
sudo ./edit-config exporting.conf
```

```ini
[graphite:my_graphite]
    enabled = yes
    destination = graphite.example.com:2003
    prefix = netdata
    update every = 10
```

### 4.11 Netdata Cloud

Netdata Cloud is a free SaaS layer that provides centralized visibility across all your Netdata agents without requiring you to open any inbound ports.

**Key Cloud features:**

- Centralized dashboards across all nodes
- Composite charts (aggregate metrics from multiple nodes)
- Anomaly Advisor (ML insights across your fleet)
- Centralized alert management and notifications
- Dynamic Configuration Manager
- Role-Based Access Control (RBAC)
- War Rooms for organizing nodes by environment or team

**Authentication methods:**

| Method | Availability |
|--------|-------------|
| Email + password | All plans |
| Google OAuth | All plans |
| GitHub OAuth | All plans |
| Enterprise SSO (SAML/OIDC) | Business plan |

**Claiming a node to Cloud:**

1. Sign in at `https://app.netdata.cloud`
2. Create or select a Space
3. Click "Connect Nodes" and copy the claim command
4. Run the command on your node:

```bash
sudo netdata-claim.sh -token=YOUR_TOKEN -rooms=YOUR_ROOM_ID -url=https://app.netdata.cloud
```

Or claim during installation:

```bash
bash <(curl -Ss https://my-netdata.io/kickstart.sh) \
  --claim-token YOUR_TOKEN \
  --claim-rooms YOUR_ROOM_ID
```

**RBAC roles:**

| Role | Permissions |
|------|-------------|
| Admin | Full access, manage members, billing |
| Manager | Manage nodes, War Rooms, alerts |
| Troubleshooter | View metrics, alerts, dashboards |
| Observer | View-only access |
| Billing | Manage billing only |

> [!TIP]
> Netdata Cloud acts as a signaling layer — your metric data stays on your infrastructure. The Cloud proxies dashboard requests through the agents in real time. No metric data is stored on Cloud servers for plans below Business tier.

---

## 5. Common Tasks

### 5.1 Monitor a New Nginx Instance

**Goal:** Get Nginx metrics in Netdata.

**Prerequisites:** Nginx with `stub_status` module enabled.

**Steps:**

1. Enable the Nginx status endpoint in your Nginx config:

```nginx
server {
    listen 127.0.0.1:80;
    location /stub_status {
        stub_status;
        allow 127.0.0.1;
        deny all;
    }
}
```

2. Reload Nginx:

```bash
sudo nginx -s reload
```

3. Verify the status endpoint:

```bash
curl http://127.0.0.1/stub_status
```

Expected output:

```
Active connections: 2
server accepts handled requests
 15 15 45
Reading: 0 Writing: 1 Waiting: 1
```

4. Netdata's go.d nginx collector auto-detects this. If not, configure manually:

```bash
cd /etc/netdata
sudo ./edit-config go.d/nginx.conf
```

```yaml
jobs:
  - name: local
    url: http://127.0.0.1/stub_status
```

5. Restart Netdata:

```bash
sudo systemctl restart netdata
```

**Verify:** Look for "Nginx" charts in the dashboard sidebar.

**If it fails:** Check `error.log` in `/var/log/netdata/` for collector errors. Ensure the `stub_status` endpoint is reachable from the Netdata user.

### 5.2 Set Up Alerts for Disk Space

**Goal:** Get warned before disks fill up.

**Prerequisites:** Netdata running with disk monitoring active (default).

**Steps:**

Netdata ships with disk space alerts by default. To customize thresholds:

```bash
cd /etc/netdata
sudo ./edit-config health.d/disks.conf
```

Find the `disk_space_usage` alarm and adjust:

```
alarm: disk_space_usage
    on: disk.space
lookup: max -1s unaligned of used
 units: %
 every: 10s
  warn: $this > 85
  crit: $this > 95
 delay: down 15m
  info: Disk space usage
    to: sysadmin
```

**Verify:** Check active alerts at `http://localhost:19999/api/v1/alarms` or in the dashboard's alerts tab.

### 5.3 Stream Metrics from Child to Parent

**Goal:** Centralize metrics from a child node to a parent.

**Prerequisites:** Two Netdata instances, network connectivity on port 19999.

**Steps:**

1. Generate a shared API key:

```bash
uuidgen
```

Example output: `11111111-2222-3333-4444-555555555555`

2. On the **parent**, edit `stream.conf`:

```bash
cd /etc/netdata
sudo ./edit-config stream.conf
```

```ini
[11111111-2222-3333-4444-555555555555]
    enabled = yes
    allow from = *
    default memory mode = dbengine
```

3. On the **child**, edit `stream.conf`:

```ini
[stream]
    enabled = yes
    destination = 192.168.1.100:19999
    api key = 11111111-2222-3333-4444-555555555555
```

4. Restart both:

```bash
sudo systemctl restart netdata
```

**Verify:** On the parent dashboard, the child node appears in the node selector.

**If it fails:** Check `error.log` on the child for connection errors. Verify firewall allows TCP 19999 between the nodes.

### 5.4 Configure Slack Notifications

**Goal:** Receive Netdata alerts in a Slack channel.

**Steps:**

1. Create an Incoming Webhook in your Slack workspace (Apps -> Incoming Webhooks -> Add to Slack)

2. Configure Netdata:

```bash
cd /etc/netdata
sudo ./edit-config health_alarm_notify.conf
```

Set these values:

```bash
SEND_SLACK="YES"
SLACK_WEBHOOK_URL="https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
DEFAULT_RECIPIENT_SLACK="#monitoring-alerts"
```

3. Test:

```bash
sudo -u netdata /usr/libexec/netdata/plugins.d/alarm-notify.sh test
```

**Verify:** You should see a test message in your Slack channel.

### 5.5 Run Netdata in Docker with Persistent Config

**Goal:** Deploy Netdata in Docker without losing config or data on container recreation.

**Steps:**

```bash
docker run -d --name=netdata \
  --pid=host --network=host \
  -v netdataconfig:/etc/netdata \
  -v netdatalib:/var/lib/netdata \
  -v netdatacache:/var/cache/netdata \
  -v /:/host/root:ro,rslave \
  -v /etc/passwd:/host/etc/passwd:ro \
  -v /etc/group:/host/etc/group:ro \
  -v /etc/localtime:/host/etc/localtime:ro \
  -v /proc:/host/proc:ro \
  -v /sys:/host/sys:ro \
  -v /etc/os-release:/host/etc/os-release:ro \
  --restart unless-stopped \
  --cap-add SYS_PTRACE \
  --cap-add SYS_ADMIN \
  --security-opt apparmor=unconfined \
  netdata/netdata
```

Edit configuration inside the container:

```bash
docker exec -it netdata bash
cd /etc/netdata
./edit-config netdata.conf
```

**Verify:** Stop and recreate the container — your settings and data persist in the named volumes.

### 5.6 Monitor Kubernetes Pods

**Goal:** Monitor pod resource usage in a Kubernetes cluster.

**Steps:**

1. Deploy Netdata as a DaemonSet (every node) plus a parent Deployment:

```bash
helm repo add netdata https://netdata.github.io/helmchart/
helm repo update
helm install netdata netdata/netdata
```

2. Access the parent's dashboard via port-forward:

```bash
kubectl port-forward svc/netdata 19999:19999
```

3. Open `http://localhost:19999` — each node's pods and containers appear automatically.

The `cgroups.plugin` on each node detects Kubernetes pods and creates per-pod charts for CPU, memory, I/O, and network.

### 5.7 Enable or Disable Specific Collectors

**Goal:** Turn off collectors you do not need, or enable ones that are disabled.

**Steps:**

To disable a plugin entirely:

```bash
cd /etc/netdata
sudo ./edit-config netdata.conf
```

```ini
[plugins]
    python.d = no
    charts.d = no
```

To disable a specific go.d collector:

```bash
sudo ./edit-config go.d.conf
```

```yaml
modules:
  nginx: no
  mysql: no
```

To enable a collector that requires configuration (e.g., SNMP):

```bash
sudo ./edit-config go.d/snmp.conf
```

```yaml
jobs:
  - name: switch01
    hostname: 192.168.1.1
    community: public
    version: 2
```

Restart Netdata after changes:

```bash
sudo systemctl restart netdata
```

### 5.8 Create Custom Alerts

**Goal:** Alert when a custom condition is met.

**Steps:**

Create a new alert file:

```bash
cd /etc/netdata
sudo ./edit-config health.d/custom.conf
```

Example — alert if HTTP response time exceeds 2 seconds:

```
alarm: web_response_slow
    on: httpcheck_mysite.response_time
lookup: average -5m unaligned
 units: ms
 every: 30s
  warn: $this > 1000
  crit: $this > 2000
 delay: down 5m
  info: HTTP response time to mysite exceeded threshold
    to: sysadmin
```

**Verify:**

```bash
# Reload alert configuration without restart
sudo netdatacli reload-health
```

Check `http://localhost:19999/api/v1/alarms` for your new alert.

### 5.9 Set Up a Reverse Proxy

**Goal:** Access Netdata behind nginx, Apache, or another reverse proxy.

Netdata supports nginx, Apache, HAProxy, Lighttpd, Caddy, and H2O as reverse proxies.

**Nginx example:**

```nginx
upstream netdata {
    server 127.0.0.1:19999;
    keepalive 64;
}

server {
    listen 443 ssl;
    server_name monitor.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Server $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_pass http://netdata;
        proxy_http_version 1.1;
        proxy_pass_request_headers on;
        proxy_set_header Connection "keep-alive";
        proxy_store off;
    }
}
```

**Caddy example (automatic HTTPS):**

```
monitor.example.com {
    reverse_proxy 127.0.0.1:19999
}
```

### 5.10 Configure Bearer Token Protection

**Goal:** Protect the Netdata API with a bearer token (alternative to reverse proxy authentication).

**Steps:**

```bash
cd /etc/netdata
sudo ./edit-config netdata.conf
```

```ini
[web]
    bearer token = YOUR_SECRET_TOKEN
```

Access the API with the token:

```bash
curl -H "Authorization: Bearer YOUR_SECRET_TOKEN" http://localhost:19999/api/v1/info
```

> [!CAUTION]
> Known issue (#22166): When bearer token protection is enabled, some API endpoints may not accept the token correctly in all request paths. If you encounter authentication failures on specific API calls, use a reverse proxy with HTTP Basic Auth as an alternative until this is resolved.

### 5.11 Connect an AI Assistant via MCP

**Goal:** Let Claude or another AI assistant query your Netdata metrics.

**Agent MCP (local, v2.6.0+):**

1. Read the auto-generated API key:

```bash
sudo cat /var/lib/netdata/mcp_dev_preview_api_key
```

2. Add to Claude Code:

```bash
claude mcp add netdata-agent -- curl http://localhost:19999/mcp
```

**Cloud MCP (all nodes, Business plan):**

1. Generate an API token with `scope:mcp` in Netdata Cloud settings
2. Configure your AI assistant to use `https://app.netdata.cloud/api/v1/mcp` with the token

### 5.12 Set Up Log Centralization with systemd-journal

**Goal:** Monitor and query systemd journal logs through Netdata.

Netdata's Rust-based `systemd-journal` plugin reads journal files and makes them searchable through the dashboard. It is enabled by default on systemd-based systems.

**View logs:** Navigate to the "systemd journal" section in the dashboard, or use the Netdata Cloud Logs Explorer.

**Centralize logs from remote hosts:** Configure `systemd-journal-remote` on the parent and `systemd-journal-upload` on children to forward journal entries.

### 5.13 Reduce Netdata Resource Usage

**Goal:** Run Netdata on a resource-constrained system.

**Options (from least to most aggressive):**

1. **Reduce collection frequency:**

```ini
[db]
    update every = 2
```

2. **Reduce retention:**

```ini
[db]
    dbengine tier 0 retention days = 3
    dbengine tier 1 retention days = 14
    dbengine tier 2 retention days = 90
```

3. **Disable ML:**

```ini
[ml]
    enabled = no
```

4. **Disable unused plugins:**

```ini
[plugins]
    apps = no
    python.d = no
    charts.d = no
```

5. **Use thin streaming mode** — stream all metrics to a parent and store nothing locally:

```ini
[db]
    db = none
```

6. **Reduce the number of dbengine tiers:**

```ini
[db]
    dbengine tier 0 retention days = 7
    dbengine number of tiers = 1
```

### 5.14 Back Up and Restore Configuration

**Goal:** Preserve your Netdata configuration across reinstalls.

**Back up:**

```bash
sudo tar czf netdata-config-backup.tar.gz /etc/netdata/
```

**Restore:**

```bash
sudo tar xzf netdata-config-backup.tar.gz -C /
sudo systemctl restart netdata
```

For Docker, the named volumes already persist. Back up the volume:

```bash
docker run --rm -v netdataconfig:/data -v $(pwd):/backup alpine \
  tar czf /backup/netdata-config.tar.gz /data
```

### 5.15 Update Netdata

**Goal:** Upgrade to the latest version.

**kickstart installs:**

```bash
bash <(curl -Ss https://my-netdata.io/kickstart.sh)
```

The kickstart script detects the existing installation and upgrades in place.

**Package manager installs:**

```bash
# Debian/Ubuntu
sudo apt-get update && sudo apt-get upgrade netdata

# RHEL/CentOS
sudo yum update netdata
```

**Docker:**

```bash
docker pull netdata/netdata
docker stop netdata && docker rm netdata
# Re-run the docker run command (volumes persist)
```

**Automatic updates:** If installed with kickstart (default), Netdata updates automatically via a daily cron job or systemd timer. Disable with:

```bash
bash <(curl -Ss https://my-netdata.io/kickstart.sh) --no-updates
```

### 5.16 Uninstall Netdata

**Goal:** Completely remove Netdata.

**kickstart installs:**

```bash
sudo /usr/libexec/netdata/netdata-uninstaller.sh --yes --env /etc/netdata/.environment
```

**Package manager:**

```bash
# Debian/Ubuntu
sudo apt-get remove --purge netdata

# RHEL/CentOS
sudo yum remove netdata
```

**Docker:**

```bash
docker stop netdata && docker rm netdata
docker volume rm netdataconfig netdatalib netdatacache
```

### 5.17 Monitor a MySQL/MariaDB Instance

**Goal:** Get MySQL/MariaDB metrics in Netdata.

**Steps:**

1. Create a monitoring user in MySQL:

```sql
CREATE USER 'netdata'@'localhost';
GRANT USAGE, REPLICATION CLIENT, PROCESS ON *.* TO 'netdata'@'localhost';
FLUSH PRIVILEGES;
```

2. Configure the collector:

```bash
cd /etc/netdata
sudo ./edit-config go.d/mysql.conf
```

```yaml
jobs:
  - name: local
    dsn: netdata@tcp(127.0.0.1:3306)/
```

3. Restart Netdata.

**Verify:** Look for "MySQL" charts in the dashboard (queries/s, connections, buffer pool, replication lag, etc.).

### 5.18 Monitor a PostgreSQL Instance

**Goal:** Get PostgreSQL metrics in Netdata.

**Steps:**

1. Create a monitoring user:

```sql
CREATE USER netdata;
GRANT pg_monitor TO netdata;
```

2. Configure:

```bash
cd /etc/netdata
sudo ./edit-config go.d/postgres.conf
```

```yaml
jobs:
  - name: local
    dsn: postgresql://netdata@127.0.0.1:5432/postgres
```

3. Restart Netdata.

### 5.19 Monitor Redis

**Goal:** Get Redis performance metrics.

Redis is auto-detected on the default port 6379. If Redis uses a non-standard port or requires authentication:

```bash
cd /etc/netdata
sudo ./edit-config go.d/redis.conf
```

```yaml
jobs:
  - name: local
    address: redis://:password@127.0.0.1:6380
```

### 5.20 Set Up Telegram Notifications

**Goal:** Receive alerts via Telegram.

**Steps:**

1. Create a Telegram bot via @BotFather, note the bot token
2. Get your chat ID (send a message to the bot, then query `https://api.telegram.org/bot<TOKEN>/getUpdates`)
3. Configure:

```bash
cd /etc/netdata
sudo ./edit-config health_alarm_notify.conf
```

```bash
SEND_TELEGRAM="YES"
TELEGRAM_BOT_TOKEN="123456789:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
DEFAULT_RECIPIENT_TELEGRAM="YOUR_CHAT_ID"
```

4. Test:

```bash
sudo -u netdata /usr/libexec/netdata/plugins.d/alarm-notify.sh test
```

### 5.21 Set Up PagerDuty Integration

**Goal:** Route critical alerts to PagerDuty for on-call escalation.

```bash
cd /etc/netdata
sudo ./edit-config health_alarm_notify.conf
```

```bash
SEND_PD="YES"
DEFAULT_RECIPIENT_PD="YOUR_PAGERDUTY_SERVICE_KEY"
```

### 5.22 Set Up Discord Notifications

**Goal:** Send alerts to a Discord channel.

```bash
cd /etc/netdata
sudo ./edit-config health_alarm_notify.conf
```

```bash
SEND_DISCORD="YES"
DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/XXXXX/XXXXX"
DEFAULT_RECIPIENT_DISCORD="monitoring"
```

### 5.23 Set Up Email Notifications

**Goal:** Receive alert emails.

```bash
cd /etc/netdata
sudo ./edit-config health_alarm_notify.conf
```

```bash
SEND_EMAIL="YES"
DEFAULT_RECIPIENT_EMAIL="[email removed]"
EMAIL_SENDER="[email removed]"
```

Requires a working MTA (sendmail, postfix, etc.) on the system.

### 5.24 Monitor SSL Certificate Expiry

**Goal:** Get alerted before certificates expire.

```bash
cd /etc/netdata
sudo ./edit-config go.d/x509check.conf
```

```yaml
jobs:
  - name: example.com
    source: https://example.com:443
  - name: internal_ca
    source: file:///etc/ssl/certs/internal-ca.pem
```

Netdata creates charts showing days until expiry and triggers alerts at 30 and 14 days by default.

### 5.25 Monitor HTTP Endpoint Availability

**Goal:** Check that a web service is up and responding.

```bash
cd /etc/netdata
sudo ./edit-config go.d/httpcheck.conf
```

```yaml
jobs:
  - name: my_api
    url: https://api.example.com/health
    response_match: '"status":"ok"'
    timeout: 5
```

Netdata tracks response time, HTTP status codes, and content match results.

---

## 6. Troubleshooting

### Dashboard Not Loading on Port 19999

**Cause:** Netdata is not running, bound to a different interface, or blocked by a firewall.

**Solution:**

```bash
# Check if Netdata is running
sudo systemctl status netdata

# Check what port it's listening on
sudo ss -tlnp | grep netdata

# Check firewall
sudo ufw status
sudo iptables -L -n | grep 19999
```

If Netdata is bound to `localhost` only, change `[web] bind to = *` in `netdata.conf` to listen on all interfaces.

**Prevention:** Verify `bind to` and `default port` settings after installation.

### High CPU Usage from apps.plugin

**Cause:** `apps.plugin` reads `/proc/<pid>/stat` for every process on every collection cycle. On systems with thousands of processes, this can consume significant CPU.

**Solution:**

1. Reduce collection frequency for apps.plugin:

```bash
cd /etc/netdata
sudo ./edit-config netdata.conf
```

```ini
[plugin:apps]
    update every = 5
```

2. Or disable apps.plugin entirely if process monitoring is not needed:

```ini
[plugins]
    apps = no
```

**Prevention:** On high-process-count systems (1000+ processes), set `update every` for apps.plugin to 2-5 seconds.

### Streaming Not Connecting (Child to Parent)

**Cause:** Firewall, wrong API key, or incorrect `stream.conf` configuration.

**Solution:**

1. Check child logs:

```bash
sudo tail -100 /var/log/netdata/error.log | grep -i stream
```

2. Verify network connectivity:

```bash
# From child
nc -zv PARENT_IP 19999
```

3. Verify API keys match exactly in both parent and child `stream.conf`

4. On the parent, ensure the API key section has `enabled = yes`

**Prevention:** Use `uuidgen` to create API keys (avoids typos). Test connectivity before configuring streaming.

### Collector Not Showing Data

**Cause:** Service not auto-detected, wrong endpoint URL, or permissions issue.

**Solution:**

1. Check if the collector is loaded:

```bash
curl -s http://localhost:19999/api/v1/info | python3 -m json.tool | grep -A5 "collectors"
```

2. Check collector logs:

```bash
sudo tail -50 /var/log/netdata/collector.log
```

3. Verify the service endpoint is accessible from the Netdata user:

```bash
sudo -u netdata curl http://127.0.0.1/stub_status
```

4. Check collector configuration:

```bash
cd /etc/netdata
sudo ./edit-config go.d/<collector>.conf
```

**Prevention:** After configuring a new collector, always restart Netdata and check logs.

### Alert Not Triggering

**Cause:** Alert syntax error, wrong chart name, or `delay` settings suppressing the alert.

**Solution:**

1. Reload health configuration:

```bash
sudo netdatacli reload-health
```

2. Check for syntax errors in logs:

```bash
sudo grep -i "health" /var/log/netdata/error.log | tail -20
```

3. Verify the chart name in your alert matches an actual chart:

```bash
curl -s http://localhost:19999/api/v1/charts | python3 -m json.tool | grep "id"
```

4. Check active alarms:

```bash
curl -s http://localhost:19999/api/v1/alarms | python3 -m json.tool
```

### Permission Denied Errors

**Cause:** Netdata runs as the `netdata` user by default and may lack permissions to access certain files, sockets, or proc entries.

**Solution:**

- **Docker socket:** Add netdata user to the docker group:

```bash
sudo usermod -aG docker netdata
sudo systemctl restart netdata
```

- **Systemd journal:** Add netdata to `systemd-journal` group:

```bash
sudo usermod -aG systemd-journal netdata
sudo systemctl restart netdata
```

- **Specific files:** Check ownership and permissions, or add Netdata to the appropriate group.

### Docker Container Exits Immediately

**Cause:** Missing required capabilities or incorrect volume mounts.

**Solution:**

Ensure your `docker run` command includes:

```bash
--cap-add SYS_PTRACE \
--cap-add SYS_ADMIN \
--security-opt apparmor=unconfined
```

Check container logs:

```bash
docker logs netdata
```

### Docker Container Shows No Host Metrics

**Cause:** Host filesystem, `/proc`, and `/sys` are not mounted into the container.

**Solution:**

Verify all required volume mounts are present:

```bash
docker inspect netdata --format '{{range .Mounts}}{{.Source}} -> {{.Destination}}{{"\n"}}{{end}}'
```

Required mounts: `/proc:/host/proc:ro`, `/sys:/host/sys:ro`, `/:/host/root:ro,rslave`

### Error: Cannot Use API When Bearer Token Protection Is Enabled

**Cause:** Known issue (#22166). Some API endpoints do not correctly validate the bearer token in all request paths.

**Solution:**

As a workaround, use a reverse proxy with HTTP Basic Auth instead of bearer token protection. Alternatively, disable bearer token and restrict access by IP:

```ini
[web]
    allow connections from = localhost 192.168.1.0/24
```

### Go Plugins Emit Logs to stderr Instead of Journal

**Cause:** Known issue (#22153). When running under a terminal (not as a service), go.d plugins write log output to stderr instead of the systemd journal.

**Solution:**

This is cosmetic when running as a service (logs go to the journal correctly). If running interactively for debugging, redirect stderr:

```bash
sudo netdata -D 2>/var/log/netdata/stderr.log
```

### Netdata Uses Too Much Memory

**Cause:** Large number of metrics, long retention, or many children streaming to a parent.

**Solution:**

1. Reduce retention:

```ini
[db]
    dbengine tier 0 retention days = 7
```

2. Reduce tiers:

```ini
[db]
    dbengine number of tiers = 1
```

3. Disable unused collectors to reduce metric count

4. Use thin streaming mode on children

### Netdata Uses Too Much Disk

**Cause:** Long retention periods with high metric count.

**Solution:**

Calculate current usage:

```bash
du -sh /var/cache/netdata/dbengine/
```

Reduce retention or tiers as shown above. At ~0.6 bytes/sample (tier 0, gorilla compression), 2,000 metrics at 14 days of per-second data uses approximately 1.5 GB.

### Dashboard Shows "No Data" After Restart

**Cause:** Database files may be corrupted, or the dbengine data directory changed.

**Solution:**

1. Check that the data directory matches what Netdata expects:

```bash
grep "cache directory" /etc/netdata/netdata.conf
ls -la /var/cache/netdata/dbengine/
```

2. If data files are corrupted, remove them (you lose historical data):

```bash
sudo systemctl stop netdata
sudo rm -rf /var/cache/netdata/dbengine/*
sudo systemctl start netdata
```

### Cloud Claim Fails

**Cause:** Network issues, expired token, or Netdata version too old.

**Solution:**

1. Check the claim log:

```bash
sudo cat /var/log/netdata/aclk.log
```

2. Verify outbound HTTPS (port 443) is allowed

3. Re-generate the claim token in Netdata Cloud and try again

4. Ensure you are running a version that supports Cloud claiming

### Automatic Updates Not Working

**Cause:** The updater cron job was removed or the `--no-updates` flag was used during install.

**Solution:**

Re-enable updates:

```bash
bash <(curl -Ss https://my-netdata.io/kickstart.sh)
```

Or check if the updater exists:

```bash
ls /etc/cron.daily/netdata-updater
# or
systemctl status netdata-updater.timer
```

### Netdata Starts But Web Interface Returns 403

**Cause:** `allow connections from` setting in `[web]` section is restricting access.

**Solution:**

```bash
cd /etc/netdata
sudo ./edit-config netdata.conf
```

```ini
[web]
    allow connections from = localhost *
```

> [!WARNING]
> Setting `allow connections from = *` permits access from any IP. In production, either restrict to specific subnets or place Netdata behind a reverse proxy with authentication.

### Collector Timeout Errors in Logs

**Cause:** The monitored service is slow to respond, or the timeout is too low.

**Solution:**

Increase the timeout in the collector config:

```yaml
jobs:
  - name: slow_service
    url: http://127.0.0.1:8080/metrics
    timeout: 10
```

### eBPF Plugin Not Loading

**Cause:** Kernel headers not installed, or kernel too old for eBPF (requires 4.11+).

**Solution:**

```bash
# Install kernel headers
sudo apt-get install linux-headers-$(uname -r)

# Verify eBPF support
ls /sys/kernel/debug/tracing/
```

### Exporting Not Sending Data

**Cause:** `exporting.conf` misconfigured or destination unreachable.

**Solution:**

1. Check exporting logs:

```bash
sudo grep -i "exporting" /var/log/netdata/error.log | tail -20
```

2. Test connectivity to the destination:

```bash
nc -zv graphite.example.com 2003
```

3. Verify `exporting.conf` syntax:

```bash
cd /etc/netdata
sudo ./edit-config exporting.conf
```

### ACLK (Cloud) Connection Drops Intermittently

**Cause:** Network instability, proxy interference, or firewall closing idle connections.

**Solution:**

The ACLK connection uses MQTT over WebSocket. Ensure your network allows persistent WebSocket connections to `*.netdata.cloud` on port 443. Check for proxy timeouts on idle connections and increase them if possible.

---

## 7. FAQ

**Q: How much RAM does Netdata use?**

A standalone agent with default settings typically uses 100-300 MB of RAM, depending on the number of metrics collected. The dbengine memory footprint scales with metric count and cache size, not retention length (historical data lives on disk).

**Q: How much disk space does Netdata use?**

With gorilla compression, tier 0 uses approximately 0.6 bytes per sample. A server with 2,000 metrics, per-second collection, and the default 14 days of tier-0 retention uses about 1.5 GB. Tiers 1 and 2 aggregate data and use far less space.

**Q: Does Netdata affect system performance?**

Netdata is designed for production systems. CPU usage is typically 1-5% of a single core. The biggest contributor to overhead is `apps.plugin` (reading /proc for every process). Disable it on systems where process monitoring is not needed.

**Q: What is the difference between Netdata Agent and Netdata Cloud?**

The Agent runs on your servers and collects/stores all metrics locally. Netdata Cloud is an optional SaaS layer that provides centralized dashboards, composite charts, ML insights across nodes, and team collaboration features. Your metric data stays on your infrastructure — Cloud acts as a real-time proxy.

**Q: Is Netdata Cloud required?**

No. The Netdata Agent is fully functional standalone. Cloud adds centralized visibility, team features, and some advanced capabilities (Anomaly Advisor, Functions, Dynamic Configuration). It has a free tier.

**Q: What is the maximum number of nodes a single parent can handle?**

This depends on hardware and metric volume. A parent with 4 GB RAM and modern CPU can handle 50-100 children comfortably. Larger deployments use hierarchical streaming (children to regional parents to global parent).

**Q: Can I use Netdata alongside Prometheus/Grafana?**

Yes. Netdata exposes a Prometheus-compatible endpoint at `/api/v1/allmetrics?format=prometheus`. Prometheus can scrape this directly. You can also use Netdata's exporting engine to push metrics to Prometheus remote-write endpoints.

**Q: How do I change the data retention period?**

Edit `netdata.conf`:

```ini
[db]
    dbengine tier 0 retention days = 30
    dbengine tier 1 retention days = 180
    dbengine tier 2 retention days = 1095
```

Restart Netdata. Longer retention uses more disk but not more RAM.

**Q: Can I run multiple Netdata instances on the same host?**

Yes, but each instance needs its own configuration directory, data directory, and web port. This is an advanced setup typically used for testing.

**Q: Does Netdata support Windows?**

Yes. Netdata has a native `windows.plugin` that collects Windows performance counters, event logs, and system metrics. Install via the MSI package or run the Agent in WSL2.

**Q: Does Netdata support macOS?**

Yes. Install via Homebrew (`brew install netdata`) or the kickstart script. The `macos.plugin` uses macOS-native APIs for system metrics.

**Q: How do I silence a specific alert temporarily?**

Use the `netdatacli` utility or the Cloud UI to silence alerts. From the command line:

```bash
# Silence all alerts for a chart
sudo netdatacli silence <chart_id>
```

In Netdata Cloud, use the alert silencing rules feature to mute alerts by node, chart, or alert name.

**Q: Is Netdata open source?**

Yes. Netdata Agent is licensed under GPLv3+. The core engine, all collectors, and the web dashboard are open source. Netdata Cloud has a free tier and paid plans; the Cloud code is not open source.

**Q: What programming languages is Netdata written in?**

The core daemon is written in C for maximum performance. Collectors are written in Go (go.d plugin, 100+ collectors), Rust (systemd-journal, OpenTelemetry), Python (python.d), and Bash (charts.d). The web dashboard is JavaScript.

**Q: How do I contribute a custom collector?**

Write a go.d module in Go (preferred), a python.d module in Python, or a charts.d module in Bash. Follow the collector development guide in the Netdata GitHub repository.

**Q: Can I export metrics to multiple backends simultaneously?**

Yes. Configure multiple export destinations in `exporting.conf`. Each destination operates independently.

**Q: What is the dbengine and why is it special?**

The dbengine is Netdata's custom time-series database optimized for per-second data. It uses gorilla compression (XOR-based floating point compression) and tiered storage (high-res to aggregated). Unlike external databases, it runs in-process with zero network overhead.

**Q: How does Netdata auto-discover services?**

Collectors (primarily go.d) probe known ports and endpoints at startup and periodically. When a service appears on its default port, the corresponding collector activates automatically with default settings.

**Q: What ports does Netdata need open?**

- **19999** (TCP, inbound): Web dashboard and API
- **443** (TCP, outbound): Netdata Cloud communication (ACLK)
- **19999** (TCP, between nodes): Streaming from child to parent

No inbound ports are required for Cloud — the agent initiates outbound connections only.

**Q: Can I run Netdata without root?**

Partially. The daemon itself can run as the `netdata` user, but some plugins (`apps.plugin`, `ebpf.plugin`, `cgroups.plugin`) need elevated privileges to read `/proc`, `/sys`, and kernel data. These plugins use capabilities (e.g., `CAP_DAC_READ_SEARCH`, `CAP_SYS_PTRACE`) rather than full root.

**Q: How do I check which version of Netdata I am running?**

```bash
netdata -v
# or
curl -s http://localhost:19999/api/v1/info | python3 -c "import sys,json; print(json.load(sys.stdin)['version'])"
```

**Q: What is thin mode for streaming?**

Thin mode means a child node does not store any data locally — it only streams to its parent. This minimizes resource usage on the child (no disk I/O, minimal RAM). The trade-off is no local dashboard and data loss if the parent is unreachable.

**Q: How does Netdata's ML anomaly detection work?**

Every metric trains its own model using a k-means clustering algorithm on recent data. Each new sample is scored as normal or anomalous based on distance from learned clusters. The anomaly rate (percentage of metrics flagged as anomalous) is itself a metric that can trigger alerts.

**Q: Can I use Netdata with Grafana?**

Yes. Use the Netdata data source plugin for Grafana (available in the Grafana marketplace) to query Netdata agents or Cloud directly. Alternatively, export metrics to Prometheus and use the Prometheus data source in Grafana.

**Q: What happens to my data if I uninstall Netdata?**

Data stored in `/var/cache/netdata/dbengine/` remains on disk until you manually delete it. Configuration in `/etc/netdata/` also remains. The uninstaller script offers options to remove or preserve data.

**Q: How do I downgrade to a previous version?**

For kickstart installs, pin a specific version by installing from the release assets on GitHub. For packages, use your package manager's version pinning feature (e.g., `apt-get install netdata=VERSION`).

---

_Generated May 2026 from netdata/netdata at 3562289. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._