Step 0: Understanding the types of commands
You can think of Splunk custom search commands as specialized command components within Splunk apps that understand your unique needs.
Each command has a specific type that serves as the boundary of how it can work and interact with other commands. Here are the different types:
- Streaming commands: Process results in one event at a time, applying transformations individually.
- Transforming commands: Arrange results into a data table for statistical analysis.
- Generating commands: Retrieve information from indexes without modifications.
- Dataset processing commands: Require the complete dataset before execution.
From here, let's take everything in steps - by completing the 4 easy steps below, you'll have a functioning custom search command.
Step 1: Setting up your Splunk environment
Let's first get the Splunk home directory under control.
$SPLUNK_HOME
is an environment variable used in various places and it depends on where you have installed Splunk Enterprise on your machine. Please set it to the right directory before continuing.
-
On Linux or macOS: Open a terminal window and type
echo $SPLUNK_HOME
. -
On Windows: Open a Command Prompt window and type
echo %SPLUNK_HOME%
.
Now in order to execute a custom command, we must first have Splunk Enterprise running. Please download the most recent version of Splunk Enterprise.
After downloading and unpacking, you can launch Splunk via the terminal by executing:
$SPLUNK_HOME/bin/splunk start
After this is successful, Splunk Enterprise will be available at http://localhost:8000 in your browser.
To create an app, open the above page and navigate to Manage Apps
, click the Create app
button, and enter your app's name along with some additional information like folder name, version, author and description.
By pressing "Save!", you'll now have a Splunk app and can access the app's directory at $SPLUNK_HOME/etc/apps/my_cutom_command_app/
.
Now that we have a container for custom commands, you must choose a programming language to write the code of the command in.
Python is the most popular language used among Splunk developers and we'll be using that going forward, but you can also use Java - the choice is yours!
Step 2: Writing the script for your command
Let's assume our custom command name is my_custom_command
.
Now that the entire environment for the custom command has been configured, we need to create a script for it at $SPLUNK_HOME/etc/my_cutom_command_app/bin/my_custom_command.py
. Note that the name of the script (the .py
file) is the same as the command name - this is not required, but good practice.
For writing the script we need the Splunk Enterprise SDK for Python, which you can copy and paste into the following folder:
$SPLUNK_HOME/etc/my_cutom_command_app/bin/splunklib
Below are examples of each of the different types of commands - streaming, transforming, generating and data processing. Pick one and move on to the next step.
You can also feel free to modify the code to play around with it right now.
Streaming
import sys
from splunklib.searchcommands import dispatch, StreamingCommand, Configuration
@Configuration()
class CustomCommand(StreamingCommand):
def stream(self, events):
for event in events:
yield event
dispatch(CustomCommand, sys.argv, sys.stdin, sys.stdout, __name__)
Reporting / Transforming
import sys
from splunklib.searchcommands import dispatch, ReportingCommand, Configuration
@Configuration()
class CustomCommand(ReportingCommand):
@Configuration()
def map(self, events):
pass
def reduce(self, events):
pass
dispatch(CustomCommand, sys.argv, sys.stdin, sys.stdout, __name__)
Generating
import sys
from splunklib.searchcommands import dispatch, GeneratingCommand, Configuration
@Configuration()
class CustomCommand(GeneratingCommand):
def generate(self):
pass
dispatch(CustomCommand, sys.argv, sys.stdin, sys.stdout, __name__)
Eventing / Data Processing
import sys
from splunklib.searchcommands import dispatch, EventingCommand, Configuration
@Configuration()
class CustomCommand(EventingCommand):
def transform(self, events):
pass
dispatch(CustomCommand, sys.argv, sys.stdin, sys.stdout, __name__)
Step 3: Tell Splunk about it
Now how does Splunk know we made a custom command? We register it within our app with two config files - commands.conf and searchbnf.conf. Create these files in your app's default directory.
commands.conf
path & content:
$SPLUNK_HOME/etc/apps/my_custom_app/default/commands.conf
[my_custom_command]
python.version = python3
filename = my_custom_command.py
chunked = true
searchbnf.conf
path & content:
$SPLUNK_HOME/etc/apps/my_custom_app/default/searchbnf.conf
[my_custom_command-command]
syntax = [my_custom_command]
shortdesc = [A short description of your custom command]
usage = public
Step 4: Restart Splunk and test it
We can now restart Splunk to apply the new configuration using this command.
$SPLUNK_HOME/bin/splunk restart
You can also do this directly from the UI via Setting > Server Controls > Restart Splunk
.
Now you can test it in the "Search and Reporting" app with this SPL command:
index=_internal | my_custom_command
Congratulations! You've successfully created a custom search command in your Splunk app. Now you can enhance and modify the script based on your specific use case.
Bonus: You can check out the Splunk-app-examples which is a treasure chest of ready-made templates and inspiration for your Splunk custom search commands.
Happy Splunking!
Top comments (0)