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 by requesting GET /.

All plugin endpoints are expected to respond within 500ms, and respond in the JSON format.

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:

{
	"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

Interfaces

Currently the only interface a plugin can fulfill is reporter.

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.