From f4192c1adb9728200191f14402d520a3ccbc40ad Mon Sep 17 00:00:00 2001 From: Tom Wilkie Date: Sun, 18 Oct 2015 11:06:47 +0000 Subject: [PATCH 1/5] Some extended basic documentation. --- README.md | 4 -- docs/scope.md | 141 +++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 139 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index ee5a09b99..bd8eed0b1 100644 --- a/README.md +++ b/README.md @@ -10,10 +10,6 @@ Weave Scope automatically generates a map of your containers, enabling you to intuitively understand, monitor, and control your applications. -Please note that the code, and especially the building and running story, is -in a **prerelease** state. Please take a look, but don't be surprised if you -hit bugs or missing pieces. - ## Getting started diff --git a/docs/scope.md b/docs/scope.md index d0782bebc..70a25990a 100644 --- a/docs/scope.md +++ b/docs/scope.md @@ -1,10 +1,147 @@ +# Weave Scope + +Weave Scope automatically generates a map of your containers, enabling you to +intuitively understand, monitor, and control your applications. + +Scope does not need any configuration and does not require the Weave Network. + +## Architecture + +Weave Scope consists of two components: the App and the Probe. These two +components are deployed as a single Docker container using the ```scope``` +script: + +``` +sudo scope launch +``` + +The Probe is responsible for gathering information about the host is it running +on. This information is sent to the app in the form of a report. The App is +responsible for processing reports from the probe into useable topologies, +serving the UI and pushing these topologies to the UI. + +``` ++-------------------------------+ +-------------------------------+ +| | | | +| Docker Host | | Your laptop | +| | | | +| +---------------------------+ | | +-----------------------+ | +| | | | | | | | +| | Weave Scope Container | | -------->| Your web browser | | +| | | | / | | | | +| | +-----------------------+ | | / | +-----------------------+ | +| | | | | | / | | +| | | Scope-app |<------- +-------------------------------+ +| | | | | | +| | +------------+----------+ | | +| | ^ | | +| | | | | +| | +------------+----------+ | | +| | | | | | +| | | Scope-probe | | | +| | | | | | +| | +-----------------------+ | | +| | | | +| +---------------------------+ | +| | ++-------------------------------+ +``` ## Multi host setup -Weave Scope uses WeaveDNS to automatically discover other instances of Scope running on your network. If you have a running WeaveDNS setup, you do not need any further steps. +When running Scope in a cluster, each Probe sends reports to each App. +The App merges the reports from each probe into a more complete report. -If you do not wish to use WeaveDNS, you can instruct Scope to cluster with other Scope instances on the command line. Hostnames and IP addresses are acceptable, both with and without ports: +``` ++-------------------------------+ +-------------------------------+ +| | | | +| Docker Host 1 | | Docker Host 2 | +| | | | +| +---------------------------+ | | +---------------------------+ | +| | | | | | | | +| | Weave Scope Container | | | | Weave Scope Container | | +| | | | | | | | +| | +-----------------------+ | | | | +-----------------------+ | | +| | | | | | | | | | | | +| | | Scope-app |<------ ------>| Scope-app | | | +| | | | | | \ / | | | | | | +| | +------------+----------+ | | \ / | | +------------+----------+ | | +| | ^ | | \/ | | ^ | | +| | | | | /\ | | | | | +| | +------------+----------+ | | / \ | | +------------+----------+ | | +| | | | | | / \ | | | | | | +| | | Scope-probe +------- -------+ Scope-probe | | | +| | | | | | | | | | | | +| | +-----------------------+ | | | | +-----------------------+ | | +| | | | | | | | +| +---------------------------+ | | +---------------------------+ | +| | | | ++-------------------------------+ +-------------------------------+ +``` + +If you run Scope on the same machine as the Weave Network, the Probe will use +WeaveDNS to automatically discover other Apps on your network. Therefore, if +you have a running WeaveDNS setup, you do not need to take any further steps. + +If you do not wish to use WeaveDNS, you can instruct Scope to cluster with +other Scope instances on the command line. Hostnames and IP addresses are +acceptable, both with and without ports: ``` # weave launch scope1:4030 192.168.0.12 192.168.0.11:4030 ``` + +## Using Scope Service + +Scope can also be used to feed reports to the Scope Service. The Scope +Service allows you centrally manage and share access to your Scope UI. In this +configuration, you only run the Probe locally - the Apps are hosted for you. + +To get an account on the Scope Service, sign up at scope.weave.works. You need +to run a Probe on every machine you want to monitor with Scope. To launch a +Probe and send reports to the service, run the following command: + +``` +sudo scope launch --service-token= +``` + +``` + ___ ,'""""'. + ,""" """"' `. + ,' `._ + ,' `"""'. + ,' `. + ,' : + ,' `. + ,""""' `"""". + ,' `. + ,' scope.weave.works `. + ,-""' `. + ,' `. + ; ,' ',' `. + ,' ; ,' `. + ,' ; ( , `. + ; ` `. ,' ,' + ; \ `. ,' ,' ,' + '. ' `. ,''. ,' `--' + `"-----"" _.-'' .-'`-.:..___...--' `-._ ,-"' `-' + /\ `""""" + || ++-----------------------------+ || +-----------------------------+ +| | || | | +| Docker Host | || | Docker Host | +| | || | | +| +-------------------------+ | || | +-------------------------+ | +| | | | || | | | | +| | Weave Scope Container | | || | | Weave Scope Container | | +| | | | || | | | | +| | +------------+--------+ | | / \ | | +------------+--------+ | | +| | | | | | / \ | | | | | | +| | | Scope-probe +--------- ---------+ Scope-probe | | | +| | | | | | | | | | | | +| | +---------------------+ | | | | +---------------------+ | | +| | | | | | | | +| +-------------------------+ | | +-------------------------+ | +| | | | ++-----------------------------+ +-----------------------------+ +```` From 8783fc49743ae4fd12a10942a661ce9a27dcdf24 Mon Sep 17 00:00:00 2001 From: Tom Wilkie Date: Mon, 19 Oct 2015 14:41:26 +0000 Subject: [PATCH 2/5] Review feedback --- docs/scope.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/scope.md b/docs/scope.md index 70a25990a..a12e8a3e3 100644 --- a/docs/scope.md +++ b/docs/scope.md @@ -4,6 +4,7 @@ Weave Scope automatically generates a map of your containers, enabling you to intuitively understand, monitor, and control your applications. Scope does not need any configuration and does not require the Weave Network. +You need to run Scope on every machine you want to monitor. ## Architecture @@ -51,6 +52,7 @@ serving the UI and pushing these topologies to the UI. When running Scope in a cluster, each Probe sends reports to each App. The App merges the reports from each probe into a more complete report. +You need to run Scope on every machine you want to monitor. ``` +-------------------------------+ +-------------------------------+ @@ -80,7 +82,9 @@ The App merges the reports from each probe into a more complete report. ``` If you run Scope on the same machine as the Weave Network, the Probe will use -WeaveDNS to automatically discover other Apps on your network. Therefore, if +WeaveDNS to automatically discover other Apps on your network. Scope acheives +this by registering itself under the address scope.weave.local; each Probe +will send reports to every App register for this address. Therefore, if you have a running WeaveDNS setup, you do not need to take any further steps. If you do not wish to use WeaveDNS, you can instruct Scope to cluster with From 9d754ba5f41b502fbd11ed48922524008636fc16 Mon Sep 17 00:00:00 2001 From: Tom Wilkie Date: Mon, 19 Oct 2015 14:47:33 +0000 Subject: [PATCH 3/5] Typo --- docs/scope.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scope.md b/docs/scope.md index a12e8a3e3..84fb93f65 100644 --- a/docs/scope.md +++ b/docs/scope.md @@ -139,7 +139,7 @@ sudo scope launch --service-token= | | | | || | | | | | | Weave Scope Container | | || | | Weave Scope Container | | | | | | || | | | | -| | +------------+--------+ | | / \ | | +------------+--------+ | | +| | +---------------------+ | | / \ | | +---------------------+ | | | | | | | | / \ | | | | | | | | | Scope-probe +--------- ---------+ Scope-probe | | | | | | | | | | | | | | | From f87e51f84996e46b3c6eaa3900373a379ac2e31c Mon Sep 17 00:00:00 2001 From: Tom Wilkie Date: Mon, 19 Oct 2015 16:23:00 +0000 Subject: [PATCH 4/5] Remove cloud. --- docs/scope.md | 27 ++++++--------------------- 1 file changed, 6 insertions(+), 21 deletions(-) diff --git a/docs/scope.md b/docs/scope.md index 84fb93f65..61b670ffb 100644 --- a/docs/scope.md +++ b/docs/scope.md @@ -110,27 +110,12 @@ sudo scope launch --service-token= ``` ``` - ___ ,'""""'. - ,""" """"' `. - ,' `._ - ,' `"""'. - ,' `. - ,' : - ,' `. - ,""""' `"""". - ,' `. - ,' scope.weave.works `. - ,-""' `. - ,' `. - ; ,' ',' `. - ,' ; ,' `. - ,' ; ( , `. - ; ` `. ,' ,' - ; \ `. ,' ,' ,' - '. ' `. ,''. ,' `--' - `"-----"" _.-'' .-'`-.:..___...--' `-._ ,-"' `-' - /\ `""""" - || + +----------------------------+ + | | + | scope.weave.works | + | | + +----------------------------+ + /\ +-----------------------------+ || +-----------------------------+ | | || | | | Docker Host | || | Docker Host | From 5ac8ce5622d15148e0e6759f0db2a90a551cfbae Mon Sep 17 00:00:00 2001 From: Peter Bourgon Date: Mon, 19 Oct 2015 18:26:29 +0200 Subject: [PATCH 5/5] Move scope.md to main README. Updates, also. --- README.md | 118 +++++++++++++++++++++++++++++++++++++++++-- docs/scope.md | 136 -------------------------------------------------- 2 files changed, 115 insertions(+), 139 deletions(-) delete mode 100644 docs/scope.md diff --git a/README.md b/README.md index bd8eed0b1..71123c8d9 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,119 @@ Now, open your web browser to **http://localhost:4040**. (If you're using boot2docker, replace localhost with the output of `boot2docker ip`.) -## Build +## Requirements + +Scope does not need any configuration and does not require the Weave Network. +But Scope does need to be running on every machine you want to monitor. + + +## Architecture + +Weave Scope consists of two components: the app and the probe. These two +components are deployed as a single Docker container using the `scope` +script. + +The probe is responsible for gathering information about the host is it running +on. This information is sent to the app in the form of a report. The app is +responsible for processing reports from the probe into usable topologies, +serving the UI, and pushing these topologies to the UI. + +``` ++--Docker host----------+ +| +--Container------+ | .---------------. +| | | | | Browser | +| | +-----------+ | | |---------------| +| | | scope-app |<---------| | +| | +-----------+ | | | | +| | ^ | | | | +| | | | | '---------------' +| | +-------------+ | | +| | | scope-probe | | | +| | +-------------+ | | +| | | | +| +-----------------+ | ++------------------------+ +``` + +## Multi host setup + +When running Scope in a cluster, each probe sends reports to each app. +The App merges the reports from each probe into a more complete report. +You need to run Scope on every machine you want to monitor. + +``` ++--Docker host----------+ +--Docker host----------+ +| +--Container------+ | | +--Container------+ | +| | | | | | | | +| | +-----------+ | | | | +-----------+ | | +| | | scope-app |<-----. .----->| scope-app | | | +| | +-----------+ | | \ / | | +-----------+ | | +| | ^ | | \/ | | ^ | | +| | | | | /\ | | | | | +| | +-------------+ | | / \ | | +-------------+ | | +| | | scope-probe |-----' '-----| scope-probe | | | +| | +-------------+ | | | | +-------------+ | | +| | | | | | | | +| +-----------------+ | | +-----------------+ | ++-----------------------+ +-----------------------+ +``` + +If you run Scope on the same machine as the Weave Network, the probe will use +weaveDNS to automatically discover other apps on your network. Scope acheives +this by registering itself under the address **scope.weave.local**. Each probe +will send reports to every app registered under this address. Therefore, if +you have a running weaveDNS setup, you do not need to take any further steps. + +If you do not wish to use weaveDNS, you can instruct Scope to cluster with +other Scope instances on the command line. Hostnames and IP addresses are +acceptable, both with and without ports: + +``` +# weave launch scope1:4030 192.168.0.12 192.168.0.11:4030 +``` + +Hostnames will be regularly resolved as A records, and each answer used as a +target. + +## Using Scope Service + +Scope can also be used to feed reports to the Scope Service. The Scope Service +allows you centrally manage and share access to your Scope UI. In this +configuration, you only run the probe locally; the apps are hosted for you. + +To get an account on the Scope Service, sign up at [scope.weave.works][]. You +need to run a probe on every machine you want to monitor with Scope. To launch +a probe and send reports to the service, run the following command: + +[scope.weave.works]: http://scope.weave.works + +``` +sudo scope launch --service-token= +``` + +``` + .-~~~-. + .- ~'` )_ ___ + / `-' )_ + | scope.weave.works \ + \ .' + ~-______________..--' + ^^ + || + || ++--Docker host----------+ || +--Docker host----------+ +| +--Container------+ | || | +--Container------+ | +| | | | || | | | | +| | +-------------+ | | / \ | | +-------------+ | | +| | | scope-probe |-----' '-----| scope-probe | | | +| | +-------------+ | | | | +-------------+ | | +| | | | | | | | +| +-----------------+ | | +-----------------+ | ++-----------------------+ +-----------------------+ +``` + + +## Developing The build is in five stages. `make deps` installs some tools we use later in the build. `make frontend` builds a UI build image with all NPM dependencies. @@ -42,8 +154,8 @@ make backend make ``` -## Run +Then, run the local build via ``` ./scope launch -``` +``` \ No newline at end of file diff --git a/docs/scope.md b/docs/scope.md deleted file mode 100644 index 61b670ffb..000000000 --- a/docs/scope.md +++ /dev/null @@ -1,136 +0,0 @@ -# Weave Scope - -Weave Scope automatically generates a map of your containers, enabling you to -intuitively understand, monitor, and control your applications. - -Scope does not need any configuration and does not require the Weave Network. -You need to run Scope on every machine you want to monitor. - -## Architecture - -Weave Scope consists of two components: the App and the Probe. These two -components are deployed as a single Docker container using the ```scope``` -script: - -``` -sudo scope launch -``` - -The Probe is responsible for gathering information about the host is it running -on. This information is sent to the app in the form of a report. The App is -responsible for processing reports from the probe into useable topologies, -serving the UI and pushing these topologies to the UI. - -``` -+-------------------------------+ +-------------------------------+ -| | | | -| Docker Host | | Your laptop | -| | | | -| +---------------------------+ | | +-----------------------+ | -| | | | | | | | -| | Weave Scope Container | | -------->| Your web browser | | -| | | | / | | | | -| | +-----------------------+ | | / | +-----------------------+ | -| | | | | | / | | -| | | Scope-app |<------- +-------------------------------+ -| | | | | | -| | +------------+----------+ | | -| | ^ | | -| | | | | -| | +------------+----------+ | | -| | | | | | -| | | Scope-probe | | | -| | | | | | -| | +-----------------------+ | | -| | | | -| +---------------------------+ | -| | -+-------------------------------+ -``` - -## Multi host setup - -When running Scope in a cluster, each Probe sends reports to each App. -The App merges the reports from each probe into a more complete report. -You need to run Scope on every machine you want to monitor. - -``` -+-------------------------------+ +-------------------------------+ -| | | | -| Docker Host 1 | | Docker Host 2 | -| | | | -| +---------------------------+ | | +---------------------------+ | -| | | | | | | | -| | Weave Scope Container | | | | Weave Scope Container | | -| | | | | | | | -| | +-----------------------+ | | | | +-----------------------+ | | -| | | | | | | | | | | | -| | | Scope-app |<------ ------>| Scope-app | | | -| | | | | | \ / | | | | | | -| | +------------+----------+ | | \ / | | +------------+----------+ | | -| | ^ | | \/ | | ^ | | -| | | | | /\ | | | | | -| | +------------+----------+ | | / \ | | +------------+----------+ | | -| | | | | | / \ | | | | | | -| | | Scope-probe +------- -------+ Scope-probe | | | -| | | | | | | | | | | | -| | +-----------------------+ | | | | +-----------------------+ | | -| | | | | | | | -| +---------------------------+ | | +---------------------------+ | -| | | | -+-------------------------------+ +-------------------------------+ -``` - -If you run Scope on the same machine as the Weave Network, the Probe will use -WeaveDNS to automatically discover other Apps on your network. Scope acheives -this by registering itself under the address scope.weave.local; each Probe -will send reports to every App register for this address. Therefore, if -you have a running WeaveDNS setup, you do not need to take any further steps. - -If you do not wish to use WeaveDNS, you can instruct Scope to cluster with -other Scope instances on the command line. Hostnames and IP addresses are -acceptable, both with and without ports: - -``` -# weave launch scope1:4030 192.168.0.12 192.168.0.11:4030 -``` - -## Using Scope Service - -Scope can also be used to feed reports to the Scope Service. The Scope -Service allows you centrally manage and share access to your Scope UI. In this -configuration, you only run the Probe locally - the Apps are hosted for you. - -To get an account on the Scope Service, sign up at scope.weave.works. You need -to run a Probe on every machine you want to monitor with Scope. To launch a -Probe and send reports to the service, run the following command: - -``` -sudo scope launch --service-token= -``` - -``` - +----------------------------+ - | | - | scope.weave.works | - | | - +----------------------------+ - /\ -+-----------------------------+ || +-----------------------------+ -| | || | | -| Docker Host | || | Docker Host | -| | || | | -| +-------------------------+ | || | +-------------------------+ | -| | | | || | | | | -| | Weave Scope Container | | || | | Weave Scope Container | | -| | | | || | | | | -| | +---------------------+ | | / \ | | +---------------------+ | | -| | | | | | / \ | | | | | | -| | | Scope-probe +--------- ---------+ Scope-probe | | | -| | | | | | | | | | | | -| | +---------------------+ | | | | +---------------------+ | | -| | | | | | | | -| +-------------------------+ | | +-------------------------+ | -| | | | -+-----------------------------+ +-----------------------------+ -````