# Log Filter Plugins

# About

Log Filter plugins provide a way to process logging output from commands, scripts and other workflow step types. They can filter the output (remove, add, modify), or they can be used to capture or convert the output. They can also add metadata to the logs, or emit new log data.

Log Filter plugins implement the LogFilterPlugin (opens new window) interface, and provider the LogFilter service.

# Behavior

Users creating Workflows can configure Log Filter plugins within their workflow in two ways:

  1. At the top level, applying to all steps in the workflow
  2. At a step level, applying only to specific step(s).

# Java Plugin Type

  • Note: Refer to Java Development for information about developing a Java plugin for Rundeck.

The plugin interface is LogFilterPlugin (opens new window). You can use the PluginLoggingContext (opens new window) to get the data context and add data to it via the Output context.

When the top level, or step level is ready, all configured Log Filter plugins will be initialized using the optional init method.

For each log event emitted within the configured level, each configured Log Filter plugin will have its handleEvent method called, in order, with a LogEventControl (opens new window) instance. The LogEventControl can be used to get or modify the content of the LogEvent (opens new window) (message, type, level, metadata). It can also control how the log event is handled:

  • emit: the log should be emitted
  • quell: the log should be futher processed, but not emitted in the final log
  • quiet: the final loglevel should be set to VERBOSE
  • remove: the log event should not be processed further

# Groovy LogFilter

Create a groovy script that calls the rundeckPlugin method and passes the LogFilterPlugin as the type of plugin:

import com.dtolabs.rundeck.plugins.logging.LogFilterPlugin
    //plugin definition

To define metadata about your plugin, and configuration properties, see the Plugin Development - Groovy Plugin Development chapter.

The LogFilterPlugin Groovy DLS supports these closure definitions:

  • init initialization for the plugin (optional)
  • handleEvent handle a log event (required)
  • complete complete the log filter processing after all events have been handled (optional)

Closure descriptions:


 * Called to initialization the plugin with the context
init { PluginLoggingContext context, Map configuration ->
    //perform initialization


 * Called to initialization the plugin with the context
handleEvent { PluginLoggingContext context, LogEventControl event, Map configuration ->
    //handle the event


 * Called to complete the plugin processing
complete { PluginLoggingContext context, Map configuration ->

# Localization

For the basics of plugin localization see: Plugin Development - Plugin Localization.

# Example

Several built-in plugins are listed here:

# Example Groovy plugins

See https://github.com/rundeck/rundeck/tree/master/examples/example-groovy-log-filter-plugins (opens new window).