From e9e3b5d5c04d2df15e50a7fbdf26be843b3be52c Mon Sep 17 00:00:00 2001 From: Alessandro Puccetti Date: Thu, 29 Sep 2016 19:09:50 +0200 Subject: [PATCH] docs/plugins: Refactoring The plugins README now points to the new repositories in the weaveworks-plugins organization (https://github.com/weaveworks-plugins). --- examples/plugins/README.md | 73 ++++++++++++++------------------------ 1 file changed, 27 insertions(+), 46 deletions(-) diff --git a/examples/plugins/README.md b/examples/plugins/README.md index 0dc0e2467..6b3e762cb 100644 --- a/examples/plugins/README.md +++ b/examples/plugins/README.md @@ -1,39 +1,28 @@ # Scope Probe Plugins -Scope probe plugins let you insert your own custom metrics into Scope -and get them displayed in the UI. +Scope probe plugins let you insert your own custom data and controls into Scope and display them in the UI. +The list of the current running plugins is displayed next to the label `PLUGINS` in the bottom right of the UI. Scope Probe plugin screenshot -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: -* 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/iowait), - using [iostat](https://en.wikipedia.org/wiki/Iostat) to provide - host-level CPU IO wait or idle metrics. +## Official Plugins -The example plugins can be run by calling `make` in their directory. -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. +You can find all the official plugins at [Weaveworks Plugins](https://github.com/weaveworks-plugins). -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. +* [IOWait](https://github.com/weaveworks-plugins/scope-iowait): a Go plugin using [iostat](https://en.wikipedia.org/wiki/Iostat) to provide host-level CPU IO wait or idle metrics. -## Plugin ID +* [HTTP Statistics](https://github.com/weaveworks-plugins/scope-http-statistics): A Python plugin using [bcc](http://iovisor.github.io/bcc/) to track multiple metrics about HTTP per process, without any application-level instrumentation requirements and negligible performance toll. This plugin is a work in progress, as of now it implements two metrics (for more information read the [plugin documentation](https://github.com/weaveworks-plugins/scope-http-statistics)): + * Number of HTTP requests per seconds. + * Number of HTTP responses code per second (per code). + +* [Traffic Control](https://github.com/weaveworks-plugins/scope-traffic-control): This plugin allows the user to modify latency and packet loss for a specific container via buttons in the UI's container detailed view. + +## Plugins Internals +This section explains the fundamental parts of the plugins structure necessary to understand how a plugin communicates with Scope. +You can find more practical examples in [Weaveworks Plugins](https://github.com/weaveworks-plugins) repositories. + +### Plugin ID Each plugin should have an unique ID. It is forbidden to change it during the plugin's lifetime. The scope probe will get the plugin's ID @@ -42,7 +31,7 @@ from the plugin's socket filename. For example, the socket named `my-plugin`. IDs can only contain alphanumeric sequences, optionally separated with a dash. -## Plugin registration +### Plugin registration All plugins should listen for HTTP connections on a unix socket in the `/var/run/scope/plugins` directory. The scope probe will recursively @@ -51,19 +40,18 @@ scan that directory every 5 seconds, to look for sockets being added sub-directory, in case you want to apply some permissions, or store other information with the socket. -## Protocol +### Protocol There are several interfaces a plugin may (or must) implement. Usually implementing an interface means handling specific requests. These requests are described below. -### Reporter interface +#### Reporter interface -Plugins _must_ implement the reporter interface. Implementing this -interface means listening for HTTP requests at `/report`. +Plugins _must_ implement the reporter interface because Scope uses it to discover which other interfaces the plugin implements. +Implementing this interface means listening for HTTP requests at `/report`. -Add the "reporter" string to the `interfaces` field in the plugin -specification. +**Note**: Plugins must add the "reporter" string to the `interfaces` field in the plugin specification even though this interface is implicitly implemented. #### Report @@ -80,12 +68,12 @@ For example: ```json { - "Processes": {}, + ..., "Plugins": [ { - "id": "iowait", - "label": "IOWait", - "description": "Adds a graph of CPU IO Wait to hosts", + "id": "plugin-id", + "label": "Human Friendly Name", + "description": "Plugin's brief description", "interfaces": ["reporter"], "api_version": "1", } @@ -106,14 +94,7 @@ description. The plugin description fields are: * `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. -You may notice a small chicken and egg problem - the plugin reports to -the scope probe what interfaces it supports, but the scope probe can -learn that only by doing a `GET /report` request which will be handled -by the plugin if it implements the "reporter" interface. This is -solved (or worked around) by requiring the plugin to always implements -the "reporter" interface. - -### Controller interface +#### Controller interface Plugins _may_ implement the controller interface. Implementing the controller interface means that the plugin can react to HTTP `POST`