Custom Alert Integration

To integrate alerts with external monitoring and notification systems, Lenses provides a simple plugin approach.

If your particular monitoring system is not supported by Lenses out of the box, this guide will walk you through the process of integrating it via a custom plugin.

Implementation

The implementation of an alerting plugin involves building a JAR that contains classes implement the Lenses alert plugin API. This API is defined by the lenses-alert-plugin-api artifact.

So the first step to implement a plugin is to setup the build process for your chosen JVM-based language, setting dependency on this API (and any other client libraries for your integration). It is also recommended to build your plugin into a single JAR containing all these dependencies to ease installation.

Once you have the build process setup, you need to implement the entry point into your plugin, which is a class implementing io.lenses.alerting.plugin.javaapi.AlertingPlugin

AlertingPlugin

In essence, this interface needs to provide metadata on your plugin to Lenses:

  • name - the name of the integration.
  • description - longer paragraph of text describing the integration.
  • configKeys - description of the configuration values that can be passed in.

Then the main method (Try<AlertingService> init(Map<String, String> config)) is where you return a configured instance of your integration - or fail returning an exception.

When configured to use your plugin, Lenses will instantiate your AlertingPlugin, and then obtain an instance of your integration by passing any configuration via the init method.

The configured instance of your integration must implement io.lenses.alerting.plugin.javaapi.AlertingService

AlertingService

This interface also provides metadata to Lenses:

  • name - the name of the integration.
  • description - longer paragraph of text describing the integration.
  • displayedInformation - configuration values that should be displayed in Lenses UI.

And contains the main method for handling an alert (Try<Alert> publish(Alert alert)), which can also fail to return an exception.

This is where you will integrate with your external service using appropriate client APIs.

Examples

The lenses-alert-plugin repository contains the code for the official plugins which serve as examples of how to write a plugin.

Installation

The installation of your plugin requires two things:

  • installation of the plugin JARs, such that they are picked up by Lenses - see Plugins section.
  • configuration, so that the alert system uses your plugin - see Alerting Plugins section.