Writing a plugin

PATHspider is written to be extensible and the plugins that included in the PATHspider distribution are only examples of the measurements that PATHspider can perform.

The exact specification of plugins is defined in pathspider.base.ISpider, though much of the functionality required is implemented by the abstract pathspider.base.Spider class which plugins should inherit.

Required Functions

In order to write a plugin you will need to produce implementations for the following: config_zero, config_one, connect and merge.

Optionally, you can provide pre_connect and post_connect.

Configurator

These functions perform global changes that may be required between performing the baseline (A) and the experimental (B) configurations. The changes may be a call to sysctl, changes via netfilter or a call to a robot arm to reposition the satellite array. In the event that global state changes are not required, these can be implemented as no-ops.

An example implementation of these methods can be found in ecnspider3:

ECNSpider.config_zero()[source]

Disables ECN negotiation via sysctl.

ECNSpider.config_one()[source]

Enables ECN negotiation via sysctl.

(Pre-,Post-)Connection

The pre-connection function will run only once, and the result of the pre-connection operation will be available to both runs of the connection and post-connection functions.

If you require to pass different values depending on the configuration, you can perform two operations in the pre-connect function, returning a tuple, and selecting the value to use based on the configuration in the later functions.

An example implementation of these methods can be found in ecnspider3:

ECNSpider.connect(job, pcs, config)[source]

Performs a TCP connection.

ECNSpider.post_connect(job, conn, pcs, config)[source]

Close the socket gracefully.

Merging

The merge function will be called for every job and given the job record and the observer record. The merge function is then to return the final record to be recorded in the dataset for the measurement run.

Warning

It is possible for the Observer to return a NO_FLOW object in some circumstances, where the flow has not been observed. Any implementation must handle this gracefully.

An example implementation of this method can be found in ecnspider3:

ECNSpider.merge(flow, res)[source]

Merge flow records.

Includes the configuration and connection success or failure of the socket connection with the flow record.

Plugin Template

A template plugin is available in the plugins that ship with the PATHspider distribution:

class templatespider.TemplateSpider[source]

A template PATHspider plugin.

ISpider Interface

PATHspider will expect the following functions and attributes to be available in any plugin:

interface pathspider.base.ISpider[source]

The ISpider interface defines the expected interface for PATHspider plugins.

worker(self, worker_number)
create_observer(self)
activate(self, worker_count, libtrace_uri)
shutdown(self)
config_one(self)
terminate(self)
configurator(self)
add_job(self, job)
start(self)
merge(self, flow, res)
config_zero(self)
exception_wrapper(self, target, *args, **kwargs)
pre_connect(self, job)
connect(self, job, pcs, config)
post_connect(self, job, conn, pcs, config)
merger(self)