OIM Alerts
The Open Integration Manager enables you to create customizable inbound alert integrations through the configuration of a generic inbound integration rather than creating custom code. The integration manager sets parsing rules for incoming payloads, preprocessing the content to match incoming data requirements before it reaches the BigPanda enrichment engine.
The OIM Alerts API allows you to easily integrate a monitoring system with BigPanda. Monitoring systems generally send out events when problems are detected and when problems have been resolved.
The API receives event payloads from a monitoring system. Incoming events sent via the API are processed according to OIM settings and BigPanda alert correlation logic. Depending on the results of the correlation, the system then creates a new incident or updates an existing incident based on Event Aggregation rules.
Configuration
To manage integration configuration rules for the Open Integration Manager via API, use the OIM Configuration API.
Note
The Open Integration Manager offers additional flexibility with authentication parameters. The following syntax can be used for the Token and App Key:
Auth Token:
query string: access_token=<token>
header: Authorization: Bearer <token>
header: x-auth-token: <token>
App Key
Query string: app_key=<app_key>
header: x-app-key: <app_key>
header: app_key: <app_key>
body: { "app_key": "<app_key>" }
How Many Events to Send (Load Limitations)
Payload size
Alert payloads must be 6MB or smaller. Larger payloads will fail to process with BigPanda. We recommend reviewing your configurations to ensure that only actionable, useful information is being sent to BigPanda.
If an integration generates more than a few hundred events per hour, review the guidelines for when to send events and ensure that the integration is properly configured. Even with hundreds of thousands of monitoring metrics, status changes do not happen very often. If an integration exceeds this guideline, it may be sending duplicate or erroneous events to BigPanda.
Under maximum load, the API can support up to a few hundred events per minute.
Open Integration Manager (OIM) Alerts
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.
Sending Multiple Alerts
BigPanda uses the timestamp to determine the latest status of an incident. If it is not included, BigPanda uses the time when the alert is received. To ensure that BigPanda accurately reflects the current status, when sending multiple alerts, you must include the timestamp for each alert or sort the alerts array by when the events occurred, in ascending order.
To send multiple alerts, you must also select the Create multiple alerts using checkbox option within OIM and specify the name of the alerts array (which may be alerts or something else), and save your integration configuration.
Resolving alerts
To maintain only the most relevant information in the incident feed, we recommend configuring monitoring systems to send resolving events to BigPanda when an alert is no longer active.
Parameters
The OIM Alert object schema includes the following attributes:
Attribute | Description | Type |
|---|---|---|
app_key | The app key of the integration, created during the first step of integration set up. | String |
status | Status of the event. One of | String |
timestamp | (Optional) Time that the event occurred. Unix epoch time when the event occurred (in seconds). If no time is specified, the value defaults to the time received in BigPanda. This field is often used for systems that send events in batches. | Timestamp (in seconds) |
<event_property> | Event properties to become tags in BigPanda. The alert object can include any number of custom JSON attributes in string, integer, or array format. | String |
<event_property> | Event properties to become tags in BigPanda. The alert object can include any number of custom JSON attributes in string, integer, or array format. When sending an array, the array values are combined into a single tag, pipe delimited in the UI. | Array |
<event_property> | Event properties to become tags in BigPanda. The alert object can include any number of custom JSON attributes in string, integer, or array format. | Integer |
description | (Optional) Brief summary of the alert for certain monitoring tools - max. 2048 characters. | String |
Sample Alert Payloads
Single Alert:
{ "app_key": "<app_key>",
"status": "critical",
"host": "production-database-1",
"check": "CPU overloaded",
"timestamp": 1402303570,
"application": "Billing",
"regions":["US1","US2","EMEA"],
"count": 47
"description": "CPU is above warning limit (40%)"
}
Multi-Alert:
{ "app_key": "<APP KEY>",
"alerts": [{
"status": "critical",
"host": "production-database-1",
"check": "CPU overloaded",
"description": "CPU is above warning limit (40%)"
}, {
"status": "critical",
"host": "production-database-2",
"check": "CPU overloaded",
"timestamp": 1402303570,
"application": "Billing"
}]
}Event Properties
The attributes included in the JSON payload become tags in BigPanda.
You can add any number of custom JSON attributes with a string, integer, or array value to the payload. Common fields include host, host, service, application, device, check, sensor, cluster, node, data center, region, and description.
When configuring the data to send through the OIM Alerts API, send attributes that:
Drive deduplication, correlation, and UI titling. Event attributes enable BigPanda to turn noisy events into high-quality alerts and actionable incidents.
Add context about the event, including where or when the alert triggered. Additional information helps your team understand the full situation while investigating an issue.
Enable automation and categorization. Tags such as business element or team help you build environments, AutoShare rules, analytics, and workflows.
Set next steps for triage and remediation. Including links to runbook wikis or investigation tools helps your team take action quicker. If a tag value starts with http, BigPanda automatically adds a link button.
Primary and Secondary Properties
Two tags are identified as the Primary and Secondary properties within BigPanda. Primary and Secondary properties are key data fields that function as the main name for alerts and drive correlation, event normalization, and deduplication. Ensure that the fields that map to the BigPanda tags marked as primary or secondary are included in all payloads.
Primary property
BigPanda cannot receive events without a primary_property.
Sending Multiple Alerts
If you want to send more than one alert in a single API call, you can modify the JSON payload to send an array of alert objects. When sending multiple alerts at the same time, you can choose to specify the app_key one time instead of for each alert.
️Sending multiple alerts with the OIM REST API
BigPanda uses the timestamp to determine the latest status of an alert. If it is not included, BigPanda uses the time when the event is received. To ensure that BigPanda accurately reflects the current status, when sending multiple events, you must include the timestamp for each event or sort the alerts array by when the events occurred, in ascending order.
To send multiple alerts, you must also select the Create multiple alerts using checkbox within OIM and specify the name of the alerts array (which may be alerts or something else), and save your integration configuration.