Anatomy of a plugin

This page describes the general anatomy of a plugin, and its (simplified) execution in Hansken.

The plugin itself

Each plugin must implement two methods:

pluginInfo(): This method returns information about the plugin.
process(): This method performs the extraction task of the plugin.

Lets dive a bit deeper into these methods in the next sections!

The method `pluginInfo()`

The pluginInfo() method returns a PluginInfo object. Hansken needs this object to be able to know the capabilities of the plugin, and to show the plugin in the list of tools. The most important fields that must be set on PluginInfo are the following:

id          | The identifier of the plugin. This will be used as a unique name for the plugin Hansken.            |
description | A description of the plugin that is shown in Hansken.                                               |
author      | The author of the plugin that is shown in Hansken.                                                  |
license     | The type of license of the plugin that is shown in Hansken.                                         |
matcher     | This matcher is used by Hansken to determine which Traces are sent to the Plugin during extraction. |

The method `process()`

During extraction, Hansken calls the process() method for every matching trace. The matcher attribute of the PluginInfo is very important as it determines which traces will be sent to the process method.

Although the plugin developer is free to program whatever seems useful, the following tasks are typically performed within the process() method:

Creating child-traces
Reading trace properties
Adding trace properties
Reading the data that the Trace represents
Writing data on a Trace

Depending on the type of plugin that is implemented, different functionality is available in the process() method. See Plugin Types for more details.

The execution in Hansken

This describes the process of running a plugin from the perspective of Hansken. The perspective of the user is described in Hansken Extraction Plugins.

Plugin discovery

Hansken manages a list of tools that can be used in extractions. The available plugins must be added to this list so that the user can select them. To accomplish this, Hansken scans the Docker registry for docker images that are plugins. Each image is started up, and a call is done to its pluginInfo() method. If the call resulted in a valid PluginInfo object, the Extraction Plugin is added to the list of tools visible to users. After the PluginInfo is retrieved, the docker image is shutdown again.

Starting an extraction

Hansken checks if any plugins are selected by the user that started the extraction. For each selected plugin, at least one docker image will be started. See Kubernetes autoscaling for more details on expanding the number of instances for each plugin.

Extracting

During an extraction, Hansken will iteratively loop through all selected tools, including Extraction Plugins. For each trace that matches on a tool, Hansken will call its process method. For Extraction Plugins, this means that the process method is called via the gRPC protocol. The trace to be processed is sent over gRPC to the plugin, and any other communication between Hansken and the Extraction Plugin (like created properties and child traces, search requests and written data) are done using gRPC.

Finishing an extraction

At the end of an extraction, Hansken will stop all associated plugins.