Merge pull request kubernetes#298 from vmarmol/readme

Reorganizing cAdvisor docs and moving many of them to their own pages.
vishh · Nov 8, 2014 · d072778 · d072778
2 parents c356d3b + 1118597
commit d072778
Show file tree

Hide file tree

Showing 6 changed files with 142 additions and 112 deletions.
diff --git a/README.md b/README.md
@@ -2,13 +2,13 @@
 
 cAdvisor (Container Advisor) provides container users an understanding of the resource usage and performance characteristics of their running containers. It is a running daemon that collects, aggregates, processes, and exports information about running containers. Specifically, for each container it keeps resource isolation parameters, historical resource usage, histograms of complete historical resource usage and network statistics. This data is exported by container and machine-wide.
 
-cAdvisor currently supports lmctfy containers as well as Docker containers (those that use the default libcontainer execdriver). Other container backends can also be added. cAdvisor's container abstraction is based on lmctfy's so containers are inherently nested hierarchically.
+cAdvisor has native support for [Docker](https://github.com/docker/docker) containers and should support just about any other container type out of the box. We strive for support accross the board so feel free to open an issue if that is not the case. cAdvisor's container abstraction is based on [lmctfy](https://github.com/google/lmctfy)'s so containers are inherently nested hierarchically.
 
 ![cAdvisor](logo.png "cAdvisor")
 
 #### Quick Start: Running cAdvisor in a Docker Container
 
-To quickly tryout cAdvisor on your machine with Docker (version 0.11 or above), we have a Docker image that includes everything you need to get started. Simply run:
+To quickly tryout cAdvisor on your machine with Docker, we have a Docker image that includes everything you need to get started. Simply run:
 
 ```
 sudo docker run \
@@ -26,131 +26,31 @@ 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).
 
-If you want to build your own cAdvisor Docker image, take a look at `deploy/Dockerfile` and `deploy/build.sh`.
+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.
 
-#### Using [InfluxDB](http://influxdb.com) as backend storage
+## Building and Testing
 
-cAdvisor now also supports [InfluxDB](http://influxdb.com) to store stats. To use InfluxDB, you need to pass some additional flags to cAdvisor:
+See the more detailed instructions in the [build page](docs/build.md). This includes instructions for building and deploying the cAdvisor Docker image.
 
-**Required**
-```
- # storage driver to use. Options are: memory (default) and influxdb
- -storage_driver=influxdb
- # Required to make glog work
- -log_dir=/
-```
-**Optional**
-```
- # The *ip:port* of the database. Default is 'localhost:8086'
- -storage_driver_host=ip:port
- # database name. Uses db 'cadvisor' by default
- -storage_driver_name
- # database username. Default is 'root'
- -storage_driver_user
- # database password. Default is 'root'
- -storage_driver_password
- # Use secure connection with database. False by default
- -storage_driver_secure
-```
+## InfluxDB and Cluster Monitoring
 
-## Cluster monitoring using cAdvisor
+cAdvisor supports exporting stats to [InfluxDB](http://influxdb.com). See the [documentation](docs/influxdb.md) for more information and examples.
 
 [Heapster](https://github.com/GoogleCloudPlatform/heapster) enables cluster wide monitoring of containers using cAdvisor.
 
-## Building and Testing cAdvisor
-
-See the more detailed instructions in the [build page](docs/build.md).
-
 ## Web UI
 
 cAdvisor exposes a web UI at its port:
 
 `http://<hostname>:<port>/`
 
-## Remote REST API
-
-cAdvisor exposes its raw and processed stats via a versioned remote REST API:
-
-`http://<hostname>:<port>/api/<version>/<request>`
-
-The current version of the API is `v1.2`.
-
-### Version 1.2
-
-This version exposes the same endpoints as `v1.1` with one additional read-only endpoint.
-
-#### Docker Container Information
-
-The resource name for Docker container information is as follows:
-
-`/api/v1.1/docker/<Docker container name or blank for all Docker containers>`
-
-The Docker name can be either the UUID or the short name of the container. It returns the information of the specified container(s). The information is returned as a list of serialized `ContainerInfo` JSON objects (found in [info/container.go](info/container.go)).
-
-### Version 1.1
-
-This version exposes the same endpoints as `v1.0` with one additional read-only endpoint.
-
-#### Subcontainer Information
-
-The resource name for subcontainer information is as follows:
-
-`/api/v1.1/subcontainers/<absolute container name>`
+See the [documentation](docs/web.md) for more details.
 
-Where the absolute container name follows the lmctfy naming convention (described bellow). It returns the information of the specified container and all subcontainers (recursively). The information is returned as a list of serialized `ContainerInfo` JSON objects (found in [info/container.go](info/container.go)).
+## Remote REST API & Clients
 
-### Version 1.0
+cAdvisor exposes its raw and processed stats via a versioned remote REST API. See the API's [documentation](docs/api.md) for more information.
 
-This version exposes two main endpoints, one for container information and the other for machine information. Both endpoints are read-only in v1.0.
-
-#### Container Information
-
-The resource name for container information is as follows:
-
-`/api/v1.0/containers/<absolute container name>`
-
-Where the absolute container name follows the lmctfy naming convention. For example:
-
-| Container Name       | Resource Name                             |
-|----------------------|-------------------------------------------|
-| /                    | /api/v1.0/containers/                     |
-| /foo                 | /api/v1.0/containers/foo                  |
-| /docker/2c4dee605d22 | /api/v1.0/containers/docker/2c4dee605d22  |
-
-Note that the root container (`/`) contains usage for the entire machine. All Docker containers are listed under `/docker`.
-
-The container information is returned as a JSON object containing:
-
-- Absolute container name
-- List of subcontainers
-- ContainerSpec which describes the resource isolation enabled in the container
-- Detailed resource usage statistics of the container for the last `N` seconds (`N` is globally configurable in cAdvisor)
-- Histogram of resource usage from the creation of the container
-
-The actual object is the marshalled JSON of the `ContainerInfo` struct found in [info/container.go](info/container.go)
-
-#### Machine Information
-
-The resource name for machine information is as follows:
-
-`/api/v1.0/machine`
-
-This resource is read-only. The machine information is returned as a JSON object containing:
-
-- Number of schedulable logical CPU cores
-- Memory capacity (in bytes)
-
-The actual object is the marshalled JSON of the `MachineInfo` struct found in [info/machine.go](info/machine.go)
-
-## REST API Clients
-
-There is an example Go client under [client/](client/) - you can use it on your own Go project by including it like this:
-
-```go
-import "github.com/google/cadvisor/client"
-client, err = client.NewClient("http://192.168.59.103:8080/")
-mInfo, err := client.MachineInfo()
-```
+There is also an official Go client implementation in the [client](client/) directory. See the[documentation](docs/clients.md) for more information.
 
 ## Roadmap
 
@@ -161,4 +61,4 @@ cAdvisor aims to improve the resource usage and performance characteristics of r
 
 ## Community
 
-Contributions, questions, and comments are all welcomed and encouraged! cAdvisor developers hang out in [#google-containers](http://webchat.freenode.net/?channels=google-containers) room on freenode.net.  We also have the [google-containers Google Groups mailing list](https://groups.google.com/forum/#!forum/google-containers).
+Contributions, questions, and comments are all welcomed and encouraged! cAdvisor developers hang out in [#google-containers](http://webchat.freenode.net/?channels=google-containers) room on [freenode.net](http://freenode.net).  We also have the [google-containers Google Groups mailing list](https://groups.google.com/forum/#!forum/google-containers).
diff --git a/docs/api.md b/docs/api.md
@@ -0,0 +1,74 @@
+# cAdvisor Remote REST API
+
+cAdvisor exposes its raw and processed stats via a versioned remote REST API:
+
+`http://<hostname>:<port>/api/<version>/<request>`
+
+The current version of the API is `v1.2`.
+
+## Version 1.2
+
+This version exposes the same endpoints as `v1.1` with one additional read-only endpoint.
+
+### Docker Container Information
+
+The resource name for Docker container information is as follows:
+
+`/api/v1.2/docker/<Docker container name or blank for all Docker containers>`
+
+The Docker name can be either the UUID or the short name of the container. It returns the information of the specified container(s). The information is returned as a list of serialized `ContainerInfo` JSON objects (found in [info/container.go](info/container.go)).
+
+## Version 1.1
+
+This version exposes the same endpoints as `v1.0` with one additional read-only endpoint.
+
+### Subcontainer Information
+
+The resource name for subcontainer information is as follows:
+
+`/api/v1.1/subcontainers/<absolute container name>`
+
+Where the absolute container name follows the lmctfy naming convention (described bellow). It returns the information of the specified container and all subcontainers (recursively). The information is returned as a list of serialized `ContainerInfo` JSON objects (found in [info/container.go](info/container.go)).
+
+## Version 1.0
+
+This version exposes two main endpoints, one for container information and the other for machine information. Both endpoints are read-only in v1.0.
+
+### Container Information
+
+The resource name for container information is as follows:
+
+`/api/v1.0/containers/<absolute container name>`
+
+Where the absolute container name follows the lmctfy naming convention. For example:
+
+| Container Name       | Resource Name                             |
+|----------------------|-------------------------------------------|
+| /                    | /api/v1.0/containers/                     |
+| /foo                 | /api/v1.0/containers/foo                  |
+| /docker/2c4dee605d22 | /api/v1.0/containers/docker/2c4dee605d22  |
+
+Note that the root container (`/`) contains usage for the entire machine. All Docker containers are listed under `/docker`.
+
+The container information is returned as a JSON object containing:
+
+- Absolute container name
+- List of subcontainers
+- ContainerSpec which describes the resource isolation enabled in the container
+- Detailed resource usage statistics of the container for the last `N` seconds (`N` is globally configurable in cAdvisor)
+- Histogram of resource usage from the creation of the container
+
+The actual object is the marshalled JSON of the `ContainerInfo` struct found in [info/container.go](info/container.go)
+
+### Machine Information
+
+The resource name for machine information is as follows:
+
+`/api/v1.0/machine`
+
+This resource is read-only. The machine information is returned as a JSON object containing:
+
+- Number of schedulable logical CPU cores
+- Memory capacity (in bytes)
+
+The actual object is the marshalled JSON of the `MachineInfo` struct found in [info/machine.go](info/machine.go)
diff --git a/docs/clients.md b/docs/clients.md
@@ -0,0 +1,12 @@
+# cAdvisor API Clients
+
+There is an official Go client implementation in the [client](client/) directory. You can use it on your own Go project by including it like this:
+
+```go
+import "github.com/google/cadvisor/client"
+
+client, err = client.NewClient("http://localhost:8080/")
+mInfo, err := client.MachineInfo()
+```
+
+Do you know of another cAdvisor client? Maybe in another language? Please let us know! We'd be happy to add a note on this page.
diff --git a/docs/deploy.md b/docs/deploy.md
@@ -0,0 +1,15 @@
+# Building and Deploying the cAdvisor Docker Container
+
+## Building
+
+Building the cAdvisor Docker container is simple, just run:
+
+```
+$ ./deploy/build.sh
+```
+
+Which will statically build the cAdvisor binary and then build the Docker image. The resulting Docker image will be called `google/cadvisor:canary`. This image is very bare, containing the cAdvisor binary and nothing else.
+
+## Deploying
+
+All cAdvisor releases are tagged and correspond to a Docker image. The latest supported release uses the `latest` tag. We have a `beta` and `canary` tag for pre-release versions with newer features. You can see more details about this in the cAdvisor Docker [registry](https://registry.hub.docker.com/u/google/cadvisor/) page.
diff --git a/docs/influxdb.md b/docs/influxdb.md
@@ -0,0 +1,22 @@
+#### 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**
+```
+ # storage driver to use. Options are: memory (default) and influxdb
+ -storage_driver=influxdb
+```
+**Optional**
+```
+ # The *ip:port* of the database. Default is 'localhost:8086'
+ -storage_driver_host=ip:port
+ # database name. Uses db 'cadvisor' by default
+ -storage_driver_name
+ # database username. Default is 'root'
+ -storage_driver_user
+ # database password. Default is 'root'
+ -storage_driver_password
+ # Use secure connection with database. False by default
+ -storage_driver_secure
+```
diff --git a/docs/web.md b/docs/web.md
@@ -0,0 +1,7 @@
+# cAdvisor Web UI
+
+cAdvisor exposes a web UI at its port:
+
+`http://<hostname>:<port>/`
+
+This UI has one primary resource at `/containers` which exports live information about all containers on the machine.