Alerts REST API

Auto-generated swagger documentation

Version 2

Version

This is the version 2.x API. Find the version 1.x API here.

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

Tenant Header

Hawkular Alerting is a multi-tenant engine. Your requests to tenant-dependent resources must include a tenant header:

Hawkular-Tenant: my-tenant

Base Path

/hawkular/alerts

REST APIs

[ / ] Alerts Handling

GET

/

Get alerts with optional filtering

PUT

/ack

Set one or more alerts Acknowledged.

PUT

/ack/{alertId}

Set one alert Acknowledged.

PUT

/alert/{alertId}

Get an existing Alert.

POST

/data

Set one or more alerts resolved.

DELETE

/delete

Delete alerts with optional filtering.

PUT

/note/{alertId}

Add a note into an existing Alert.

PUT

/resolve

Set one or more alerts resolved.

PUT

/resolve/{alertId}

Set one alert resolved.

PUT

/tags

Add tags to existing Alerts.

DELETE

/tags

Remove tags from existing Alerts.

GET

/watch

Get alerts with optional filtering

DELETE

/{alertId}

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.

Long

Timestamp in millisecond since epoch.

entTime

No

Filter out alerts created after this time.

Long

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|description'.
Specify '*' for description 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.

Long

Timestamp in millisecond since epoch.

endResolvedTime

No

Filter out alerts resolved after this time.

Long

Timestamp in millisecond since epoch.

startAckTime

No

Filter out alerts acknowledged before this time.

Long

Timestamp in millisecond since epoch.

endAckTime

No

Filter out alerts acknowledged after this time.

Long

Timestamp in millisecond since epoch.

startStatusTime

No

Filter out alerts with some lifecycle state before this time.

Long

Timestamp in millisecond since epoch.

endStatusTime

No

Filter out alerts with some lifecycle after this time.

Long

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.

List 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 PUT /alert/{alertId}

Get an existing Alert.

Path parameters

Parameter Required Description Type Allowable Values

alertId

Yes

Get an existing Alert.

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

404

Alert not found.

ApiError

500

Internal server error.

ApiError

Endpoint POST /data

Set one or more alerts resolved.

Body

Required Description Data Type

Yes

Data to be processed by alerting.

List 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 DELETE /delete

Delete 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.

Long

Timestamp in millisecond since epoch.

entTime

No

Filter out alerts created after this time.

Long

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|description'.
Specify '*' for description 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.

Long

Timestamp in millisecond since epoch.

endResolvedTime

No

Filter out alerts resolved after this time.

Long

Timestamp in millisecond since epoch.

startAckTime

No

Filter out alerts acknowledged before this time.

Long

Timestamp in millisecond since epoch.

endAckTime

No

Filter out alerts acknowledged after this time.

Long

Timestamp in millisecond since epoch.

startStatusTime

No

Filter out alerts with some lifecycle state before this time.

Long

Timestamp in millisecond since epoch.

endStatusTime

No

Filter out alerts with some lifecycle after this time.

Long

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

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 alerts 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

500

Internal server error.

ApiError

Endpoint PUT /resolve/{alertId}

Set one alert resolved.

Query parameters

Parameter Required Description Type Allowable Values

alertId

Yes

The alertId to set resolved.

String

-

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 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|description'.

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 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, Tags deleted successfully.

-

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint GET /watch

Get 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.

Long

Timestamp in millisecond since epoch.

entTime

No

Filter out alerts created after this time.

Long

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|description'.
Specify '*' for description 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.

Long

Timestamp in millisecond since epoch.

endResolvedTime

No

Filter out alerts resolved after this time.

Long

Timestamp in millisecond since epoch.

startAckTime

No

Filter out alerts acknowledged before this time.

Long

Timestamp in millisecond since epoch.

endAckTime

No

Filter out alerts acknowledged after this time.

Long

Timestamp in millisecond since epoch.

startStatusTime

No

Filter out alerts with some lifecycle state before this time.

Long

Timestamp in millisecond since epoch.

endStatusTime

No

Filter out alerts with some lifecycle after this time.

Long

Timestamp in millisecond since epoch.

watchInterval

No

Define interval when watcher notifications will be sent.

Long

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, Alerts deleted.

ApiDeleted

400

Bad Request/Invalid Parameters

ApiError

404

Alert not found.

ApiError

500

Internal server error.

ApiError

[ /actions ] Actions Handling

GET

/actions

Find all action ids grouped by plugin.

PUT

/actions

Update an existing ActionDefinition.

POST

/actions

Create a new ActionDefinition.

GET

/actions/history

Get actions from history with optional filtering.

PUT

/actions/history/delete

Delete actions from history with optional filtering.

GET

/actions/plugin/{actionPlugin}

Find all action ids of an specific action plugin.

GET

/actions/{actionPlugin}/{actionId}

Get an existing action definition.

DELETE

/actions/{actionPlugin}/{actionId}

Delete 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 description a collection of actionIds.

Response

Status codes

Status Code Reason Response Model

200

Successfully fetched map of action ids grouped by plugin.

Map of [Collection]

500

Internal server error.

ApiError

Endpoint PUT /actions

Update an existing ActionDefinition.

Returns updated ActionDefinition.

Body

Required Description Data Type

Yes

ActionDefinition to be created.

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 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.

List of String

400

Existing ActionDefinition/Invalid Parameters.

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.

String

Timestamp in millisecond since epoch.

endTime

No

Filter out actions created after this time.

String

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.

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.

List 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.

String

Timestamp in millisecond since epoch.

endTime

No

Filter out actions created after this time.

String

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.

results

No

Filter out alerts for unspecified result.

String

Comma separated list of action results.

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.

ApiDeleted

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, ActionDefinition found.

ActionDefinition

404

No ActionDefinition found.

ApiError

500

Internal server error.

ApiError

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

Delete 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

ActionDefinition Deleted.

ActionDefinition

404

No Action found.

ApiError

500

Internal server error.

ApiError

[ /admin ] Cross tenant Operations

GET

/admin/alerts

Get alerts with optional filtering from multiple tenants.

GET

/admin/events

Get events with optional filtering from multiple tenants.

GET

/admin/watch/alerts

Get alerts with optional filtering from multiple tenants.

GET

/admin/watch/events

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.

Long

Timestamp in millisecond since epoch.

entTime

No

Filter out alerts created after this time.

Long

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|description'.
Specify '*' for description 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.

Long

Timestamp in millisecond since epoch.

endResolvedTime

No

Filter out alerts resolved after this time.

Long

Timestamp in millisecond since epoch.

startAckTime

No

Filter out alerts acknowledged before this time.

Long

Timestamp in millisecond since epoch.

endAckTime

No

Filter out alerts acknowledged after this time.

Long

Timestamp in millisecond since epoch.

startStatusTime

No

Filter out alerts with some lifecycle state before this time.

Long

Timestamp in millisecond since epoch.

endStatusTime

No

Filter out alerts with some lifecycle after this time.

Long

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.

List 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> 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.

String

Timestamp in millisecond since epoch.

endTime

No

Filter out events created after this time.

String

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|description'.
Specify '*' for description 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.

String

-

Response

Status codes

Status Code Reason Response Model

200

Successfully fetched list of events.

List of Event

400

Bad Request/Invalid Parameters.

ApiError

500

Internal server error.

ApiError

Endpoint GET /admin/watch/alerts

Get 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.

Long

Timestamp in millisecond since epoch.

entTime

No

Filter out alerts created after this time.

Long

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|description'.
Specify '*' for description 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.

Long

Timestamp in millisecond since epoch.

endResolvedTime

No

Filter out alerts resolved after this time.

Long

Timestamp in millisecond since epoch.

startAckTime

No

Filter out alerts acknowledged before this time.

Long

Timestamp in millisecond since epoch.

endAckTime

No

Filter out alerts acknowledged after this time.

Long

Timestamp in millisecond since epoch.

startStatusTime

No

Filter out alerts with some lifecycle state before this time.

Long

Timestamp in millisecond since epoch.

endStatusTime

No

Filter out alerts with some lifecycle after this time.

Long

Timestamp in millisecond since epoch.

watchInterval

No

Define interval when watcher notifications will be sent.

Long

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> 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.

String

Timestamp in millisecond since epoch.

endTime

No

Filter out events created after this time.

String

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|description'.
Specify '*' for description 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.

Long

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 ] Events Handling

GET

/events

Get events with optional filtering.

POST

/events

Create a new Event.

POST

/events/data

Send events to the engine for processing/condition evaluation.

PUT

/events/delete

Delete events with optional filtering.

GET

/events/event/{eventId}

Get an existing Event.

PUT

/events/tags

Add tags to existing Events.

DELETE

/events/tags

Remove tags from existing Events.

GET

/events/watch

Watch events with optional filtering.

DELETE

/events/{eventId}

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.

String

Timestamp in millisecond since epoch.

endTime

No

Filter out events created after this time.

String

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|description'.
Specify '*' for description 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.

String

-

Response

Status codes

Status Code Reason Response Model

200

Successfully fetched list of events.

List 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.

List of Event

Response

Status codes

Status Code Reason Response Model

200

Success, Events Sent.

Event

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.

String

Timestamp in millisecond since epoch.

endTime

No

Filter out events created after this time.

String

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|description'.
Specify '*' for description 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. Number of events deleted.

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

Event id to be deleted.

String

-

Query parameters

Parameter Required Description Type Allowable Values

thin

No

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

String

-

Response

Status codes

Status Code Reason Response Model

200

Success, Event found.

Event

404

Event not found.

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|description'.

Response

Status codes

Status Code Reason Response Model

200

Success, Events tagged successfully.

Event

400

Bad Request/Invalid Parameters.

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 eventIds to untag.

String

Comma separated list of events 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.

Event

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.
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.

String

Timestamp in millisecond since epoch.

endTime

No

Filter out events created after this time.

String

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|description'.
Specify '*' for description 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.

Long

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

500

Internal server error.

ApiError

[ /export ] Export of triggers and actions definitions

GET

/export

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

500

Internal server error.

ApiError

[ /import ] Import of triggers and actions definitions

POST

/import/{strategy}

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

Yes

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

GET

/plugins

Find all action plugins.

GET

/plugins/{actionPlugin}

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.

List of String

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

Success, Action Plugin found.

List of String

404

Action Plugin not found.

ApiError

500

Internal server error.

ApiError

[ /status ] Status of Alerting Service

GET

/status

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

Success, Event Created.

Map of String

500

Internal server error.

ApiError

[ /triggers ] Triggers Definitions Handling

POST

/triggers

Create a new trigger.

GET

/triggers

Get triggers with optional filtering.

PUT

/triggers/enabled

Update triggers to be enabled or disabled.

POST

/triggers/groups

Create a new group trigger.

PUT

/triggers/groups/enabled

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

POST

/triggers/groups/members

Create a new member trigger for a parent trigger.

PUT

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

Make a non-orphan member trigger into an orphan.

PUT

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

Make an orphan member trigger into an group trigger.

DELETE

/triggers/groups/{groupId}

Delete a group trigger.

PUT

/triggers/groups/{groupId}

Update an existing group trigger definition and its member definitions.

PUT

/triggers/groups/{groupId}/conditions

Set the conditions for the group trigger.

PUT

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

Set the conditions for the group trigger.

POST

/triggers/groups/{groupId}/dampenings

Create a new group dampening.

DELETE

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

Delete an existing group dampening definition.

PUT

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

Update an existing group dampening definition.

GET

/triggers/groups/{groupId}/members

Find all group member trigger definitions.

POST

/triggers/trigger

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

PUT

/triggers/trigger/{triggerId}

Update an existing full trigger (trigger, dampenings and conditions).

GET

/triggers/trigger/{triggerId}

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

GET

/triggers/{triggerId}

Get an existing trigger definition.

DELETE

/triggers/{triggerId}

Delete an existing standard or group member trigger definition.

PUT

/triggers/{triggerId}

Update an existing trigger definition.

GET

/triggers/{triggerId}/conditions

Get all conditions for a specific trigger.

PUT

/triggers/{triggerId}/conditions

Set the conditions for the trigger.

PUT

/triggers/{triggerId}/conditions/{triggerMode}

Set the conditions for the trigger.

POST

/triggers/{triggerId}/dampenings

Create a new dampening.

GET

/triggers/{triggerId}/dampenings

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

GET

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

Get dampening using triggerId and triggerMode.

GET

/triggers/{triggerId}/dampenings/{dampeningId}

Get an existing dampening.

DELETE

/triggers/{triggerId}/dampenings/{dampeningId}

Delete an existing dampening definition.

PUT

/triggers/{triggerId}/dampenings/{dampeningId}

Update an existing dampening definition.

Endpoint POST /triggers

Create a new trigger.

Returns 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 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|description'.
Specify '*' for description 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.

List of Trigger

404

Trigger not found

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 not found

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

Group member trigger 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 not found

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 PUT /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.

Trigger

404

Trigger not found.

ApiError

500

Internal server error.

ApiError

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

Make an orphan member trigger into an group trigger.

Path parameters

Parameter Required Description Type Allowable Values

memberId

Yes

Orphan Member Trigger id to be assigned into a group trigger

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.

Trigger

404

Trigger not found.

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 definition 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.

Trigger

400

Bad Request/Invalid Parameters.

ApiError

404

Trigger not found.

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

triggerId

Yes

The relevant Trigger.

String

-

Body

Required Description Data Type

Yes

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

List of GroupConditionsInfo

Response

Status codes

Status Code Reason Response Model

200

Success, Group Condition Set created.

List of Condition

400

Bad Request/Invalid Parameters.

ApiError

404

Trigger not 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

triggerId

Yes

The relevant Trigger.

String

-

triggerMode

Yes

FIRING or AUTORESOLVE (not case sensitive)

String

-

Body

Required Description Data Type

Yes

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

List of GroupConditionsInfo

Response

Status codes

Status Code Reason Response Model

200

Success, Group Condition Set created.

List of Condition

400

Bad Request/Invalid Parameters.

ApiError

404

Trigger not 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 deleted.

String

-

dampeningId

Yes

Dampening id for dampening definition to be deleted.

String

-

Response

Status codes

Status Code Reason Response Model

200

Success, Dampening updated.

FullTrigger

400

Bad Request/Invalid Parameters.

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

Updated dampening definition.

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.

No pagination.

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.

String

-

Response

Status codes

Status Code Reason Response Model

200

Successfully fetched list of triggers.

List of Trigger

404

Trigger not found

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 PUT /triggers/trigger/{triggerId}

Update an existing full trigger (trigger, dampenings and conditions).

Return updated full trigger.

Path parameters

Parameter Required Description Type Allowable Values

triggerId

Yes

Trigger definition id to be updated.

String

-

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 updated.

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

Trigger definition id to be retrieved.

String

-

Response

Status codes

Status Code Reason Response Model

200

Success, Trigger found.

FullTrigger

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

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.

-

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.

Trigger

400

Bad Request/Invalid Parameters.

ApiError

404

Trigger not found.

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.

List of Condition

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.

List of Condition

Response

Status codes

Status Code Reason Response Model

200

Success, Condition Set created.

List of Condition

400

Bad Request/Invalid Parameters.

ApiError

404

Trigger not found.

ApiError

500

Internal server error.

ApiError

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

Set the conditions for the trigger.

This sets the conditions for the trigger. 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.

List of Condition

Response

Status codes

Status Code Reason Response Model

200

Success, Condition Set created.

List of Condition

400

Bad Request/Invalid Parameters.

ApiError

404

Trigger not found.

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

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

Success, Trigger found.

List of Dampening

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

-

Response

Status codes

Status Code Reason Response Model

200

Success, Trigger found.

List of Dampening

400

Bad Request/Invalid Parameters.

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

Successfully fetched list of triggers.

Dampening

404

Damppening not found

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 updated.

FullTrigger

400

Bad Request/Invalid Parameters.

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

Updated dampening definition.

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

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

No

Tenant id owner of this trigger.

String

Tenant is overwritten from Hawkular-Tenant HTTP header parameter request

id

No

Trigger identifier. Unique within the tenant.

String

-

Auto-generated UUID if not explicitly defined.

name

No

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.

Map of [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.

Map of [String, String]

-

actions

No

A list of links to actions.

List 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.

Map of [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

-

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.

Subtype of ActionDefinition

Name Required Description Type Allowable Values Default Value

eventId

No

Event id from where this action is generated.

String

-

ctime

No

Time when this action was generated.

long

-

event

No

Attached Event from where this action is generated.

Event

-

result

No

Result of action processing.

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.

List of FullTrigger

-

groupMembersInfo

No

List of group member triggers information.

List of GroupMemberInfo

-

actions

No

List of action definitions.

List of ActionDefinition

-

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

No

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

String

FIRING, AUTORESOLVE

type

No

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

int

>= 1

evalTotalSetting

No

Number of allowed evaluation attempts for RELAXED_COUNT

int

> evalTrueSetting

evalTimeSetting

No

Time period in milliseconds for RELAXED_TIME, STRICT_TIME, STRICT_TIMEOUT

long

> 0

dampeningId

No

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

String

-

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

No

A list of conditions for a Group Trigger.

List of Condition

-

dataIdMemberMap

No

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.

Map of [String, Map of [String, String]]

-

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

No

Action plugin identifier.

String

Only plugins deployed on the system are valid.

actionId

No

Action definition identifier.

String

-

global

No

Flag to indicate this is a global action.

boolean

-

properties

No

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

Map of [String, String]

-

states

No

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

List of String

OPEN, ACKNOWLEDGED, RESOLVED

calendar

No

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

TimeConstraint

-

ApiDeleted

Payload for a simple REST deleted number response.

Name Required Description Type Allowable Values Default Value

deleted

No

Deleted items.

Integer

-

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

No

Trigger context for member Trigger.

Map of [String, String]

-

memberTags

No

Trigger tags for member Trigger.

Map of [String, String]

-

dataIdMap

No

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.

Map of [String, String]

-

Condition

A base class for condition definition.

Name Required Description Type Allowable Values Default Value

tenantId

No

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

No

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

String

FIRING, AUTORESOLVE

type

No

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.

int

-

conditionSetIndex

No

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

int

-

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.

Map of [String, String]

-

displayString

No

A canonical display string for the condition expression. Can be null until the condition is fully defined.

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

No

Data id unique within the tenant.

String

-

timestamp

No

Timestamp for the data.

long

-

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.

Map of [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

No

Trigger id for parent Group Trigger.

String

-

memberId

No

Trigger id for member Trigger.

String

-

memberName

No

Trigger name for member Trigger.

String

-

memberDescription

No

Trigger description for member Trigger.

String

-

memberContext

No

Trigger context for member Trigger.

Map of [String, String]

-

memberTags

No

Trigger tags for member Trigger.

Map of [String, String]

-

dataIdMap

No

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.

Map of [String, String]

-

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

No

Unique identifier for this event.

String

-

ctime

No

Creation time for this event.

long

Timestamp in milliseconds.

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

No

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

No

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

No

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.

Map of [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.

Map of [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.

List of List of ConditionEval

-

ApiError

Payload for a REST error response.

Name Required Description Type Allowable Values Default Value

errorMsg

No

The error message.

String

-

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.

Subtype of Event

Name Required Description Type Allowable Values Default Value

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

notes

No

Notes attached with this alert.

List of Note

-

lifecycle

No

List of lifecycle states that this alert has navigated.

List of LifeCycle

-

resolvedEvalSets

No

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

List of List of ConditionEval

-

FullTrigger

Representation of a Trigger with Dampening and Condition objects.

Name Required Description Type Allowable Values Default Value

trigger

No

The trigger.

Trigger

-

dampenings

No

A list of dampenings linked with the trigger.

List of Dampening

-

conditions

No

A list of conditions linked with the trigger.

List of Condition

-

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

No

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

String

LT, GT, LTE, GTE

data2Id

No

Data identifier of the metric used for comparison.

String

-

data2Multiplier

No

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

Double

-

EventCondition

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

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

<event.field> <operator> <constant> [,<event.field> <operator> <constant>]*

<event.field> represent a fixed field of event structure or a key of tags.
Supported fields are the following:
- tenantId
- id
- ctime
- text
- category
- tags.<key>

<operator> is a string representing a string/numeric operator, supported ones are:
"==" equals
"!=" not equals
"starts" starts with String operator
"ends" ends with String operator
"contains" contains String operator
"match" match String operator
"<" less than
"⇐" less or equals than
">" greater than
">=" greater or equals than
"==" equals

<constant> is a string that might be interpreted as a number if is not closed with single quotes or a string constant if it is closed with single quotes
i.e. 23, 'test'

A constant string can contain special character comma but escaped with backslash.
i.e '\,test', 'test\,'

So, putting everything together, a valid expression might look like:
event.id starts 'IDXYZ', event.tag.category == 'Server', event.tag.from end '.com'

A non valid expression will return false.

Subtype of Condition

Name Required Description Type Allowable Values Default Value

expression

No

Event expression used for this condition.

String

-

ConditionEval

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

Name Required Description Type Allowable Values Default Value

match

No

Result of the condition evaluation.

boolean

-

evalTimestamp

No

Time of condition evaluation.

long

-

dataTimestamp

No

Time stamped on the data used in the evaluation.

long

-

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.

Map of [String, String]

-

displayString

No

A canonical display string of the evaluation (the result of a call to #getLog()).

String

-

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

No

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

No

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

-

AvailabilityCondition

An availability condition definition.

Examples:
X is DOWN

Subtype of Condition

Name Required Description Type Allowable Values Default Value

operator

No

Availability operator.

String

DOWN, NOT_UP, UP

ThresholdCondition

A numeric threshold condition.

Subtype of Condition

Name Required Description Type Allowable Values Default Value

operator

No

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

String

LT, GT, LTE, GTE

threshold

No

Condition threshold.

Double

-

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

No

Action plugin identifier.

String

Only plugins deployed on the system are valid.

actionId

No

Action definition identifier.

String

Only existing action definitions on the system are valid.

states

No

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

List of String

OPEN, ACKNOWLEDGED, RESOLVED

calendar

No

A TimeConstraint restricting active times for this action.

TimeConstraint

-

Note

A simple note representation.

Name Required Description Type Allowable Values Default Value

user

No

The user who creates the note.

String

-

ctime

No

Note creation time.

long

Timestamp in milliseconds.

text

No

The note text.

String

-

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, in milliseconds, starting to count from trigger was enabled or last received data/event.

Subtype of Condition

Name Required Description Type Allowable Values Default Value

interval

No

A time interval defined in milliseconds.

long

-

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.

long

Timestamp in milliseconds.

ThresholdRangeCondition

A numeric threshold range condition.

Subtype of Condition

Name Required Description Type Allowable Values Default Value

operatorLow

No

Define whether low threshold value is inclusive or exclusive.

String

INCLUSIVE, EXCLUSIVE

operatorHigh

No

Define whether high threshold value is inclusive or exclusive.

String

INCLUSIVE, EXCLUSIVE

thresholdLow

No

Low threshold of the range interval.

Double

-

thresholdHigh

No

High threshold of the range interval.

Double

-

inRange

No

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

boolean

-

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

No

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

String

-

endTime

No

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

-

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

No

Indicate if a metric is increasing/decreasing.

String

DECREASING, INCREASING, NA

period

No

Time period used for the evaluation.

String

SECOND, MINUTE, HOUR, DAY, WEEK

operator

No

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

String

LT, GT, LTE, GTE

threshold

No

Condition threshold.

Double

-

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.

List of [NelsonRule]

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

All Rules

sampleSize

No

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

int

-

50

StringCondition

A string comparison condition.

Subtype of Condition

Name Required Description Type Allowable Values Default Value

operator

No

String operator.

String

EQUAL, NOT_EQUAL, STARTS_WITH, ENDS_WITH, CONTAINS, MATCH

pattern

No

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

-

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.

Double

-

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.

Double

-

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.

Double

-

value2

No

Numeric value used for data2Id.

Double

-

context2

No

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

Map of [String, 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

-

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.

long

-

time

No

Time when most recently evaluation of missing condition.

long

-

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.

Double

-

value

No

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

Double

-

previousTime

No

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

long

-

time

No

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

long

-

rate

No

Calculated rate for this evaluation.

Double

-

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

-

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

redhatlogo-white

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