BigPanda Query Language (BPQL)
BigPanda Query Language (BPQL) is used for complex incident investigation and correlation pattern building in BigPanda. BPQL is necessary when searching or filtering using specific criteria. BPQL allows you to search for specific values in custom or standard tags, as opposed to general keyword searches which are much broader. Use BPQL to construct advanced search query strings and conditions to help you quickly diagnose problems and manage your infrastructure effectively.
Where To Use BPQL
Use BPQL to construct advanced query strings:
In the Incidents tab - Search incidents in the selected Environment and folder. You can search active incidents or incidents resolved in the last 24 hours.
In the Environments editor - Create criteria and conditions for filtering incidents into environments.
In the Unified Search tab - Search current and historical monitoring data. You can filter incidents by Environment, source, and exact time period in the last 3 months.
In the Alert Correlation editor - Filter which alerts are correlated by the pattern.
In the Changes section - Search for specific tag values in changes associated with the incident to help identify the incident's Root Cause.
In the Alert Enrichment editor - Extract a tag value from the source tag value when creating an extraction enrichment tag.
In the Alert Filtering editor - Apply a condition to choose which alerts are filtered.
In the Incident Enrichment editor - Establish conditions for automatic incident enrichment to be applied.
In the Planned Maintenance editor - Define which alerts are suppressed by the maintenance plan.
Query Assist
Query Assist opens automatically when a user clicks a Search or Condition filter field where BPQL is enabled.
Suggested tags appear in the left pane. These suggestions are based on and ordered by tag creation time. Click Show More to view additional values. You can also type a value into the search box to filter the list by name.
Recent tags only
Dropdowns only include alert tags that have been updated or included in an alert in the last 90 days. To use an older tag, simply type the tag name.
Syntax help appears in the right pane and lists helpful definitions and examples. Hover over a tag or operator to populate information about that value in the Syntax Help pane.
Click the blue arrow at the right of Query Assist to collapse the Syntax Help portion and view only suggested values. Click the blue arrow again to expand the Syntax Help pane again.
Building Queries Using Query Assist
Begin building a query by typing the first tag name, or selecting one of the suggested values to populate it in the search box. Enter a space after the value to prompt Query Assist to move to the next step and display available operators for the query.
Quotes
Use quotes (" or ') around an exact phrase that contains spaces. For example, to search for checks containing CPU over 90% you'd enter check="CPU over 90%"
You can use special characters between quotes.
Search with incident tags
Incident tags and some incident metadata can be used to search and filter incidents. Standard incident tags that can be searched include source_system, status, assignee, assigner, severity, zero_impact, is_active, comment. See the Tag Naming documentation for a list of system limitations tied to specific tags.
When searching or defining BPQL conditions using incident tags, you must use the Incident Tag ID, not the incident tag name.
To see the incident tag ID, click an incident tag name in Query Assist. The tag ID is then populated in the search bar or input field. You can also find the Incident Tag ID on the Settings > Incident Enrichment screen in the incident tag details pane.
To search using an incident tag, the tag ID must be preceded by incident. (For example, incident.runbook)
Enter a space after the operator to prompt the query assist to move to the next step. It will display suggested tag values based on existing incidents and past searches.
When building a conditional filter, you will need to save the environment, pattern, or tag to save the query settings.
Enter a space after the tag value to create a more complex query using multiple conditions. Query assist will list available conditional operators. Select or enter the desired operator in the search field and hit enter to begin the prompt process for the second tag. Continue entering or selecting values until satisfied with your query.
Syntax Rules
BPQL uses the following syntax rules:
Basic Queries
The basic syntax for a query with a single condition is: <tag> <operator> <value>. For example:
host = srv-ny-1
Tags and values are not case sensitive, except in OIM Event Filtering.
When searching for comments, you can use "comment" as a tag to search for comments specific to a particular incident.
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.
Case Sensitive in OIM Event Filtering
BPQL is only case sensitive in OIM Event Filtering to allow for greater granularity. In all other parts of BigPanda, BPQL is case insensitive.
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 set precedence 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 Name Search Restrictions
Spaces, periods, and special characters are not supported when querying tag names. When creating multi-word tags, spaces should be removed or replaced with underscores.
BPQL also does not support the use of most BigPanda Reserved Words such as incident_identifier or primary_property
source_system can be used in BPQL to create correlation patterns, custom tags, and unified searches.
description can be used in BPQL to create extraction enrichment tags.
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 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*
Asterisks will function as wildcards even if enclosed in quotes (" or ')
Wildcard limitations for Environments
Environment conditions do not support wildcards for the IN and NOT IN operators.
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">
The special characters within quotes will act as literal text.
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 queries are limited to 32,000 characters or less; values above 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. Patterns must be entered with the correct character case for the query to match. Other searches in BigPanda, including wildcards and exact phrases, are case insensitive.
Queries may return the entire pattern or partial pattern depending upon the screen they are used in. If a query is performed on a screen where start (^) and end ($) characters are always assumed, partial matches will not be returned. See Start and End Pattern Support table for more information. If a query is performed on a screen that supports the inclusion of the start (^) and end ($) characters in the query, the query will return partial matches by default and you must include the characters to perform an exact match.
Queries with
\s,\d, or\ware not supported.
Start (^) and End ($) Pattern Support
Screen | Is the start (^) and end ($) for the pattern assumed? | Is the start (^) and end ($) for the pattern supported? |
|---|---|---|
Yes | No | |
Yes | Yes | |
Yes | No | |
No | Yes | |
Yes | No | |
No | Yes | |
Yes | No | |
No | Yes | |
No | Yes | |
No | Yes | |
No | Yes |
Search 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
Operator | Description | Example |
|---|---|---|
| Equals |
|
| Not equal |
|
| Strict match; true for all alerts in an incident |
|
| Equal to one of the values in a list |
|
| Not equal to any of the values in a list Note: When using this operator, BigPanda requires a check for the same tag to work correctly. Without it, the query will default to "true." |
|
| At least one of the conditions is true |
|
| All of the conditions are true |
|
Strict Match vs. Equals
Strict match criteria must be met by all alerts within an incident, while an equals (=) search finds incidents that have at least one matching alert, even if other alerts do not match the criteria.
Incident-level functionality
Strict match applies only to incidents, not alerts. Product elements that apply to alerts (such as Alert Enrichment or Alert Filtering) do not support strict matching within BPQL conditions.
For example:
If the strict match criteria is host==="prod-1"
Incidents where all alerts are from the prod-1 host are listed as results.
Any incidents where only some of the alerts match do not appear in the results.
The below table compares a strict match and an equals search results for this query:
Example Incidents | Strict Match (host==="prod-1") | Equals Match (host="prod-1") |
|---|---|---|
Incident 1 contains: Alert 1 on host = prod-1 Alert 2 on host = prod-1 - Alert 3 on host = prod-1 | Yes | Yes |
Incident 2 contains: Alert 1 on host = prod-1 Alert 2 on host = prod-2 - Alert 3 on host = prod-1 | No | Yes |
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.
Strict match syntax
Strict match syntax will only work with alert tags. Strict match for incident tags is not supported.
Next Steps
Learn how to Search for Incidents in BigPanda.
Learn how to create Correlation Patterns using BPQL.
Find information about BigPanda Formula Language (BPFL)