# Netdata Monitoring Cluster

> Distributed real-time monitoring with Netdata parent-child streaming architecture. Central dashboard aggregates metrics from multiple nodes.

- Category: Monitoring & Observability
- Difficulty: intermediate
- Components: netdata-parent, netdata-child
- Tags: netdata, infrastructure, metrics, realtime, distributed
- Source: https://docker.recipes/monitoring/netdata-cluster

## Overview

Netdata is a high-performance, real-time system monitoring and performance analytics platform that provides sub-second granularity metrics collection with zero-configuration auto-detection of system components, applications, and services. Originally developed as an open-source project focused on lightweight resource usage and instant deployment, Netdata has evolved into a comprehensive monitoring solution that can scale from single servers to large distributed infrastructures while maintaining its core philosophy of immediate visibility without complex setup procedures.

This deployment creates a distributed monitoring architecture using Netdata's parent-child streaming functionality, where the netdata-parent container acts as a central aggregation hub that receives and stores metrics from remote nodes, while the netdata-child container demonstrates the streaming agent configuration that collects local system metrics and forwards them to the parent node. The parent node provides the primary web dashboard interface and persistent data storage, while child nodes operate in a lightweight streaming mode that minimizes local resource usage and eliminates the need for distributed storage management.

This configuration is ideal for system administrators managing multi-server environments, DevOps teams requiring centralized observability across distributed infrastructure, and organizations that need real-time performance monitoring without the complexity and overhead of traditional enterprise monitoring solutions. The parent-child architecture enables horizontal scaling of monitoring coverage while maintaining centralized visualization and alerting capabilities.

## Features

- Real-time metrics streaming with sub-second granularity from child nodes to parent aggregator
- Zero-configuration auto-detection of 800+ system metrics, applications, and services on each monitored node
- Interactive web dashboard with drill-down capabilities for analyzing metrics across the entire infrastructure
- Automatic anomaly detection using machine learning algorithms trained on historical metric patterns
- Custom alerting system with support for multiple notification channels including webhooks and cloud integrations
- Distributed architecture that reduces bandwidth usage through intelligent metric compression and streaming protocols
- Built-in health monitoring with configurable thresholds for system components, processes, and custom metrics
- API key-based authentication for secure metric streaming between geographically distributed nodes

## Use cases

- Multi-server application monitoring where developers need unified visibility across web servers, databases, and application nodes
- Container orchestration environments requiring real-time monitoring of Kubernetes clusters or Docker Swarm deployments
- Edge computing deployments where lightweight monitoring agents stream metrics from remote locations to central operations centers
- Development and staging environment monitoring with centralized dashboards for CI/CD pipeline performance analysis
- Hybrid cloud infrastructure monitoring combining on-premises servers with cloud instances under single management interface
- High-frequency trading or real-time application monitoring where sub-second metric resolution is critical for performance optimization
- Managed service provider environments where multiple client infrastructures require centralized monitoring with tenant isolation

## Prerequisites

- Docker host with at least 512MB RAM available for the parent node and 256MB per child node
- Network connectivity between parent and child nodes on port 19999 for metric streaming
- Understanding of system monitoring concepts including CPU, memory, disk, and network performance metrics
- Basic knowledge of UUID generation for creating secure API keys for stream authentication
- Administrative access to mount host system directories (/proc, /sys) for comprehensive system metric collection
- Firewall configuration allowing inbound connections to the parent node from all child monitoring nodes

## docker-compose.yml

```yaml
services:
  netdata-parent:
    image: netdata/netdata:latest
    container_name: netdata-parent
    restart: unless-stopped
    hostname: netdata-parent
    ports:
      - "${NETDATA_PORT:-19999}:19999"
    cap_add:
      - SYS_PTRACE
    security_opt:
      - apparmor:unconfined
    volumes:
      - netdata_config:/etc/netdata
      - netdata_lib:/var/lib/netdata
      - netdata_cache:/var/cache/netdata
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
      - /etc/os-release:/host/etc/os-release:ro
    environment:
      - NETDATA_CLAIM_TOKEN=${CLAIM_TOKEN:-}
      - NETDATA_CLAIM_ROOMS=${CLAIM_ROOMS:-}

  netdata-child:
    image: netdata/netdata:latest
    container_name: netdata-child
    restart: unless-stopped
    hostname: netdata-child
    cap_add:
      - SYS_PTRACE
    security_opt:
      - apparmor:unconfined
    volumes:
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
      - /etc/os-release:/host/etc/os-release:ro
    environment:
      - NETDATA_STREAM_DESTINATION=netdata-parent:19999
      - NETDATA_STREAM_API_KEY=${STREAM_API_KEY}

volumes:
  netdata_config:
  netdata_lib:
  netdata_cache:
```

## .env

```bash
# Netdata Cluster Configuration
NETDATA_PORT=19999

# Generate a UUID for streaming: uuidgen
STREAM_API_KEY=11111111-2222-3333-4444-555555555555

# Optional: Netdata Cloud claim token (get from app.netdata.cloud)
CLAIM_TOKEN=
CLAIM_ROOMS=
```

## Usage notes

- Access parent dashboard at http://localhost:19999
- Child node automatically streams metrics to parent
- Generate stream API key with: uuidgen
- Deploy child container on other hosts pointing to parent
- Optional: claim to Netdata Cloud for alerts and dashboards
- Add more child nodes by replicating the child service config

## Troubleshooting

- Child node shows 'connection refused' errors: Verify netdata-parent container is running and port 19999 is accessible, check NETDATA_STREAM_DESTINATION environment variable format
- Stream authentication failures between nodes: Regenerate STREAM_API_KEY using uuidgen command and ensure identical keys are configured on both parent and child containers
- Missing system metrics on monitored nodes: Verify /proc and /sys host directories are properly mounted as read-only volumes in the container configuration
- High memory usage on netdata-parent container: Reduce metric retention period by configuring history settings or increase available memory allocation for the parent node
- Dashboard shows 'no data' for child nodes: Check network connectivity between containers and verify child node hostname resolution in the parent container logs
- Permission denied errors during container startup: Add SYS_PTRACE capability and configure apparmor:unconfined security option for proper system monitoring access

