
Configure scripted alerts
Configure scripted alerts with savedsearches.conf. Use the $SPLUNK_HOME/etc/system/README/savedsearches.conf.example
as an example, or create your own savedsearches.conf
. Edit this file in $SPLUNK_HOME/etc/system/local/
, or your own custom application directory in $SPLUNK_HOME/etc/apps/
. For more information on configuration files in general, see "About configuration files".
Script options
Your alert can trigger a shell script or batch file, which must be located in $SPLUNK_HOME/bin/scripts
. Use the following attribute/value pairs:
action.script = <string>
Splunk currently enables you to pass arguments to scripts both as command line arguments and as environment variables. This is because command line arguments don't always work with certain interfaces, such as Windows.
The values available in the environment are as follows:
SPLUNK_ARG_0
Script nameSPLUNK_ARG_1
Number of events returnedSPLUNK_ARG_2
Search termsSPLUNK_ARG_3
Fully qualified query stringSPLUNK_ARG_4
Name of reportSPLUNK_ARG_5
Trigger reason (for example, "The number of events was greater than 1")SPLUNK_ARG_6
Browser URL to view the reportSPLUNK_ARG_7
Not used for historical reasonsSPLUNK_ARG_8
File in which the results for this search are stored (contains raw results)
These can be referenced in UNIX shell as $SPLUNK_ARG_0
and so on, or in Microsoft batch files via %SPLUNK_ARG_0%
and so on. In other languages (perl, python, and so on), use the language native methods to access the environment.
These values are also available as positional arguments passed on the command line of the script. You can use these as well if they are more convenient. Relatively old versions of Splunk do not provide the environment variables. However, due to platform reasons, they are not entirely reliable in Microsoft Windows.
The command line arguments that Splunk passes to the script are:
0
= Script name1
= Number of events returned2
= Search terms3
= Fully qualified query string4
= Name of report5
= Trigger reason (i.e. "The number of events was greater than 1")6
= Browser URL to view the report7
= This option has been deprecated and is no longer used8
= File where the results for this search are stored (contains raw results)
Note: Splunk encourages Windows users to use the $SPLUNK_ARG_<number>
environment variables when passing arguments to scripts.
If you want to run a script written in a different language (for example PERL, Python, VBScript) you must specify the interpreter you want Splunk to use in the first line of your script, following the #!. For example:
to run a PERL script:
---- myscript.pl ---- #!/path/to/perl ...... ......
to use Python to interpret the script file:
---- myscript.py ----- #!/path/to/python ..... .....
For an example of how to configure scripts to work with alerts, see the topic "Send SNMP traps to other systems," in this manual.
*nix Example
You can configure Splunk to send alerts to syslog. This is useful if you already have syslog set up to send alerts to other applications, and you want Splunk's alerts to be included.
Check the Splunk Wiki for information about the best practices for using UDP when configuring Syslog input.
Write a script that calls logger
(or any other program that writes to syslog). Your script can call any number of the variables your alert returns.
Create the following script and make it executable:
logger $5
Put your script in $SPLUNK_HOME/bin/scripts
.
Now create an alert that calls your script. See "About alerts" in the Alerting Manual for help with alert creation through Splunk Web. You'll need to provide the script filepath.
Note: If you'd rather configure the alert in savedsearches.conf
, see "Configure alerts in savedsearches.conf" in this manual.
Edit your report to call the script. If your script is in $SPLUNK_HOME/bin/scripts
you don't have to specify the full path.
The logit
script logs the trigger reason to syslog:
Aug 15 15:01:40 localhost logger: Report [j_myadmin]: The number of events(65) was greater than 10
Windows Example
If you're running Windows, you can configure Splunk to send an alert to the Windows Event Log.
In this example, write a script that calls the EVENTCREATE
utility (or any other command-line executable that can write to the Event Log). Your script can call any number of the variables your alert returns.
Create the following batch file:
@echo off EVENTCREATE /T ERROR /SO Splunk /D %SPLUNK_ARG_5%
Note: You can use the type that best suits the message contained in the argument, ERROR
is only used here as an example.
Put the batch file in %SPLUNK_HOME%/bin/scripts
.
Now create an alert that calls your script. See "About alerts" in the Alerting Manual for help with alert creation through Splunk Web. You'll need to provide the script filepath.
Note: If you'd rather configure the alert in savedsearches.conf
, see "Configure alerts in savedsearches.conf" in this manual.
Edit your report to call the script. If your script is in $SPLUNK_HOME/bin/scripts
you don't have to specify the full path.
Troubleshoot
Check out this excellent topic on troubleshooting alert scripts on the Splunk Community Wiki.
PREVIOUS Configure alerts in savedsearches.conf |
NEXT Send SNMP traps to other systems |
This documentation applies to the following versions of Splunk® Enterprise: 6.1, 6.1.1, 6.1.2, 6.1.3, 6.1.4, 6.1.5, 6.1.6, 6.1.7, 6.1.8, 6.1.9, 6.1.10, 6.1.11, 6.1.12, 6.1.13
Comments
According to alert_actions.conf the arguments passed by Splunk differ from the ones in these docs. Arguments at index 2 and 3 are equal (duplicate $search$ in alert_actions.conf), argument 8 is the search_id and argument 9 is the result-file.
S.linner, I searched the current alert_actions.conf file for a list of the arguments as you outlined them in your comment, but could not find it.<br /><br />However, the arguments as listed in the Script options section of this topic are correct.<br /><br />Note the following:<br /><br />Arg 2 and Arg 3 both refer to the search string, which could account for your finding these args equivalent.<br /><br />Arg 7 is not used for historical reasons, which means older documentation referring to positions 8 and 9 should be adjusted.<br /><br />You can also find documentation for the arguments here in the runshellscript topic of the Search Reference: http://docs.splunk.com/Documentation/Splunk/6.1.3/SearchReference/Runshellscript