Python classes for custom search commands

The Splunk SDK for Python includes a splunklib.searchcommands module for creating custom search commands. You can download the Splunk SDK for Python on GitHub.

Module structure

The core of the search commands module contains four classes:

  • EventingCommand: Defines a search command that applies a transformation to search results as they travel through the events pipeline. Examples of eventing commands include sort, dedup, and cluster.
  • GeneratingCommand: Defines a search command that generates event records based on command arguments. Examples of generating commands include search (at the beginning of the pipeline), inputcsv, input lookup, and metadata.
  • ReportingCommand: Defines a search command that processes search results and generates a reporting data structure. Examples of reporting commands include stats, top, and timechart.
  • StreamingCommand: Defines a search command that applies a transformation to search results as they travel through the processing pipeline. Examples of streaming commands include search, eval, and where.

Use the following helper classes:

  • The Configuration class removes the need to manually configure the commands.conf file by enabling you to dynamically configure commands in your code.
  • The Option class removes the need to parse and validate search command arguments manually by enabling you to include them as a required or optional property.

EventingCommand class

The EventingCommand class is the base class for dataset processing commands that filter results arriving at a search head from one or more search peers as they travel through the events pipeline.

Eventing commands typically filter, group, order, or augment event records. Examples of eventing commands from the built-in Splunk Enterprise command set include sort_, dedup_, and cluster_. Each execution of an eventing command should produce a set of event records that is independently usable by downstream processors.

GeneratingCommand class

The GeneratingCommand class defines a search command that generates events based on command arguments.

Implement a generate method as a generator function that yields dict or list(dict) instances. Generating commands receive no input, and must be the first command in the pipeline. By default, Splunk Enterprise runs your command locally on a search head.

@Configuration()

You can change the default behavior by specifying that the events should be streamed, as follows:

@Configuration(streaming=True)

Splunk Enterprise runs the command locally (by default) or remotely on one or more indexers (if you've specified streaming). If you only want Splunk Enterprise to run the command locally on a search head, and not remotely on indexers, specify the following:

@Configuration(streaming=True, local=True)

If your generating command produces event records in time order, specify the following:

@Configuration(generates_timeorder=True)

ReportingCommand class

The ReportingCommand class defines a search command that processes search results and generates a reporting data structure. Reporting search commands run as either reduce or map/reduce operations.

You can implement a map method as a generator function that iterates over a set of event records and yields dict or list(dict) instances. Configure the map operation using a Configuration decorator on the ReportingCommand.map method, and configure it as described in StreamingCommand.

StreamingCommand class

The StreamingCommand class defines a search command that applies a transformation to search results as they travel through the processing pipeline.

Implement a stream method as a generator function that iterates over a set of event records and yields dict or list(dict) instances.

Streaming commands typically filter, augment, or update search result records. By default, Splunk Enterprise runs a streaming command locally on a search head or remotely on one or more indexers. If you only want Splunk Enterprise to run the streaming command locally on a search head, and not remotely on indexers, specify the following:

@Configuration(local=True)

If your streaming command modifies the time order of event records, specify the following:

@Configuration(overrides_timeorder=True)