
Set up custom alert configuration files
Learn how to define custom alert action app settings in configuration files.
Custom alert action app configuration files
Here are all of the configuration files that you can use to manage a custom alert action app. Some files are required to make the app work and others are optional.
File | Description | Required? |
---|---|---|
alert_actions.conf
|
Contains settings for the custom alert action. | Yes |
app.conf
|
Package and UI information about the app. | Yes |
savedsearches.conf
|
Define instance settings for saved search actions. | A local copy is required on the Splunk platform instance but not in the custom alert action app directory. |
restmap.conf
|
Define attribute/value pairs for REST endpoints and provide validation rules. | Optional |
alert_actions.conf.spec
|
Describes attributes and possible values for configuring global saved search actions in alert_actions.conf .
|
Optional |
savedsearches.conf.spec
|
Describes attributes and possible values for saved search entries in savedsearches.conf .
|
Optional |
default.meta
|
Defines alert action permission and scope. | Optional |
Set up required configurations
alert_actions.conf
Create a stanza in alert_actions.conf
to configure the custom alert action.
Stanza naming
Follow these guidelines when naming the alert action stanza.
- The stanza name must be unique. Two apps cannot define the same alert action.
- The stanza name can contain only the following characters.
- alphanumeric characters
- underscores
- hyphens
- The stanza name cannot contain spaces.
Typically, developers name stanzas using lower case letters separated by underscores as needed. Once you have a stanza name, match the name of the script or executable file for the custom alert action to the stanza name.
Alert action attributes
The following attributes can be set in the alert action stanza within alert_actions.conf
.
Attribute | Type | Default | Description |
---|---|---|---|
is_custom | boolean | 0 | Indicates if the app implements a custom alert action. Custom alert action developers should set this value to 1. |
label | text | N/A | Display name of the alert action in the Splunk Enterprise UI. |
icon_path | relative file path to the custom alert action icon. The icon appears in the Splunk Web user interface. | To enable the custom alert action icon, indicate the relative path to the icon image file from
The best practice is to use a 48 x 48 px PNG file. The icon displays at 24 x 24 pixels. The custom alert action icon is not the same as the app icon that appears on Splunkbase. To use the Splunkbase app icon for the custom alert action icon in Splunk Web, specify | |
alert.execute.cmd | text | Provide the name/path of the script or binary to invoke, especially to avoid conflicts for modular inputs and custom alert actions with the same name or scheme. If specifying a binary outside of the [app]/bin search path, use a *.path file, where the content of the file is the absolute path of the binary. Environment variables are replaced when reading path files.
| |
alert.execute.cmd.arg.<n> | text | Change the command line arguments passed to the script when it is invoked. | |
payload_format | (xml | json) | xml | Indicates format for payload sent to STDIN of the user-provided script. |
disabled | boolean | 0 | Indicates whether the alert action is disabled. Set to "1" to disable the alert action. |
param.[param_name] | Custom alert action parameter that is passed to the script as part of the payload. All parameters in the alert action stanza are treated as custom settings for the custom alert action. They are all passed to the alert script as part of the XML or JSON configuration payload. |
These additional settings from alert_actions.conf
are also honored. For more details, see alert_actions.conf.
Setting | Type | Default | Description |
---|---|---|---|
command | search string to invoke | sendalert $action_name$ results_file="$results.file$" results_link="$results.url$" |
Partial search string executed by the scheduler when the alert is triggered. Developers can override default behavior to invoke a different custom search command or to pre-process the data before piping to sendalert .If you plan to include a subsearch in your |
maxtime | parameter for command search string
|
"$action.<action name>.maxtime{default=5m}$" |
Sets the timeout for the command. Applies only to the sendalert command and custom search commands that use the deprecated Version 1 Custom Search Command protocol. Commands that use the Version 2 Custom Search Command protocol set their timeouts with the maxwait setting in commands.conf . Usage of either maxtime or maxwait are required, as they keep actions from backing up the alert queue and shutting down the search scheduler.
|
maxinputs | parameter for command search string
|
"action.<action name>.maxresults{default=50000}" |
Along with max_action_results in limits.conf , maxinputs sets the maximum number of inputs that can be passed to the command when it is invoked. Applies only to streaming custom search commands that use the deprecated Version 1 Custom Search Command protocol. Use max_action_results for commands that use the Version 2 Custom Search Command protocol.
|
ttl | integer | 10p | Provides the minimum time to live, in seconds, of the search artifacts produced by this action in the dispatch directory. If the integer is followed by the letter 'p', this measures the minimum time to live in terms of scheduled periods rather than seconds. |
hostname | text | Custom hostname. | |
forceCsvResults | true | false | auto | When set to auto, automatically detects if the sendalert command is in the search that the alert is based on or the sendalert command is used in the alert actions. If the sendalert command is detected (or if set to 'true'), the search results are stored in the CSV format in the results.csv.gz file in the dispatch directory. Otherwise the search results are stored in the default SRS format, which is a serialized Splunk-specific search results format.
|
Example
The following example shows a stanza in the alert_actions.conf
for a custom alert action.
$SPLUNK_HOME$/etc/apps/[name]/default/alert_actions.conf
[logger] is_custom = 1 label = My Alert Action icon_path = myicon.png payload_format = json disabled = 0 # Custom params param.foo = bar param.param1 = I can use a token: $result.host$
savedsearches.conf
A local copy of savedsearches.conf
captures alert action user configurations for a particular Splunk instance.
For each Splunk platform instance, savedsearches.conf
user settings override any global alert_actions.conf
alert action settings.
Example
In this example, the alert_actions.conf
file for a custom alert action defines a global parameter and setting for the alert action.
alert_actions.conf
[my_custom_alert] param.email_option = 0
In a Splunk platform instance, the following setting for the same parameter in the local savedsearches.conf
file overrides the global setting from the app.
savedsearches.conf
action.my_custom_alert.param.email_option= 1
How configurations propagate to the alert action
When the custom alert action script runs, it reads in payload information about the system and the alert. The payload includes alert action configurations merged from alert_actions.conf
and savedsearches.conf
.
The following example payload includes a <configuration>
element with parameters and settings from the two files.
<alert> <server_host>localhost:8089</server_host> <server_uri>https://localhost:8089</server_uri> <session_key>1234512345</session_key> <results_file> /opt/splunk/var/run/splunk/12938718293123.121/results.csv.gz </results_file> <results_link> http://splunk.server.local:8000/en-US/app/search?sid=12341234.123 </results_link> <sid>12341234.123</sid> <search_name>My Saved Search</search_name> <owner>admin</owner> <app>search</app> <configuration> <stanza name="[my_custom_alert]"> <param name="[param_name_1]">[some value]</param> <param name="[param_name_2]">[other value]</param> </stanza> </configuration> </alert>
- Note: For searches generated using the advanced search option,
results_file
andresults_link
parameters are not included in the payload passed to the custom alert action script.
Optional configurations
For information on optional configuration files, see Optional custom alert action components.
PREVIOUS Custom alert action component reference |
NEXT Create a custom alert action script |
This documentation applies to the following versions of Splunk® Enterprise: 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.2.10, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 7.3.5, 7.3.6, 7.3.7, 7.3.8, 7.3.9, 8.0.0, 8.0.1, 8.0.2, 8.0.3, 8.0.4, 8.0.5, 8.0.6, 8.0.7, 8.0.8, 8.0.9, 8.0.10, 8.1.0, 8.1.1, 8.1.2, 8.1.3, 8.1.4, 8.1.5, 8.1.6, 8.1.7, 8.1.8, 8.1.9, 8.1.10, 8.1.11, 8.1.12, 8.2.0, 8.2.1, 8.2.3, 8.2.4, 8.2.5, 8.2.6, 8.2.7, 8.2.8, 8.2.9, 9.0.0, 9.0.1, 8.2.2, 9.0.2, 9.0.3
Feedback submitted, thanks!