...
If a plugin named 'PluginName' is available, its parse_enrich function is executed and if successful, the modifications made by the function replace the event properties. Parsing then continues normally.
Parser Plugins
For situations where external input must be incorporated into events at the time of parsing, opEvents 2.2 and newer support user-defined parser plugins (for the generic extensible parser).
The directory install/parser_plugins contains an example plugin called TestPlugin.pm and a README file with documetation.
Requirements
All plugins must be valid Perl (Package) code. The files must be named Something.pm and reside in the directory conf/parser-plugins. Each plugin must have a proper 'package Something;' namespace declaration that matches the file name, and this package namespace must not clash with any existing opEvents or NMIS components. The '1;' line at the end of the file is required.
It's recommended that the plugin have a version declaration right after the package namespace declaration, e.g.. 'our $VERSION = "1.2.3";'
The plugin may load extra Perl modules with 'use', but it must not use any package-level global variables. All its variables and any objects that it might create must have local scope. The plugin must not use Exporter to export anything from its namespace.
Plugin Interface
A plugin must offer a function called parse_enrich or it will be ignored by opEvents.
When triggered by a plugin(SomeName) parser directive, the parse_enrich function of that plugin will be called with two arguments, line and event (in that order).
- Line is the complete log entry/line that is being processed and cannot be modified.
- Event is a hash reference and contains the preliminary live data structure of the event as parsed so far.
Event properties can be changed, added and deleted by the plugin function by modifying this live event hash.
The parse_enrich function must return one of the following:
- 1: to indicate that it succeeded,
- 0 or undef: to indicate that event parsing should be aborted for this line and no event should be created (like the parser directive
ignore), - or any other string value as an error message (which will be logged).
Any changes made to the event properties are ignored unless the function completes successfully and returns 1. This also applies to a crashing parse_enrich function, or if is terminated because it ran over time.
Plugin Configuration
The configuration option opevents_plugin_max_runtime (default: 5 seconds) sets the maximum execution time for a single parse_enrich call. If a plugin's function runs longer than that it is terminated and an error message is logged; any changes that it may have made to the live event datastructure are ignored in this case.
Plugin Activation
A generic extensible parser rule can invoke one or more parser plugins using the action directive plugin(PluginName).
When such a plugin call directive is encountered for the first time, the opEvents daemon loads (and caches) all available plugins that meet the requirements. To reread modified plugins, opeventsd must be restarted.
If a plugin named 'PluginName' is available, its parse_enrich function is executed and if successful, the modifications made by the function replace the event properties. Parsing then continues normally.