mirror of
https://github.com/weaveworks/scope.git
synced 2026-03-05 19:21:46 +00:00
7632e0b3c5
Squash of: * Include plugins in the report * show plugin list in the UI * moving metric and metadata templates into the probe reports * update js for prime -> priority * added retry to plugin handshake * added iowait plugin * review feedback * plugin documentation
58 lines
2.1 KiB
Markdown
58 lines
2.1 KiB
Markdown
# Scope Plugins
|
|
|
|
## <a id="protocol"></a>Protocol
|
|
|
|
All plugins should listen for HTTP connections on a unix socket in the
|
|
`/var/run/scope/plugins` directory. The scope probe will recursively scan that
|
|
directory every 5 seconds, to look for sockets being added (or removed). It is
|
|
also valid to put the plugin unix socket in a sub-directory, in case you want
|
|
to apply some permissions, or store other information with the socket.
|
|
|
|
When a new plugin is detected, the scope probe will conduct a basic
|
|
[Handshake](#handshake) by requesting `GET /`.
|
|
|
|
All plugin endpoints are expected to respond within 500ms, and respond in the JSON format.
|
|
|
|
### <a id="handshake"></a>Handshake
|
|
|
|
When the scope probe discovers a new plugin unix socket it needs to know some
|
|
information about the plugin. To learn this it will make a GET request for the
|
|
`/` endpoint.
|
|
|
|
An example response is:
|
|
|
|
```json
|
|
{
|
|
"name": "iowait",
|
|
"description": "Adds a graph of CPU IO Wait to hosts",
|
|
"interfaces": []string{"reporter"},
|
|
"api_version": "1",
|
|
}
|
|
```
|
|
|
|
The fields are:
|
|
|
|
* `name` is used to check for duplicate plugins, and displayed in the UI
|
|
* `description` is displayed in the UI
|
|
* `interfaces` tells the scope probe which endpoints this plugin supports
|
|
* `api_version` is used to ensure both the plugin and the scope probe can speak to each other
|
|
|
|
### <a id="interfaces"></a>Interfaces
|
|
|
|
Currently the only interface a plugin can fulfill is `reporter`.
|
|
|
|
#### <a id="reporter"></a>Reporter
|
|
|
|
The `reporter` interface allows a plugin to add information into the probe report. This could include more nodes, or new fields on existing nodes.
|
|
|
|
Endpoints:
|
|
|
|
* GET /report
|
|
This endpoint should return a scope probe-style report. For an example of the
|
|
datastructure see `/api/report` on any scope instance. At the moment the plugin
|
|
is limited to adding nodes or fields to existing topologies (Endpoint, Process,
|
|
Container, etc), along with `metadata_templates` and `metric_templates` to
|
|
display more information. For an example of adding a metric to the hosts, see
|
|
[the example iowait
|
|
plugin.](https://github.com/weaveworks/scope/tree/master/example/plugins/iowait)
|