
Configure a script for an alert action
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, Splunk Enterprise passes positional arguments to the script that capture information about the alert. The positional arguments are also available as environment variables.
You can access the 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 that 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.
For an example of how to configure scripts to work with alerts, see the topic "Send SNMP traps to other systems," in this manual.
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 Splunk Enterprise.
- 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 to 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.
Troubleshoot scripts launched from an alert
The Splunk Community Wiki has a topic, Troubleshooting alert scripts, that can help you configure and troubleshoot scripts launched from an alert.
PREVIOUS Configure alerts in savedsearches.conf |
NEXT Send SNMP traps to other systems |
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
Comments
Took me a while to figure out, that the sessionKey passed on stdin is urlencoded. Maybe you should add a hint in the documentation.
Thank you, @Lweber. This is now noted above.