github/weave-scope
1
0
Fork 0
mirror of https://github.com/weaveworks/scope.git synced 2026-07-18 12:59:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

Restructured Scope Docs (#1416)

Browse Source 
* New Scope Docs

* Remove most of the readme and add links to the docs.

* Fix some links

* cosmetic

bolded docker versions and clarified kube section
This commit is contained in:
Anita Buehrle
2016-05-10 05:41:04 -05:00
committed by Tom Wilkie
parent 7a58e1115e
commit b624df63d3
19 changed files with 688 additions and 354 deletions
Download Patch File Download Diff File Expand all files Collapse all files

357
README.md
View File

@@ -35,367 +35,16 @@ This script will download and run a recent Scope image from the Docker Hub.
Now, open your web browser to **http://localhost:4040**. (If you're using
boot2docker, replace localhost with the output of `boot2docker ip`.)
For instructions on installing Scope on [Kubernetes](site/installing.md#k8s), [DCOS](site/installing.md#dcos) or [ECS](site/installing.md#ecs), see [our docs](site/introducing.md).
## <a name="help"></a>Getting help
If you have any questions about, feedback for or problem with Scope we invite
you to:
- Read [our docs](site/introducing.md).
- <a href="https://weave-scope-slack.herokuapp.com">join our public slack channel</a>
- send an email to <a href="mailto:weave-users@weave.works">weave-users@weave.works</a>
- <a href="https://github.com/weaveworks/scope/issues/new">file an issue</a>
Your feedback is always welcome!
## <a name="requirements"></a>Requirements
Scope does not need any configuration and does not require the Weave Network.
Scope does need to be running on every machine you want to monitor.
Scope allows anyone with access to the UI control over your containers: as
such, the Scope app endpoint (port 4040) should not be made accessible on
the Internet. Additionally traffic between the app and the probe is currently
insecure and should not traverse the internet.
Scope will periodically check with our servers to see if a new version is
available. To disable this, run:
```
CHECKPOINT_DISABLE=true scope launch
```
For more information, [read this](https://github.com/weaveworks/go-checkpoint).
## <a name="architecture"></a>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 | | |
| | +-------------+ | |
| | | |
| +-----------------+ |
+-----------------------+
```
## <a name="using-weave-scope-in-standalone-mode"></a>Using Weave Scope in Standalone Mode
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 achieves
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:
```
# scope 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.
## <a name="using-weave-scope-in-cloud-service-mode"></a>Using Weave Scope in Cloud Service Mode
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=<token>
```
```
.-~~~-.
.- ~'` )_ ___
/ `-' )_
| scope.weave.works \
\ .'
~-______________..--'
^^
||
||
+--Docker host----------+ || +--Docker host----------+
| +--Container------+ | || | +--Container------+ |
| | | | || | | | |
| | +-------------+ | | / \ | | +-------------+ | |
| | | scope-probe |-----' '-----| scope-probe | | |
| | +-------------+ | | | | +-------------+ | |
| | | | | | | |
| +-----------------+ | | +-----------------+ |
+-----------------------+ +-----------------------+
```
## <a name="launching-weave-scope-and-compose-in-cloud-service-mode"></a>Launching Weave Scope and Docker Compose in Cloud Service Mode
The SCOPE_SERVICE_TOKEN is found when you [log in to the Scope service](https://scope.weave.works/) - launch Docker Compose with one of the two fragments below and the value of the token set as an environment variable:
SCOPE_SERVICE_TOKEN=abcdef_my_token docker-compose up -d
### Docker Compose format version 2:
version: '2'
services:
probe:
image: weaveworks/scope:0.13.1
network_mode: "host"
pid: "host"
privileged: true
labels:
- "works.weave.role=system"
volumes:
- "/var/run/docker.sock:/var/run/docker.sock:rw"
command:
- "--probe.docker"
- "true"
- "--service-token"
- "${SCOPE_SERVICE_TOKEN}"
### Docker Compose format version 1:
probe:
image: weaveworks/scope:0.13.1
net: "host"
pid: "host"
privileged: true
labels:
- "works.weave.role=system"
volumes:
- "/var/run/docker.sock:/var/run/docker.sock:rw"
command:
- "--probe.docker"
- "true"
- "--service-token"
- "${SCOPE_SERVICE_TOKEN}"
## <a name="using-weave-scope-with-amazon-ecs"></a>Using Weave Scope with Amazon's EC2 Container Service
We currently provide three options for launching Weave Scope in ECS:
* A [CloudFormation template](https://www.weave.works/deploy-weave-aws-cloudformation-template/) to launch and easily evaluate Scope directly from your browser.
* An [Amazon Machine Image (AMI)](https://github.com/weaveworks/integrations/tree/master/aws/ecs#weaves-ecs-amis) for each ECS region.
* [A simple way to tailor the AMIs to your needs](https://github.com/weaveworks/integrations/tree/master/aws/ecs#creating-your-own-customized-weave-ecs-ami).
## <a name="using-weave-scope-with-kubernetes"></a>Using Weave Scope with Kubernetes
Scope comes with built-in Kubernetes support. We recommend to run Scope natively
in your Kubernetes cluster using
[these resource definitions](https://github.com/helm/charts/tree/master/weavescope/manifests).
1. Make sure your cluster allows privileged pods (required by the Scope
probes). Privileged pods are allowed by default from Kubernetes 1.1.
If you are running an earlier version or a non-default configuration,
make sure your API Server and all your Kubelets are provided with flag `--allow_privileged`
at launch time.
2. Make sure
[DaemonSets](https://github.com/kubernetes/kubernetes/blob/master/docs/design/daemon.md)
are enabled in your cluster (enabled by default from
Kubernetes 1.2). DaemonSets are needed to ensure that each Kubernetes node
runs a Scope Probe:
* To enable DaemonSets in an existing cluster, make sure to add a
`--runtime-config=extensions/v1beta1/daemonsets=true` argument to the
[apiserver](https://github.com/kubernetes/kubernetes/blob/master/docs/admin/kube-apiserver.md)'s configuration
(normally found at `/etc/kubernetes/manifest/kube-apiserver.manifest`) followed by a
[restart of the apiserver and controller manager](https://github.com/kubernetes/kubernetes/issues/18656).
* If you are creating a new cluster, set `KUBE_ENABLE_DAEMONSETS=true` in
your cluster configuration.
* Note that prior to Kubernetes version 1.2 DaemonSets would fail to schedule pods on
unschedulable nodes (typically the master). This will result in the probe
not running on that node. See [#1030](https://github.com/weaveworks/scope/issues/1030)
for more information. We advise you to use Kubernetes version 1.2 or higher.
3. Download the resource definitions:
```
for I in app-rc app-svc probe-ds; do
curl -s -L https://raw.githubusercontent.com/helm/charts/master/weavescope/manifests/scope-$I.yaml -o scope-$I.yaml
done
```
4. Tweak the Scope probe configuration at `scope-probe-ds.yaml`, namely:
* If you have an account at
[http://scope.weave.works](http://scope.weave.works) and want to use Scope
in Cloud Service Mode, uncomment the `--probe.token=foo` argument,
substitute `foo` by the token found in your account page, and comment out
the `$(WEAVE_SCOPE_APP_SERVICE_HOST):$(WEAVE_SCOPE_APP_SERVICE_PORT)`
argument.
5. Install Scope in your cluster (order is important):
```
kubectl create -f scope-app-rc.yaml # Only if you want to run Scope in Standalone Mode
kubectl create -f scope-app-svc.yaml # Only if you want to run Scope in Standalone Mode
kubectl create -f scope-probe-ds.yaml
```
6. Open Scope in your browser
* When running Scope in Standalone mode do:
```
kubectl port-forward $(kubectl get pod --selector=provider=weave-scope-app -o jsonpath={.items..metadata.name}) 4040
```
and open [http://localhost:4040](http://localhost:4040) in your browser. This allows you to access the Scope UI securely, without
opening it to the Internet.
* When running Scope in Cloud Service mode, simply log in to [https://scope.weave.works](https://scope.weave.works)
## <a name="probe_plugins"></a>Scope Probe Plugins
Scope allows you to create plugins generating custom
metrics. Those metrics will be displayed in the Scope UI.
Here is an annotated screenshot of Scope while executing a plugin which extracts
incoming HTTP request rates of your application without instrumenting it.
<img src="imgs/plugin.png" width="400" alt="Scope Probe plugin screenshot" align="center">
You can read more about Scope Probe plugins and find some examples
[here](https://github.com/weaveworks/scope/tree/master/examples/plugins).
## <a name="developing"></a>Developing
Building Scope from source depends on the latest version of
[docker](https://www.docker.com/), so please install that before
proceeding.
The main build is `make`, which builds the UI build container, builds
the UI in said container, builds the backend build container, builds
the app and probe in said container, and finally pushes the lot into
a Docker image called **weaveworks/scope**.
```
make
```
Then, run the local build via
```
./scope launch
```
If needed, install tools used for managing dependencies, managing releases, and doing coverage analysis via
```
make deps
```
Note that the tools from `make deps` will depend on a local install of
[Go](https://golang.org).
## <a name="developing"></a>Debugging
Scope has a collection of built-in debugging tools to aid Scope developers.
- To get debug information in the logs launch Scope with `--debug`:
```
scope launch --debug
docker logs weavescope
```
- To have the Scope App or Scope Probe dump their goroutine stacks, run:
```
kill -QUIT $(pgrep -f scope-(app|probe))
docker logs weavescope
```
- The Scope Probe is instrumented with various counters and timers. To have it dump those values, run:
```
kill -USR1 $(pgrep -f scope-probe)
docker logs weavescope
```
Both the Scope App and the Scope Probe offer [HTTP endpoints with profiling information](https://golang.org/pkg/net/http/pprof/).
These cover things such as CPU usage and memory consumption:
- The Scope App enables its HTTP profiling endpoints by default, which
are accessible on the same port the Scope UI is served (4040).
- The Scope Probe doesn't enable its profiling endpoints by default.
To enable them, you must launch Scope with `--probe.http.listen addr:port`.
For instance, launching Scope with `scope launch --probe.http.listen :4041`, will
allow you access the Scope Probe's profiling endpoints on port 4041.
Then, you can collect profiles in the usual way. For instance:
- To collect the memory profile of the Scope App:
```
go tool pprof http://localhost:4040/debug/pprof/heap
```
- To collect the CPU profile of the Scope Probe:
```
go tool pprof http://localhost:4041/debug/pprof/profile
```
If you don't have `go` installed, you can use a Docker container instead:
- To collect the memory profile of the Scope App:
```
docker run --net=host -v $PWD:/root/pprof golang go tool pprof http://localhost:4040/debug/pprof/heap
```
- To collect the CPU profile of the Scope Probe:
```
docker run --net=host -v $PWD:/root/pprof golang go tool pprof http://localhost:4041/debug/pprof/profile
```
You will find the output profiles in your working directory. To analyse the dump, do something like:
```
go tool pprof prog/scope pprof.localhost\:4040.samples.cpu.001.pb.gz
Entering interactive mode (type "help" for commands)
(pprof) pdf >cpu.pdf
```

85
site/building.md Normal file
View File

@@ -0,0 +1,85 @@
---
title: Developing and Debugging
menu_order: 90
---
The following topics are discussed:
* [Developing](#developing)
* [Debugging](#debugging)
* [Profiling](#profiling)
## <a name="developing"></a>Developing
Building Scope from source depends on the latest version of [docker](https://www.docker.com/), so please install that before proceeding.
The build process is automated using `make`, which builds the UI build container, builds the UI in said container, builds the backend build container, builds the app and probe in said container, and finally pushes the lot into a Docker image called **weaveworks/scope**.
make
Then, run the local build via:
./scope launch
If needed, install the tools used for managing dependencies, managing releases, and doing coverage analysis via:
make deps
>**Note:** The tools from `make deps` depend on a local install of
[Go](https://golang.org).
## <a name="debugging"></a>Debugging
Scope has a collection of built-in debugging tools to aid Scope developers.
To get debug information in the logs launch Scope with `--debug`:
scope launch --debug
docker logs weavescope
To have the Scope App or Scope Probe dump their goroutine stacks, run:
kill -QUIT $(pgrep -f scope-(app|probe))
docker logs weavescope
The Scope Probe is instrumented with various counters and timers. To have it dump those values, run:
kill -USR1 $(pgrep -f scope-probe)
docker logs weavescope
## <a name="profiling"></a>Profiling
Both the Scope App and the Scope Probe offer [HTTP endpoints with profiling information](https://golang.org/pkg/net/http/pprof/).
These cover things such as CPU usage and memory consumption:
* The Scope App enables its HTTP profiling endpoints by default, which are accessible on the same port the Scope UI is served (4040).
* The Scope Probe doesn't enable its profiling endpoints by default. To enable them, you must launch Scope with `--probe.http.listen addr:port`. For instance, launching Scope with `scope launch --probe.http.listen :4041`, will allow you access the Scope Probe's profiling endpoints on port 4041.
Then, you can collect profiles in the usual way. For instance:
To collect the memory profile of the Scope App:
go tool pprof http://localhost:4040/debug/pprof/heap
To collect the CPU profile of the Scope Probe:
go tool pprof http://localhost:4041/debug/pprof/profile
If you don't have `go` installed, you can use a Docker container instead:
To collect the memory profile of the Scope App:
docker run --net=host -v $PWD:/root/pprof golang go tool pprof http://localhost:4040/debug/pprof/heap
To collect the CPU profile of the Scope Probe:
docker run --net=host -v $PWD:/root/pprof golang go tool pprof http://localhost:4041/debug/pprof/profile
You will find the output profiles in your working directory.

50
site/features.md Normal file
View File

@@ -0,0 +1,50 @@
---
title: Feature Overview
menu_order: 15
---
Browse the current feature set for Scope with links to relevant indepth topics:
* [Topology Mapping](#topology-mapping)
* [Flexible Filtering](#flexible-filtering)
* [Powerful Search](#powerful-search)
* [Real-time App and Container Metrics](#real-time-app-and-container-metrics)
* [Interact With and Manage Containers](#interact-with-and-manage-containers)
* [Troubleshoot Apps](#troubleshoot-apps)
##<a name="topology-mapping"></a>Topology Mapping
Scope builds logical topologies of your application and infrastructure. A topology is a collection of nodes and edges, where nodes can represent objects like processes, container or hosts. In Scope, edges represent TCP connections between nodes. Scope displays an intelligent map of your app, so that different node types can be easily viewed and specific microservices can be drilled down on and inspected.
!['Automatic Topology Mapping'](images/topology.png)
##<a name="flexible-view-filtering"></a>Flexible Filtering
Nodes can be filtered by various properties, for example in the Container view, you can filter by System Containers vs Application Containers or by Stopped vs. Running Containers. Scope can also display various metrics such as CPU and Memory usage in the nodes, for example allowing you to easily find the container using the most CPU or memory. Mouse-over any of the nodes to view its filtered metric at a glance.
###<a name="powerful-search"></a> Powerful Search
Powerful search capability enables you to find node types, containers and processes by name, label or even path. The search functionality supports simple operands so that you can for example, find processes consuming a certain Memory limit or nodes using too much CPU. You can also stack filters to create custom, complex search criterion.
!['Stack Filters'](images/search-python.png)
##<a name="real-time-app-and-container-metrics"></a>Real-time App and Container Metrics
View contextual metrics, tags and metadata for your containers. Effortlessly navigate between processes inside your container to the hosts that your containers run on, arranged in expandable, sortable tables.
Choose an overview of your container infrastructure, or focus on a specific microservice. Identify and correct issues to ensure the stability and performance of your containerized applications.
##<a name="interact-with-and-manage-containers"></a>Interact With and Manage Containers
Interact with your containers directly: pause, restart and stop containers without having to leave the Scope browser window.
##<a name="troubleshoot-apps"></a>Troubleshoot Apps
A convenient terminal window is provided that enables you to interact with your app and to troubleshoot and diagnose any issues all within the same context.
##<a name="generate-custom-metrics-using-the-plugin-api"></a>Generate Custom Metrics using the Plugin API
Scope includes a Plugin API, so that custom metrics may be generated and integrated with the Scope UI.
For information on how to generate your own metrics in Scope, see [Generating Custom Metrics with Plugins](/site/plugins.md).

92
site/how-it-works.md Normal file
View File

@@ -0,0 +1,92 @@
---
title: Understanding Weave Scope
menu_order: 70
---
The following topics are discussed:
* [Service Mode](#scope-reporting-in-service-mode)
* [Stand-alone Mode](#scope-reporting-in-stand-alone-mode)
* [Managing Clusters with Scope and weaveDNS](#managing-clusters-with-scope-and-weavedns)
Weave Scope consists of two components: the app and the probe. The components are deployed as a single Docker container using the scope script. The probe is responsible for gathering information about the host on which it is running. This information is sent to the app in the form of a report. The app processes reports from the probe into usable topologies, serving the UI, as well as pushing these topologies to the UI.
+--Docker host----------+
| +--Container------+ | .---------------.
| | | | | Browser |
| | +-----------+ | | |---------------|
| | | scope-app |<---------| |
| | +-----------+ | | | |
| | ^ | | | |
| | | | | '---------------'
| | +-------------+ | |
| | | scope-probe | | |
| | +-------------+ | |
| | | |
| +-----------------+ |
+-----------------------+
##<a name="stand-alone-mode"></a>Standalone Mode
When running Scope in a cluster, each probe sends its reports to a dedicated app. The app merges the reports from its probe into a comprehensive report that is sent to the browser. To visualize your entire infrastructure and apps running on that infrastructure, Scope must be launched on to every machine you are using.
+--Docker host----------+ +--Docker host----------+
| +--Container------+ | | +--Container------+ |
| | | | | | | |
| | +-----------+ | | | | +-----------+ | |
| | | scope-app |<-----. .----->| scope-app | | |
| | +-----------+ | | \ / | | +-----------+ | |
| | ^ | | \/ | | ^ | |
| | | | | /\ | | | | |
| | +-------------+ | | / \ | | +-------------+ | |
| | | scope-probe |-----' '-----| scope-probe | | |
| | +-------------+ | | | | +-------------+ | |
| | | | | | | |
| +-----------------+ | | +-----------------+ |
+-----------------------+ +-----------------------+
## <a name="service-mode"></a>Service Mode
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, the probe is run locally and the apps are hosted for you.
.-~~~-.
.- ~'` )_ ___
/ `-' )_
| scope.weave.works \
\ .'
~-______________..--'
^^
||
||
+--Docker host----------+ || +--Docker host----------+
| +--Container------+ | || | +--Container------+ |
| | | | || | | | |
| | +-------------+ | | / \ | | +-------------+ | |
| | | scope-probe |-----' '-----| scope-probe | | |
| | +-------------+ | | | | +-------------+ | |
| | | | | | | |
| +-----------------+ | | +-----------------+ |
+-----------------------+ +-----------------------+
To register with the service, go to [scope.weave.works](https://scope.weave.works), enter your email address and wait for the confirmation email that contains your service token.
![`Weave Scope` Early Access Form](images/scope-early-access.png)
>**Note**: Candidates for the Early Access Program are evaluated on a case per case basis. It may take a few days before you receive a confirmation email. To accelerate the process, please send an email to `help@weave.works` which explains your use-case.
The service token is also accessible from the Scope as a Service main page after you've logged in:
![Weave Scope Configure Your App](images/scope-cloud-main-page.png)
##Disabling Automatic Updates
Scope periodically checks with our servers to see if a new version is available. You can disable this by setting:
CHECKPOINT_DISABLE=true scope launch
For more information, see [Go Checkpoint](https://github.com/weaveworks/go-checkpoint).
**See Also**
* [Installing Weave Scope](/site/installing.md)

BIN
site/images/automatic-topologies-grouping.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 124 KiB

BIN
site/images/cloudformation-launch-stack.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.8 KiB

BIN
site/images/contextual-details.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 161 KiB

BIN
site/images/microservices-under-control.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 164 KiB

BIN
site/images/plugin-features.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 100 KiB

BIN
site/images/plugin.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 85 KiB

BIN
site/images/scope-cloud-main-page.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 472 KiB

BIN
site/images/scope-early-access.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 574 KiB

BIN
site/images/search-python.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 116 KiB

BIN
site/images/topologies.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 126 KiB

BIN
site/images/topology.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 127 KiB

240
site/installing.md Normal file
View File

@@ -0,0 +1,240 @@
---
title: Installing Weave Scope
menu_order: 20
---
Weave Scope consists of three parts: the probe, the app and the user interface. It can be deployed either as a standalone configuration, or if you don’t want to manage the administration yourself, you can sign up for Weave Scope as a service.
The following topics are discussed:
* [Installing Scope on Docker](#docker)
* [In Service Mode](#docker-service)
* [Using Weave Net](#docker-weave)
* [Using Docker Compose](#docker-compose)
* [Using Docker Compose in Service Mode](#docker-compose-sercice)
* [Installing Scope on Kubernetes](#k8s)
* [Installing Scope on Amazon ECS](#ecs)
* [Installing Scope on Mesosphere DC/OS](#dcos)
##<a name="docker"></a>Installing Scope on Docker
To install Scope on your local Docker machine in Standalone Mode, run the following commands:
sudo wget -O /usr/local/bin/scope https://git.io/scope
sudo chmod a+x /usr/local/bin/scope
sudo scope launch
This script downloads and runs a recent Scope image from the Docker Hub. Scope needs to be installed onto every machine that you want to monitor. Once launched, Scope doesn’t require any other configuration and it also doesn’t depend on Weave Net.
After it’s been launched, open your browser to `http://localhost:4040`.
>**Note:** If you're using boot2docker, replace localhost with the output of boot2docker IP.
> Scope allows anyone with access to the UI control over your containers: as such, the Scope app endpoint (port 4040) should not be made accessible on the Internet. Additionally traffic between the app and the probe is currently insecure and should also not traverse the Internet.
###<a name="docker-service"></a>In Service Mode
To install Scope on your local Docker machine in Service Mode, run the following commands:
sudo wget -O /usr/local/bin/scope https://git.io/scope
sudo chmod a+x /usr/local/bin/scope
sudo scope launch --service-token=<token>
Where `--service-token=<token>` is the token that was sent to you when you signed up.
This script downloads and runs a recent Scope docker image from the Docker Hub. Scope needs to be installed onto every machine that you want to monitor. Once launched, Scope doesn’t require any other configuration and it also doesn’t depend on Weave Net.
After it’s been launched, open your web browser to [scope.weave.works](https://scope.weave.works) and login using your email. Click on 'My Scope' in the top right-hand corner to see the Scope UI.
###<a name="docker-weave"></a> Using Weave Net
If Scope is running on the same machine as the Weave Network, then the probe uses weaveDNS to automatically discover any other apps on the network. Scope does this by registering itself under the address scope.weave.local.
Each probe sends its reports to every app registered at this address. If you have weaveDNS set up and running, no further steps are necessary.
If you don’t want to use weaveDNS, then Scope can be instructed to cluster with other Scope instances on the command line. Hostnames and IP addresses are acceptable, both with and without ports, for example:
# scope 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.
###<a name="docker-compose"></a>Using Docker Compose
To install Scope on your local Docker machine in Standalone Mode using Docker Compose, run the following commands using one of the two fragments below.
docker-compose up -d
Scope needs to be installed onto every machine that you want to monitor. Once launched, Scope doesn’t require any other configuration and it also doesn’t depend on Weave Net.
After it’s been launched, open your browser to `http://localhost:4040`.
**Docker Compose Format Version 1:**
probe:
image: weaveworks/scope:0.15
net: "host"
pid: "host"
privileged: true
labels:
- "works.weave.role=system"
volumes:
- "/var/run/docker.sock:/var/run/docker.sock:rw"
command:
- "--probe.docker"
- "true"
**Docker Compose Format Version 2:**
version: '2'
services:
probe:
image: weaveworks/scope:0.15
network_mode: "host"
pid: "host"
privileged: true
labels:
- "works.weave.role=system"
volumes:
- "/var/run/docker.sock:/var/run/docker.sock:rw"
command:
- "--probe.docker"
- "true"
Version 2 of this YAML file supports networks and volumes as defined by any plugins you might be using. See [Compose File Reference](https://docs.docker.com/compose/compose-file/) for more information.
###<a name="docker-compose"></a>Using Docker Compose in Service Mode
To install Scope on your local Docker machine in Service Mode using Docker Compose, run the following commands using one of the two fragments below.
SCOPE_SERVICE_TOKEN=<token> docker-compose up -d
Where `SCOPE_SERVICE_TOKEN=<token>` is the token that was sent to you when you signed up.
Scope needs to be installed onto every machine that you want to monitor. Once launched, Scope doesn’t require any other configuration and it also doesn’t depend on Weave Net.
After it’s been launched, open your web browser to [scope.weave.works](https://scope.weave.works) and login using your email. Click on 'My Scope' in the top right-hand corner to see the Scope UI.
**Docker Compose Format Version 1:**
probe:
image: weaveworks/scope:0.15
net: "host"
pid: "host"
privileged: true
labels:
- "works.weave.role=system"
volumes:
- "/var/run/docker.sock:/var/run/docker.sock:rw"
command:
- "--probe.docker"
- "true"
- "--service-token"
- "${SCOPE_SERVICE_TOKEN}"
**Docker Compose Format Version 2:**
version: '2'
services:
probe:
image: weaveworks/scope:0.15
network_mode: "host"
pid: "host"
privileged: true
labels:
- "works.weave.role=system"
volumes:
- "/var/run/docker.sock:/var/run/docker.sock:rw"
command:
- "--probe.docker"
- "true"
- "--service-token"
- "${SCOPE_SERVICE_TOKEN}"
Version 2 of this YAML file supports networks and volumes as defined by any plugins you might be using. See [Compose File Reference](https://docs.docker.com/compose/compose-file/) for more information.
##<a name="k8s"></a>Installing Scope on Kubernetes
To install Scope on a Kubernetes cluster in Standalone Mode, follow these instructions:
**Before You Begin**
Ensure that the cluster allows privileged pods - this is required by the Scope probes. By default, privileged pods are allowed from Kubernetes 1.1 and up. If you are running an earlier version or a non-default configuration, ensure that your API Server and all of your Kubelets are launched with the flag `--allow_privileged`.
Your cluster must also support [DaemonSets](https://github.com/kubernetes/kubernetes/blob/master/docs/design/daemon.md). DaemonSets are necessary to ensure that each Kubernetes node can run a Scope Probe.
To enable DaemonSets in an existing cluster, add the `--runtime-config=extensions/v1beta1/daemonsets=true` argument to the [apiserver](https://github.com/kubernetes/kubernetes/blob/master/docs/admin/kube-apiserver.md)'s configuration. This is normally found in the `/etc/kubernetes/manifest/kube-apiserver.manifest`file after a restart of [the apiserver and controller manager](https://github.com/kubernetes/kubernetes/issues/18656) has occurred. If you are creating a new cluster, set `KUBE_ENABLE_DAEMONSETS=true` in your cluster configuration.
>**Note:** Prior to Kubernetes version 1.2 DaemonSets would fail to schedule pods on unschedulable nodes (typically the master). This will result in the probe not running on that node. See [#1030](https://github.com/weaveworks/scope/issues/1030) for more information. It is advised that you use Kubernetes version 1.2 or higher.
**Install Scope on Your Cluster**
It is recommended that you run Scope natively in your Kubernetes cluster using the manifest generator service.
The simplest way to get the latest release of Scope deployed onto a Kubernetes cluster is the following:
```
kubectl create -f 'https://scope.weave.works/k8s-gen/weavescope.json' --validate=false
```
Allowable parameters:
- `v` - Weave Scope version or tag, e.g. `latest` or `0.15.0`, current release is the default
- `service-token` - Weave Scope Cloud Service token
- `k8s-service-type` - Kubernetes service type (for running Scope in Standalone mode), can be either
`LoadBalancer` or `NodePort`, by default this is unspecified (only internal access)
To download the Scope manifest, use the YAML version of the manifest, since it is easier to read, for example:
```
curl --silent --remote-name https://scope.weave.works/k8s-gen/weavescope.yaml
```
kubectl create -f https://git.io/scope-k8s
This runs a recent Scope image from the Docker Hub and will launch a probe onto every node as well as a single app. Once launched, Scope doesn’t require any other configuration and it also doesn’t depend on Weave Net.
**Open Scope in Your Browser**
kubectl port-forward --namespace=kube-system $(kubectl get pod --namespace=kube-system --selector=name=weave-scope-app -o jsonpath={.items..metadata.name}) 4040
Open http://localhost:4040 in your browser. This allows you to access the Scope UI securely, without opening it to the Internet.
##<a name="ecs"></a>Installing Scope on Amazon ECS
There are currently three options for launching Weave Scope in ECS:
* A [CloudFormation template](https://www.weave.works/deploy-weave-aws-cloudformation-template/) to launch and easily evaluate Scope directly from your browser.
* An [Amazon Machine Image (AMI)](https://github.com/weaveworks/integrations/tree/master/aws/ecs#weaves-ecs-amis) for each ECS region.
* [A simple way to tailor the AMIs to your needs](https://github.com/weaveworks/integrations/tree/master/aws/ecs#creating-your-own-customized-weave-ecs-ami).
The AWS CloudFormation template is the easiest way to get started with Weave Net and Weave Scope. CloudFormation templates provide developers and systems administrators a simple way to create a collection or a stack of related AWS resources, and it provisions and updates them in an orderly and predictable fashion.
Use this specially created Weaveworks CloudFormation template to create an EC2 instance with all of the resources you need, including Weave Net and Weave Scope.
Before launching the stack:
* [Set up an Amazon Account](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/get-set-up-for-amazon-ec2.html)
* [Create the Key Pairs]("http://docs.aws.amazon.com/gettingstarted/latest/wah/getting-started-prereq.html). You will need to reference the name of the key pairs when you create the stack.
The link below will launch a sample app using a Cloudformation template, but you can swap out the IdentiOrca app and use your own app instead.
**Ready to launch a stack?  Click here to launch a stack to AWS:**
[![](images/cloudformation-launch-stack.png)](https://console.aws.amazon.com/cloudformation/home#/stacks/new?templateURL=https:%2F%2Fs3.amazonaws.com%2Fweaveworks-cfn-public%2Fintegrations%2Fecs-identiorca.json)
For step by step instructions on how to configure the stack, see: [Install Weave to AWS with One-Click](https://www.weave.works/deploy-weave-aws-cloudformation-template/)
##<a name="dcos"></a>Installing Scope as a DC/OS Package
Scope can be installed as a DC/OS Package through the open Universe.
DC/OS is short for Datacenter Operating System, a distributed operating system using Apache Mesos as its kernel. The easiest way to get start with DC/OS in the public-cloud is to [deploy it on Amazon Web Services (AWS)](https://mesosphere.com/amazon/).
For more information see, [Deploying Weave Scope on DC/OS](https://www.weave.works/guides/deploy-weave-scope-dcos/)
**See Also**
* [Understanding Weave Scope](/site/how-it-works.md)

66
site/introducing.md Normal file
View File

@@ -0,0 +1,66 @@
---
title: Introducing Weave Scope
menu_order: 10
---
Weave Scope is a visualization, and monitoring tool for Docker and Kubernetes. It provides a top down view into your app as well as your entire infrastructure, and allows you to diagnose any problems with your distributed containerized app, in real time, as it being deployed to a cloud provider.
To install Scope on your local Docker machine, run the following commands:
sudo wget -O /usr/local/bin/scope https://git.io/scope
sudo chmod a+x /usr/local/bin/scope
sudo scope launch
Scope can be used in standalone mode, where you deploy it locally onto your hosts, or you can use Weave Scope in Service Mode. Scope can be depoloyed to Kubernetes, DCOS and ECS cluster. See [Installing Weave Scope](/site/installing.md) for more information.
##Getting Microservices Under Control
Microservices-based architecture poses significant challenges when deployed to Docker containers in the cloud. Microservices tend to be dynamic with many distributed components, which can make monitoring difficult. But with Weave Scope, visualizing network bottlenecks, troubleshooting CPU consumption and memory leaks is simplified. With Views, you can quickly examine various metrics about your containerized app.
!['Microservices Under Control'](images/microservices-under-control.png)
##Automatic Topologies and Intelligent Grouping
Weave Scope generates a map of your processes, containers and hosts, so that you can understand, monitor, and control your applications.
It uses established APIs (for example: /proc, conntrack, the Docker API etc.) to gather information about the hosts on which it is running. And it does this without any modifications to your application or needing a custom kernel module.
Information collected by Weave Scope’s probes is used to build a topology of the applications and the containers running on the hosts. Reports are generated locally by the probe (agent) and then sent to the app via HTTP, where they are merged and processed to form cluster-wide views.
!['Automatic Topologies and Intelligent Grouping'](images/automatic-topologies-grouping.png)
Intelligently group nodes to help diagnose problems in your app as well as to clarify and model its infrastructure set up. For example, you can use the Docker ‘containers-grouped-by-hostname’ view to identify and dedupe replicas of containers that back multiple services, and show which services within your Docker infrastructure are in communication.
##Developer Friendly: Contextual Details and Metrics
Drill down on nodes in any topology, and view contextual details for your containers, hosts and processes. Metrics have been brought front and center, the tags and metadata user interface redefined with the children of your container/host arranged in expandable, sortable tables. For example, the container consuming the most CPU or memory on a given host can be determined quickly with just a few clicks.
!['Developer Friendly: Contextual Details and Metrics'](images/contextual-details.png)
Weave Scope accumulates and stores 15-second sparklines of metrics such as memory and CPU usage, These provide a snapshot so that you can quickly understand how your containers are performing.
You can drill up and down between the various topologies that Scope natively understands. This enables you to easily navigate from containers, to hosts, processes, images, pods and services - and back again.
Scope can display metrics from Weave Net, Docker Containers, and the Linux Kernel.
##Real-time Container Monitoring
With Weave Scope you can control the entire container lifecycle across your cluster hosts from a single UI. Start, stop, pause and restart containers from the details panel, and toggle filters for stopped containers in the containers view.
Controlling Scope containers goes beyond simple lifecycle operations. Scope can also attach and exec. Attach executes a Docker attach against the container and lets you interact with it live. Exec runs a shell in the container so that you can debug your running app in real-time.
##Orchestrator Aware and Cloud Integrations
Weave Scope can visualize your app within:
* Docker Datacenter
* Kubernetes
* Amazon ECS
**See Also**
* [Installing Weave Scope](/site/installing.md)
* [Feature Overview](/site/features.md)

73
site/k8s/scope.yaml Normal file
View File

@@ -0,0 +1,73 @@
apiVersion: v1
kind: List
items:
- apiVersion: v1
kind: ReplicationController
metadata:
name: weavescope-app
namespace: kube-system
labels:
name: weavescope-app
spec:
replicas: 1
template:
metadata:
labels:
provider: weavescope-app
spec:
containers:
- name: weavescope-app
image: weaveworks/scope:0.15
args:
- --no-probe
- --app.weave.addr=
ports:
- containerPort: 4040
hostPort: 4040
- apiVersion: v1
kind: Service
metadata:
name: weavescope-app
namespace: kube-system
spec:
type: LoadBalancer
ports:
- name: app
port: 4040
selector:
name: weavescope-app
- apiVersion: extensions/v1beta1
kind: DaemonSet
metadata:
name: weavescope-probe
namespace: kube-system
spec:
template:
metadata:
name: weavescope-probe
spec:
hostPID: true
hostNetwork: true
containers:
- name: weavescope-probe
image: weaveworks/scope:0.15
args:
- --no-app
- --probe.docker=true
- --probe.kubernetes=true
- --probe.weave.addr=
- --probe.docker.bridge=docker0
- --probe.resolver=$(KUBE_DNS_SERVICE_HOST):$(KUBE_DNS_SERVICE_PORT)
- weave-scope-app.kube-system.svc.cluster.local:4040
securityContext:
privileged: true
resources:
limits:
cpu: 50m
volumeMounts:
- name: docker-sock
mountPath: /var/run/docker.sock
volumes:
- name: docker-sock
hostPath:
path: /var/run/docker.sock

79
site/plugins.md Normal file
View File

@@ -0,0 +1,79 @@
---
title: Generating Custom Metrics with Plugins
menu_order: 80
---
The following topics are discussed:
* [Listening Protocol](#listening-protocol)
* [Reporting](#reporting)
* [Interfaces](#interfaces)
With a Scope probe plugin, you can insert custom metrics into Scope and have them display in the user interface together with the Scope's standard set of metrics.
![Custom Metrics With Plugins](images/plugin-features.png)
You can find some examples in [the example plugins](https://github.com/weaveworks/scope/tree/master/examples/plugins) directory.
There are currently two different examples:
* A [Python plugin](https://github.com/weaveworks/scope/tree/master/examples/plugins/http-requests) using [bcc](http://iovisor.github.io/bcc/) to extract incoming HTTP request rates per process, without any application-level instrumentation requirements and negligible performance toll (metrics are obtained in-kernel without any packet copying to userspace).
>**Note:** This plugin needs a [recent kernel version with ebpf support](https://github.com/iovisor/bcc/blob/master/INSTALL.md#kernel-configuration). It will not compile on current [dlite](https://github.com/nlf/dlite) and boot2docker hosts.
* A [Go plugin](https://github.com/weaveworks/scope/tree/master/examples/plugins/iovisor), using [iostat](https://en.wikipedia.org/wiki/Iostat) to provide host-level CPU IO wait metrics.
The example plugins are run by calling `make` in their directory. This builds the plugin, and immediately runs it in the foreground. To run the plugin in the background, see the `Makefile` for examples of the `docker run ...` command.
If the running plugin was picked up by Scope, you will see it in the list of `PLUGINS` in the bottom right of the UI.
## <a id="listening-protocol"></a>Listening Protocol
All plugins must listen for HTTP connections on a Unix socket in the `/var/run/scope/plugins` directory. The Scope probe recursively scans that directory every 5 seconds, to look for any sockets being added (or removed). It is also valid to put the plugin Unix socket into a sub-directory, in case you want to apply some permissions, or store any other information with the socket.
When a new plugin is detected, the scope probe begins requesting reports from it via `GET /report`.
All plugin endpoints are expected to respond within 500ms, and respond in the JSON format.
### <a id="reporting"></a>Reporting
When the Scope probe discovers a new plugin Unix socket, it begins to periodically make a `GET` request to the `/report` endpoint. The report data structure returned from this will be merged into the probe's report and sent to the app. An example of the report structure can be viewed at the `/api/report` endpoint of any Scope app.
In addition to any data about the topology nodes, the report returned from the plugin must include some metadata about the plugin itself.
For example:
```json
{
"Processes": {},
"Plugins": [
{
"id": "iowait",
"label": "IOWait",
"description": "Adds a graph of CPU IO Wait to hosts",
"interfaces": ["reporter"],
"api_version": "1",
}
]
}
```
> **Note:** The `Plugins` section includes exactly one plugin description. The plugin description fields are: `interfaces` including `reporter`.
The fields are:
* `id` is used to check for duplicate plugins. It is required.
* `label` is a human readable plugin label displayed in the UI. It is required.
* `description` is displayed in the UI
* `interfaces` is a list of interfaces which this plugin supports. It is required, and must equal `["reporter"]`.
* `api_version` is used to ensure both the plugin and the scope probe can speak to each other. It is required, and must match the probe.
### <a id="interfaces"></a>Interfaces
Currently the only interface a plugin can fulfill is `reporter`.
**See Also**
* [Building Scope](/site/building.md)