Graylog offers various extension points to customize and extend its functionality through writing Java code.
The first step for writing a plugin is creating a skeleton that is the same for each type of plugin. The next chapter is explaining how to do this and will then go over to chapters explaining plugin types in detail.
Graylog comes with a stable plugin API for the following plugin types:
- Inputs: Accept/write any messages into Graylog
- Outputs: Forward ingested messages to other systems as they are processed
- Services: Run at startup and able to implement any functionality
- Alert Conditions: Decide whether an alert will be triggered depending on a condition
- Alert Notifications: Called when a stream alert condition has been triggered
- Processors: Transform/drop incoming messages (can create multiple new messages)
- Filters: (Deprecated) Transform/drop incoming messages during processing
- REST API Resources: An HTTP resource exposed as part of the Graylog REST API
- Periodical: Called at periodical intervals during server runtime
- Decorators: Used during search time to modify the presentation of messages
- Authentication Realms: Allowing to implement different authentication mechanisms (like single sign-on or 2FA)
What you need in your development environment before starting is:
There are lots of different ways to get those on your local machine, unfortunately we cannot list all of them, so please refer to your operating system-specific documentation,
Graylog uses a couple of conventions and techniques in its code, so be sure to read about the API concepts for an overview.
To go along with this documentation, there is a sample plugin on Github. This documentation will link to specific parts for your reference. It is fully functional, even though it does not implement any useful functionality. Its purpose to provide a reference for helping to implement your own plugins.
Creating a plugin skeleton¶
The easiest way to get started is to use our Graylog meta project, which will create a complete plugin project infrastructure will all required classes, build definitions, and configurations. Using the meta project allows you to have the Graylog server project and your own plugins (or 3rd party plugins) in the same project, which means that you can run and debug everything in your favorite IDE or navigate seamlessly in the code base.
We are working on a replacement tool for the
graylog-project meta project, but for the time being it still works.
Maven is a widely used build tool for Java, that comes pre-installed on many operating systems or can be installed using most package managers. Make sure that you have at least version 3 before you go on.
Use it like this:
$ git clone [email protected]:Graylog2/graylog-project.git
This will create a checkout of the meta project in your current work dir. Now change to the
graylog-project directory and execute the step which to download the necessary base modules:
Now you can bootstrap the plugin you want to write from here, by doing:
$ scripts/bootstrap-plugin jira-alarmcallback
It will ask you a few questions about the plugin you are planning to build. Let’s say you work for a company called ACMECorp and want to build an alarm callback plugin that creates a JIRA ticket for each alarm that is triggered:
groupId: com.acmecorp version: 1.0.0 package: com.acmecorp pluginClassName: JiraAlarmCallback
Note that you do not have to tell the archetype wizard what kind of plugin you want to build because it is creating the generic plugin skeleton for you but nothing that is related to the actual implementation. More on this in the example plugin chapters later.
You now have a new folder called
graylog-plugin-jira-alarmcallback that includes a complete plugin skeleton including Maven build files. Every Java IDE
out there can now import the project automatically without any required further configuration.
In IntelliJ IDEA for example you can just use the File -> Open dialog to open the
graylog-project directory as a fully configured Java project, which should include the Graylog server and your plugin as submodules.
Please pay close attention to the README file of the Graylog meta project and follow any further instructions listed there to set up your IDE properly.
If you want to continue working on the command line, you can do the following to compile the server and your plugin:
$ mvn package
The anatomy of a plugin¶
Each plugin contains information to describe itself and register the extensions it contains.
A single plugin can contain multiple extensions to Graylog.
For example a hypothetical plugin might contribute an input, an output and alert notifications to communicate with systems. For convenience this would be bundled in a single plugin registering multiple extensions.
At the very minimum you need to implement two interfaces:
bootstrap-plugin script generates these implementations for you, and you simply need to fill out the details.
Graylog uses Java’s ServiceLoader mechanism to find your plugin’s main class, so if you rename your
Plugin implementation, you need to also adjust the service file.
Please also see Google Guava’s AutoService which Graylog uses in conjunction with the plain ServiceLoader.
In addition to the service, Graylog needs an additional resource file called
graylog-plugin.properties in a special location. This file contains information about the plugin, specifically which classloader the plugin needs to be in, so it needs to be read before the plugin is actually loaded.
Typically you can simply take the default that has been generated for you.
Registering your extension¶
So far the plugin itself does not do anything, because it neither implements any of the available extensions, nor could Graylog know which ones are available from your code.
Graylog uses dependency injection to wire up its internal components as well as the plugins. Thus the extensions a plugin provides need to be exposed as a PluginModule which provides you with a lot of helper methods to register the various available extensions to cut down the boiler plate code you have to write.
An empty module is created for you.
PluginModule exposes a lot of extension points, but not all of them are considered stable API for external use.
If in doubt, please reach out to us on our community support channels.
Web Plugin creation¶
Sometimes your plugin is not only supposed to work under the hoods inside a Graylog server as an input, output, alarm callback, etc. but you also want to contribute previously nonexisting functionality to Graylog’s web interface. Since version 2.0 this is now possible. When using the most recent Graylog meta project to bootstrap the plugin skeleton, you are already good to go for this. Otherwise please see our chapter about Creating a plugin skeleton.
This might be overwhelming at first if you are not accustomed to JS-development, but fortunately we have set up a lot to make writing plugins easier for you!
If you use our proposed way for Creating a plugin skeleton, and followed the part about the Writing Plugins, you are already good to go for building a plugin with a web part. All you need is a running Graylog server on your machine. Everything else is fetched at build time!
Getting up and running with a web development environment is as easy as this:
$ scripts/start-web-dev [...] $ open http://localhost:8080
This starts the development web server. It even tries to open a browser window going to it (probably working on Mac OS X only).
If your Graylog server is not running on
http://localhost:9000/api/, then you need to edit
graylog2-server/graylog2-web-interface/config.js (in your
graylog-project directory) and adapt the
Web Plugin structure¶
These are the relevant files and directories in your plugin directory for the web part of it:
- This is the configuration file for the webpack module bundler. Most of it is already preconfigured by our
PluginWebpackConfigclass, so the file is very small. You can override/extend every configuration option by passing a webpack snippet though.
- In this file you can customize some of the parameters of the build. There is one mandatory parameter named
web_src_pathwhich defines the absolute or relative location to a checkout of the Graylog source repository.
- This is a standard npm JSON file describing the web part of your plugin, especially its dependencies. You can read more about its format.
- This is where the actual code for the web part of your plugin goes to. For the start there is a simple
index.jsxfile, which shows you how to register your plugin and the parts it provides with the Graylog web interface. We will get to this in detail later.
Required conventions for web plugins¶
There is a single file which is the entry point of your plugin, which means that the execution of your plugin starts there. By convention this is src/web/index.jsx. You can rename/move this file, you just have to adapt your webpack configuration to reflect this change, but it is not recommended.
In any case, this file needs to contain the following code at the very top:
// eslint-disable-next-line no-unused-vars import webpackEntry from 'webpack-entry';
This part is responsible to include and execute the webpack-entry file, which is responsible to set up webpack to use the correct URL format when loading assets for this plugin. If you leave this out, erratic behavior will be the result.
Best practices for web plugin development¶
Both the web interface and plugins for it depend on a number of libraries like React, RefluxJS and others. To prevent those getting bundled into both the web interface and plugin assets, therefore wasting space or causing problems (especially React does not like to be present more than once), we extract those into a commons chunk which is reused by the web interface and plugins.
This has no consequences for you as a plugin author, because the configuration to make use of this is already generated for you when using the meta project or the maven archetype. But here are some details about it:
Common libraries are built into a separate
vendor bundle using an own configuration file named webpack.vendor.js. Using the DLLPlugin a manifest is extracted which allow us to reuse the generated bundle. This is then imported in our main web interface webpack configuration file and the corresponding generated webpack config file for plugins.
Building the plugin is easy because the meta project has created all necessary files and settings for you. Just run
mvn package either from the meta project’s directory (to build the server and the plugin) or from the plugin
directory (to build the plugin only):
$ mvn package
This will generate a
.jar file in
target/ that is the complete plugin file:
$ ls target/jira-alarmcallback-1.0.0-SNAPSHOT.jar target/jira-alarmcallback-1.0.0-SNAPSHOT.jar
Installing and loading plugins¶
The only thing you need to do to run the plugin in Graylog is to copy the
.jar file to your plugins folder that is configured in your
graylog.conf. The default is just
plugin/ relative from your
This is a list of default plugin locations for the different installation methods.
|Operating System Packages||
graylog-server and the plugin should be available to use from the web interface immediately.