Configure admission rules to prefilter searches

Admission rules let you filter out searches automatically before they start, based on a predicate condition that you define. If a search meets the specified condition, the search does not run.

You can use admission rules to prevent the execution of rogue searches, such as poorly written and potentially harmful searches that might consume an excessive amount of resources and interfere with critical search workloads. For example, you can create a rule to filter out wildcard searches that target all indexes, or filter out searches in the alltime time range.

You can also use admission rules to set up time-bound access to searches for roles, users, apps and so on. For example, you can create a rule that filters out all ad hoc searches from a certain role during peak business days, but allows the same role to run searches on weekends. And you can create rules that limit the number of concurrent ad hoc searches to retain search capacity for scheduled searches.

Admission rules are enabled by default for the sc_admin role. You can create a maximum of 100 admission rules per Splunk Cloud Platform deployment.

Admission rules apply to base searches only. Admission rules do not apply to subsearches.

Admission rules evaluation behavior

Admission rules have no explicit ordering. Admission rules are evaluated for ad hoc searches at the the time the search is dispatched.

Admission rules for scheduled searches are evaluated asynchronously every 600s by default. As a result, changes to an admission rule or scheduled search can take up to 600s to become active.

If a search meets the conditions of a rule, the rule takes effect before the search is executed. If a search is already running, and you create a new admission rule that applies to that search, the running search is not affected by the new rule.

Create an admission rule using Splunk Web

To create and edit admission rules, a user's role must have the list_workload_rules and edit_workload_rules capabilities.

To create an admission rule using Splunk Web:

1. In Splunk Web, click Settings > Workload Management.
2. Click Add Admission Rule.
3. Define the following fields to configure a new admission rule:

   Field	Action
   Name	Specify the name of the admission rule.
   Predicate (Condition)	Specify a predicate (condition) that must match to trigger this rule. The predicate syntax is <type>=<value> with optional AND, OR, NOT, (). For example, app=search AND role=power triggers all searches belonging to both the Search app and the power role. Valid predicate types are app, role, index, user, search_type, search_mode, search_time_range, and adhoc_search_percentage. For supported predicate values, see Specify predicate values on this page. In complex predicates, AND, OR, and NOT operators must be upper case. Lower case is not supported.
   Schedule	(Optional) Set a schedule for the admission rule. The schedule determines the time period during which the rule is valid. If set to Always On (the default), the rule remains valid indefinitely and does not expire. If set to Time Range, the rule is valid during the specified time range only and expires when the time range ends. If set to Every Day, Every Week, or Every Month, the rule becomes valid on a recurring basis during the specified time range every day, on the specified days of the week, or on the specified days of the month. The schedule time for an admission rule is based on the system timezone, regardless of the timezone set for an individual user in the UI.
   Action	Specify the action to perform when a search meets the predicate condition. If set to Filter search, the rule filters out any search that meets the specified predicate condition. If set to Queue search, the rule places a search that meets the predicate condition in a queue to be re-run at a later time, when the predicate condition allows it. This action is currently allowed for adhoc_search_percentage predicate type rules only.
   User Message	Enter a custom message that notifies the end user when a search triggers the admission rule action. For example, "This search meets specified admission rule conditions. The search was not executed." If an ad hoc search triggers the rule action, the custom message appears beneath the search bar in the Search and Reporting app. If a scheduled search triggers the action, a default message appears in scheduler.log only.

4. Click Submit.

Specify predicate values

The table describes valid values for each admission rule predicate type:

Predicate type	Valid values
app	Name of the app. For example, app=search The correct name to specify for an app is the name of the app directory located in $SPLUNK_HOME/etc/apps. You can also find the correct name for an app in Splunk Web: Click Apps > Manage Apps. See app names listed under Folder name. App names are case insensitive.
role	Name of the role. For example, role=admin. The role predicate supports a wildcard (*) in the rule definition. For example, a rule that contains role=support_* will match the role names support_team1, support_team2 and so on. A rule that contains role=* will match all role name values. For information on how role inheritance impacts role predicate matches, see Searches run by single user can match multiple roles in the Workload Management manual in the Splunk Enterprise documentation.
user	Name of any valid user. For example, user=bob. The reserved internal user "nobody" is invalid; the reserved internal user "splunk-system-user" is valid. The user predicate supports a wildcard (*) in the rule definition. For example, a rule that contains user=* will match all user name values.
index	Name of the index. For example, index=_internal. Value can refer to internal or public index. The index predicate supports a wildcard (*) in the rule definition. For example, a rule that contains index=support_*, will match the index names support_prod, support_test, and so on. A rule that contains index=_* will match any index name that starts with an underscore, such as _internal, _audit, and _introspection. index=* is a special case, where * is not treated as a wildcard, but as a literal string match. For example, if a rule contains index=*, it will match the exact string index=* or index=_*. index=* will not match all internal indexes, such as index=_internal, index=_audit, and so on.
search_type	Supports adhoc, scheduled, datamodel_acceleration, report_acceleration, and summary_index search types.
search_mode	Supports realtime and historical search modes.
search_time_range	Supports alltime search time range only.
adhoc_search_percentage	[0-100]. The percentage of the total search concurrency limit that you want to allocate to ad hoc searches. Specify an adhoc_search_percentage value to set a limit on the number of ad hoc searches that can run concurrently on the local search head. Use this to prevent skipped scheduled searches on systems running large numbers of ad hoc searches. See Example 4: Ad hoc search quota control. When specifying adhoc_search_percentage, you must also specify search_type=adhoc in the predicate statement. For example, search_type=adhoc AND adhoc_search_percentage>10. In a search head cluster environment, the adhoc_search_percentage value applies to each individual cluster member. The adhoc_search_percentage predicate does not work with other predicate types, with the exception of search_type=adhoc. Specifying any another predicate type returns an error.

Enable admission rules

The admission rules feature must be enabled for any existing admission rules to apply to searches. In Splunk Cloud Platform, the admission rules feature is enabled for the sc_admin role by default and cannot be disabled.

Enable individual admission rules

You can enable or disable individual admission rules. This lets you create and save multiple different admission rules and deploy them as needed. Individual admission rules are enabled by default when you create them. Disabled admission rules are not evaluated and have no impact on search execution.

To enable or disable an individual admission rule:

1. In Splunk Web, click Settings > Workload Management > Admission Rules.
2. In the Status column, toggle the switch to enable or disable the individual admission rule.

Example admission rules

The following examples show how you can define admission rules to filter out searches based on your use case objectives.

Example 1: Stop wildcard searches

The following rule excludes data model acceleration searches that use index=* from the filter:

index=* AND (NOT search_type=datamodel_acceleration)

Example 2: Stop alltime searches

Some monitoring searches use the alltime time range. The following rule excludes those searches from the filter:

search_time_range=alltime AND (NOT role=sc_admin) AND (NOT app=splunk_instance_monitoring)

The "View index inheritance for roles" feature also uses an alltime search. You can exclude users or roles that need to view indexes from the filter. The above rule excludes the sc_admin role.

REST API searches default to the alltime time range, unless you explicitly define a different time range in the search query.

Example 3: Do not allow certain users to run ad hoc searches at peak hours

search_type=adhoc AND role=new_users

After you define the admission rule predicate, set the schedule for the rule, specifying the time range that corresponds to your peak hours.

Example 4: Ad hoc search quota control

You can define admission rules to limit the number of concurrent ad hoc searches running on your system.

The following rule limits the number of concurrent ad hoc searches to 50% of the total search concurrency limit:

search_type=adhoc AND adhoc_search_percentage>50 

After you specify the predicate statement, set the action for the rule to Filter search or Queue search.

If set to Filter search, the rule filters out any ad hoc searches over the 50% concurrency limit. If set to Queue search, the rule places any ad hoc searches over the 50% concurrency limit in a queue to be run again when the number of concurrent ad hoc searches falls below the 50% threshold.

For more information on search concurrency limits in Splunk Cloud Platform, see Set limits for concurrent scheduled searches in the Splunk Cloud Platform Admin Manual.

For more admission rule use case examples, see Scenario 3: Create admission rules to prefilter searches.