Configure a script for an alert action
The run a script alert action is officially deprecated. It has been replaced with custom alert actions as a more scalable and robust framework for integrating custom actions. See Using custom alert actions for information on building customized alert actions that can include scripts. |
If you have Splunk Enterprise, you can configure an alert to run a shell script or batch file when the alert triggers. This topic shows how to access information about an alert in a script that runs as an alert action.
The script or batch file that an alert triggers must be at either of the following locations:
$SPLUNK_HOME/bin/scripts $SPLUNK_HOME/etc/apps/<AppName>/bin/scripts
Working directories for scripts
Specify an absolute path whenever a path is needed. If you use relative paths, it is important to remember that they are rooted in the Search and Reporting app's bin
folder.
Access arguments to scripts that are run as an alert action
When you run a script as an alert action, positional arguments that capture alert information are passed to the script. The positional arguments are also available as environment variables.
You can access information from each argument using the notation in the following table.
Arg | Environment Variable | Value |
---|---|---|
0 | SPLUNK_ARG_0 | Script name |
1 | SPLUNK_ARG_1 | Number of events returned |
2 | SPLUNK_ARG_2 | Search terms |
3 | SPLUNK_ARG_3 | Fully qualified query string |
4 | SPLUNK_ARG_4 | Name of report |
5 | SPLUNK_ARG_5 | Trigger reason
For example, "The number of events was greater than 1." |
6 | SPLUNK_ARG_6 | Browser URL to view the report. |
7 | SPLUNK_ARG_7 | Not used for historical reasons. |
8 | SPLUNK_ARG_8 | File in which the results for the search are stored.
Contains raw results in gzip file format. |
You can reference the information captured by these arguments in UNIX shell scripts or Microsoft batch files, as shown below. In other languages, such as perl and python, use the methods native to the language to access script arguments.
# UNIX scripts can access environment variables and positional args $SPLUNK_ARG_0 $0 # Microsoft batch files capture environment variables reliably %SPLUNK_ARG_0%
Test script that accesses positional arguments
Use the following test script to see the results of accessing the positional arguments.
To use this test script, create an alert that runs the script as an alert action. Then check the contents of the generated echo_output.txt
file:
# $SPLUNK_HOME/bin/scripts/echo.sh # simple script that writes parameters 0-7 to # $SPLUNK_HOME/bin/scripts/echo_output.txt # $SPLUNK_ARG_0 and $0 show how to use the long and short form. read sessionKey echo "'$SPLUNK_ARG_0' '$0' '$1' '$2' '$3' '$4' '$5' '$6' '$7' '$8' '$sessionKey'" >> \ "$SPLUNK_HOME/bin/scripts/echo_output.txt"
- Note: The
sessionKey
is URL encoded.
Script example: Write to syslog
You can configure a script for an alert to write to the system log daemon. This is useful if you have syslog set up to send alerts to other applications and you want to include alerts from your Splunk deployment.
- Create a script,
logIt
that callslogger
, or any other program that writes to syslog.
Place the script in$SPLUNK_HOME/bin/scripts
. - Add the following in
logIt
:logger $5
The script can access any of the arguments available when called as an alert action. - Create an alert on a report that runs
logIt
as an alert action.
When the alert triggers, the log entry looks something like this:Aug 15 15:01:40 localhost logger: Report [j_myadmin]: The number of events(65) was greater than 10
See Best practices for using UDP when configuring a syslog input, a topic in the Splunk Community Wiki.
Script example: Write to the Windows Event Log
For Windows platforms, you can configure an alert action to run a script that writes to the Windows Event Log.
The following example shows a script that calls the EVENTCREATE
utility that writes to the Event log. The script can access any of the environment variables available with an alert. You can substitute the EVENTCREATE utility with any command-line executable that writes to the Event Log.
- Create the following batch file,
logIt.bat
.
Place the script in$SPLUNK_HOME/bin/scripts
. - Include the following command in the batch file:@echo offUse the type that best suits the message contained in the argument. This example uses
EVENTCREATE /T ERROR /SO Splunk /D %SPLUNK_ARG_5%ERROR
. - Create an alert to a report that runs
logIt.bat
as an alert action.
Configure alerts in savedsearches.conf |
This documentation applies to the following versions of Splunk Cloud Platform™: 8.2.2112, 8.2.2201, 8.2.2202, 8.2.2203, 9.0.2205, 9.0.2208, 9.0.2209, 9.0.2303, 9.0.2305, 9.1.2308, 9.1.2312, 9.2.2403 (latest FedRAMP release), 9.2.2406
Feedback submitted, thanks!