plugins/

README

Scope Probe Plugins

Scope probe plugins let you insert your own custom metrics into Scope and get them displayed in the UI.

You can find some examples at the the example plugins directory. We currently provide two examples:

• A Python plugin using 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. It will not compile on current dlite and boot2docker hosts.
• A Go plugin, using iostat to provide host-level CPU IO wait metrics.

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.

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.

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 begin requesting reports from it via GET /report.

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

Report

When the scope probe discovers a new plugin unix socket it will begin periodically making 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:

{
  "Processes": {},
  "Plugins": [
    {
      "id":          "iowait",
      "label":       "IOWait",
      "description": "Adds a graph of CPU IO Wait to hosts",
      "interfaces":  ["reporter"],
      "api_version": "1",
    }
  ]
}

Note that 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.

Interfaces

Currently the only interface a plugin can fulfill is reporter.