Splunk® Enterprise

Alerting Manual

Download manual as PDF

This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

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.

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

Thank you, @Lweber. This is now noted above.

Frobinson splunk, Splunker
November 4, 2015

Took me a while to figure out, that the sessionKey passed on stdin is urlencoded. Maybe you should add a hint in the documentation.

Lweber
November 4, 2015

Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters