Create a custom alert action script
Alert action script workflow
The script executes the alert action, such as sending an email or connecting to a web resource. To execute the alert action, the script follows a workflow to get information about the triggered alert and run the alert action.
Typically, the script's workflow looks like this:
- Check the execution mode, based on command line arguments.
- Read configuration payload from
- Run the alert action.
Executable files recognized for introspection
There are several types of executable files recognized for introspection.
|Recognized file types|
| *Nix platforms|
| Windows platforms|
About the execution mode
When the alert action is triggered, the script receives one command line argument, which is the string
--execute. This argument indicates the execution mode. Your script should check for the
--execute argument. Additional execution modes might be added to this interface.
About the script configuration payload
alert_actions.conf file and
savedsearches.conf file define the content of the configuration payload. Upon startup, the script reads the configuration from the payload. Developers typically create the configuration files before writing the script because of this dependency. The configuration file format is usually XML, but can be JSON if specified in
The configuration payload contains:
- Global information about the system
- Information about the triggered alert and search
* Saved search name
* Path to file containing the search results
* URL to the search results
- Alert action configuration
* This configuration contains the merged parameters of
- The first search result
Script runtime threshold
The script runs separately for each triggered alert. It should have a brief execution time and terminate once the alert action execution completes. The script is forcefully terminated if the runtime exceeds its runtime threshold. The default runtime threshold is 5 minutes.
Script naming guidelines
The name of the script should be the same as in its
alert_actions.conf stanza. You can add an optional file name extension. For example,
myapp/bin/myalertaction.py corresponds to
alert_actions.conf. For more information, see alert_actions.conf.
Where to place the script or executable
Place the script or executable in the following directory:
Override a script with
Developers can use the
alert.execute.cmd option to override the filename of the script to execute. You can use a custom binary and executed arguments for more flexibility. Create a stanza and place the path file and arguments in
[myjavaaction] . . . alert.execute.cmd = java.path alert.execute.cmd.arg.0 = -jar alert.execute.cmd.arg.1 = $SPLUNK_HOME/etc/apps/myapp/bin/my.jar alert.execute.cmd.arg.2 = --execute
Script override considerations
- If you use a custom path file and arguments, make sure that the stanza name in
- If you use the
alert.execute.cmdsettings to specify a command to execute, the arguments are also overridden and not appended.
--executeis not added unless manually specified,
- The external process starts with the arguments exactly as specified in the
.path file for a custom binary
As shown in the example above, specify a
.path file for
alert.execute.cmd in the custom alert action's
alert_actions.conf stanza. Absolute paths are not supported for
alert.execute.cmd, although they can be used for its arguments. You can also use environment variables, such as
$SPLUNK_HOME$ inside the
You can provide an architecture-specific version of a custom alert action script or executable by placing the appropriate version in the corresponding architecture-specific
/bin directory for the app. Architecture-specific directories are available for these Intel-based architectures:
- Apple (darwin)
Only use a platform-specific directory when it is a requirement for that architecture. If you place a script in an architecture-specific directory, the script runs the appropriate version of the script. Otherwise, a platform-neutral version of the script runs in the default
/linux_x86/bin/[myscript] /linux_x86_64/bin/[myscript] /darwin_x86/bin/[myscript] /darwin_x86_64/bin/[myscript]
Set up custom alert configuration files
Define a custom alert action user interface
This documentation applies to the following versions of Splunk® Enterprise: 6.4.0, 6.4.1, 6.4.2, 6.4.3, 6.4.4, 6.4.5, 6.4.6, 6.4.7, 6.4.8, 6.5.0, 6.5.1, 6.5.1612 (Splunk Cloud only), 6.5.2, 6.5.3, 6.5.4, 6.5.5, 6.6.0, 6.6.1, 6.6.2, 6.6.3