Alerts REST API

Auto-generated swagger documentation

Overview

Media Type

The API uses JSON to communicate with clients.

You should add the following accept header to your requests:

Accept: application/json

When you send JSON data with a POST or PUT request, you must add the following content type header:

Content-Type: application/json

Base Path

/hawkular/alerts

REST APIs

[ / ] Alerts Handling

  1. Get alerts with optional filtering

  2. Set one or more alerts Acknowledged.

  3. Set one alert Acknowledged.

  4. Get an existing Alert.

  5. Send data for alert processing/condition evaluation.

  6. Delete alerts with optional filtering.

  7. Add a note into an existing Alert.

  8. Set one or more alerts resolved.

  9. Set one alert Resolved.

  10. Remove tags from existing Alerts.

  11. Add tags to existing Alerts.

  12. Watch alerts with optional filtering

  13. Delete an existing Alert.

Endpoint GET /

Get alerts with optional filtering

If not criteria defined, it fetches all alerts available in the system.
Tags Query language (BNF):

<tag_query> ::= ( <expression> | "(" <object> ")" | <object> <logical_operator> <object> )
<expression> ::= ( <tag_name> | <not> <tag_name> | <tag_name> <boolean_operator> <tag_value> | <tag_name> <array_operator> <array> )
<not> ::= [ "NOT" | "not" ]
<logical_operator> ::= [ "AND" | "OR" | "and" | "or" ]
<boolean_operator> ::= [ "=" | "!=" ]
<array_operator> ::= [ "IN" | "NOT IN" | "in" | "not in" ]
<array> ::= ( "[" "]" | "[" ( "," <tag_value> )* )
<tag_name> ::= <identifier>
<tag_value> ::= ( "'" <regexp> "'" | <simple_value> )
;
; <identifier> and <simple_value> follow pattern [a-zA-Z_0-9][\-a-zA-Z_0-9]*
; <regexp> follows any valid Java Regular Expression format

Query parameters

Parameter Required Description Type Allowable Values

startTime

No

Filter out alerts created before this time.

integer

Timestamp in millisecond since epoch.

endTime

No

Filter out alerts created after this time.

integer

Timestamp in millisecond since epoch.

alertIds

No

Filter out alerts for unspecified alertIds.

string

Comma separated list of alert IDs.

triggerIds

No

Filter out alerts for unspecified triggers.

string

Comma separated list of trigger IDs.

statuses

No

Filter out alerts for unspecified lifecycle status.

string

Comma separated list of [OPEN, ACKNOWLEDGED, RESOLVED]

severities

No

Filter out alerts for unspecified severity.

string

Comma separated list of [LOW, MEDIUM, HIGH, CRITICAL]

tags

No

[DEPRECATED] Filter out alerts for unspecified tags.

string

Comma separated list of tags, each tag of format 'name|value'.
Specify '*' for value to match all values.

tagQuery

No

Filter out alerts for unspecified tags.

string

A tag query expression.

startResolvedTime

No

Filter out alerts resolved before this time.

integer

Timestamp in millisecond since epoch.

endResolvedTime

No

Filter out alerts resolved after this time.

integer

Timestamp in millisecond since epoch.

startAckTime

No

Filter out alerts acknowledged before this time.

integer

Timestamp in millisecond since epoch.

endAckTime

No

Filter out alerts acknowledged after this time.

integer

Timestamp in millisecond since epoch.

startStatusTime

No

Filter out alerts with some lifecycle state before this time.

integer

Timestamp in millisecond since epoch.

endStatusTime

No

Filter out alerts with some lifecycle after this time.

integer

Timestamp in millisecond since epoch.

thin

No

Return only thin alerts, do not include: evalSets, resolvedEvalSets.

boolean

-

Response

Status codes

Status Code Reason Response Model

200

Successfully fetched list of alerts.

array of Alert

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint PUT /ack

Set one or more alerts Acknowledged.

Query parameters

Parameter Required Description Type Allowable Values

alertIds

Yes

List of alerts to Ack.

string

Comma separated list of alert IDs.

ackBy

No

User acknowledging the alerts.

string

-

ackNotes

No

Additional notes associated with the acknowledgement.

string

-

Response

Status codes

Status Code Reason Response Model

200

Success, Alerts Acknowledged invoked successfully.

-

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint PUT /ack/{alertId}

Set one alert Acknowledged.

Path parameters

Parameter Required Description Type Allowable Values

alertId

Yes

The alertId to Ack.

string

An existing alertId.

Query parameters

Parameter Required Description Type Allowable Values

ackBy

No

User acknowledging the alerts.

string

-

ackNotes

No

Additional notes associated with the acknowledgement.

string

-

Response

Status codes

Status Code Reason Response Model

200

Success, Alert Acknowledged invoked successfully.

-

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint GET /alert/{alertId}

Get an existing Alert.

Path parameters

Parameter Required Description Type Allowable Values

alertId

Yes

Id of alert to be retrieved

string

-

Query parameters

Parameter Required Description Type Allowable Values

thin

No

Return only a thin alert, do not include: evalSets, resolvedEvalSets.

boolean

-

Response

Status codes

Status Code Reason Response Model

200

Success, Alert found.

Alert

400

Bad Request/Invalid Parameters.

ApiError

404

Alert not found.

ApiError

500

Internal server error

ApiError

Endpoint POST /data

Send data for alert processing/condition evaluation.

Body

Required Description Data Type

Yes

Data to be processed by alerting.

array of Data

Response

Status codes

Status Code Reason Response Model

200

Success, data added.

-

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint PUT /delete

Delete alerts with optional filtering.

Return number of alerts deleted.
WARNING: If not criteria defined, it deletes all alerts stored in the system.
Tags Query language (BNF):

<tag_query> ::= ( <expression> | "(" <object> ")" | <object> <logical_operator> <object> )
<expression> ::= ( <tag_name> | <not> <tag_name> | <tag_name> <boolean_operator> <tag_value> | <tag_name> <array_operator> <array> )
<not> ::= [ "NOT" | "not" ]
<logical_operator> ::= [ "AND" | "OR" | "and" | "or" ]
<boolean_operator> ::= [ "=" | "!=" ]
<array_operator> ::= [ "IN" | "NOT IN" | "in" | "not in" ]
<array> ::= ( "[" "]" | "[" ( "," <tag_value> )* )
<tag_name> ::= <identifier>
<tag_value> ::= ( "'" <regexp> "'" | <simple_value> )
;
; <identifier> and <simple_value> follow pattern [a-zA-Z_0-9][\-a-zA-Z_0-9]*
; <regexp> follows any valid Java Regular Expression format

Query parameters

Parameter Required Description Type Allowable Values

startTime

No

Filter out alerts created before this time.

integer

Timestamp in millisecond since epoch.

endTime

No

Filter out alerts created after this time.

integer

Timestamp in millisecond since epoch.

alertIds

No

Filter out alerts for unspecified alertIds.

string

Comma separated list of alert IDs.

triggerIds

No

Filter out alerts for unspecified triggers.

string

Comma separated list of trigger IDs.

statuses

No

Filter out alerts for unspecified lifecycle status.

string

Comma separated list of [OPEN, ACKNOWLEDGED, RESOLVED]

severities

No

Filter out alerts for unspecified severity.

string

Comma separated list of [LOW, MEDIUM, HIGH, CRITICAL]

tags

No

[DEPRECATED] Filter out alerts for unspecified tags.

string

Comma separated list of tags, each tag of format 'name|value'.
Specify '*' for value to match all values.

tagQuery

No

Filter out alerts for unspecified tags.

string

A tag query expression.

startResolvedTime

No

Filter out alerts resolved before this time.

integer

Timestamp in millisecond since epoch.

endResolvedTime

No

Filter out alerts resolved after this time.

integer

Timestamp in millisecond since epoch.

startAckTime

No

Filter out alerts acknowledged before this time.

integer

Timestamp in millisecond since epoch.

endAckTime

No

Filter out alerts acknowledged after this time.

integer

Timestamp in millisecond since epoch.

startStatusTime

No

Filter out alerts with some lifecycle state before this time.

integer

Timestamp in millisecond since epoch.

endStatusTime

No

Filter out alerts with some lifecycle after this time.

integer

Timestamp in millisecond since epoch.

Response

Status codes

Status Code Reason Response Model

200

Success, Alerts deleted.

ApiDeleted

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint PUT /note/{alertId}

Add a note into an existing Alert.

Path parameters

Parameter Required Description Type Allowable Values

alertId

Yes

The alertId to add the note.

string

An existing alertId.

Query parameters

Parameter Required Description Type Allowable Values

user

No

Author of the note.

string

-

text

No

Text of the note.

string

-

Response

Status codes

Status Code Reason Response Model

200

Success, Alert note added successfully.

-

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint PUT /resolve

Set one or more alerts resolved.

Query parameters

Parameter Required Description Type Allowable Values

alertIds

Yes

List of alertIds to set resolved.

string

Comma separated list of alert IDs.

resolvedBy

No

User resolving the alerts.

string

-

resolvedNotes

No

Additional notes associated with the resolution.

string

-

Response

Status codes

Status Code Reason Response Model

200

Success, Alerts Resolution invoked successfully.

-

400

Bad Request/Invalid Parameters.

ApiError

404

Alert not found.

ApiError

500

Internal server error.

ApiError

Endpoint PUT /resolve/{alertId}

Set one alert Resolved.

Path parameters

Parameter Required Description Type Allowable Values

alertId

Yes

The alertId to set resolved.

string

-

Query parameters

Parameter Required Description Type Allowable Values

resolvedBy

No

User resolving the alerts.

string

-

resolvedNotes

No

Additional notes associated with the resolution.

string

-

Response

Status codes

Status Code Reason Response Model

200

Success, Alerts Resolution invoked successfully.

-

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint DELETE /tags

Remove tags from existing Alerts.

Query parameters

Parameter Required Description Type Allowable Values

alertIds

Yes

List of alerts to untag.

string

Comma separated list of alert IDs.

tagNames

Yes

List of tag names to remove.

string

Comma separated list of tags names.

Response

Status codes

Status Code Reason Response Model

200

Success, Alerts untagged successfully.

-

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint PUT /tags

Add tags to existing Alerts.

Query parameters

Parameter Required Description Type Allowable Values

alertIds

Yes

List of alerts to tag.

string

Comma separated list of alert IDs.

tags

Yes

List of tags to add.

string

Comma separated list of tags.
Each tag of format 'name|value'.

Response

Status codes

Status Code Reason Response Model

200

Success, Alerts tagged successfully.

-

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint GET /watch

Watch alerts with optional filtering

Return a stream of alerts ordered by the current lifecycle stime.
Changes on lifecycle alert are monitored and sent by the watcher.

If not criteria defined, it fetches all alerts available in the system.

Time criterias are used only for the initial query.
After initial query, time criterias are discarded, watching alerts by current lifecycle stime.
Non time criterias are active.

If not criteria defined, it fetches all alerts available in the system.
Tags Query language (BNF):

<tag_query> ::= ( <expression> | "(" <object> ")" | <object> <logical_operator> <object> )
<expression> ::= ( <tag_name> | <not> <tag_name> | <tag_name> <boolean_operator> <tag_value> | <tag_name> <array_operator> <array> )
<not> ::= [ "NOT" | "not" ]
<logical_operator> ::= [ "AND" | "OR" | "and" | "or" ]
<boolean_operator> ::= [ "=" | "!=" ]
<array_operator> ::= [ "IN" | "NOT IN" | "in" | "not in" ]
<array> ::= ( "[" "]" | "[" ( "," <tag_value> )* )
<tag_name> ::= <identifier>
<tag_value> ::= ( "'" <regexp> "'" | <simple_value> )
;
; <identifier> and <simple_value> follow pattern [a-zA-Z_0-9][\-a-zA-Z_0-9]*
; <regexp> follows any valid Java Regular Expression format

Query parameters

Parameter Required Description Type Allowable Values

startTime

No

Filter out alerts created before this time.

integer

Timestamp in millisecond since epoch.

endTime

No

Filter out alerts created after this time.

integer

Timestamp in millisecond since epoch.

alertIds

No

Filter out alerts for unspecified alertIds.

string

Comma separated list of alert IDs.

triggerIds

No

Filter out alerts for unspecified triggers.

string

Comma separated list of trigger IDs.

statuses

No

Filter out alerts for unspecified lifecycle status.

string

Comma separated list of [OPEN, ACKNOWLEDGED, RESOLVED]

severities

No

Filter out alerts for unspecified severity.

string

Comma separated list of [LOW, MEDIUM, HIGH, CRITICAL]

tags

No

[DEPRECATED] Filter out alerts for unspecified tags.

string

Comma separated list of tags, each tag of format 'name|value'.
Specify '*' for value to match all values.

tagQuery

No

Filter out alerts for unspecified tags.

string

A tag query expression.

startResolvedTime

No

Filter out alerts resolved before this time.

integer

Timestamp in millisecond since epoch.

endResolvedTime

No

Filter out alerts resolved after this time.

integer

Timestamp in millisecond since epoch.

startAckTime

No

Filter out alerts acknowledged before this time.

integer

Timestamp in millisecond since epoch.

endAckTime

No

Filter out alerts acknowledged after this time.

integer

Timestamp in millisecond since epoch.

startStatusTime

No

Filter out alerts with some lifecycle state before this time.

integer

Timestamp in millisecond since epoch.

endStatusTime

No

Filter out alerts with some lifecycle after this time.

integer

Timestamp in millisecond since epoch.

watchInterval

No

Define interval when watcher notifications will be sent.

integer

Interval in seconds

thin

No

Return only thin alerts, do not include: evalSets, resolvedEvalSets.

boolean

-

Response

Status codes

Status Code Reason Response Model

200

Errors will close the stream. Description is sent before stream is closed.

ApiError

Endpoint DELETE /{alertId}

Delete an existing Alert.

Path parameters

Parameter Required Description Type Allowable Values

alertId

Yes

Alert id to be deleted.

string

-

Response

Status codes

Status Code Reason Response Model

200

Success, Alert deleted.

-

400

Bad Request/Invalid Parameters.

ApiError

404

Alert not found.

ApiError

500

Internal server error.

ApiError

[ /actions ] Actions Handling

  1. Find all action ids grouped by plugin.

  2. Create a new ActionDefinition.

  3. Update an existing ActionDefinition.

  4. Get actions from history with optional filtering.

  5. Delete actions from history with optional filtering.

  6. Find all action ids of an specific action plugin.

  7. Delete an existing ActionDefinition.

  8. Get an existing action definition.

Endpoint GET /actions

Find all action ids grouped by plugin.

Return a map[string, array of string]] where key is the plugin id and value a collection of actionIds.

Response

Status codes

Status Code Reason Response Model

200

Successfully fetched map of action ids grouped by plugin.

map[string,array of object]

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint POST /actions

Create a new ActionDefinition.

Returns created ActionDefinition

Body

Required Description Data Type

Yes

ActionDefinition to be created.

ActionDefinition

Response

Status codes

Status Code Reason Response Model

200

Success, ActionDefinition Created.

ActionDefinition

400

Existing ActionDefinition/Invalid Parameters

ApiError

500

Internal server error.

ApiError

Endpoint PUT /actions

Update an existing ActionDefinition.

Returns updated ActionDefinition.

Body

Required Description Data Type

Yes

ActionDefinition to be updated.

ActionDefinition

Response

Status codes

Status Code Reason Response Model

200

Success, ActionDefinition Updated.

ActionDefinition

400

Bad Request/Invalid Parameters.

ApiError

404

ActionDefinition not found for update.

ApiError

500

Internal server error.

ApiError

Endpoint GET /actions/history

Get actions from history with optional filtering.

If not criteria defined, it fetches all actions stored in the system.

Query parameters

Parameter Required Description Type Allowable Values

startTime

No

Filter out actions created before this time.

integer

Timestamp in millisecond since epoch.

endTime

No

Filter out actions created after this time.

integer

Timestamp in millisecond since epoch.

actionPlugins

No

Filter out actions for unspecified actionPlugin.

string

Comma separated list of plugin names.

actionIds

No

Filter out actions for unspecified actionId.

string

Comma separated list of actions IDs.

alertIds

No

Filter out actions for unspecified alertIds.

string

Comma separated list of alert IDs

results

No

Filter out alerts for unspecified result.

string

Comma separated list of action results.

thin

No

Return only thin actions, do not include full alert, only alertId.

boolean

-

Response

Status codes

Status Code Reason Response Model

200

Successfully fetched list of actions.

array of Action

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint PUT /actions/history/delete

Delete actions from history with optional filtering.

WARNING: If not criteria defined, it deletes all actions history stored in the system.

Query parameters

Parameter Required Description Type Allowable Values

startTime

No

Filter out actions created before this time.

integer

Timestamp in millisecond since epoch.

endTime

No

Filter out action created after this time.

integer

Timestamp in millisecond since epoch.

actionPlugins

No

Filter out actions for unspecified actionPlugin.

string

Comma separated list of plugin names.

actionIds

No

Filter out actions for unspecified actionId.

string

Comma separated list of action IDs.

alertIds

No

Filter out actions for unspecified alertIds.

string

Comma separated list of alert IDs.

results

No

Filter out alerts for unspecified result.

string

Comma separated list of action results.

Response

Status codes

Status Code Reason Response Model

200

Success, Actions deleted.

ApiDeleted

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint GET /actions/plugin/{actionPlugin}

Find all action ids of an specific action plugin.

Path parameters

Parameter Required Description Type Allowable Values

actionPlugin

Yes

Action plugin to filter query for action ids.

string

-

Response

Status codes

Status Code Reason Response Model

200

Successfully fetched list of action ids.

array of string

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint DELETE /actions/{actionPlugin}/{actionId}

Delete an existing ActionDefinition.

Path parameters

Parameter Required Description Type Allowable Values

actionPlugin

Yes

Action plugin.

string

-

actionId

Yes

Action id to be deleted.

string

-

Response

Status codes

Status Code Reason Response Model

200

Success, ActionDefinition Deleted.

-

400

Bad Request/Invalid Parameters.

ApiError

404

ActionDefinition not found for delete.

ApiError

500

Internal server error.

ApiError

Endpoint GET /actions/{actionPlugin}/{actionId}

Get an existing action definition.

Path parameters

Parameter Required Description Type Allowable Values

actionPlugin

Yes

Action plugin.

string

-

actionId

Yes

Action id to be retrieved.

string

-

Response

Status codes

Status Code Reason Response Model

200

Success, Action found.

ActionDefinition

400

Bad Request/Invalid Parameters.

ApiError

404

No Action found.

ApiError

500

Internal server error.

ApiError

[ /admin ] Cross tenant Operations

  1. Get alerts with optional filtering from multiple tenants.

  2. Get events with optional filtering from multiple tenants.

  3. Watch alerts with optional filtering from multiple tenants.

  4. Watch events with optional filtering from multiple tenants.

Endpoint GET /admin/alerts

Get alerts with optional filtering from multiple tenants.

If not criteria defined, it fetches all alerts available in the system.

Multiple tenants are expected on HawkularTenant header as a comma separated list.
i.e. HawkularTenant: tenant1,tenant2,tenant3
Tags Query language (BNF):

<tag_query> ::= ( <expression> | "(" <object> ")" | <object> <logical_operator> <object> )
<expression> ::= ( <tag_name> | <not> <tag_name> | <tag_name> <boolean_operator> <tag_value> | <tag_name> <array_operator> <array> )
<not> ::= [ "NOT" | "not" ]
<logical_operator> ::= [ "AND" | "OR" | "and" | "or" ]
<boolean_operator> ::= [ "=" | "!=" ]
<array_operator> ::= [ "IN" | "NOT IN" | "in" | "not in" ]
<array> ::= ( "[" "]" | "[" ( "," <tag_value> )* )
<tag_name> ::= <identifier>
<tag_value> ::= ( "'" <regexp> "'" | <simple_value> )
;
; <identifier> and <simple_value> follow pattern [a-zA-Z_0-9][\-a-zA-Z_0-9]*
; <regexp> follows any valid Java Regular Expression format

Query parameters

Parameter Required Description Type Allowable Values

startTime

No

Filter out alerts created before this time.

integer

Timestamp in millisecond since epoch.

endTime

No

Filter out alerts created after this time.

integer

Timestamp in millisecond since epoch.

alertIds

No

Filter out alerts for unspecified alertIds.

string

Comma separated list of alert IDs.

triggerIds

No

Filter out alerts for unspecified triggers.

string

Comma separated list of trigger IDs.

statuses

No

Filter out alerts for unspecified lifecycle status.

string

Comma separated list of [OPEN, ACKNOWLEDGED, RESOLVED]

severities

No

Filter out alerts for unspecified severity.

string

Comma separated list of [LOW, MEDIUM, HIGH, CRITICAL]

tags

No

[DEPRECATED] Filter out events for unspecified tags.

string

Comma separated list of tags, each tag of format 'name|value'.
Specify '*' for value to match all values.

tagQuery

No

Filter out alerts for unspecified tags.

string

A tag query expression.

startResolvedTime

No

Filter out alerts resolved before this time.

integer

Timestamp in millisecond since epoch.

endResolvedTime

No

Filter out alerts resolved after this time.

integer

Timestamp in millisecond since epoch.

startAckTime

No

Filter out alerts acknowledged before this time.

integer

Timestamp in millisecond since epoch.

endAckTime

No

Filter out alerts acknowledged after this time.

integer

Timestamp in millisecond since epoch.

startStatusTime

No

Filter out alerts with some lifecycle state before this time.

integer

Timestamp in millisecond since epoch.

endStatusTime

No

Filter out alerts with some lifecycle after this time.

integer

Timestamp in millisecond since epoch.

thin

No

Return only thin alerts, do not include: evalSets, resolvedEvalSets.

boolean

-

Response

Status codes

Status Code Reason Response Model

200

Successfully fetched list of alerts.

array of Alert

400

Bad Request/Invalid Parameters

ApiError

500

Internal server error.

ApiError

Endpoint GET /admin/events

Get events with optional filtering from multiple tenants.

If not criteria defined, it fetches all events stored in the system.

Multiple tenants are expected on HawkularTenant header as a comma separated list.
i.e. HawkularTenant: tenant1,tenant2,tenant3
Tags Query language (BNF):

<tag_query> ::= ( <expression> | "(" <object> ")" | <object> <logical_operator> <object> )
<expression> ::= ( <tag_name> | <not> <tag_name> | <tag_name> <boolean_operator> <tag_value> | <tag_name> <array_operator> <array> )
<not> ::= [ "NOT" | "not" ]
<logical_operator> ::= [ "AND" | "OR" | "and" | "or" ]
<boolean_operator> ::= [ "=" | "!=" ]
<array_operator> ::= [ "IN" | "NOT IN" | "in" | "not in" ]
<array> ::= ( "[" "]" | "[" ( "," <tag_value> )* )
<tag_name> ::= <identifier>
<tag_value> ::= ( "'" <regexp> "'" | <simple_value> )
;
; <identifier> and <simple_value> follows pattern [a-zA-Z_0-9][\-a-zA-Z_0-9]*
; <regexp> follows any valid Java Regular Expression format

Query parameters

Parameter Required Description Type Allowable Values

startTime

No

Filter out events created before this time.

integer

Timestamp in millisecond since epoch.

endTime

No

Filter out events created after this time.

integer

Timestamp in millisecond since epoch.

eventIds

No

Filter out events for unspecified eventIds.

string

Comma separated list of event IDs.

triggerIds

No

Filter out events for unspecified triggers.

string

Comma separated list of trigger IDs.

categories

No

Filter out events for unspecified categories.

string

Comma separated list of category values.

tags

No

[DEPRECATED] Filter out events for unspecified tags.

string

Comma separated list of tags, each tag of format 'name|value'.
Specify '*' for value to match all values.

tagQuery

No

Filter out events for unspecified tags.

string

A tag query expression.

thin

No

Return only thin events, do not include: evalSets.

boolean

-

Response

Status codes

Status Code Reason Response Model

200

Successfully fetched list of events.

array of Event

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint GET /admin/watch/alerts

Watch alerts with optional filtering from multiple tenants.

Return a stream of alerts ordered by the current lifecycle stime.
Changes on lifecycle alert are monitored and sent by the watcher.

If not criteria defined, it fetches all alerts available in the system.

Time criterias are used only for the initial query.
After initial query, time criterias are discarded, watching alerts by current lifecycle stime.
Non time criterias are active.

Multiple tenants are expected on HawkularTenant header as a comma separated list.
i.e. HawkularTenant: tenant1,tenant2,tenant3
Tags Query language (BNF):

<tag_query> ::= ( <expression> | "(" <object> ")" | <object> <logical_operator> <object> )
<expression> ::= ( <tag_name> | <not> <tag_name> | <tag_name> <boolean_operator> <tag_value> | <tag_name> <array_operator> <array> )
<not> ::= [ "NOT" | "not" ]
<logical_operator> ::= [ "AND" | "OR" | "and" | "or" ]
<boolean_operator> ::= [ "=" | "!=" ]
<array_operator> ::= [ "IN" | "NOT IN" | "in" | "not in" ]
<array> ::= ( "[" "]" | "[" ( "," <tag_value> )* )
<tag_name> ::= <identifier>
<tag_value> ::= ( "'" <regexp> "'" | <simple_value> )
;
; <identifier> and <simple_value> follow pattern [a-zA-Z_0-9][\-a-zA-Z_0-9]*
; <regexp> follows any valid Java Regular Expression format

Query parameters

Parameter Required Description Type Allowable Values

startTime

No

Filter out alerts created before this time.

integer

Timestamp in millisecond since epoch.

endTime

No

Filter out alerts created after this time.

integer

Timestamp in millisecond since epoch.

alertIds

No

Filter out alerts for unspecified alertIds.

string

Comma separated list of alert IDs.

triggerIds

No

Filter out alerts for unspecified triggers.

string

Comma separated list of trigger IDs.

statuses

No

Filter out alerts for unspecified lifecycle status.

string

Comma separated list of [OPEN, ACKNOWLEDGED, RESOLVED]

severities

No

Filter out alerts for unspecified severity.

string

Comma separated list of [LOW, MEDIUM, HIGH, CRITICAL]

tags

No

[DEPRECATED] Filter out events for unspecified tags.

string

Comma separated list of tags, each tag of format 'name|value'.
Specify '*' for value to match all values.

tagQuery

No

Filter out alerts for unspecified tags.

string

A tag query expression.

startResolvedTime

No

Filter out alerts resolved before this time.

integer

Timestamp in millisecond since epoch.

endResolvedTime

No

Filter out alerts resolved after this time.

integer

Timestamp in millisecond since epoch.

startAckTime

No

Filter out alerts acknowledged before this time.

integer

Timestamp in millisecond since epoch.

endAckTime

No

Filter out alerts acknowledged after this time.

integer

Timestamp in millisecond since epoch.

startStatusTime

No

Filter out alerts with some lifecycle state before this time.

integer

Timestamp in millisecond since epoch.

endStatusTime

No

Filter out alerts with some lifecycle after this time.

integer

Timestamp in millisecond since epoch.

watchInterval

No

Define interval when watcher notifications will be sent.

integer

Interval in seconds

thin

No

Return only thin alerts, do not include: evalSets, resolvedEvalSets.

boolean

-

Response

Status codes

Status Code Reason Response Model

200

Errors will close the stream. Description is sent before stream is closed.

ApiError

Endpoint GET /admin/watch/events

Watch events with optional filtering from multiple tenants.

Return a stream of events ordered by ctime.

If not criteria defined, it fetches all events stored in the system.

Time criterias are used only for the initial query.
After initial query, time criterias are discarded, watching events by ctime.
Non time criterias are active.

If not criteria defined, it fetches all events stored in the system.

Multiple tenants are expected on HawkularTenant header as a comma separated list.
i.e. HawkularTenant: tenant1,tenant2,tenant3
Tags Query language (BNF):

<tag_query> ::= ( <expression> | "(" <object> ")" | <object> <logical_operator> <object> )
<expression> ::= ( <tag_name> | <not> <tag_name> | <tag_name> <boolean_operator> <tag_value> | <tag_name> <array_operator> <array> )
<not> ::= [ "NOT" | "not" ]
<logical_operator> ::= [ "AND" | "OR" | "and" | "or" ]
<boolean_operator> ::= [ "=" | "!=" ]
<array_operator> ::= [ "IN" | "NOT IN" | "in" | "not in" ]
<array> ::= ( "[" "]" | "[" ( "," <tag_value> )* )
<tag_name> ::= <identifier>
<tag_value> ::= ( "'" <regexp> "'" | <simple_value> )
;
; <identifier> and <simple_value> follows pattern [a-zA-Z_0-9][\-a-zA-Z_0-9]*
; <regexp> follows any valid Java Regular Expression format

Query parameters

Parameter Required Description Type Allowable Values

startTime

No

Filter out events created before this time.

integer

Timestamp in millisecond since epoch.

endTime

No

Filter out events created after this time.

integer

Timestamp in millisecond since epoch.

eventIds

No

Filter out events for unspecified eventIds.

string

Comma separated list of event IDs.

triggerIds

No

Filter out events for unspecified triggers.

string

Comma separated list of trigger IDs.

categories

No

Filter out events for unspecified categories.

string

Comma separated list of category values.

tags

No

[DEPRECATED] Filter out events for unspecified tags.

string

Comma separated list of tags, each tag of format 'name|value'.
Specify '*' for value to match all values.

tagQuery

No

Filter out events for unspecified tags.

string

A tag query expression.

watchInterval

No

Define interval when watcher notifications will be sent.

integer

Interval in seconds

thin

No

Return only thin events, do not include: evalSets.

boolean

-

Response

Status codes

Status Code Reason Response Model

200

Errors will close the stream. Description is sent before stream is closed.

ApiError

[ /events ] Event Handling

  1. Get events with optional filtering.

  2. Create a new Event.

  3. Send events to the engine for processing/condition evaluation.

  4. Delete events with optional filtering.

  5. Get an existing Event.

  6. Remove tags from existing Events.

  7. Add tags to existing Events.

  8. Watch events with optional filtering.

  9. Delete an existing Event.

Endpoint GET /events

Get events with optional filtering.

If not criteria defined, it fetches all events stored in the system.
Tags Query language (BNF):

<tag_query> ::= ( <expression> | "(" <object> ")" | <object> <logical_operator> <object> )
<expression> ::= ( <tag_name> | <not> <tag_name> | <tag_name> <boolean_operator> <tag_value> | <tag_name> <array_operator> <array> )
<not> ::= [ "NOT" | "not" ]
<logical_operator> ::= [ "AND" | "OR" | "and" | "or" ]
<boolean_operator> ::= [ "=" | "!=" ]
<array_operator> ::= [ "IN" | "NOT IN" | "in" | "not in" ]
<array> ::= ( "[" "]" | "[" ( "," <tag_value> )* )
<tag_name> ::= <identifier>
<tag_value> ::= ( "'" <regexp> "'" | <simple_value> )
;
; <identifier> and <simple_value> follow pattern [a-zA-Z_0-9][\-a-zA-Z_0-9]*
; <regexp> follows any valid Java Regular Expression format

Query parameters

Parameter Required Description Type Allowable Values

startTime

No

Filter out events created before this time.

integer

Timestamp in millisecond since epoch.

endTime

No

Filter out events created after this time.

integer

Timestamp in millisecond since epoch.

eventIds

No

Filter out events for unspecified eventIds.

string

Comma separated list of event IDs.

triggerIds

No

Filter out events for unspecified triggers.

string

Comma separated list of trigger IDs.

categories

No

Filter out events for unspecified categories.

string

Comma separated list of category values.

tags

No

[DEPRECATED] Filter out events for unspecified tags.

string

Comma separated list of tags, each tag of format 'name|value'.
Specify '*' for value to match all values.

tagQuery

No

Filter out events for unspecified tags.

string

A tag query expression.

thin

No

Return only thin events, do not include: evalSets.

boolean

-

Response

Status codes

Status Code Reason Response Model

200

Successfully fetched list of events.

array of Event

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint POST /events

Create a new Event.

Persist the new event and send it to the engine for processing/condition evaluation.
Returns created Event.

Body

Required Description Data Type

Yes

Event to be created. Category and Text fields required,

Event

Response

Status codes

Status Code Reason Response Model

200

Success, Event Created.

Event

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint POST /events/data

Send events to the engine for processing/condition evaluation.

Only events generated by the engine are persisted.
Input events are treated as external data and those are not persisted into the system.

Body

Required Description Data Type

Yes

Events to be processed by alerting.

array of Event

Response

Status codes

Status Code Reason Response Model

200

Success, Event Created.

-

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint PUT /events/delete

Delete events with optional filtering.

Return number of events deleted.
WARNING: If not criteria defined, it deletes all events stored in the system.
Tags Query language (BNF):

<tag_query> ::= ( <expression> | "(" <object> ")" | <object> <logical_operator> <object> )
<expression> ::= ( <tag_name> | <not> <tag_name> | <tag_name> <boolean_operator> <tag_value> | <tag_name> <array_operator> <array> )
<not> ::= [ "NOT" | "not" ]
<logical_operator> ::= [ "AND" | "OR" | "and" | "or" ]
<boolean_operator> ::= [ "=" | "!=" ]
<array_operator> ::= [ "IN" | "NOT IN" | "in" | "not in" ]
<array> ::= ( "[" "]" | "[" ( "," <tag_value> )* ) +
<tag_name> ::= <identifier>
<tag_value> ::= ( "'" <regexp> "'" | <simple_value> )
;
 ; <identifier> and <simple_value> follow pattern [a-zA-Z_0-9][\-a-zA-Z_0-9]*
; <regexp> follows any valid Java Regular Expression format

Query parameters

Parameter Required Description Type Allowable Values

startTime

No

Filter out events created before this time.

integer

Timestamp in millisecond since epoch.

endTime

No

Filter out events created after this time.

integer

Timestamp in millisecond since epoch.

eventIds

No

Filter out events for unspecified eventIds.

string

Comma separated list of event IDs.

triggerIds

No

Filter out events for unspecified triggers.

string

Comma separated list of trigger IDs.

categories

No

Filter out events for unspecified categories.

string

Comma separated list of category values.

tags

No

[DEPRECATED] Filter out events for unspecified tags.

string

Comma separated list of tags, each tag of format 'name|value'.
Specify '*' for value to match all values.

tagQuery

No

Filter out events for unspecified tags.

string

A tag query expression.

Response

Status codes

Status Code Reason Response Model

200

Success.

ApiDeleted

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint GET /events/event/{eventId}

Get an existing Event.

Path parameters

Parameter Required Description Type Allowable Values

eventId

Yes

Id of Event to be retrieved.

string

-

Query parameters

Parameter Required Description Type Allowable Values

thin

No

Return only a thin event, do not include: evalSets, dampening.

boolean

-

Response

Status codes

Status Code Reason Response Model

200

Success, Event found.

Event

400

Bad Request/Invalid Parameters.

ApiError

404

Event not found.

ApiError

500

Internal server error.

ApiError

Endpoint DELETE /events/tags

Remove tags from existing Events.

Query parameters

Parameter Required Description Type Allowable Values

eventIds

Yes

List of events to untag.

string

Comma separated list of event IDs.

tagNames

Yes

List of tag names to remove.

string

Comma separated list of tags names.

Response

Status codes

Status Code Reason Response Model

200

Success, Events untagged successfully.

-

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint PUT /events/tags

Add tags to existing Events.

Query parameters

Parameter Required Description Type Allowable Values

eventIds

Yes

List of eventIds to tag.

string

Comma separated list of events IDs.

tags

Yes

List of tags to add.

string

Comma separated list of tags.
Each tag of format 'name|value'.

Response

Status codes

Status Code Reason Response Model

200

Success, Events tagged successfully.

-

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint GET /events/watch

Watch events with optional filtering.

Return a stream of events ordered by ctime.

If not criteria defined, it fetches all events stored in the system.

Time criterias are used only for the initial query.
After initial query, time criterias are discarded, watching events by ctime.
Non time criterias are active.
If not criteria defined, it fetches all events stored in the system.
Tags Query language (BNF):

<tag_query> ::= ( <expression> | "(" <object> ")" | <object> <logical_operator> <object> )
<expression> ::= ( <tag_name> | <not> <tag_name> | <tag_name> <boolean_operator> <tag_value> | <tag_name> <array_operator> <array> )
<not> ::= [ "NOT" | "not" ]
<logical_operator> ::= [ "AND" | "OR" | "and" | "or" ]
<boolean_operator> ::= [ "=" | "!=" ]
<array_operator> ::= [ "IN" | "NOT IN" | "in" | "not in" ]
<array> ::= ( "[" "]" | "[" ( "," <tag_value> )* )
<tag_name> ::= <identifier>
<tag_value> ::= ( "'" <regexp> "'" | <simple_value> )
;
; <identifier> and <simple_value> follow pattern [a-zA-Z_0-9][\-a-zA-Z_0-9]*
; <regexp> follows any valid Java Regular Expression format

Query parameters

Parameter Required Description Type Allowable Values

startTime

No

Filter out events created before this time.

integer

Timestamp in millisecond since epoch.

endTime

No

Filter out events created after this time.

integer

Timestamp in millisecond since epoch.

eventIds

No

Filter out events for unspecified eventIds.

string

Comma separated list of event IDs.

triggerIds

No

Filter out events for unspecified triggers.

string

Comma separated list of trigger IDs.

categories

No

Filter out events for unspecified categories.

string

Comma separated list of category values.

tags

No

[DEPRECATED] Filter out events for unspecified tags.

string

Comma separated list of tags, each tag of format 'name|value'.
Specify '*' for value to match all values.

tagQuery

No

Filter out events for unspecified tags.

string

A tag query expression.

watchInterval

No

Define interval when watcher notifications will be sent.

integer

Interval in seconds

thin

No

Return only thin events, do not include: evalSets.

boolean

-

Response

Status codes

Status Code Reason Response Model

200

Errors will close the stream. Description is sent before stream is closed.

ApiError

Endpoint DELETE /events/{eventId}

Delete an existing Event.

Path parameters

Parameter Required Description Type Allowable Values

eventId

Yes

Event id to be deleted.

string

-

Response

Status codes

Status Code Reason Response Model

200

Success, Event deleted.

-

400

Bad Request/Invalid Parameters.

ApiError

404

Event not found.

ApiError

500

Internal server error.

ApiError

[ /export ] Export of triggers and actions definitions

  1. Export a list of full triggers and action definitions.

Endpoint GET /export

Export a list of full triggers and action definitions.

Response

Status codes

Status Code Reason Response Model

200

Successfully exported list of full triggers and action definitions.

Definitions

400

Bad Request/Invalid Parameters

ApiError

500

Internal server error.

ApiError

[ /import ] Import of triggers and actions definitions

  1. Import a list of full triggers and action definitions.

Endpoint POST /import/{strategy}

Import a list of full triggers and action definitions.

Return a list of effectively imported full triggers and action definitions.

Import options:

DELETE

Existing data in the backend is DELETED before the import operation.
All FullTrigger and [ActionDefinition objects] defined in the Definitions parameter are imported.

ALL

Existing data in the backend is NOT DELETED before the import operation.
All FullTrigger and ActionDefinition objects defined in the Definitions parameter are imported.
Existing FullTrigger and ActionDefinition objects are overwritten with new values passed in the Definitions parameter.
NEW

Existing data in the backend is NOT DELETED before the import operation.
Only NEW FullTrigger and ActionDefinition objects defined in the Definitions parameters are imported.
Existing FullTrigger and ActionDefinition objects are maintained in the backend.

OLD
Existing data in the backend is NOT DELETED before the import operation.
Only FullTrigger and ActionDefinition objects defined in the Definitions parameter that previously exist in the backend are imported and overwritten.
New FullTrigger and ActionDefinition objects that don’t exist previously in the backend are ignored.

Path parameters

Parameter Required Description Type Allowable Values

strategy

Yes

Import strategy.

string

DELETE, ALL, NEW, OLD

Body

Required Description Data Type

No

Collection of full triggers and action definitions to import.

Definitions

Response

Status codes

Status Code Reason Response Model

200

Successfully exported list of full triggers and action definitions.

Definitions

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

[ /plugins ] Query operations for action plugins

  1. Find all action plugins.

  2. Find list of properties to fill for a specific action plugin.

Endpoint GET /plugins

Find all action plugins.

Response

Status codes

Status Code Reason Response Model

200

Successfully fetched list of actions plugins.

array of string

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint GET /plugins/{actionPlugin}

Find list of properties to fill for a specific action plugin.

Each action plugin can have a different and variable number of properties.
This method should be invoked before of a creation of a new action.

Path parameters

Parameter Required Description Type Allowable Values

actionPlugin

Yes

Action plugin to query.

string

-

Response

Status codes

Status Code Reason Response Model

200

Action Plugin found.

array of string

400

Bad Request/Invalid Parameters.

ApiError

404

Action Plugin not found.

ApiError

500

Internal server error

ApiError

[ /status ] Status of Alerting Service

  1. Get status info of Alerting Service.

Endpoint GET /status

Get status info of Alerting Service.

Status fields:
{
"status":"<STARTED>|<FAILED>",
"Implementation-Version":"<Version>",
"Built-From-Git-SHA1":"<Git-SHA1>",
"distributed":"<true|false>",
"members":"<comma list of nodes IDs>"
}

Response

Status codes

Status Code Reason Response Model

200

successful operation

map[string,string]

[ /triggers ] Triggers Definitions Handling

  1. Get triggers with optional filtering.

  2. Create a new trigger.

  3. Update triggers to be enabled or disabled.

  4. Create a new group trigger.

  5. Update group triggers and their member triggers to be enabled or disabled.

  6. Create a new member trigger for a parent trigger.

  7. Make a non-orphan member trigger into an orphan.

  8. Make a non-orphan member trigger into an orphan.

  9. Delete a group trigger.

  10. Update an existing group trigger definition and its member definitions.

  11. Set the conditions for the group trigger.

  12. Set the conditions for the group trigger.

  13. Create a new group dampening.

  14. Delete an existing group dampening definition.

  15. Update an existing group dampening definition.

  16. Find all group member trigger definitions.

  17. Create a new full trigger (trigger, dampenings and conditions).

  18. Get an existing full trigger definition (trigger, dampenings and conditions).

  19. Delete an existing standard or group member trigger definition.

  20. Get an existing trigger definition.

  21. Update an existing trigger definition.

  22. Get all conditions for a specific trigger.

  23. Set the conditions for the trigger.

  24. Set the conditions for the trigger, for the given trigger mode.

  25. Get all Dampenings for a Trigger (1 Dampening per mode).

  26. Create a new dampening.

  27. Get dampening using triggerId and triggerMode.

  28. Delete an existing dampening definition.

  29. Get an existing dampening.

  30. Update an existing dampening definition.

Endpoint GET /triggers

Get triggers with optional filtering.

If not criteria defined, it fetches all triggers stored in the system.

Query parameters

Parameter Required Description Type Allowable Values

triggerIds

No

Filter out triggers for unspecified triggerIds.

string

Comma separated list of trigger IDs.

tags

No

Filter out triggers for unspecified tags.

string

Comma separated list of tags, each tag of format 'name|value'.
Specify '*' for value to match all values.

thin

No

Return only thin triggers. Currently Ignored.

boolean

-

Response

Status codes

Status Code Reason Response Model

200

Successfully fetched list of triggers.

array of Trigger

400

Bad request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint POST /triggers

Create a new trigger.

Return created trigger.

Body

Required Description Data Type

Yes

Trigger definition to be created.

Trigger

Response

Status codes

Status Code Reason Response Model

200

Success, Trigger created.

Trigger

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint PUT /triggers/enabled

Update triggers to be enabled or disabled.

Query parameters

Parameter Required Description Type Allowable Values

triggerIds

Yes

List of trigger ids to enable or disable

string

Comma separated list of triggerIds to be enabled or disabled.

enabled

Yes

Set enabled or disabled.

boolean

-

Response

Status codes

Status Code Reason Response Model

200

Success, Triggers updated.

-

400

Bad Request/Invalid Parameters.

ApiError

404

Trigger doesn’t exist.

ApiError

500

Internal server error.

ApiError

Endpoint POST /triggers/groups

Create a new group trigger.

Returns created group trigger.

Body

Required Description Data Type

Yes

Trigger definition to be created.

Trigger

Response

Status codes

Status Code Reason Response Model

200

Success, Group Trigger Created.

Trigger

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint PUT /triggers/groups/enabled

Update group triggers and their member triggers to be enabled or disabled.

Query parameters

Parameter Required Description Type Allowable Values

triggerIds

Yes

List of group trigger ids to enable or disable

string

Comma separated list of group triggerIds to be enabled or disabled.

enabled

Yes

Set enabled or disabled.

boolean

-

Response

Status codes

Status Code Reason Response Model

200

Success, Group Triggers updated.

-

400

Bad Request/Invalid Parameters.

ApiError

404

Group Trigger doesn’t exist.

ApiError

500

Internal server error.

ApiError

Endpoint POST /triggers/groups/members

Create a new member trigger for a parent trigger.

Returns Member Trigger created if operation finished correctly.

Body

Required Description Data Type

Yes

Group member trigger to be created.

GroupMemberInfo

Response

Status codes

Status Code Reason Response Model

200

Success, Member Trigger Created.

Trigger

400

Bad Request/Invalid Parameters.

ApiError

404

Group trigger not found.

ApiError

500

Internal server error.

ApiError

Endpoint POST /triggers/groups/members/{memberId}/orphan

Make a non-orphan member trigger into an orphan.

Path parameters

Parameter Required Description Type Allowable Values

memberId

Yes

Member Trigger id to be made an orphan.

string

-

Response

Status codes

Status Code Reason Response Model

200

Success, Trigger updated.

-

400

Bad Request/Invalid Parameters.

ApiError

404

Trigger doesn’t exist/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint POST /triggers/groups/members/{memberId}/unorphan

Make a non-orphan member trigger into an orphan.

Path parameters

Parameter Required Description Type Allowable Values

memberId

Yes

Member Trigger id to be made an orphan.

string

-

Body

Required Description Data Type

Yes

Only context and dataIdMap are used when changing back to a non-orphan.

UnorphanMemberInfo

Response

Status codes

Status Code Reason Response Model

200

Success, Trigger updated.

-

400

Bad Request/Invalid Parameters.

ApiError

404

Trigger doesn’t exist.

ApiError

500

Internal server error.

ApiError

Endpoint DELETE /triggers/groups/{groupId}

Delete a group trigger.

Path parameters

Parameter Required Description Type Allowable Values

groupId

Yes

Group Trigger id.

string

-

Query parameters

Parameter Required Description Type Allowable Values

keepNonOrphans

Yes

Convert the non-orphan member triggers to standard triggers.

boolean

-

keepOrphans

Yes

Convert the orphan member triggers to standard triggers.

boolean

-

Response

Status codes

Status Code Reason Response Model

200

Success, Group Trigger Removed.

-

400

Bad Request/Invalid Parameters.

ApiError

404

Group Trigger not found.

ApiError

500

Internal server error.

ApiError

Endpoint PUT /triggers/groups/{groupId}

Update an existing group trigger definition and its member definitions.

Path parameters

Parameter Required Description Type Allowable Values

groupId

Yes

Group Trigger id to be updated.

string

-

Body

Required Description Data Type

Yes

Updated group trigger definition.

Trigger

Response

Status codes

Status Code Reason Response Model

200

Success, Group Trigger updated.

-

400

Bad Request/Invalid Parameters.

ApiError

404

Trigger doesn’t exist.

ApiError

500

Internal server error.

ApiError

Endpoint PUT /triggers/groups/{groupId}/conditions

Set the conditions for the group trigger.

This replaces any existing conditions on the group and member conditions for all trigger modes.
Return the new group conditions.

Path parameters

Parameter Required Description Type Allowable Values

groupId

Yes

The relevant Group Trigger.

string

-

Body

Required Description Data Type

No

Collection of Conditions to set and Map with tokens per dataId on members.

GroupConditionsInfo

Response

Status codes

Status Code Reason Response Model

200

Success, Group Condition Set created.

array of Condition

400

Bad Request/Invalid Parameters.

ApiError

404

No trigger found.

ApiError

500

Internal server error

ApiError

Endpoint PUT /triggers/groups/{groupId}/conditions/{triggerMode}

Set the conditions for the group trigger.

This replaces any existing conditions on the group and member conditions.
Return the new group conditions.

Path parameters

Parameter Required Description Type Allowable Values

groupId

Yes

The relevant Group Trigger.

string

-

triggerMode

Yes

The trigger mode.

string

FIRING or AUTORESOLVE (not case sensitive)

Body

Required Description Data Type

No

Collection of Conditions to set and Map with tokens per dataId on members.

GroupConditionsInfo

Response

Status codes

Status Code Reason Response Model

200

Success, Group Condition Set created.

array of Condition

400

Bad Request/Invalid Parameters.

ApiError

404

No trigger found.

ApiError

500

Internal server error

ApiError

Endpoint POST /triggers/groups/{groupId}/dampenings

Create a new group dampening.

Return group Dampening created.

Path parameters

Parameter Required Description Type Allowable Values

groupId

Yes

Group Trigger definition id attached to dampening.

string

-

Body

Required Description Data Type

Yes

Dampening definition to be created.

Dampening

Response

Status codes

Status Code Reason Response Model

200

Success, Dampening created.

Dampening

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint DELETE /triggers/groups/{groupId}/dampenings/{dampeningId}

Delete an existing group dampening definition.

Path parameters

Parameter Required Description Type Allowable Values

groupId

Yes

Trigger definition id to be retrieved.

string

-

dampeningId

Yes

Dampening id for dampening definition to be deleted.

string

-

Response

Status codes

Status Code Reason Response Model

200

Success, Dampening deleted.

-

400

Bad Request/Invalid Parameters.

ApiError

404

No Dampening found.

ApiError

500

Internal server error.

ApiError

Endpoint PUT /triggers/groups/{groupId}/dampenings/{dampeningId}

Update an existing group dampening definition.

Note that the trigger mode can not be changed.
Return Dampening updated.

Path parameters

Parameter Required Description Type Allowable Values

groupId

Yes

Trigger definition id to be retrieved.

string

-

dampeningId

Yes

Dampening id.

string

-

Body

Required Description Data Type

Yes

Updated dampening definition.

Dampening

Response

Status codes

Status Code Reason Response Model

200

Success, Dampening Updated.

Dampening

400

Bad Request/Invalid Parameters.

ApiError

404

No Dampening Found.

ApiError

500

Internal server error

ApiError

Endpoint GET /triggers/groups/{groupId}/members

Find all group member trigger definitions.

Pagination is not yet implemented.

Path parameters

Parameter Required Description Type Allowable Values

groupId

Yes

Group TriggerId.

string

-

Query parameters

Parameter Required Description Type Allowable Values

includeOrphans

No

include Orphan members? No if omitted.

boolean

-

Response

Status codes

Status Code Reason Response Model

200

Successfully fetched list of triggers.

array of Trigger

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint POST /triggers/trigger

Create a new full trigger (trigger, dampenings and conditions).

Return created full trigger.

Body

Required Description Data Type

Yes

FullTrigger (trigger, dampenings, conditions) to be created.

FullTrigger

Response

Status codes

Status Code Reason Response Model

200

Success, FullTrigger created.

FullTrigger

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint GET /triggers/trigger/{triggerId}

Get an existing full trigger definition (trigger, dampenings and conditions).

Path parameters

Parameter Required Description Type Allowable Values

triggerId

Yes

Full Trigger definition id to be retrieved.

string

-

Response

Status codes

Status Code Reason Response Model

200

Success, FullTrigger found.

FullTrigger

400

Bad Request/Invalid Parameters.

ApiError

404

Trigger not found.

ApiError

500

Internal server error.

ApiError

Endpoint DELETE /triggers/{triggerId}

Delete an existing standard or group member trigger definition.

This can not be used to delete a group trigger definition.

Path parameters

Parameter Required Description Type Allowable Values

triggerId

Yes

Trigger definition id to be deleted.

string

-

Response

Status codes

Status Code Reason Response Model

200

Success, Trigger deleted.

-

400

Bad Request/Invalid Parameters.

ApiError

404

Trigger not found.

ApiError

500

Internal server error.

ApiError

Endpoint GET /triggers/{triggerId}

Get an existing trigger definition.

Path parameters

Parameter Required Description Type Allowable Values

triggerId

Yes

Trigger definition id to be retrieved.

string

-

Response

Status codes

Status Code Reason Response Model

200

Success, Trigger found.

Trigger

400

Bad Request/Invalid Parameters.

ApiError

404

Trigger not found.

ApiError

500

Internal server error.

ApiError

Endpoint PUT /triggers/{triggerId}

Update an existing trigger definition.

Path parameters

Parameter Required Description Type Allowable Values

triggerId

Yes

Trigger definition id to be updated.

string

-

Body

Required Description Data Type

Yes

Updated trigger definition.

Trigger

Response

Status codes

Status Code Reason Response Model

200

Success, Trigger updated.

-

400

Bad Request/Invalid Parameters.

ApiError

404

Trigger doesn’t exist.

ApiError

500

Internal server error.

ApiError

Endpoint GET /triggers/{triggerId}/conditions

Get all conditions for a specific trigger.

Path parameters

Parameter Required Description Type Allowable Values

triggerId

Yes

Trigger definition id to be retrieved.

string

-

Response

Status codes

Status Code Reason Response Model

200

Successfully fetched list of conditions.

array of Condition

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint PUT /triggers/{triggerId}/conditions

Set the conditions for the trigger.

This sets the conditions for all trigger modes, replacing existing conditions for all trigger modes. Returns the new conditions.

Path parameters

Parameter Required Description Type Allowable Values

triggerId

Yes

The relevant Trigger.

string

-

Body

Required Description Data Type

Yes

Collection of Conditions to set.

array of Condition

Response

Status codes

Status Code Reason Response Model

200

Success, Condition Set created.

array of Condition

400

Bad Request/Invalid Parameters.

ApiError

404

No trigger found.

ApiError

500

Internal server error.

ApiError

Endpoint PUT /triggers/{triggerId}/conditions/{triggerMode}

Set the conditions for the trigger, for the given trigger mode.

This replaces any existing conditions. Returns the new conditions.

Path parameters

Parameter Required Description Type Allowable Values

triggerId

Yes

The relevant Trigger.

string

-

triggerMode

Yes

The trigger mode.

string

FIRING or AUTORESOLVE (not case sensitive)

Body

Required Description Data Type

Yes

Collection of Conditions to set.

array of Condition

Response

Status codes

Status Code Reason Response Model

200

Success, Condition Set created.

array of Condition

400

Bad Request/Invalid Parameters.

ApiError

404

No trigger found.

ApiError

500

Internal server error.

ApiError

Endpoint GET /triggers/{triggerId}/dampenings

Get all Dampenings for a Trigger (1 Dampening per mode).

Path parameters

Parameter Required Description Type Allowable Values

triggerId

Yes

Trigger definition id to be retrieved.

string

-

Response

Status codes

Status Code Reason Response Model

200

Successfully fetched list of dampenings.

array of Dampening

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint POST /triggers/{triggerId}/dampenings

Create a new dampening.

Return Dampening created.

Path parameters

Parameter Required Description Type Allowable Values

triggerId

Yes

Trigger definition id attached to dampening.

string

-

Body

Required Description Data Type

Yes

Dampening definition to be created.

Dampening

Response

Status codes

Status Code Reason Response Model

200

Success, Dampening created.

Dampening

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint GET /triggers/{triggerId}/dampenings/mode/{triggerMode}

Get dampening using triggerId and triggerMode.

Path parameters

Parameter Required Description Type Allowable Values

triggerId

Yes

Trigger definition id to be retrieved.

string

-

triggerMode

Yes

Trigger mode

string

FIRING, AUTORESOLVE

Response

Status codes

Status Code Reason Response Model

200

Successfully fetched list of dampenings.

array of Dampening

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint DELETE /triggers/{triggerId}/dampenings/{dampeningId}

Delete an existing dampening definition.

Path parameters

Parameter Required Description Type Allowable Values

triggerId

Yes

Trigger definition id to be deleted.

string

-

dampeningId

Yes

Dampening id for dampening definition to be deleted.

string

-

Response

Status codes

Status Code Reason Response Model

200

Success, Dampening deleted.

-

400

Bad Request/Invalid Parameters.

ApiError

404

No Dampening found.

ApiError

500

Internal server error

ApiError

Endpoint GET /triggers/{triggerId}/dampenings/{dampeningId}

Get an existing dampening.

Path parameters

Parameter Required Description Type Allowable Values

triggerId

Yes

Trigger definition id to be retrieved.

string

-

dampeningId

Yes

Dampening id

string

-

Response

Status codes

Status Code Reason Response Model

200

Success, Dampening Found.

Dampening

400

Bad Request/Invalid Parameters.

ApiError

404

No Dampening Found.

ApiError

500

Internal server error.

ApiError

Endpoint PUT /triggers/{triggerId}/dampenings/{dampeningId}

Update an existing dampening definition.

Note that the trigger mode can not be changed.
Return Dampening updated.

Path parameters

Parameter Required Description Type Allowable Values

triggerId

Yes

Trigger definition id to be retrieved.

string

-

dampeningId

Yes

Dampening id.

string

-

Body

Required Description Data Type

Yes

Updated dampening definition

Dampening

Response

Status codes

Status Code Reason Response Model

200

Success, Dampening Updated.

Dampening

400

Bad Request/Invalid Parameters.

ApiError

404

No Dampening Found.

ApiError

500

Internal server error

ApiError

Data Types

Action

An action represents a consequence of an event.

An Action object represents a particular action linked with a specific event.
Action objects are generated by the Alerting engine and processed by plugins.
An Action object stores the eventId property and optionally may contain the full Event object.
An Action may store the result of the processing by a plugin.

Name Required Description Type Allowable Values Default Value

eventId

No

Event id from where this action is generated.

string

-

-

tenantId

No

Tenant id owner of this trigger.

string

Tenant is overwritten from Hawkular-Tenant HTTP header parameter request

-

actionPlugin

Yes

Action plugin identifier.

string

Only plugins deployed on the system are valid.

-

ctime

No

Time when this action was generated.

integer

-

-

actionId

Yes

Action definition identifier.

string

-

-

event

No

Attached Event from where this action is generated.

Event

-

-

global

No

Flag to indicate this is a global action.

boolean

-

-

result

No

Result of action processing.

string

-

-

properties

Yes

Plugin properties. Each plugin defines its own specific properties that can be supplied at action definition level.

object

map[string,string]

-

states

No

A list of Alert.Status restricting active states for this action. TriggerAction constraints take precedence, if defined

array of string

-

-

calendar

No

A TimeConstraint restricting active times for this action. TriggerAction constraints take precedence, if defined.

TimeConstraint

-

-

ActionDefinition

An action represents a consequence of an event.

Actions are processed by plugins, and plugins offer a map of properties to personalize an action.
An ActionDefinition stores which properties will be used for a specific action in a specific plugin.

A Trigger definition can be assigned a list of action definitions.

The alert engine will instantiate a specific Action based on its ActionDefinition.

An ActionDefinition can add default constraints to determine when an action will be performed.

TriggerAction can override the default constraints. + — States constraint: a set of Alert.Status (represented by its string value).
The action is limited to the specified states. By default the action applies to all Alert states.
Unlike Alerts, Events don’t have lifecycle. All TriggerActions are applied at Event creation time.
+ — Calendar constraint: A TimeConstraint.
The action is applied only when the event create time occurs during the specified time intervals,
absolute or relative, as defined. By default the action can be performed at any time.

If a TriggerAction defines any constraints the ActionDefinition constraints will be ignored.
If a TriggerAction defines no constraints the ActionDefinition constraints will be used.

Name Required Description Type Allowable Values Default Value

tenantId

No

Tenant id owner of this trigger.

string

Tenant is overwritten from Hawkular-Tenant HTTP header parameter request

-

actionPlugin

Yes

Action plugin identifier.

string

Only plugins deployed on the system are valid.

-

actionId

Yes

Action definition identifier.

string

-

-

global

No

Flag to indicate this is a global action.

boolean

-

-

properties

Yes

Plugin properties. Each plugin defines its own specific properties that can be supplied at action definition level.

object

map[string,string]

-

states

No

A list of Alert.Status restricting active states for this action. TriggerAction constraints take precedence, if defined

array of string

-

-

calendar

No

A TimeConstraint restricting active times for this action. TriggerAction constraints take precedence, if defined.

TimeConstraint

-

-

Alert

Alerts are generated when an Alert Trigger fires, based on a set of defined conditions
that have been matched, possibly more than once or have held true over a period of time.

When fired the trigger can perform actions based on plugins (e-mail, sms, etc).

Alerts then start moving through the Open, Acknowledged, Resolved life-cycle.

- Open status represents an alert which has not been seen/taken yet by any user.
- Acknowledge status represents an alert which has been seen/taken by any user and it is pending resolution.
- Resolved status represents an alert which problem has been resolved.

Alerts can be resolved automatically using AUTORESOLVE Trigger conditions or manually via API.

Alert can attach a list of notes defined by the user.

There are many options on triggers to help ensure that alerts are not generated too frequently,
including ways of automatically disabling and enabling the trigger.

Name Required Description Type Allowable Values Default Value

eventType

No

Indicate if this object is an EVENT or an ALERT. This is a read-only field controlled by the system for serialization purposes.

string

EVENT, ALERT

-

severity

No

Severity set for a Trigger and assigned to an alert when it is generated.

string

LOW, MEDIUM, HIGH, CRITICAL

MEDIUM

status

No

Lifecycle current status.

string

OPEN, ACKNOWLEDGED, RESOLVED

-

tenantId

No

Tenant id owner of this event.

string

Tenant is overwritten from Hawkular-Tenant HTTP header parameter request

-

id

Yes

Unique identifier for this event.

string

-

-

notes

No

Notes attached with this alert.

array of Note

-

-

ctime

Yes

Creation time for this event.

integer

-

-

lifecycle

No

List of lifecycle states that this alert has navigated.

array of LifeCycle

-

-

dataSource

No

Optional dataSource for Event. Used for Trigger in EventCondition to evaluate events with triplet [tenantId, source, dataId] as unique identifier.

string

Timestamp in milliseconds.

-

resolvedEvalSets

No

The Eval Sets that resolved the Trigger in AUTORESOLVE mode.
Null for non AUTORESOLVE triggers.

array of array of ConditionEval

-

-

dataId

Yes

Data identifier used for Events condition evaluation. Events must supply a valid dataId to be considered for EventCondition evaluation.
DataIds in an events context should incorporate the source of the event (for uniqueness).
Events generated from a Trigger will have dataId set to the triggerId, therefore allowing chaining with other EventCondition.

string

-

-

category

Yes

Category of Event. Suitable for display.
Alerts will use ALERT category.
Events generated from Trigger will use Trigger.eventCategory or TRIGGER category as default.

string

Any category defined by the user.

ALERT or TRIGGER

text

Yes

Description of the event. Suitable for display.
Events generated from Trigger will use Trigger.eventText or Trigger.description/Trigger.name as default.

string

Any description defined by the user.

-

context

No

Properties defined by the user for this event.
Events generated from Trigger will use Trigger.context.
Context cannot be used as part of Event conditions expressions or criteria in finder methods.

object

map[string,string]

-

tags

No

Tags defined by the user for this event.
Events generated from Trigger will use Trigger.tags.
Tags can be used as part of Event conditions expressions and criteria in finder methods.
Tag value cannot be null.

object

map[string,string]

-

trigger

No

Trigger that created the event.
Null for API-generated Events.

Trigger

-

-

dampening

No

Dampening defined when the event was created.
Null for API-generated Events.

Dampening

-

-

evalSets

No

The Eval Sets that fired the trigger.
Null for API-generated Events.

array of array of ConditionEval

-

-

ApiDeleted

Payload for a simple REST deleted number response.

Name Required Description Type Allowable Values Default Value

deleted

No

Deleted items.

integer

-

-

ApiError

Payload for a REST error response.

Name Required Description Type Allowable Values Default Value

errorMsg

No

Description of the error message.

string

-

-

AvailabilityCondition

An availability condition definition.

Examples:
X is DOWN

Subtype of Condition

Name Required Description Type Allowable Values Default Value

operator

Yes

Availability operator.

string

DOWN, NOT_UP, UP

-

AvailabilityConditionEval

An evaluation state for availability condition.

Subtype of ConditionEval

Name Required Description Type Allowable Values Default Value

condition

No

Availability condition linked with this state.

AvailabilityCondition

-

-

value

No

Availability value used for dataId.

string

UP, DOWN, UNAVAILABLE

-

CompareCondition

A numeric comparison condition.

Examples:
X > 80% of Y, FreeSpace < 20% of TotalSpace

Subtype of Condition

Name Required Description Type Allowable Values Default Value

operator

Yes

Compare operator [LT (<), GT (>), LTE (⇐), GTE (>=)].

string

LT, GT, LTE, GTE

-

data2Id

Yes

Data identifier of the metric used for comparison.

string

-

-

data2Multiplier

Yes

Straight multiplier to be applied to data2Id on the comparison. Final comparison expression can be read as "dataId <operator> data2Multiplier*data2Id".

number

-

-

CompareConditionEval

An evaluation state for compare condition.

Subtype of ConditionEval

Name Required Description Type Allowable Values Default Value

condition

No

Compare condition linked with this state.

CompareCondition

-

-

value1

No

Numeric value used for dataId.

number

-

-

value2

No

Numeric value used for data2Id.

number

-

-

context2

No

Properties defined by the user at Data level on the data2Id used for this evaluation.

object

map[string,string]

-

Condition

A base class for condition definition.

Name Required Description Type Allowable Values Default Value

tenantId

Yes

Tenant id owner of this condition.

string

Tenant is overwritten from Hawkular-Tenant HTTP header parameter request

-

triggerId

No

The owning trigger.

string

triggerId is set up from REST request parameters

-

triggerMode

Yes

The owning trigger’s mode when this condition is active.

string

FIRING, AUTORESOLVE

-

type

Yes

The type of the condition defined. Each type has its specific properties defined on its subtype of condition.

string

AVAILABILITY, COMPARE, STRING, THRESHOLD, RANGE, EXTERNAL, EVENT, RATE, MISSING, NELSON

-

conditionSetSize

No

Number of conditions associated with a particular trigger. This is a read-only value defined by the system.

integer

-

-

conditionSetIndex

No

Index of the current condition. This is a read-only value defined by the system.

integer

-

-

conditionId

No

A composed key for the condition. This is a read-only value defined by the system.

string

-

-

context

No

Properties defined by the user for this condition.

object

map[string,string]

-

dataId

Yes

Data identifier used for condition evaluation. dataId is used in conjunction with operators defined at subtype condition level.

string

-

-

ConditionEval

A base class to represent an evaluation state of a specific condition.

Name Required Description Type Allowable Values Default Value

evalTimestamp

No

Time of condition evaluation.

integer

-

-

dataTimestamp

No

Time stamped on the data used in the evaluation.

integer

-

-

type

No

The type of the condition eval defined. Each type has its specific properties defined on its subtype of condition eval.

string

AVAILABILITY, COMPARE, STRING, THRESHOLD, RANGE, EXTERNAL, EVENT, RATE, MISSING, NELSON

-

context

No

Properties defined by the user at Data level on the dataId used for this evaluation.

object

map[string,string]

-

Dampening

A representation of dampening status.

It’s often the case that you don’t want a trigger to fire every time a condition set is met.
Instead, you want to ensure that the issue is not a spike of activity.
Hawkular Alerting provides several ways of ensuring triggers fire only as desired.

This is a Trigger Dampening in Hawkular Alerting terminology.

Dampening types:

STRICT

- N consecutive true evaluations.
- Useful for ignoring spikes in activity or waiting for a prolonged event.

RELAXED_COUNT

- N true evaluations out of M total evaluations.
- Useful for ignoring short spikes in activity but catching frequently spiking activity.

RELAXED_TIME

- N true evaluations in T time.
- Useful for ignoring short spikes in activity but catching frequently spiking activity.
STRICT_TIME

- Only true evaluations for at least T time.
- Useful for reporting a continued aberration.

STRICT_TIMEOUT

- Only true evaluations for T time.
- Useful for reporting a continued aberration with a more guaranteed firing time.

Name Required Description Type Allowable Values Default Value

tenantId

No

Tenant id owner of this dampening.

string

Tenant is overwritten from Hawkular-Tenant HTTP header parameter request

-

triggerId

No

The owning trigger.

string

triggerId is set up from REST request parameters

-

triggerMode

Yes

The owning trigger’s mode when this dampening is active.

string

FIRING, AUTORESOLVE

-

type

Yes

The type of the dampening.

string

STRICT, RELAXED_COUNT, RELAXED_TIME, STRICT_TIME, STRICT_TIMEOUT

-

evalTrueSetting

No

Number of required true evaluations for STRICT, RELAXED_COUNT, RELAXED_TIME

integer

-

-

evalTotalSetting

No

Number of allowed evaluation attempts for RELAXED_COUNT

integer

-

-

evalTimeSetting

No

Time period in milliseconds for RELAXED_TIME, STRICT_TIME, STRICT_TIMEOUT

integer

-

-

dampeningId

No

A composed key for the dampening. This is a read-only value defined by the system.

string

-

-

Data

A base class for incoming data into alerts subsystem.
All Data has TenantId, Id and a timestamp.
An Id should be unique within the tenant.
The timestamp is used to ensure that data is time-ordered when being sent into the alerting engine.
If not assigned the timestamp will be assigned to current time.

Name Required Description Type Allowable Values Default Value

tenantId

No

Tenant id owner of this data.

string

Tenant is overwritten from Hawkular-Tenant HTTP header parameter request

-

source

No

Extended mechanism to match trigger conditions against Data with [source, dataId] identifiers. In this way it is possible to qualify triggers and data with a source such that a trigger only evaluates data having the same source.

string

-

-

id

Yes

Data id unique within the tenant.

string

-

-

timestamp

No

Timestamp for the data.

integer

-

If not assigned, timestamp will be assigned to current time.

value

No

Value for single-value condition types.

string

-

-

context

No

Properties defined by the user for this data. Context is propagated on generated Events/Alerts.

object

map[string,string]

-

Definitions

Representation of a list of full triggers (trigger, dampenings and conditions),group members triggers and actions definitions.
Used for bulk import/export operations.

Name Required Description Type Allowable Values Default Value

triggers

No

List of full triggers.

array of FullTrigger

-

-

groupMembersInfo

No

List of group member triggers information.

array of GroupMemberInfo

-

-

actions

No

List of action definitions.

array of ActionDefinition

-

-

Event

An Alert is an Event.

For the most part an Event can be thought of as an Alert without life-cycle.

Alerts are always generated by a Trigger.

Events may be generated by a Trigger or may be created directly via the API.

Name Required Description Type Allowable Values Default Value

eventType

No

Indicate if this object is an EVENT or an ALERT. This is a read-only field controlled by the system for serialization purposes.

string

EVENT, ALERT

-

tenantId

No

Tenant id owner of this event.

string

Tenant is overwritten from Hawkular-Tenant HTTP header parameter request

-

id

Yes

Unique identifier for this event.

string

-

-

ctime

Yes

Creation time for this event.

integer

-

-

dataSource

No

Optional dataSource for Event. Used for Trigger in EventCondition to evaluate events with triplet [tenantId, source, dataId] as unique identifier.

string

Timestamp in milliseconds.

-

dataId

Yes

Data identifier used for Events condition evaluation. Events must supply a valid dataId to be considered for EventCondition evaluation.
DataIds in an events context should incorporate the source of the event (for uniqueness).
Events generated from a Trigger will have dataId set to the triggerId, therefore allowing chaining with other EventCondition.

string

-

-

category

Yes

Category of Event. Suitable for display.
Alerts will use ALERT category.
Events generated from Trigger will use Trigger.eventCategory or TRIGGER category as default.

string

Any category defined by the user.

ALERT or TRIGGER

text

Yes

Description of the event. Suitable for display.
Events generated from Trigger will use Trigger.eventText or Trigger.description/Trigger.name as default.

string

Any description defined by the user.

-

context

No

Properties defined by the user for this event.
Events generated from Trigger will use Trigger.context.
Context cannot be used as part of Event conditions expressions or criteria in finder methods.

object

map[string,string]

-

tags

No

Tags defined by the user for this event.
Events generated from Trigger will use Trigger.tags.
Tags can be used as part of Event conditions expressions and criteria in finder methods.
Tag value cannot be null.

object

map[string,string]

-

trigger

No

Trigger that created the event.
Null for API-generated Events.

Trigger

-

-

dampening

No

Dampening defined when the event was created.
Null for API-generated Events.

Dampening

-

-

evalSets

No

The Eval Sets that fired the trigger.
Null for API-generated Events.

array of array of ConditionEval

-

-

EventCondition

An EventCondition is used for condition evaluations over Event data using expressions.

Expression is a comma separated list of the following 3-token structure:

<eventField> <operator> <constant> [,<eventField> <operator> <constant>]*

<eventField> represents a fixed field of the Event structure, or a tag key.
Supported eventFields:
- tenantId (String)
- id (String)
- ctime (Numeric time since epoch in milliseconds)
- text (String)
- category (String)
- tags.<key> (String)

<operator> is a string representing a string/numeric operator. Supported operators:
"starts" starts with String
"ends" ends with String
"contains" contains String
"match" regex match String
"==" equals
"!=" not equals
"<" less than
"⇐" less than or equals
">" greater than
">=" greater than or equals

A String <constant> must be enclosed in single-quotes. Special characters must be
escaped with a backslash. Examples: 'test', '\,test\\'
A Numeric <constant> must be a valid number. Examples: 0, 23, 90.5, -10
Example of a valid expression:
id starts 'IDXYZ', category == 'Server', tags.from ends '.com'

An invalid expression will always return false.

Subtype of Condition

Name Required Description Type Allowable Values Default Value

expression

Yes

Event expression used for this condition.

string

-

-

EventConditionEval

An evaluation state for event condition.

Subtype of ConditionEval

Name Required Description Type Allowable Values Default Value

condition

No

Event condition linked with this state.

EventCondition

-

-

value

No

Event value used for dataId.

Event

-

-

ExternalCondition

An ExternalCondition is used for condition evaluations performed outside of the Alerting engine.

The external engine will send StringData providing the data for which the external evaluation
has already evaluated to true.

The Alerting engine assumes a true evaluation for the data being sent in from the external engine. In other words, every ExternalConditionEval will have a true evaluation and therefore, for triggers with only a single external condition, and with default dampening, an alert will be fired for each data submission.

Subtype of Condition

Name Required Description Type Allowable Values Default Value

alerterId

Yes

An identifier assigned by the external alerter to identify this condition as being handled by that. It should be unique enough such that external AlerterIds are unique.

string

-

-

expression

Yes

The operator/pattern/expression/description of the external condition. The use of this field is up to the external engine, It may be a pattern, expression or operator used to configure/drive an external evaluation engine or may just be a static description of the externally defined event.

string

-

-

ExternalConditionEval

An evaluation state for an external condition.
Note that external conditions may report a Data value or an Event.

Subtype of ConditionEval

Name Required Description Type Allowable Values Default Value

condition

No

External condition linked with this state.

ExternalCondition

-

-

value

No

String value used for dataId.

string

-

-

event

No

Event value used for dataId.

Event

-

-

FullTrigger

Representation of a Trigger with Dampening and Condition objects.

Name Required Description Type Allowable Values Default Value

trigger

Yes

The trigger.

Trigger

-

-

dampenings

No

A list of dampenings linked with the trigger.

array of Dampening

-

-

conditions

No

A list of conditions linked with the trigger.

array of Condition

-

-

GroupConditionsInfo

A convenience class used in the REST API to POST a new Group Condition.

A group-level condition uses dataId tokens for the dataIds defined in the condition.
The group members must then replace the tokens with actual dataIds.

For example, we may define a group ThresholdCondition like ( $SystemLoad$ > 80 ).
Each member must then replace $SystemLoad$ with the actual system load dataId for that member.

The dataIdMemberMap is a map of the dataId tokens in the group conditions to the actual dataIds
used for the current member triggers.
Because most condition types have only one dataId the map will typically have 1 entry per condition.
But because a condition could have multiple dataIds (e.g CompareCondition has dataId and data2Id),
it may have more entries than conditions.
The inner map maps member triggerIds to the dataId to be used for that member trigger for the given token.
It should have 1 entry for each member trigger.

For example, let’s define a group trigger with two conditions:

ThresholdCondition( $SystemLoad$ > 80 )
ThresholdCondition( $HeapUsed$ > 70 )

If the group has two current members, with triggerId’s Member1 and Member2,
the map would look like this:

{
"$SystemLoad$":{"Member1":"Member1SystemLoad", "Member2":"Member2SystemLoad"},
"$HeapUsed$":{"Member1":"Member1HeapUsed", "Member2":"Member2HeapUsed"}
}

So, in the example the actual $SystemLoad$ dataIds would be Member1SystemLoad and Member2SystemLoad.
With this Map we can now add the group-level conditions and also the two member-level conditions
to each member

A NOTE ABOUT EXTERNAL CONDITIONS. <code>ExternalCondition.expression</code> will automatically have the
same token replacement performed. So, all occurrences of the dataId token found in the expression,
will be replaced with the mapping. This allows the expression of a group external condition to be
automatically customized to the member.

Name Required Description Type Allowable Values Default Value

conditions

Yes

A list of conditions for a Group Trigger.

array of Condition

-

-

dataIdMemberMap

Yes

A map of the dataId tokens in the group conditions to the actual dataIds used for the current member triggers. Can be empty if the group has no existing members.

object

map[string,map[string,string]]

-

GroupMemberInfo

A convenience class used in the REST API to POST a new group Member Trigger.

A group-level condition uses dataId tokens for the dataIds defined in the condition.
The group members must then replace the tokens with actual dataIds.

For example, we may define a group ThresholdCondition like ( $SystemLoad$ > 80 ).
Each member must then replace $SystemLoad$ with the actual system load dataId for that member.
The dataIdMap is a map of the dataId tokens in the group conditions to the actual dataIds to
be used for the member being added. For example, assume the group trigger has two conditions defined:

ThresholdCondition( $SystemLoad$ > 80 ) and ThresholdCondition( $HeapUsed$ > 70 )

And now let’s assume we are adding a new member, Member1. The map would look like this:

{ "$SystemLoad$":"Member1SystemLoad", "$HeapUsed$":"Member1HeapUsed" }

So, in the example the actual dataIds would be Member1SystemLoad and Member1HeapUsed.
With this Map we can now add the new member trigger.

A NOTE ABOUT EXTERNAL CONDITIONS. ExternalCondition.expression will automatically have the
same token replacement performed. So, all occurrences of the dataId token found in the expression,
will be replaced with the mapping.
This allows the expression of a group external condition to be automatically customized to the member.

Name Required Description Type Allowable Values Default Value

groupId

Yes

Trigger id for parent Group Trigger.

string

-

-

memberId

Yes

Trigger id for member Trigger.

string

-

-

memberName

Yes

Trigger name for member Trigger.

string

-

-

memberDescription

Yes

Trigger description for member Trigger.

string

-

-

memberContext

Yes

Trigger context for member Trigger.

object

map[string,string]

-

memberTags

Yes

Trigger tags for member Trigger.

object

map[string,string]

-

dataIdMap

Yes

A map of the dataId tokens in the group conditions to the actual dataIds to be used for the member being added.
Can be empty if the group has no current conditions.

object

map[string,string]

-

LifeCycle

A lifecycle state representation.

Name Required Description Type Allowable Values Default Value

status

No

The status of this lifecycle.

string

OPEN, ACKNOWLEDGED, RESOLVED

OPEN

user

No

The user who creates the state
Open statutes are created by 'system'
In AUTORESOLVE triggers Resolved statutes are create by 'AutoResolve'.

string

-

-

stime

No

Creation time for this state.

integer

-

-

MissingCondition

A MissingCondition is used to evaluate when a data or an event has not been received on time interval.

A MissingCondition will be evaluated to true when a data/event has not been received in the last interval time starting to count from trigger was enabled or last received data/event.

Subtype of Condition

Name Required Description Type Allowable Values Default Value

interval

Yes

A time interval defined in milliseconds.

integer

-

-

MissingConditionEval

An evaluation state for missing condition.

Subtype of ConditionEval

Name Required Description Type Allowable Values Default Value

condition

No

Missing condition linked with this state.

MissingCondition

-

-

previousTime

No

Time when trigger was enabled or last time a data/event was received.

integer

-

-

time

No

Time when most recently evaluation of missing condition.

integer

-

-

NelsonCondition

A condition to detect instability based on historical data.

From one to all of the defined Nelson rules can be evaluated. See
https://en.wikipedia.org/wiki/Nelson_rules for a description of the rules.

Subtype of Condition

Name Required Description Type Allowable Values Default Value

activeRules

No

Set of NelsonRule to evaluate.

array of string

Rule1, Rule2, Rule3, Rule4, Rule5, Rule6, Rule7, Rule8

All Rules

sampleSize

No

Number of samples used to establish baseline information (mean, standard deviation).

integer

-

50

Note

A simple note representation.

Name Required Description Type Allowable Values Default Value

user

Yes

The user who creates the note.

string

-

-

ctime

No

Note creation time.

integer

-

-

text

Yes

The note text.

string

-

-

RateCondition

A threshold condition against rate of change over time.

Typically used for "counter" metrics, that continuously increase or decrease.
Given the last two datums for dataId:

deltaTime = datum.time - prevDatum.time
deltaValue = datum.value - prevData.value
periods = deltaTime / <conditionPeriod>
rate = deltaValue / periods
match = rate <conditionOperator> <conditionThreshold>

In other words, take the rate of change for the most recent datums and compare it to the threshold.
For example,
Let’s say we have a metric, sessionCount, that increments for each new session. If the sessionCount increases too quickly, say more than 20 per minute, we want an alert. We’d want:

RateCondition( 'SessionCount', INCREASING, MINUTE, GT, 20 )

By specifying the SessionCount data as increasing, we know to ignore/reset if the previous session count is less than the current session count. This indicates that maybe the counter was reset (maybe due to a restart).

Note that rate of change is always determined as an absolute value. So threshold values should be >= 0.

Subtype of Condition

Name Required Description Type Allowable Values Default Value

direction

Yes

Indicate if a metric is increasing/decreasing.

string

DECREASING, INCREASING, NA

-

period

Yes

Time period used for the evaluation.

string

SECOND, MINUTE, HOUR, DAY, WEEK

-

operator

Yes

Compare operator [LT (<), GT (>), LTE (⇐), GTE (>=)].

string

LT, GT, LTE, GTE

-

threshold

Yes

Condition threshold.

number

-

-

RateConditionEval

An evaluation state for rate condition.

Subtype of ConditionEval

Name Required Description Type Allowable Values Default Value

condition

No

Rate condition linked with this state.

RateCondition

-

-

previousValue

No

First (older) value for dataId used in the evaluation.

number

-

-

value

No

Second (newer) value for dataId used in the evaluation.

number

-

-

previousTime

No

Time for first (older) value for dataId used in the evaluation.

integer

-

-

time

No

Time for second (newer) value for dataId used in the evaluation.

integer

-

-

rate

No

Calculated rate for this evaluation.

number

-

-

StringCondition

A string comparison condition.

Subtype of Condition

Name Required Description Type Allowable Values Default Value

operator

Yes

String operator.

string

EQUAL, NOT_EQUAL, STARTS_WITH, ENDS_WITH, CONTAINS, MATCH

-

pattern

Yes

Pattern to be used with the string operator.

string

-

-

ignoreCase

No

Flag to indicate whether pattern should ignore case in the string operator expression.

boolean

-

false

StringConditionEval

An evaluation state for string condition.

Subtype of ConditionEval

Name Required Description Type Allowable Values Default Value

condition

No

String condition linked with this state.

StringCondition

-

-

value

No

String value for dataId used in the evaluation.

string

-

-

ThresholdCondition

A numeric threshold condition.

Subtype of Condition

Name Required Description Type Allowable Values Default Value

operator

Yes

Compare operator [LT (<), GT (>), LTE (⇐), GTE (>=)].

string

LT, GT, LTE, GTE

-

threshold

Yes

Condition threshold.

number

-

-

ThresholdConditionEval

An evaluation state for threshold condition.

Subtype of ConditionEval

Name Required Description Type Allowable Values Default Value

condition

No

Threshold condition linked with this state.

ThresholdCondition

-

-

value

No

Numeric value for dataId used in the evaluation.

number

-

-

ThresholdRangeCondition

A numeric threshold range condition.

Subtype of Condition

Name Required Description Type Allowable Values Default Value

operatorLow

Yes

Define whether low threshold value is inclusive or exclusive.

string

INCLUSIVE, EXCLUSIVE

-

operatorHigh

Yes

Define whether high threshold value is inclusive or exclusive.

string

INCLUSIVE, EXCLUSIVE

-

thresholdLow

Yes

Low threshold of the range interval.

number

-

-

thresholdHigh

Yes

High threshold of the range interval.

number

-

-

inRange

Yes

Flag to indicate if condition will match when value is within the range interval or outside the range interval.

boolean

-

-

ThresholdRangeConditionEval

An evaluation state for threshold range condition.

Subtype of ConditionEval

Name Required Description Type Allowable Values Default Value

condition

No

Threshold range condition linked with this state.

ThresholdRangeCondition

-

-

value

No

Numeric value for dataId used in the evaluation.

number

-

-

TimeConstraint

Define a time interval (startTime, endTime) used as a constraint for action execution.
Time interval can be defined in an absolute or relative expression.

An absolute time interval uses the pattern yyyy.MM.dd[,HH:mm] for startTime and endTime properties.
For example, these representations are valid absolute expressions for time interval:

{startTime: "2016.02.01", endTime: "2016.03.01", relative: false}
{startTime: "2016.02.01,09:00", endTime: "2016.03.01,18:00", relative: false}

Absolute time interval are marked with flag relative set to false.
Hour and minutes can be optional in absolute format, by default it takes 00:00 value.

A relative interval is used for repetitive expressions.
It can be defined an interval between months (i.e. December to March), between days of the week
(i.e. Sunday to Friday), between hours and minutes (i.e. 23:00 to 04:30), or a combination of month,
day of the week and/or hours and minutes.
Relative interval uses the pattern [MMM],[WWW],[HH:mm] where months and days of the week can be used in long or short format.
Same pattern should be applied to both startTime and endTime properties.
For example, these representations are valid relative expressions for time interval:

{startTime: "Jul", endTime: "Dec", relative: true}
{startTime: "July", endTime: "December", relative: true}

All dates within July and December months will be valid.

{startTime: "Jul,Mon", endTime: "Dec,Fri", relative: true}
{startTime: "July,Monday", endTime: "December,Friday", relative: true}

All dates within July and December months and within Monday and Friday days are valid.
So, a Sunday day of August will not be valid according previous example.

{startTime: "Jul,Mon,09:00", endTime: "Dec,Fri,18:00", relative: true}
{startTime: "July,Monday", endTime: "December,Friday", relative: true}

All dates within July and December months and within Monday and Friday days and time between 09:00 and18:00 are valid.
So, a Monday day of August at 18:01 will not be valid according previous example.

{startTime:"Monday,09:00", endTime:"Friday,18:00", relative: true}
{startTime:"Mon,09:00", endTime:"Fri,18:00", relative: true}

All dates within Monday and Friday day and time between 09:00 and 18:00 will be valid.
So, a Monday at 18:01 will not be valid according previous example.

{startTime:"July,09:00", endTime:"August,18:00", relative: true}
{startTime:"Jul,09:00", endTime:"Aug,18:00", relative: true}

All dates within July and December months and time between 09:00 and 18:00 are valid.
A day of August at 18:01 will not be valid according previous example.

{startTime:"09:00", endTime:"18:00", relative: true}

All times within 09:00 and 18:00 are valid.

TimeConstraint inRange property defines whether a given time must fall inside or outside
the defined interval. Setting inRange == true means the constraint will be satisfied if a
given date is within the interval (taking the limits as inclusive). By setting
inRange == false the constraint is satisfied if a given date is outside of the interval.
By default, inRange == true.
For example,

{startTime:"09:00", endTime:"18:00", relative: true, inRange: true}

All times within 09:00 and 18:00 are satisfied by the interval.

{startTime:"09:00", endTime:"18:00", relative: true, inRange: false}

All times from 18:01 to 08:59 are satisfied in the interval.

By default the defined absolute or relative intervals use the default time zone (of the server).
This can be unpredictable unless the server time zone is well known and acceptable. It is
recommended to explicitly set the time zone for which the TimeConstraint intervals are applicable.
This is done by setting the timeZoneName property.
For example, here is a TimeConstraint for business hours:

{startTime:"09:00", endTime:"18:00"}

If the server is running in London then this reflects business hours in London. But perhaps the
admins are in New York and the TimeConstraint should actually reflect their local time zone.
In that case use:

{startTime:"09:00", endTime:"18:00", timeZoneName: "America/New_York", relative: true}

It is also possible to use a GMT-relative value:

{startTime:"09:00", endTime:"18:00", timeZoneName: "GMT-5:00", relative: true}

Name Required Description Type Allowable Values Default Value

startTime

Yes

Define the start of the time interval. It can be in absolute or relative format.

string

-

-

endTime

Yes

Define the end of the time interval. It can be in absolute or relative format.

string

-

-

relative

No

Define if startTime and endTime properties are defined in absolute or relative format.

boolean

-

true

inRange

No

Indicate if time constraint is satisfied when a given timestamp is inside or outside the interval.

boolean

-

true

timeZoneName

No

Indicate the time zone in which the times are expressed. If not specified the server’s default time zone is applied. Time zone is expressed in standard Area/Location format. It is recommended to specify the time zone unless you are sure of the server environment.

string

-

-

Trigger

A Trigger definition.

A Trigger can fire an Alert or an Event.

Triggers always start in FIRING mode.

If the auto-resolve feature is enabled for the Trigger, then it will switch to AUTORESOLVE mode after firing.

When the auto-resolve condition set is satisfied, or if the Trigger is reloaded (manually, via edit, or at startup), the trigger returns to FIRING mode.

The mode is also needed when defining a trigger, to indicate the relevant mode for a conditions or dampening definition.

Name Required Description Type Allowable Values Default Value

tenantId

Yes

Tenant id owner of this trigger.

string

Tenant is overwritten from Hawkular-Tenant HTTP header parameter request

-

id

Yes

Trigger identifier. Unique within the tenant.

string

-

Auto-generated UUID if not explicitly defined.

name

Yes

Trigger name. Used for display.

string

-

-

description

No

Trigger description. Used for display.

string

-

-

type

No

The type of the trigger.

string

STANDARD, GROUP, DATA_DRIVEN_GROUP, MEMBER, ORPHAN

STANDARD

eventType

No

The type of event produced by the trigger.

string

ALERT, EVENT

ALERT

eventCategory

No

The category of the event produced by the trigger.

string

-

-

eventText

No

The text of the event produced by the trigger.

string

-

If not eventText defined. Description will be used. If not description defined, trigger name will be used.

severity

No

Severity of a trigger.

string

LOW, MEDIUM, HIGH, CRITICAL

MEDIUM

context

No

Properties defined by the user for this trigger. Context is propagated on generated Events/Alerts. Context cannot be used as criteria on finder methods.

object

map[string,string]

-

tags

No

Tags defined by the user for this trigger. A tag is a [name, value] pair.Tags can be used as criteria on finder methods.
Tag value cannot be null.

object

map[string,string]

-

actions

No

A list of links to actions.

array of TriggerAction

-

-

autoDisable

No

Disable automatically after firing.

boolean

-

false

autoEnable

No

Enable automatically if disabled and resolved manually.

boolean

-

false

autoResolve

No

Switch to auto-resolve mode after firing.

boolean

-

false

autoResolveAlerts

No

Resolve all unresolved alerts when auto-resolve condition-set is satisfied.

boolean

-

false

autoResolveMatch

No

The policy used for deciding whether the trigger auto-resolved condition-set is satisfied. ALL conditions must evaluate to true or ANY one condition must evaluate to true.

string

ALL, ANY

ALL

dataIdMap

No

Only set for MEMBER triggers, the dataIdMap used when adding the member. It is reused for group condition updates unless a new dataIdMap is provided.

object

map[string,string]

-

memberOf

No

Only set for MEMBER triggers, the group trigger for which this is a member.

string

-

-

enabled

No

A enabled trigger is loaded into the engine for data evaluation.

boolean

-

false

firingMatch

No

The policy used for deciding whether the trigger condition-set is satisfied. ALL conditions must evaluate to true or ANY one condition must evaluate to true.

string

ALL, ANY

ALL

source

No

Extended mechanism to match trigger conditions against Data with [source, dataId] identifiers. In this way it is possible to qualify triggers and data with a source such that a trigger only evaluates data having the same source.

string

-

-

TriggerAction

Links an ActionDefinition with a Trigger.

The TriggerAction can override the constraints set on the [ActionDefintion].
If a TriggerAction defines any constraints the ActionDefinition constraints will be ignored.
If a TriggerAction defines no constraints the ActionDefinition constraints will be used.

Name Required Description Type Allowable Values Default Value

tenantId

No

Tenant id owner of this trigger.

string

Tenant is overwritten from Hawkular-Tenant HTTP header parameter request

-

actionPlugin

Yes

Action plugin identifier.

string

Only plugins deployed on the system are valid.

-

actionId

Yes

Action definition identifier.

string

Only existing action definitinons on the system are valid.

-

states

No

A list of Alert.Status restricting active states for this action.

array of string

-

-

calendar

No

A TimeConstraint restricting active times for this action.

TimeConstraint

-

-

UnorphanMemberInfo

A convenience class used in the REST API to un-orphan an orphan group Member Trigger.

A group-level condition uses dataId tokens for the dataIds defined in the condition.
The group members must then replace the tokens with actual dataIds.

For example, we may define a group ThresholdCondition like ( $SystemLoad$ > 80 ).
Each member must then replace $SystemLoad$ with the actual system load dataId for that member.
The dataIdMap is a map of the dataId tokens in the group conditions to the actual dataIds to
be used for the member being added. For example, assume the group trigger has two conditions defined:

ThresholdCondition( $SystemLoad$ > 80 ) and ThresholdCondition( $HeapUsed$ > 70 )

And now let’s assume we are adding a new member, Member1. The map would look like this:

{ "$SystemLoad$":"Member1SystemLoad", "$HeapUsed$":"Member1HeapUsed" }

So, in the example the actual dataIds would be Member1SystemLoad and Member1HeapUsed.
With this Map we can now add the new member trigger.

A NOTE ABOUT EXTERNAL CONDITIONS. ExternalCondition.expression will automatically have the
same token replacement performed. So, all occurrences of the dataId token found in the expression,
will be replaced with the mapping.
This allows the expression of a group external condition to be automatically customized to the member.

Name Required Description Type Allowable Values Default Value

memberContext

Yes

Trigger context for member Trigger.

object

map[string,string]

-

memberTags

Yes

Trigger tags for member Trigger.

object

map[string,string]

-

dataIdMap

Yes

A map of the dataId tokens in the group conditions to the actual dataIds to be used for the member being added.
Can be empty if the group has no current conditions.

object

map[string,string]

-

redhatlogo-white

© 2016 | Hawkular is released under Apache License v2.0