Policy management API v3.0

Resource: alert_cache

Allows generated alerts to be stored for later retrieval. The cache holds 128 alerts per policy id. Alerts whose end_time is more than an hour old will pruned from the cache periodically. A sample algorithm to retrieve the alerts every 5 seconds: (1) query_ts = null (2) if query_ts is null, alerts = GET /alert_cache (3) else alerts = GET /alert_cache?start_time=<query_ts> (4) if alerts are empty, wait 5 seconds, go to step (2) (5) find the largest violation timestamp in the returned alerts, assign to query_ts (6) process returned alerts (7) wait 5 seconds, got to step 2

http://{device}/api/npm.policies/3.0/alert_cache

JSON

[
  {
    "disambiguator_list": [
      string
    ],
    "id": integer,
    "max_severity": integer,
    "notification_prefix": string,
    "overwrite_violations_on_update": boolean,
    "policy_description": string,
    "policy_id": integer,
    "policy_name": string,
    "policy_type": integer,
    "severity": integer,
    "time_range": {
      "end": string,
      "start": string
    },
    "violations": [
      {
        "attributes": {
          "additional_info_values": [
            {
              "key": string,
              "value": string
            }
          ],
          "count": integer,
          "metric_context": [
            {
              "data": [
                {
                  "fc": number,
                  "mjh": number,
                  "mjl": number,
                  "mnh": number,
                  "mnl": number,
                  "nmh": number,
                  "nml": number,
                  "ts": string,
                  "va": number
                }
              ],
              "metric": string
            }
          ],
          "metric_values": [
            {
              "metric": string,
              "valid": boolean,
              "value": number
            }
          ],
          "severity": integer,
          "timestamp": string
        },
        "keys": [
          string
        ]
      }
    ]
  }
]

[
  {
    "disambiguator_list": [
      string
    ],
    "id": integer,
    "max_severity": integer,
    "notification_prefix": string,
    "overwrite_violations_on_update": boolean,
    "policy_description": string,
    "policy_id": integer,
    "policy_name": string,
    "policy_type": integer,
    "severity": integer,
    "time_range": {
      "end": string,
      "start": string
    },
    "violations": [
      {
        "attributes": {
          "additional_info_values": [
            {
              "key": string,
              "value": string
            }
          ],
          "count": integer,
          "metric_context": [
            {
              "data": [
                {
                  "fc": number,
                  "mjh": number,
                  "mjl": number,
                  "mnh": number,
                  "mnl": number,
                  "nmh": number,
                  "nml": number,
                  "ts": string,
                  "va": number
                }
              ],
              "metric": string
            }
          ],
          "metric_values": [
            {
              "metric": string,
              "valid": boolean,
              "value": number
            }
          ],
          "severity": integer,
          "timestamp": string
        },
        "keys": [
          string
        ]
      }
    ]
  }
]

Property Name	Type	Description	Notes
alert_cache	<array of <object>>	Allows generated alerts to be stored for later retrieval. The cache holds 128 alerts per policy id. Alerts whose end_time is more than an hour old will pruned from the cache periodically. A sample algorithm to retrieve the alerts every 5 seconds: (1) query_ts = null (2) if query_ts is null, alerts = GET /alert_cache (3) else alerts = GET /alert_cache?start_time=<query_ts> (4) if alerts are empty, wait 5 seconds, go to step (2) (5) find the largest violation timestamp in the returned alerts, assign to query_ts (6) process returned alerts (7) wait 5 seconds, got to step 2
alert_cache[items]	<object>	An object describing an alert on the system	Required properties: [policy_type, policy, time_range, severity];
alert_cache[items].disambiguator_list	<array of <string>>	An optional array whose members are used as a key when deciding which alerts can be merged with this one	Optional;
alert_cache[items].disambiguator_list [items]	<string>
alert_cache[items].id	<integer>	The unique identifier of this alert	Optional; Minimum 0;
alert_cache[items].max_severity	<integer>	The maximum severity attained by this Alert over its duration	Optional; Range: 0 to 100;
alert_cache[items]. overwrite_violations_on_update	<boolean>	If true, updates to this alert will overwrite previous information; if false, the update is merged into the alert	Optional;
alert_cache[items].policy_description	<string>	The description of the policy that generated this alert	Optional;
alert_cache[items].policy_id	<integer>	The unique identifier of the policy that generated this alert	Optional; Minimum 0;
alert_cache[items].policy_name	<string>	The name of the policy that generated this alert	Optional;
alert_cache[items].policy_type	<integer>	The type of the policy that generated this alert
alert_cache[items].severity	<integer>	The current severity of this Alert	Range: 0 to 100;
alert_cache[items].time_range	<object>	A time range pair, consisting of a start and end time.	Required properties: [start, end];
alert_cache[items].time_range.end	<string>	The ending time. This is a high-precision time value in Unix Epoch format.
alert_cache[items].time_range.start	<string>	The start time. This is a high-precision time value in Unix Epoch format.
alert_cache[items].violations	<array of <object>>		Optional;
alert_cache[items].violations[items]	<object>	violating entity and value(s)
alert_cache[items].violations[items]. attributes	<object>	Information about the violating metric values.	Optional;
alert_cache[items].violations[items]. attributes.additional_info_values	<array of <object>>	Optional information used to help display the violator	Optional;
alert_cache[items].violations[items]. attributes.additional_info_values [items]	<object>
alert_cache[items].violations[items]. attributes.additional_info_values [items].key	<string>		Optional;
alert_cache[items].violations[items]. attributes.additional_info_values [items].value	<string>		Optional;
alert_cache[items].violations[items]. attributes.count	<integer>	The number of times this violator has appeared in the alert	Optional;
alert_cache[items].violations[items]. attributes.metric_context	<array of <object>>		Optional;
alert_cache[items].violations[items]. attributes.metric_context[items]	<object>		Required properties: [metric];
alert_cache[items].violations[items]. attributes.metric_context[items].data	<array of <object>>		Optional;
alert_cache[items].violations[items]. attributes.metric_context[items].data [items]	<object>	Represents the tolerance bands used in Adaptive Threshold alert detail reports.
alert_cache[items].violations[items]. attributes.metric_context[items].data [items].fc	<number>		Optional;
alert_cache[items].violations[items]. attributes.metric_context[items].data [items].mjh	<number>		Optional;
alert_cache[items].violations[items]. attributes.metric_context[items].data [items].mjl	<number>		Optional;
alert_cache[items].violations[items]. attributes.metric_context[items].data [items].mnh	<number>		Optional;
alert_cache[items].violations[items]. attributes.metric_context[items].data [items].mnl	<number>		Optional;
alert_cache[items].violations[items]. attributes.metric_context[items].data [items].nmh	<number>		Optional;
alert_cache[items].violations[items]. attributes.metric_context[items].data [items].nml	<number>		Optional;
alert_cache[items].violations[items]. attributes.metric_context[items].data [items].ts	<string>		Optional;
alert_cache[items].violations[items]. attributes.metric_context[items].data [items].va	<number>		Optional;
alert_cache[items].violations[items]. attributes.metric_context[items]. metric	<string>
alert_cache[items].violations[items]. attributes.metric_values	<array of <object>>		Optional;
alert_cache[items].violations[items]. attributes.metric_values[items]	<object>	Holds a metric and its value. Value can be null. Valid is deprecated.	Required properties: [metric];
alert_cache[items].violations[items]. attributes.metric_values[items].metric	<string>
alert_cache[items].violations[items]. attributes.metric_values[items].valid	<boolean>		Optional;
alert_cache[items].violations[items]. attributes.metric_values[items].value	<number>		Optional;
alert_cache[items].violations[items]. attributes.severity	<integer>	The current severity of this Violation in this Alert	Optional; Range: 0 to 100;
alert_cache[items].violations[items]. attributes.timestamp	<string>	Epoch timestamp representing the last time this violator was updated in the alert	Optional;
alert_cache[items].violations[items]. keys	<array of <string>>		Optional;
alert_cache[items].violations[items]. keys[items]	<string>
alert_cache[items].notification_prefix	<string>	Used to help route notifications for this alert to the correct recipients

Links

alert_cache: create

POST http://{device}/api/npm.policies/3.0/alert_cache

Request Body

Provide an alert_cache data object.

Response Body

On success, the server does not provide any body in the responses.

alert_cache: get

GET http://{device}/api/npm.policies/3.0/alert_cache{?policy_id,start_time,end_time}

Response Body

Returns an alert_cache data object.

Type: PolicyCounts

JSON

[
  {
    "count": integer,
    "type": integer
  }
]

[
  {
    "count": integer,
    "type": integer
  }
]

Property Name	Type	Notes
PolicyCounts	<array of <object>>
PolicyCounts[items]	<object>
PolicyCounts[items].count	<integer>	Optional;
PolicyCounts[items].type	<integer>	Optional;

Type: SubscriptionList

JSON

[
  {
    "email_address": string,
    "notification_frequency": string,
    "recipient_id": integer
  }
]

[
  {
    "email_address": string,
    "notification_frequency": string,
    "recipient_id": integer
  }
]

Property Name	Type	Description	Notes
SubscriptionList	<array of <object>>
SubscriptionList[items]	<object>	Pairs a recipient ID with a notification frequency
SubscriptionList[items].email_address	<string>		Optional;
SubscriptionList[items].recipient_id	<integer>		Optional;
SubscriptionList[items]. notification_frequency	<string>		Values: continuous, on_crossing, on_change, on_expire;

Type: column_list

Collection of data column IDs.

JSON

[
  string
]

[
  string
]

Property Name	Type	Description	Notes
column_list	<array of <string>>	Collection of data column IDs.
column_list[items]	<string>	Data column ID.

Type: data_def_source

Data source specificiation for a data definition.

JSON

{
  "name": string,
  "origin": string,
  "path": string,
  "reference_id": string,
  "tags": [
    string
  ],
  "type": string,
  <prop>: any
}

{
  "name": string,
  "origin": string,
  "path": string,
  "reference_id": string,
  "tags": [
    string
  ],
  "type": string,
  <prop>: any
}

Property Name	Type	Description	Notes
data_def_source	<object>	Data source specificiation for a data definition.	Required properties: [name];
data_def_source.name	<string>	Name of the data source for the data definition.
data_def_source.origin	<string>	The origin data source for a query that is performing a sub-query into another data source (e.g., alerting requesting into system_metrics). Required in these cases for data column validation.	Optional;
data_def_source.path	<string>	Reference path to the requested data from within the data source.	Optional;
data_def_source.reference_id	<string>	Reference to another data_def which will be used as a source to this one.	Optional;
data_def_source.tags	<array of <string>>	Custom labels for this data source	Optional;
data_def_source.tags[items]	<string>
data_def_source.type	<string>	Data type requested	Optional;
data_def_source.<prop>	<any>		Optional;