Splunk® Enterprise

Search Manual

Download manual as PDF

This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

Write a custom search command

A custom search command is a Python script that reads data in and writes data out.

Search command script requirements

The search command script should be located in the appropriate directory and given a name that follows some basic rules.

Script location
The search command script must be located in the appropriate $SPLUNK_HOME/etc/apps/<app_name>/bin/ directory. Most of the scripts that ship with Splunk Enterprise are associated with the Search & Reporting app and are stored in $SPLUNK_HOME/etc/apps/search/bin. Refer to scripts in that directory for examples.
If you use Splunk Cloud and want to create custom search commands, you must file a Support ticket. You do not have filesystem access to your Splunk Cloud deployment.
Script name
The script name should be the same as the command name that you will invoke in your Splunk search and follow the naming convention <command_name>.py. Search command names can consist of only alphanumeric (a-z and 0-9) characters. New commands should have unique names. The name cannot be the same name of any of the built-in or existing custom commands.

Build the command script using the Splunk SDK for Python

For information about the handing inputs, outputs, and errors with the Splunk SDK for Python, see How to create custom search commands using Splunk SDK for Python on the Splunk dev portal.

After you build the search command script, you must Add the custom command to your Splunk deployment.

Build the command script using the Intersplunk.py SDK

As part of building the script, you need to specify how to handle inputs, send output, and handle errors.

Handling inputs

With the Intersplunk.py SDK, the input to the script should be formatted in pure CSV or in Intersplunk, which is a header section followed by a blank line followed by pure CSV body.

The simplest way to interpret your script input is to use splunk.Intersplunk.readResults, which takes three optional parameters and returns a list of dicts (which represents the list of input events). The optional parameters are input_buf, settings, and has_header.

inputbuf
The inputbuf parameter where to read input from. If the parameter is None, which is the default value, the input is read from sys.stdin.
settings
The settings parameter is expected to be a dict where any information found in the input header is stored. The default value for this parameter is None, which means that no settings are recorded
has_header
The has_header parameter specifics whether or not input header is used. The default value for this parameter is True.

To indicate if your script expects a header, use the enableheader attribute. The default value for the enableheader attribute is True, which means that the input will contain the header section and you are using the Intersplunk format.

If your script does not expect a header section in the input, enableheader is False, you can directly use the Python CSV module to read the input. For example:

import csv

r = csv.reader(sys.stdin)
for l in r:
...

The advantage of using the Python CSV is that you can break at any time in the for loop, and only lines in the input that you had iterated to at that point are read into memory. This leads to much better performance in some use cases.

Sending output

You can also Intersplunk.py SDK to construct your output of the script. splunk.Intersplunk.generateErrorResults takes a string and writes the correct error output to sys.stdout. splunk.Intersplunk.outputResults takes a list of dict objects and writes the appropriate CSV output to sys.stdout.

To output data, add:

splunk.Intersplunk.outputResults(results)

The output of your script is expected to be pure CSV. For an error condition, simply return a CSV with a single "ERROR" column and a single row (besides the header row) with the contents of the message.

Handling errors

The arguments that are passed to your script (in sys.argv) are the same arguments that are used to invoke your custom command in the search language, unless your script has the attribute supports_getinfo = true. The supports_getinfo attribute indicates that the first argument to your script is either __GETINFO__ or __EXECUTE__. This allows you to call the script with the command arguments at parse time to check for syntax errors before any execution of the search. Errors at this time will short circuit any real execution of the search query. If called with __GETINFO__, this also allows you to dynamically specify the properties of your script (such as streaming or not) depending on your arguments.

If your script has the attribute supports_getinfo set to 'true', you should first make a call like:

(isgetinfo, sys.argv) = splunk.Intersplunk.isGetInfo(sys.argv)

This call will strip the first argument from sys.argv and check if you are in GETINFO mode or EXECUTE mode. If you are in GETINFO mode, your script should use splunk.Intersplunk.outputInfo() to return the properties of your script or splunk.Intersplunk.parseError() if the arguments are invalid.

The definition of outputInfo() and its arguments is as follows:

def outputInfo(streaming, generating, retevs, reqsop, preop, timeorder=False)

You can also set these attributes in the commands.conf file. See How to edit a configuration file.

See also

PREVIOUS
About writing custom search commands
  NEXT
Select a location for your custom search command

This documentation applies to the following versions of Splunk® Enterprise: 6.2.0, 6.2.1, 6.2.2, 6.2.3, 6.2.4, 6.2.5, 6.2.6, 6.2.7, 6.2.8, 6.2.9, 6.2.10, 6.2.11, 6.2.12, 6.2.13, 6.2.14, 6.2.15, 6.3.0, 6.3.1, 6.3.2, 6.3.3, 6.3.4, 6.3.5, 6.3.6, 6.3.7, 6.3.8, 6.3.9, 6.3.10, 6.3.11, 6.3.12, 6.3.13, 6.3.14


Comments

Thanks Cphair for your comment. We have started working on the list. I'll make sure that there is a link from here to that list. Appreciate the feedback!

Lstewart splunk, Splunker
September 22, 2015

Can you document clearly, either here or in its own page, exactly which commands are streaming and which are not? I understand the difference, but there are a lot of built-in search commands and it is not always obvious how they behave under the hood.

Cphair
September 21, 2015

Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters