Alert Filters

Renamed API

The Alert Filter Plans API was previously called V1 Maintenance Plans or V1 Plans. The functionality of the API has not changed, but the name has been updated to clarify which BigPanda feature the API manages.

The Alert Filter Plans API enables users to set and maintain alert filters to reduce noise for operators.

Plans are configured with BPQL queries and, once activated, will suppress alerts that match the criteria.

The Alert Filters API can be used to manage Alert Filters that have been configured in the BigPanda API. Alert filters affect alerts after they have been normalized and enriched, enabling complex filters based on additional metadata and enrichment tags. The plan ID for alert filters is the last 24 characters in the filter URL.

Alert Filter Schedules define a start and stop time frame for the alert filter. If a filter does not have a schedule defined, it will start immediately and run indefinitely - filtering all matching alerts until deactivated.

Schedule ID

The schedule ID is needed to add the schedule to a filter.

Alert Filters

Authentication

All BigPanda APIs require Bearer Token Authorization in the call headers.

This API uses the Org Token type of Authorization token.

BigPanda recommends adding Authentication headers only in the secure tool you use to make API calls.

Use Cases

You can use the Alert Filters API to keep in sync with infrastructure changes and parallel your monitoring activity accordingly. For example, the set of servers under a certain host, i.e. Billing, is scheduled to undergo upgrades for a duration of one week. Due to the non-operational nature of the servers during this time, all alerts generated by them will be unnecessary for monitoring.

Instead of having these alerts continue to stream into the feed and disrupt workflow, create a matching Filter with the query host = "billing*" and a Schedule of one week in the same time frame as the upgrades. This will suppress the irrelevant alerts from ever entering BigPanda.

Plan limit

Each organization can have up to 3,500 alert filters.

Condition limitations

Alert Filter conditions cannot be longer than 25,000 characters long.

All alert tags in filter conditions are case-insensitive.

The condition body parameter uses special BPQL object formatting. See BPQL Object Syntax for more information.

Not all tags are available for alert filter conditions. See the Tag Naming documentation for a list of tags that have limited functionality in BigPanda.

OK status

By default, alert filters ignore events that have an ok status. These events will still enter the system and resolve any related open alerts.

This setting can be changed by explicitly including the exclude_status field as an empty array.

Alert Filter API Quick Start

Renamed API

You can suppress alerts that meet a defined query with the Alert Filter Plans API. A time window for when the suppression will start and end can be defined by the addition of a Schedule.

UI management

Alert Filters can also be managed from within BigPanda. See Manage Alert Filters for more information.

Step 1: Define The Alert Filter Schedule

As an example scenario, suppose that a company's servers and devices under its San Jose host are undergoing upgrades and will yield false alerts from procedural reboots and state changes. The associated monitoring tools will inevitably see these changes as alerts and stream them into BigPanda. To prevent the cluttering of workflow, you would create an alert filter to capture the relevant devices under the San Jose host and suppress their alerts and a schedule to capture the timeframe of the maintenance period.

Start by creating a schedule to define the specific start and end timeframe:

Send a POST request to /schedules.

The start and end parameters follow the Unix epoch format.
For more information, see Create an Alert Filter Schedule

curl -iX POST https://api.bigpanda.io/resources/v1.0/schedules \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $(token)" \
  -d '{
    "name": "San Jose Host Maintenance Schedule",
    "starts_on": 1491265491,
    "ends_on": 1491294307,
    "active": true
  }'

Replace text

Be sure to replace ${token} with the corresponding value for your organization.

Copy the id value from the response body. You will use it as the schedule id parameter when creating a filter in the next step.

Step 2: Define The Filter Plan With Schedule

Create an alert filter to isolate the suppression of alerts to only the devices affected during the maintenance period - the San Jose host. See the Alert Filter Plan Objects documentation for required fields.

Schedule ID

The schedule ID is needed to add a schedule to a filter.

Filter ID

The plan id for Alert Filters can be extracted from the URL of the filter in the BigPanda UI.

To define a new alert filter:

Plan limit

Each organization can have up to 3,500 Alert filters.

Condition limitations

Alert filter conditions cannot be longer than 25,000 characters long.

All alert tags in filter conditions are case-insensitive.

The condition body parameter uses special BPQL object formatting. See BPQL Object Syntax for more information.

Send a POST request to /plans.
- Specify the name of the filter.
- Specify the schedule to associate with the filter. The id value is copied from Step 1.
- Specify the bpql object to query. In this case, we want to filter "San Jose" hosts to capture the relevant devices.
- Specify the active parameter to true to enable the filter.
- For more information, see Create an Alert Filter
```
curl -iX POST https://api.bigpanda.io/resources/v1.0/plans \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $(token)" \
  -d '{
        "name": "San Jose Maintenance Plan",
        "schedule": "590b72b91f0000130063753c"
        "bpql": {"=": ["host", "prod-san-jose"]},
        "active": true
  }'
```
Warning
This process is defined for a hypothetical sample environment. You can adapt the values as necessary to meet your infrastructure conventions and the needs of your teams.
Like in Step 1, be sure to replace ${token} with the corresponding value for your organization.
(Recommended) Send test alerts from the San Jose host and ensure that they are suppressed and the filter works as expected.

Parameters

The Alert Filter Plan object schema includes the following attributes:

Attribute	Description	Type
id	System-generated unique identifier for the alert filter.	String
name	User defined name for the alert filter.	String
description	Brief summary of the alert filter.	String
bpql	The BPQL object to identify which alerts will be filtered.	JSON
exclude_status	A list of alert status values that will be excluded from the filter. With new filters, the OK status is excluded by default unless exclude_status is explicitly declared in the payload.	Array of Strings
active	Whether the filter is active and will apply to incoming alerts	Boolean
created_on	Date and time the filter was created in ISO 8601 format.	Long
created_by	The ID of the user who created the filter.	String
updated_on	Date and time the filter was last updated in ISO 8601 format.	Long
updated_by	The ID of the user who last updated the filter.	String
schedule	The ID of the schedule associated to the filter.	String
custom_tags	Metadata about the plan in an array of key-value pairs. Attributes: - name - Ordered pair tuple name. String - value - Object value. String	Array of Objects

Sample Alert Filter Plan Object:

{
        "name": "Folsom Patch",
        "bpql": {"=": ["host", "prod-api-1"]},
        "active": true,
        "description": "Patching Folsom server farm",
        "custom_tags" : [{
        	 "name": "server_farm",
           "value": "folsom"
          }]
  }

Parameters

The Alert Filter Schedule object schema includes the following attributes:

Attribute	Description	Type
id	System-generated unique identifier for the schedule.	String
name	User defined name for the schedule.	String
description	Brief summary of the schedule.	String
starts_on	Unix epoch time when the schedule starts (in seconds).	Long
ends_on	Unix epoch time when the schedule ends (in seconds).	Long
time_zone	The schedule's time zone setting. Default is UTC. See the full list of supported time zones here.
duration	The calculated time between the ends_on and starts_on in seconds.	Long
created_on	Unix epoch time when the schedule was created (in seconds).	Long
created_by	The ID of the user who created the schedule.	String
updated_on	Unix epoch time when the schedule was last updated (in seconds).	Long
updated_by	The ID of the user who last updated the schedule.	String
active	Indicates if the schedule is active and can be applied to alert filters.	Boolean

Sample Alert Filter Schedule Object

{
    "name": "Weekend Maintenance",
    "starts_on": 1491265491,
    "ends_on": 1491294307,
    "time_zone": "UTC",
    "active": true
  }

In this section:

Alert Filters

Alert Filters

Use Cases

Alert Filter API Quick Start

Step 1: Define The Alert Filter Schedule

Step 2: Define The Filter Plan With Schedule

Parameters

Sample Alert Filter Plan Object:

Parameters

Sample Alert Filter Schedule Object

Search results