Alert Filter API Quick Start

📘

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.

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.

Relevant Permissions

See the Manage Alert Filters documentation for a full explanation of the permissions required to access the Alert Filter Plans API and the Alert Filter Schedules API:

To learn more about how BigPanda's permissions work, see the Roles Management guide.

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:

1. 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
  }'

❗️

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

2. 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:

1. 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
  }'

❗️

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.

2. (Recommended) Send test alerts from the San Jose host and ensure that they are suppressed and the filter works as expected.

🚧

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.