Alerting Manual

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.

1. Create a script, logIt that calls logger, or any other program that writes to syslog.
   Place the script in $SPLUNK_HOME/bin/scripts.
2. Add the following in logIt:
   
   logger $5
   
   The script can access any of the arguments available when called as an alert action.
   
   
3. 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.

1. Create the following batch file, logIt.bat.
   Place the script in $SPLUNK_HOME/bin/scripts.
2. Include the following command in the batch file:
   @echo off
   EVENTCREATE /T ERROR /SO Splunk /D %SPLUNK_ARG_5%
   Use the type that best suits the message contained in the argument. This example uses ERROR.
   
   
3. 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.