Merge pull request #1339 from weaveworks/fix-plugin-doc

Fix plugins docs

examples/plugins/README.md

@@ -2,6 +2,8 @@
 
 Scope probe plugins let you insert your own custom metrics into Scope and get them displayed in the UI.
 
+<img src="../../imgs/plugin.png" width="800" alt="Scope Probe plugin screenshot" align="center">
+
 You can find some examples at the
 [the example plugins](https://github.com/weaveworks/scope/tree/master/examples/plugins)
 directory. We currently provide two examples:
@@ -9,6 +11,7 @@ directory. We currently provide two examples:
   [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.
+  **Note:** This plugin needs a kernel version 4.3+. 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
@@ -19,6 +22,9 @@ This will build the plugin, and immediately run 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="protocol"></a>Protocol
 
@@ -42,14 +48,13 @@ 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 information about the plugin.
+from the plugin must include some metadata about the plugin itself.
 
 For example:
 
 ```json
 {
-  "Processes: { ... },
-  ...
+  "Processes": {},
   "Plugins": [
     {
       "id":          "iowait",
@@ -62,9 +67,9 @@ For example:
 }
 ```
 
-Note that the "Plugins" section includes exactly one plugin
+Note that the `Plugins` section includes exactly one plugin
 description. The plugin description fields are:
-"interfaces" including "reporter".
+`interfaces` including `reporter`.
 
 The fields are:
 

examples/plugins/iowait/Makefile

@@ -5,7 +5,12 @@ IMAGE=weavescope-iowait-plugin
 UPTODATE=.$(EXE).uptodate
 
 run: $(UPTODATE)
-	docker run --rm -it --privileged -v /var/run/scope/plugins:/var/run/scope/plugins --name $(IMAGE) $(IMAGE) -hostname=$(shell hostname)
+	# --net=host gives us the remote hostname, in case we're being launched against a non-local docker host.
+	# We could also pass in the `-hostname=foo` flag, but that doesn't work against a remote docker host.
+	docker run --rm -it \
+		--net=host \
+		-v /var/run/scope/plugins:/var/run/scope/plugins \
+		--name $(IMAGE) $(IMAGE)
 
 $(UPTODATE): $(EXE) Dockerfile
 	docker build -t $(IMAGE) .

examples/plugins/iowait/main.go

@@ -22,7 +22,7 @@ func main() {
 	)
 	flag.Parse()
 
-	log.Println("Starting...")
+	log.Printf("Starting on %s...\n", *hostID)
 
 	// Check we can get the iowait for the system
 	_, err := iowait()
@@ -80,7 +80,9 @@ func (p *Plugin) Report(w http.ResponseWriter, r *http.Request) {
 				 %q: {
 					 "metrics": {
 						 "iowait": {
-							 "samples": [ {"date": %q, "value": %f} ]
+							 "samples": [ {"date": %q, "value": %f} ],
+							 "min": 0,
+							 "max": 100
 						 }
 					 }
 				 }