Adding runtime options docs.

Also some cleanups of other docs.

README.md

@@ -26,7 +26,7 @@ cAdvisor is now running (in the background) on `http://localhost:8080`. The setu
 
 **Note**: If you're running on CentOS, RHEL, or are using LXC take a look at our [running instructions](docs/running.md).
 
-We have detailed [instructions](docs/running.md#standalone) on running cAdvisor standalone outside of Docker. If you want to build your own cAdvisor Docker image see our [deployment](docs/deploy.md) page.
+We have detailed [instructions](docs/running.md#standalone) on running cAdvisor standalone outside of Docker. cAdvisor [running options](docs/runtime_options.md) may also be interesting for advanced usecases. If you want to build your own cAdvisor Docker image see our [deployment](docs/deploy.md) page.
 
 ## Building and Testing
 

cadvisor.go

@@ -39,7 +39,7 @@ var argIp = flag.String("listen_ip", "", "IP to listen on, defaults to all IPs")
 var argPort = flag.Int("port", 8080, "port to listen")
 var maxProcs = flag.Int("max_procs", 0, "max number of CPUs that can be used simultaneously. Less than 1 for default (number of cores).")
 
-var argDbDriver = flag.String("storage_driver", "", "storage driver to use. Empty means none. Options are: <empty> (default), bigquery, and influxdb")
+var argDbDriver = flag.String("storage_driver", "", "storage driver to use. Data is always cached shortly in memory, this controls where data is pushed besides the local cache. Empty means none. Options are: <empty> (default), bigquery, and influxdb")
 var versionFlag = flag.Bool("version", false, "print cAdvisor version and exit")
 
 func main() {

container/raw/container_hints.go

@@ -25,20 +25,20 @@ import (
 	"os"
 )
 
-var argContainerHints = flag.String("container_hints", "/etc/cadvisor/container_hints.json", "container hints file")
+var argContainerHints = flag.String("container_hints", "/etc/cadvisor/container_hints.json", "location of the container hints file")
 
 type containerHints struct {
 	AllHosts []containerHint `json:"all_hosts,omitempty"`
 }
 
 type containerHint struct {
-	FullName                string `json:"full_path,omitempty"`
-	NetworkInterface        *networkInterface `json:"network_interface,omitempty"`
-	Mounts                  []mount `json:"mounts,omitempty"`
+	FullName         string            `json:"full_path,omitempty"`
+	NetworkInterface *networkInterface `json:"network_interface,omitempty"`
+	Mounts           []mount           `json:"mounts,omitempty"`
 }
 
 type mount struct {
-	HostDir string `json:"host_dir,omitempty"`
+	HostDir      string `json:"host_dir,omitempty"`
 	ContainerDir string `json:"container_dir,omitempty"`
 }
 

docs/influxdb.md

@@ -1,13 +1,15 @@
-#### Exporting cAdvisor Stats to InfluxDB
+# Exporting cAdvisor Stats to InfluxDB
 
 cAdvisor supports exporting stats to [InfluxDB](http://influxdb.com). To use InfluxDB, you need to pass some additional flags to cAdvisor telling it where the InfluxDB instance is located:
 
-**Required**
+Set the storage driver as InfluxDB.
+
 ```
- # storage driver to use. Options are: memory (default) and influxdb
  -storage_driver=influxdb
 ```
-**Optional**
+
+Specify what InfluxDB instance to push data to:
+
 ```
  # The *ip:port* of the database. Default is 'localhost:8086'
  -storage_driver_host=ip:port

docs/running.md

@@ -48,6 +48,10 @@ $ sudo cadvisor
 
 cAdvisor is now running (in the foreground) on `http://localhost:8080/`.
 
+## Runtime Options
+
+cAdvisor has a series of flags that can be used to configure its runtime behavior. More details can be found in runtime [options](docs/runtime_options.md).
+
 ## I need help!
 
 We aim to have cAdvisor run everywhere! If you run into issues getting it running, feel free to file an issue. We are very responsive in supporting our users and update our documentation with new setups.

docs/runtime_options.md

@@ -0,0 +1,72 @@
+# cAdvisor Runtime Options
+
+This document describes a set of runtime flags available in cAdvisor.
+
+## Housekeeping
+
+Housekeeping is the periodic actions cAdvisor takes. During these actions, cAdvisor will gather container stats. These flags control how and when cAdvisor performs housekeeping.
+
+#### Dynamic Housekeeping
+
+Dynamic housekeeping intervals let cAdvisor very how oftern it gathers stats.
+It does this depending on how active the container is. Turning this off
+provides predictable housekeeping intervals, but increases the resource usage
+of cAdvisor.
+
+```
+--allow_dynamic_housekeeping=true: Whether to allow the housekeeping interval to be dynamic
+```
+
+#### Housekeeping Intervals
+
+Intervals for housekeeping. cAdvisor has two housekeepings: global and per-container.
+
+Global housekeeping is a singular housekeeping done once in cAdvisor. This typically does detection of new containers. Today, cAdvisor discovers new containers with kernel events so this global housekeeping is mostly used as backup in the case that there are any missed events.
+
+Per-container housekeeping is run once on each container cAdvisor tracks. This typically gets container stats.
+
+```
+--global_housekeeping_interval=1m0s: Interval between global housekeepings
+--housekeeping_interval=1s: Interval between container housekeepings
+```
+
+## Container Hints
+
+Container hints are a way to pass extra information about a container to cAdvisor. In this way cAdvisor can augment the stats it gathers. For more information on the container hints format see its [definition](container/raw/container_hints.go). Note that container hints are only used by the raw container driver today.
+
+```
+--container_hints="/etc/cadvisor/container_hints.json": location of the container hints file
+```
+
+## HTTP
+
+Specify where cAdvisor listens.
+
+```
+--listen_ip="": IP to listen on, defaults to all IPs
+--port=8080: port to listen
+```
+
+## Debugging and Logging
+
+cAdvisor-native flags that help in debugging:
+
+```
+--log_cadvisor_usage=false: Whether to log the usage of the cAdvisor container
+--version=false: print cAdvisor version and exit
+```
+
+From [glog](https://github.com/golang/glog) here are some flags we find useful:
+
+```
+--log_dir="": If non-empty, write log files in this directory
+--logtostderr=false: log to standard error instead of files
+--alsologtostderr=false: log to standard error as well as files
+--stderrthreshold=0: logs at or above this threshold go to stderr
+--v=0: log level for V logs
+--vmodule=: comma-separated list of pattern=N settings for file-filtered logging
+```
+
+## Storage Drivers
+
+See [InfluxDB instructions](docs/influxdb.md).