Where To Use BPQL
Use BPQL to construct advanced query strings:
- On the Incidents tab—to search incidents in the selected Environment and folder. You can search active incidents or incidents resolved in the last 24 hours.
- On the Search tab—to search current and historical monitoring data. You can filter incidents by Environment, source, and exact time period in the last 3 months.
- In the Correlation editor—to filter which alerts are correlated by the pattern.
Syntax Rules
Basic Queries
The basic syntax for a query with a single condition is: <tag> <operator> <value>. For example:host=srv-ny-1
This example uses the host tag, the equals operator, and the value srv-ny-1. Tags and values are not case sensitive.
Finding Tag Names
The available tags can vary based on the source system and integration. To find the tag names for an integration, you can view an alert in the BigPanda UI or reference the documentation on standard tags. On the Search tab, the search bar displays suggested tags and relevant system names as you type.
Multiple Conditions and Precedence of Operators (Parentheses)
For multiple conditions, use any combination of AND and OR to combine terms in a query. For example:
host=srv-1 AND check=chk-1
Use parentheses (( )) to give priority to a part of the query. For example:
host=srv-1 AND (check=chk-1 OR check=chk-2 OR check=chk-3)
You can use nested parentheses. For example:
host=srv-1 AND (check=chk-1 OR (check=chk-2 AND status=critical))
Tag Names with Spaces and Special Characters
Spaces, periods, and special characters are not supported when querying tag names. When creating multi-word tags, spaces should be concatenated together into one word or combined with underscores. Please see the Tag Naming Requirements in the Enrichments doc for more information.
servicelevel
Yes
service_level
Yes
service level
No
service.level
No
servicelevel!
No
Value Phrases with Spaces
Use quotes (" or ') around an exact phrase that contains spaces. Spaces are allowed only between quotes. For example, to search for checks containing CPU over 90%:
check="*CPU over 90%*"
You can use special characters and wildcards between quotes.
Wildcards
Use an asterisk (*) as a wildcard to match multiple values that contain a common element. For example, to search for hosts that end with .host1.com:
host=*.host1.com
To search for hosts that start with db and end with .domain1.com.
host=db*.domain1.com
To search for hosts that contain prod:
host=*prod*
You can use wildcards inside of quotes (exact phrases).
Special Characters
Use quotes (" or ') around an exact phrase that contains any of the following special characters:
= " ' | : \ / ( ) { } [ ] ^ ~ * ? , ` < >
For example, to search for a specific URL:
url="*https://my.domain.com/businessapp*"
Regular Expressions (Regex)
Use a slash (/) as the first and last character to search for values that match a regex; for example, host = /<regex pattern>/.
Use a regex to find values that match a certain pattern. For example, this regex query looks for host values with any three characters followed by abc then by any 3 digits:
host=/...abc[0-9]{3}/
Regex tag value queries are limited to 32,000 characters or less; values surpassing this limit are trimmed.
Regex Syntax
BigPanda searches follow the Elasticsearch Regular Expression Syntax. This syntax has some differences compared to other common regex engines, including:
- Values are case sensitive; you must enter patterns with the correct character case for the query to match. Other searches in BigPanda, including wildcards and exact phrases, are case insensitive.
- Queries require the entire pattern to obtain a match. Regex queries do not match on partial patterns because the start (
^) and end patterns ($) are always assumed. - Queries with
\s,\d, or\ware not supported.
Searching for Tags with Empty Values
A specific regex search syntax needs to be used when searching for tags with empty values:
host != /[a-zA-Z0-9]+/
Operators
=
:
Equals
host=srv-ny-1host:srv-ny-1
!=
Not equal
host!=srv-ny-1
===
Strict match; true for all alerts in an incident
host===srv-1
IN
in
Equal to one of the values in a list
host IN [srv-1, srv-2]host in [srv-1, srv-2]
NOT IN
not in
Not equal to any of the values in a list
host NOT IN [srv-1, srv-2]host not in [srv-1, srv-2]
OR
or
At least one of the conditions is true
host=srv-1 OR host=srv-2host=srv-1 or host=srv-2
AND
and
All of the conditions are true
host=srv-1 AND check=chk-1host=srv-1 and check=chk-1
Strict Match vs. Equals
Strict match criteria must be met by all alerts within an incident, whereas an equals (=) search finds incidents that have at least one matching alert, even if other alerts do not match the criteria. For example, if the strict match criteria is host==="prod-1", incidents where all alerts match the host are listed as results. However, incidents where only some of the alerts match, such as alerts from the same cluster but not the same host, do not appear in the results.
The following example shows a strict match versus an equals search.
Incident 1 contains:
- Alert 1 on host = prod-1
- Alert 2 on host = prod-1
- Alert 3 on host = prod-1
Incident 2 contains:
- Alert 1 on host = prod-1
- Alert 2 on host = prod-2
- Alert 3 on host = prod-1
Strict match considers all alerts in the incident regardless of status
Strict match considers both active and inactive alerts in an incident. If the active alerts in an incident meet the criteria and the inactive alerts don't, the incident does not match.
Keyword Searches
A keyword search looks for a value in descriptions, source system names, and in any tag—in contrast to a BPQL query, which looks for a value in a specific tag. For tags that contain multiple values, a keyword search identifies matches if any of the values match the search term.
You can use an asterisk (*) as a wildcard to match multiple values that contain a common element. For example:
phx*db
Keyword searches can find exact search terms between special characters without using wildcards. For example, if you search for api, it matches all tags, source system names, and descriptions where api is present between special characters, such as prod-api-1 and web-api. You do not need to use wildcards; for example, *api*.
You can use quotes (" or ') around an exact phrase that contains spaces. Spaces are allowed only between quotes. For example:
"CPU over 90*"
You can use a slash (/) as the first and last character to search for values that match a regex. Regular expressions are case sensitive and are limited to 32,000 characters. For example:
/...Phx[0-9]{3}/