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.
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.
New API version and additional functionality
The Alert Enrichments V2.1 API adds additional functionality and performance to Alert Enrichment API capabilities. When possible, BigPanda recommends leveraging the V2.1 API instead of the V2.0 functionality.
If you have previously configured API management of Alert Enrichment using the V1 or V2.0 API, you can update those processes to the new version by following the steps in the Migrating to Alert Enrichment V2.1 documentation.
No additional steps are necessary to configure a new API call using the V2.1 API.
Alert Enrichment 2.0
Authentication
All BigPanda APIs require Bearer Token Authorization in the call headers.
This API uses the User API Key type of Authorization token.
BigPanda recommends adding Authentication headers only in the secure tool you use to make API calls.
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.
JSON Format
The Alert Enrichment API accepts only standard double quoted JSON formatting. Python JSON uses single quotes and will not be accepted by the API.
If using Python, please sanitize your JSON to adhere to standard double quoted JSON formatting. See the sample payload below as an example of an acceptable JSON format.
Example JSON formatted payload:
curl --request POST \
--url https://api.bigpanda.io/resources/v2.0/alert-enrichments \
--header "Authorization: Bearer ${your_api_key}" \
--header 'Content-Type: application/json' \
--data '{
"field": "states",
"secondary_field": true,
"object": {
"subobject": [
{
"field": "string",
"secondary_field": "also string"
]
},
"another_field": "url.com"
}'
Parameters
The Enrichment item object schema includes the following attributes:
Attribute | Description | Example |
|---|---|---|
active | Whether the enrichment item is applied to all incoming alert data. |
|
id | System-generated unique identifier for the enrichment item. |
|
version | Internal version number of the current data mapping table for this enrichment item. This number is incremented automatically each time the table/item is updated. |
|
type | Enrichment function type used to create enrichment items. |
|
config | Configuration details associated with the enrichment technique. | For a mapping enrichment, this attribute contains the map's definitions like table name, query & result tags and note. |
when | A BPQL query for filtering the incoming alerts to be enriched | BPQL string, BPQL object or boolean "when": true "when": "host != x" "when": { "!=": [ "host", "x" ] } |
note | A description |
|
`