Skip to main content
Sumo Logic

Construct a Search Filter for a Role

This page describes how to define a search filter for a role. These instructions apply to Step 5 of the procedure detailed on the Create a New Role page. 

Understanding search filters

A search filter for a role defines what log data a user with that role can access. You can define a search filter using keywords, wildcards, and selected Sumo metadata fields and logical operators. Here is a simple role filter:

_sourceCategory=labs*

This filter grants access to logs whose _sourceCategory begins with the string “labs”. (Logs whose _sourceCategory don’t start with “labs” won’t be accessible.)

When a user with this filter enters a query like:

_sourcecategory=labs/apache | parse "* --" as src_ip
| count by src_ip | sort _count

Sumo silently (it’s transparent to the user) adds the role filter to the beginning of the query with an AND:

_sourceCategory=labs* AND (_sourcecategory=labs/apache
| parse "* --" as src_ip | count by src_ip | sort _count)

The example above positively grants access to log data. You can do the opposite: explicitly deny access to data, with an exclamation point (!). For example:

 _sourceCategory=!JobX*

The role filter above denies access to log data whose  _sourceCategory begins with “JobX”. (Access to log data with other source category values is not restricted.)

The examples above are simple: they involve a single role, and hence a single role filter. 

Typically however, a Sumo user will have multiple roles. If a user has multiple roles, Sumo ORs the several role filters and prepends that expression to the the user’s queries with an AND, as discussed in Multiple role filters and filter precedence.   

Search filter basics

The sections below list search filter limitations, and describe how you can use keywords, wildcards, metadata, and logical operators in filters. 

The explanations of the behavior of each example filter assume that no other role filters apply. In practice, you will likely assign multiple roles to users. After you understand the basics of how a role filters work, see Multiple role filters and filter precedence.

Search filter limitations

  • Role filters cannot include vertical pipes (|).
  • Scheduled Views and Partitions are not supported in role filters, due to potentially conflicting field names and value types. 
  • Role filters apply to log searches, not metric searches.

Using metadata in a search filter

You can use any of these Sumo metadata fields in a role search filter.

_collector
_source
_sourceCategory
_sourceHost
_sourceName

This search filter grants access to log data from the collector named “HR_Tools”, and no other data:

_collector=HR_Tools

When a user with that role filter runs a query, Sumo runs it like this:

_collector=HR_Tools AND <user-query>

Using AND and OR in a search filter

You can use AND and OR in a search filter. For example, this role filter uses OR to grant access to log data from two source categories:

_sourceCategory=stock OR _sourceCategory=insurance

When a user with that role filter runs a query, Sumo runs it like this:

(_sourceCategory=stock OR _sourceCategory=insurance) AND <user-query> 

This role filter below uses AND to grant access to log data with the source category “insurance” from the collector named “HR_Tools”:

_collector=HR_Tools AND _sourceCategory=insurance

When a user with that role filter runs a query, Sumo runs it like this:

(_collector=HR_Tools AND _sourceCategory=insurance) AND <user-query>

Using keywords in a search filter 

You can include a string you want to search for in a role search filter. This role filter grants access to logs from the collector named “HR_Tools” that contain the string “enrollment”: 

_collector=HR_Tools AND enrollment

When a user with that role filter runs a query, Sumo runs it like this:

(_collector=HR_Tools AND enrollment) AND <user-query>

Using wildcards in a search filter 

You can use an asterisk (*) as a wildcard in role search filter. This role filter grants access to logs from all collectors whose name begins with “HR”:

_collector=HR* 

When a user with that role filter runs a query, Sumo runs it like this:

_collector=HR* AND <user-query>

This role filter grants access to logs that contain the string “violation” from all collectors whose name begins with “HR”.

_collector=HR* AND violation

When a user with that role filter runs a query, Sumo runs it like this:

(_collector=HR* AND violation) AND <user-query>

Using ! as a NOT in a search filter

You can use an exclamation point character (!) in a role search filter to restrict, rather than allow, access. For example, this filter:

!_sourceHost=humanresources* AND !_sourceName=*finance* AND !_sourceCategory=*secret*

denies access to log data whose:  

_sourceHost begins with “humanresources” 
_sourceName contains “finance”
_sourceCategory contains “secret”

When a user with that role filter runs a query, Sumo runs it like this:

(!_sourceHost=humanresources* AND !_sourceName=*finance* AND !_sourceCategory=*secret*) AND <your-query> 

Multiple role filters and filter precedence

When a user is assigned to multiple Sumo roles, Sumo combines the role filters from each of the roles using OR to come up with the combined role filter. 

When multiple roles filters are applied to a query, the least restrictive filter takes precedence. So, when a user has multiple roles, the less restrictive roles will have no effect. 

Example 1

Assume the following role filters.

Role Filter
Role A _source="GCP Audit" AND _collector="GCP"
Role B _sourceCategory="Vx*"

Role A allows access to log data whose _source tag is “GCP Audit” and _collector tag is “GCP”. 

Role B Allows access to log data whose _sourceCategory tag begins with “Vx”.  

When a user with Roles A and B runs a query, Sumo applies the filters with an OR, and prepends them with an AND to your query, like this:

((_source="GCP Audit" AND _collector="GCP") OR _sourceCategory="Vx*") 
AND <your-query> 

The combined filters enable access to log data whose _source tag is “GCP Audit” and _collector tag is “GCP”, and to any log data whose _sourceCategory tag begins with “Vx”.

Example 2

Assume the following role filters.

Role Filter
Role A _collector=fee*
Role B !_collector=fi*

Role A allows access only to log data whose _collector tag matches “fee*”, and not to data whose _collector tag is any other value.

Role B Allows access to any log data whose _collector tag does not match “fi”.  

When a user with Roles A and B runs a query, Sumo combines the two filters with an OR, and prepends them with an AND to your query, like this:

(_collector=fee  OR !_collector=fi) AND <your-query> 

The least restrictive of the role filters takes precedence. So, although Role A effectively restricts results to log data that matches _collector=fee*, Role B allows grants access to all collectors, except for those that match _collector=fi*. So, Role B takes precedence and Role A has no effect.

Example 3 

Assume the following role filters.

Role Filter
Role A _sourceCategory=analytics-lab*
Role B _sourceCategory=analytics*


Role A allows access only to log data whose _sourceCategory is “analytics-lab”.

Role B Allows access to log data whose _sourceCategory begins with “analytics”.

When a user with Roles A and B runs a query, Sumo combines the two filters with an OR, like this:

(_sourceCategory=analytics-lab OR _sourceCategory=analytics*) AND <your-query> 

The least restrictive of the role filters takes precedence. Role A alone grants access to a log data from a single  source category, “analytics-lab”.  Role B grants access to log data to any source category that starts with “analytics”. Since the least restrictive filter takes precedence, data tagged _sourceCategory=analyticsLong could be returned in addition to data tagged _sourceCategory=analytics-lab.

Example 4

Assume the following role filters.

Role Filter
Role A _collector=prod*
Role B !_sourceCategory=*shoguns*

Role A allows access to log data whose _collector tag matches “prod*”, and not to data whose _collector tag does not.

Role B prevents access to log data whose _sourceCategory tag does contain “shoguns”. Data with any  _sourceCategory tag that does not contain “shoguns” is available. 

When a user with Roles A and B runs a query, Sumo combines the two filters with an OR, and prepends them with an AND to your query, like this:

(_collector=prod* OR !_sourceCategory=*shoguns*) AND <your-query> 

Role B is the least restrictive. Users with the combined role filter will be able to view any log data whose  _sourceCategory does not contain the string “shoguns”, regardless of the value of the _collector tag.