Introduction to custom search commands

Custom search commands are user-defined Splunk Search Processing Language (SPL) commands that extend SPL to serve your specific needs. Although Splunk Enterprise ships with an extensive set of search commands, it is possible that these existing commands do not meet your exact requirements. Custom search commands enable you to perform additional data analysis in Splunk. You can implement custom search commands by creating Python scripts.

You can create the following types of SPL commands.

  • Eventing commands
  • Generating commands
  • Reporting commands
  • Streaming commands
To learn more about different types of search commands in Splunk, see Types of commands in the Search Manual.

How custom search commands work

Custom search commands process data through an external Python script that runs alongside splunkd at search time.

  1. Splunk parses each line of SPL and determines whether the search command is custom. Custom search commands are designated by a stanza in the commands.conf file.
  2. If the search command is custom, Splunk executes the external Python script for the command.
  3. Splunk pipes search results through this Python script in chunks via STDIN and writes them out over STDOUT.
  4. After processing through the custom search command Python script, search results re-enter the main search pipeline.

The following diagram illustrates how search results exit and then re-enter the search pipeline for a custom search command.

This diagram shows the search pipeline for a custom search command. Data exits the main pipeline to process through an external Python script.

Throughout the custom search command process, splunkd and the custom search command Python script exchange metadata through a series of getinfo and execute commands.

  1. splunkd sends the getinfo command to request information, including the command type and required fields, from the custom search command script.
  2. splunkd sends a separate execute command for each chunk of search results in the pipeline.
  3. The custom search command script processes each chunk of search results.
  4. The script sends a response back to splunkd.

After all search results have passed through the external search command script, splunkd closes the STDIN pipe to terminate the process.

Workflow for creating custom search commands

Use the following workflow to create a custom search command.

  1. Create a new app in Splunk Enterprise.
    Custom search commands work best as a separate app in Splunk Enterprise.
  2. Inside of your app, create a Python script for your search command.
  3. Register the search command.
  4. Enable search assistant text for the search command.
  5. Package and deploy the app.
  6. Modify the app and access control settings.

Tools for creating custom search commands

The Splunk SDK for Python contains the following tools to help you create a custom search command. You can download the Splunk SDK for Python on GitHub.

Python classes

The splunklib.searchcommands module of the Splunk SDK for Python includes the classes that you need to create a custom search command. The specific class that you use depends on the type of command that you want to create.

For more information about how to use these classes, see Python classes for custom search commands.
For details about the splunklib.searchcommands module in the SDK, see splunklib.searchcommands on GitHub.

Examples

The examples/searchcommands_app directory of the Splunk SDK for Python contains a sample app with examples for each type of custom search command.

For more information about these examples, see Custom search command examples.

 

Templates

The Splunk SDK for Python includes templates to help you get started writing your custom search command script. The template that you use depends on the type of command that you want to create.

The following templates are located in the examples/searchcommands_template/bin directory of the SDK.

  • filter.py: A template for filtering (eventing) commands
  • generate.py: A template for generating commands
  • report.py: A template for reporting commands
  • stream.py: A template for streaming commands

To download the templates from the SDK, see examples/searchcommands_template/bin on GitHub.

Next Steps

See Create a custom search command.