README.md

   1 netdata
   2 =======
   3
   4 ### Linux real time system monitoring, over the web!
   5
   6 **Netdata** is a daemon that collects system information from a linux system and presents a web site to view the data.
   7 The presentation is full of charts that precisely render all system values, in realtime, for a short time (1 hour by default).
   8
   9 You can use it to monitor all your servers, linux PCs or linux embedded devices, without the need to ssh to them.
  10 Also, you can view a short history of all collected values, so if something happens you can use **netdata** to find out what and when.
  11
  12 Check it live at:
  13
  14  - [My Home Gentoo Box](http://195.97.5.206:19999/)
  15  - [My Home Raspberry Pi B+](http://195.97.5.204:19999/) with data collection every 5s (raspbian playing movies 24x7)
  16  - [My Home Raspberry Pi 2](http://195.97.5.205:19999/) (osmc as an access point)
  17
  18 Here is a screenshot:
  19
  20 ![image](https://cloud.githubusercontent.com/assets/2662304/2593406/3c797e88-ba80-11e3-8ec7-c10174d59ad6.png)
  21
  22
  23 # Features
  24
  25 - **highly optimized C code**
  26
  27   It only needs a few milliseconds per second to collect all the data.
  28   It will nicelly run even on a raspberry pi with just one cpu core, or any other embedded system.
  29
  30 - **extremely lightweight**
  31
  32   It only needs a few megabytes of memory to store all its round robin database.
  33
  34   Internally, it uses a **custom-made 32-bit number** to store all the values, along with a limited number of metadata for each collected value. This floating point number can store in 29 bits values from -167772150000000.0 to  167772150000000.0 with a precision of 0.00001 (yes, it is a floating point number, meaning that higher integer values have less decimal precision) and 3 bits for flags (2 are currently used and 1 is reserved for future use). This provides an extremely optimized memory footprint.
  35
  36 - **per second data collection**
  37
  38   Every chart, every value, is updated every second. Of course, you can control collection period per module.
  39
  40   **netdata** can perform several calculations on each value collected:
  41
  42   - **absolute**, the collected value should be stored as collected
  43   - **incremental**, the difference of the collected value to the last collected value should be stored (this is used for counters that always get incremented - netdata automatically interpolates these values so that small delays at the data collection layer will not affect the quality of the result - also, **netdata** detects arithmetic overflows and presents them properly at the charts)
  44   - **percentage of absolute row**, stores the percentage of the collected value, in the sum of all collected values of the chart
  45   - **percentage of incremental row**, stores the percentage of this value, in the sum of the the **incremental** differences of the chart
  46
  47 - **visualizes QoS classes automatically**
  48
  49   If you also use FireQOS for QoS, it collects class names automatically.
  50
  51 - **appealing web site**
  52
  53   The web site uses bootstrap and google charts for a very appealing result.
  54   It works even on mobile devices and adapts to screen size changes and rotation.
  55
  56 - **web charts do respect your browser resources**
  57
  58   The charts adapt to show only as many points are required to have a clear view.
  59   Also, the javascript code respects your browser resources (stops refreshing when the window looses focus, when scrolling, etc).
  60
  61 - **highly configurable**
  62
  63   All charts and all features can be enabled or disabled.
  64   The program generates its configuration file based on the resources available on the system it runs, for you to edit.
  65
  66 - It reads and renders charts for all these:
  67  - `/proc/net/dev` (all netwrok interfaces for all their values)
  68  - `/proc/diskstats` (all disks for all their values)
  69  - `/proc/net/snmp` (total IPv4, TCP and UDP usage)
  70  - `/proc/net/netstat` (more IPv4 usage)
  71  - `/proc/net/stat/nf_conntrack` (connection tracking performance)
  72  - `/proc/net/ip_vs/stats` (IPVS connection statistics)
  73  - `/proc/stat` (CPU utilization)
  74  - `/proc/meminfo` (memory information)
  75  - `/proc/vmstat` (system performance)
  76  - `/proc/net/rpc/nfsd` (NFS server statistics for both v3 and v4 NFS)
  77  - `tc` classes (QoS classes)
  78
  79 - It supports **plugins** for collecting information from other sources!
  80
  81   Plugins can be written in any computer language (pipe / stdout communication for data collection).
  82
  83   It ships with 2 plugins: `apps.plugin` and `charts.d.plugin`:
  84
  85  - `apps.plugin` is a plugin that attempts to collect statistics per process.
  86
  87  - `charts.d.plugin` provides a simple way to script data collection in BASH. It includes example plugins that collect values from:
  88
  89   - `nut` (UPS load, frequency, voltage, etc)
  90   - `pi` (raspberry pi CPU clock and temperature)
  91   - `postfix` (e-mail queue size)
  92   - `squid` (web proxy statistics)
  93
  94 - netdata is a web server, supporting gzip compression
  95
  96   It serves its own static files and dynamic files for rendering the site.
  97   (it does not support authentication or SSL - limit its access using your firewall)
  98
  99
 100 # How it works
 101
 102 1. You run a daemon on your linux: netdata.
 103  This deamon is written in C and is extremely lightweight.
 104
 105  netdata:
 106
 107   - reads several /proc files
 108   - keeps track of the values in memroy (a short history)
 109   - generates JSON and JSONP HTTP responses containing all the data needed for the web graphs
 110   - is a web server. You can access JSON data by using:
 111
 112  ```
 113  http://127.0.0.1:19999/data/net.eth0
 114  ```
 115
 116  This will give you the JSON file for traffic on eth0.
 117  The above is equivalent to:
 118
 119  ```
 120  http://127.0.0.1:19999/data/net.eth0/3600/1/average/0/0
 121  ```
 122
 123  where:
 124
 125   - 3600 is the number of entries to generate.
 126   - 1 is grouping count, 1 = every single entry, 2 = half the entries, 3 = one every 3 entries, etc
 127   - `average` is the grouping method. It can also be `max`.
 128   - 0/0 they are `before` and `after` timestamps, allowing panning on the data
 129
 130
 131 2. On your web page, you add a few javascript lines and a DIV for every graph you need.
 132  Your browser will hit the web server to fetch the JSON data and refresh the graphs.
 133
 134 3. Graphs are generated using Google Charts API (so, your client needs to have internet access).
 135
 136
 137 # Installation
 138
 139 ## Automatic installation
 140
 141 Before you start, make sure you have `zlib` development files installed.
 142 To install it in Ubuntu, you need to run:
 143
 144 ```sh
 145 apt-get install zlib1g-dev
 146 ```
 147
 148 Then do this to install and run netdata:
 149
 150 ```sh
 151 git clone https://github.com/ktsaou/netdata.git netdata.git
 152 cd netdata.git
 153 ./netdata.start
 154 ```
 155
 156 Once you run it, the file conf.d/netdata.conf will be created. You can edit this file to set options for each graph.
 157 To apply the changes you made, you have to run netdata.start again.
 158
 159 If you run `netdata.start` as `root`, netdata will start by default as `nobody`. Otherwise it will run as the user that started it. If you run it as `root`, you can set the user you want it to run in the config file `conf.d/netdata.conf`.
 160
 161 To access the web site for all graphs, go to:
 162
 163  ```
 164  http://127.0.0.1:19999/
 165  ```
 166
 167 You can get the running config file at any time, by accessing `http://127.0.0.1:19999/netdata.conf`.