Create a custom alert action script

Alert action script workflow

The script executes the alert action, such as sending an email or connecting to a web resource. To execute the alert action, the script follows a workflow to get information about the triggered alert and run the alert action.

Typically, the script's workflow looks like this:

• Check the execution mode, based on command line arguments.
• Read configuration payload from stdin.
• Run the alert action.
• Terminate.

Executable files recognized for introspection

There are several types of executable files recognized for introspection.

Recognized file types
*Nix platforms filename.sh filename.py filename.js filename (executable file without an extension)
Windows platforms filename.bat filename.cmd filename.py filename.js filename.exe

About the execution mode

When the alert action is triggered, the script receives one command line argument, which is the string --execute. This argument indicates the execution mode. Your script should check for the --execute argument. Additional execution modes might be added to this interface.

About the script configuration payload

The alert_actions.conf file and savedsearches.conf file define the content of the configuration payload. Upon startup, the script reads the configuration from the payload. Developers typically create the configuration files before writing the script because of this dependency. The configuration file format is usually XML, but can be JSON if specified in alert_actions.conf.

The configuration payload contains:

• Global information about the system
  * splunkd session key
  * splunkd management URL
  


• Information about the triggered alert and search
  * SID
  * Saved search name
  * Path to file containing the search results
  * URL to the search results
  


• Alert action configuration
  * This configuration contains the merged parameters of alert_actions.conf and savedsearches.conf.
  


• The first search result
  

Script runtime threshold

The script runs separately for each triggered alert. It should have a brief execution time and terminate once the alert action execution completes. The script is forcefully terminated if the runtime exceeds its runtime threshold. The default runtime threshold is 5 minutes.

Script naming guidelines

The name of the script should be the same as in its alert_actions.conf stanza. You can add an optional file name extension. For example, myapp/bin/myalertaction.py corresponds to [myalertaction] in alert_actions.conf. For more information, see alert_actions.conf.

Where to place the script or executable

Place the script or executable in the following directory:

$SPLUNK_HOME$/etc/apps/[myapp]/bin/

Override a script with alert.execute.cmd

Developers can use the alert.execute.cmd option to override the filename of the script to execute. You can use a custom binary and executed arguments for more flexibility. Create a stanza and place the path file and arguments in alert_actions.conf.

[myjavaaction]
. . .
alert.execute.cmd = java.path
alert.execute.cmd.arg.0 =  -jar
alert.execute.cmd.arg.1 = $SPLUNK_HOME/etc/apps/myapp/bin/my.jar
alert.execute.cmd.arg.2 = --execute

Script override considerations

• If you use a custom path file and arguments, make sure that the stanza name in alert_actions.conf is unique.

• If you use the alert.execute.cmd settings to specify a command to execute, the arguments are also overridden and not appended. --execute is not added unless manually specified,

• The external process starts with the arguments exactly as specified in the alert_actions.conf stanza.

.path file for a custom binary

As shown in the example above, specify a .path file for alert.execute.cmd in the custom alert action's alert_actions.conf stanza. Absolute paths are not supported for alert.execute.cmd, although they can be used for its arguments. You can also use environment variables, such as $SPLUNK_HOME$ inside the .path file.

Architecture-specific scripts

You can provide an architecture-specific version of a custom alert action script or executable by placing the appropriate version in the corresponding architecture-specific /bin directory for the app. Architecture-specific directories are available for these Intel-based architectures:

• Linux
• Apple (darwin)
• Windows

Only use a platform-specific directory when it is a requirement for that architecture. If you place a script in an architecture-specific directory, the script runs the appropriate version of the script. Otherwise, a platform-neutral version of the script runs in the default /bin directory.

$SPLUNK_HOME$/etc/apps/[App]

/linux_x86/bin/[myscript]
/linux_x86_64/bin/[myscript]

/darwin_x86/bin/[myscript]
/darwin_x86_64/bin/[myscript]

$SPLUNK_HOME$\etc\apps\[App]

\windows_x86\bin\[myscript]
\windows_x86_64\bin\[myscript]