Alert Enrichment V2

Enrichment is the process of adding contextual information to alerts in BigPanda. Use the Enrichments API to define alert tags and enrichment maps that help users understand incidents more quickly and enrich BigPanda functionality, including correlation patterns and maintenance plans.

The Enrichments API allows you to programmatically create custom enrichment maps that add contextual information to alerts.

🚧

The Alert Enrichment V2 API uses the underlying systems of the Enrichment V2 Engine. Your organization must have migrated to Enrichment V2 before using the Alert Enrichment V2 API.

DO NOT USE the API without Enrichment V2 enabled or existing V1 Enrichment patterns may be damaged.

Define an enrichment schema using these API resources:

  • Alert Enrichments object, which defines the enrichment technique and configuration details associated with that technique. For example, in a mapping enrichment, the configuration details include a description of the data mapping table.
  • Sub-objects that are specific to the enrichment technique. For mapping enrichment, the Map endpoint allows you to upload and maintain a data mapping table.

The API works by evaluating all incoming alerts to see if they match an active enrichment definition. Matching alerts are enriched with the defined alert tags according to the instructions in the enrichment definition.

Relevant Permissions

Roles with the following permissions can access the Enrichments API:

Enrichments_Read
Enrichments_jobs_Read

Read only - view the Enrichments API.

Enrichments_Full_Access
Enrichments_jobs_Full_Access

Full access - use the Enrichments API to view and define mapping enrichments.

To learn more about how BigPanda's permissions work, see the RBAC - Role Based Access Control guide.

Use Cases

Use the Enrichment API to develop a common language between monitoring systems and to identify upstream and downstream dependencies between configuration items.

Cross-Source Relationships

Define common tags to identify when alerts from different monitoring sources are related to the same monitored object in your infrastructure. For example, you can define a mapping enrichment for cluster based on the Pingdom service. Then, define an extraction enrichment for cluster based on the Nagios host name. Now, a cross-source correlation pattern on the cluster tag can group related alerts from either system into the same incident.

Topology Metadata

Understand the physical and logical relationships between alerting objects and the rest of your infrastructure. For example, you can leverage a CMDB to identify when different objects have the same parent object (such as multiple hosts in the same cluster). Then, define correlation patterns for objects with the same parent, Environments that reflect your infrastructure, and/or maintenance plans that suppress alerts for objects downstream of an object under maintenance.

Operational Metadata

Help IT Operations teams categorize, prioritize, route, and remediate an incident. For example, you can leverage a team spreadsheet to add assignments, categories, and priorities to alerts. Then, define Environments, dashboards, and Analytics reports to ensure the right teams have visibility into issues and/or define AutoShare rules to automatically trigger escalation processes.

Available Objects and Actions

Object

Description

Supported Methods

API Endpoint

Alert Enrichments Object

Defines the schema for an enrichment.

POST, GET, PATCH,PUT,

https://api.bigpanda.io/resources/v2.0/enrichments-config

Use the Enrichments API to perform these actions.

Action

Definition

Description

Create Alert Enrichment Item

POST /alert-enrichments/

Creates a new definition for an enrichment schema.

Update Alert Enrichment Item

PATCH /alert-enrichments//{id}

Activates or deactivates a specific enrichment definition.

Delete Alert Enrichment Item

DELETE /alert-enrichments//{id}

Deletes an existing enrichment item.

Retrieve Alert Enrichment Item

GET /enrichments-config/tags/{RuleID'}

Retrieves a specific enrichment item.

List all Enrichment items of a Tag

GET /enrichments-config/tags/{TagName'}

Retrieves all the enrichment items for a tag.

List all Alert Tags

GET /enrichments-config/tags

Lists all alert tags that exist for an organization.

Retrieve Tags order

GET /enrichments-config

Retrieves the tags order (execution plan).

Update Tags order

PUT /enrichments-config

Updates the tags order (execution plan).

Retrieve Enrichment item's order of a Tag

GET /enrichments-config/tags/{TagName}/order

Retrieves the enrichment items order for a tag.

Update Enrichment item's order of a Tag

PUT /enrichments-config/tags/{TagName}/order

Updates the enrichment items order for a tag.

Create Mapping Enrichment Table

POST /alert-enrichments/
(type=mapping)

Creates and Defines a new enrichment mapping table that.

Update Mapping Enrichment definitions

PATCH /alert-enrichments/{Map_id}

Activates or deactivates a specific enrichment definition.

Create Mapping Enrichment Table Rows

POST /alert-enrichments/{map_id}/map

Creates specific rows of an existing mapping enrichment table.

Update Mapping Enrichment Table Rows

PATCH /alert-enrichments/{map_id}/map

Updates specific rows of an existing mapping enrichment table.

Retrieve Mapping Enrichment

GET /alert-enrichments/{map_id}/map

Retrieves a specific enrichment map.

Check Status of Upload Job

GET /alert-enrichments-jobs/{job_id}

Checks the status of an asynchronous job to upload or update a mapping enrichment table.

🚧

Rate Limitations

To maintain quality of service, the Alert Enrichment API is limited to 5 requests per second.
Additional requests will return a 429 response code and the request will need to be retried.