Module: Grafana::Alerts

Included in:
Client
Defined in:
lib/grafana/alerts.rb

Overview

You can use the Alerting API to get information about alerts and their states but this API cannot be used to modify the alert. To create new alerts or modify them you need to update the dashboard json that contains the alerts.

This API can also be used to create, update and delete alert notifications.

original API Documentation can be found under: docs.grafana.org/http_api/alerting/

Instance Method Summary collapse

Instance Method Details

#alert(alert_id) ⇒ Hash

Get one alert

curl -H ‘Content-Type: application/json;charset=UTF-8’ ‘admin:[email protected]:3030/api/alerts/1’

Examples:

alert( 1 )
alert( 'foo' )

Parameters:

  • alert_id (Mixed) —

    Alertname (String) or Alertid (Integer)

Returns:

Raises:

  • (ArgumentError) 


90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/grafana/alerts.rb', line 90

def alert( alert_id )

  if( alert_id.is_a?(String) && alert_id.is_a?(Integer) )
    raise ArgumentError.new(format('wrong type. \'alert_id\' must be an String (for an Alert name) or an Integer (for an Alert Id), given \'%s\'', alert_id.class.to_s))
  end
  raise ArgumentError.new('missing \'alert_id\'') if( alert_id.size.zero? )

#       if(alert_id.is_a?(String))
#         data = alerts( alerts: 'all' ).select { |_k,v| v['name'] == alert_id }
#         alert_id = data.keys.first if( data )
#       end

#       puts alert_id
  # GET /api/alerts/:id

  endpoint = format( '/api/alerts/%d' , alert_id )

#       puts endpoint

  @logger.debug("Attempting get alert id #{alert_id} (GET #{endpoint})") if @debug

  get( endpoint )
end

#alert_notifications ⇒ Hash

Get alert notifications

Examples:

alert_notifications

Returns:



153
154
155
156
 
# File 'lib/grafana/alerts.rb', line 153

def alert_notifications
  logger.debug('Getting alert notifications') if @debug
  get('/api/alert-notifications')
end

#alert_pause(alert_id) ⇒ Hash

Pause single alert

Examples:

alert_pause( 1 )
alert_pause( 'foo' )

Parameters:

  • alert_id (Mixed) —

    Alertname (String) or Alertid (Integer)

Returns:

Raises:

  • (ArgumentError) 


125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/grafana/alerts.rb', line 125

def alert_pause( alert_id )

  if( alert_id.is_a?(String) && alert_id.is_a?(Integer) )
    raise ArgumentError.new(format('wrong type. \'alert_id\' must be an String (for an Alert name) or an Integer (for an Alert Id), given \'%s\'', alert_id.class.to_s))
  end
  raise ArgumentError.new('missing \'alert_id\'') if( alert_id.size.zero? )

  if( alert_id.is_a?(String) )
    data = alerts( alerts: 'all' ).select { |_k,v| v['name'] == alert_id }
    alert_id = data.keys.first if( data )
  end

  endpoint = format( '/api/alerts/%d/pause', alert_id )

  @logger.debug("Attempting pause alert id #{alert_id} (POST #{endpoint})") if @debug

  # POST /api/alerts/:id/pause
#       puts alert_id
  post( endpoint )
end

#alerts(params) ⇒ Array

Get alerts

These parameters are used as querystring parameters. For example:

To specify multiple states use the following format: ?state=paused&state=alerting

GET /api/alerts/ curl -H ‘Content-Type: application/json;charset=UTF-8’ ‘admin:[email protected]:3030/api/alerts’

Parameters:

Options Hash (params):

  • dashboard_id (Mixed) —

    alerts for a specified dashboard.

  • panel_id (Integer) —

    alerts for a specified panel on a dashboard.

  • limit (Integer) — default: 10 —

    response to x number of alerts.

  • state (Integer) — default: ALL, no_data, paused, alerting, ok, pending
  • alerts (Array) —

    with one or more of the following alert states: ‘ALL’, ‘no_data’, ‘paused’, ‘alerting’, ‘ok’, ‘pending’.

Returns:

Raises:

  • (ArgumentError) 


29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/grafana/alerts.rb', line 29

def alerts( params )

  raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
#       raise ArgumentError.new('missing \'params\'') if( params.size.zero? )

  dashboard_id = validate( params, required: false, var: 'dashboard_id' )
  panel_id     = validate( params, required: false, var: 'panel_id', type: Integer )
  limit        = validate( params, required: false, var: 'limit', type: Integer )
  alert_array  = validate( params, required: false, var: 'alerts', type: Array )
  valid_alerts = %w[ALL no_data paused alerting ok pending].sort

  unless( alert_array.nil? )
    alert_array  = alert_array.sort
#         valid   = alert_array & valid_alerts
    invalid = alert_array - valid_alerts

    raise ArgumentError.new(format('wrong alerts type. only %s allowed, given \'%s\'', valid_alerts.join(', '), alert_array.join(', '))) if( invalid.count != 0 )
  end

  if( dashboard_id.is_a?(String) )

    dashboard = search_dashboards( query: dashboard_id )

    return { 'status' => 404, 'message' => format( 'No Dashboard \'%s\' found', dashboard_id) } if( dashboard.nil? || dashboard.dig('status').to_i != 200 )

    dashboard = dashboard.dig('message').first unless( dashboard.nil? && dashboard.dig('status').to_i == 200 )
    dashboard_id = dashboard.dig('id') unless( dashboard.nil? )

    return { 'status' => 404, 'message' => format( 'No Dashboard \'%s\' found', dashboard_id) } if( dashboard_id.nil? )
  end

  api     = []
  api << format( 'dashboardId=%s', dashboard_id ) unless( dashboard_id.nil? )
  api << format( 'panelId=%s', panel_id ) unless( panel_id.nil? )
  api << format( 'limit=%s', limit ) unless( limit.nil? )

  unless( alert_array.nil? )
    alert_array = alert_array.join( '&state=' ) if( alert_array.is_a?( Array ) )
    api << format( 'state=%s', alert_array )
  end
  api = api.join( '&' )

  endpoint = format( '/api/alerts/?%s' , api )

  @logger.debug("Attempting to search for alerts (GET #{endpoint})") if @debug

  get( endpoint )
end

#create_alert_notification(params) ⇒ Hash

Create alert notification

Examples:

params = {
  name: 'new alert notification',
  type:  'email',
  default: false,
  settings: {
    addresses: '[email protected];[email protected]'
  }
}
create_alert_notification( params )

Parameters:

Options Hash (params):

  • name (String) —

    short description - required

  • type (String) —

    one of ‘slack’, ‘pagerduty’,‘email’,‘webhook’,‘kafka’,‘hipchat’, ‘victorops’,‘sensu’,‘opsgenie’,‘threema’,‘pushover’,‘telegram’,‘line’,‘prometheus-alertmanager’ - required

  • default (Boolean) — default: false
  • settings (Hash)

Returns:

Raises:

  • (ArgumentError) 


185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
 
# File 'lib/grafana/alerts.rb', line 185

def create_alert_notification( params )

  raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
  raise ArgumentError.new('missing params') if( params.size.zero? )

  # TODO
  # type are 'email'
  # and the other possible values?
  name     = validate( params, required: true, var: 'name', type: String )
  type     = validate( params, required: true, var: 'type', type: String ) || 'email'
  default  = validate( params, required: false, var: 'default', type: Boolean ) || false
  settings = validate( params, required: false, var: 'settings', type: Hash )

  unless( type.nil? )
    valid_types = %w[slack pagerduty email webhook kafka hipchat victorops sensu opsgenie threema pushover telegram line prometheus-alertmanager]
    raise ArgumentError.new(format('wrong notification type. only %s allowed, given \%s\'', valid_types.join(', '), type)) if( valid_types.include?(type.downcase) == false )
  end

  # TODO
  # check if the alert 'name' already created
  return { 'status' => 404, 'message' => format( 'alert notification \'%s\' alread exists', name) } if( alert_notification?(name) )

#       data = alert_notifications
#       data = data.dig('message').first unless( data.nil? && data.dig('status').to_i == 200 )
#       data = data.select { |k| k['name'] == name }
#       return { 'status' => 404, 'message' => format( 'alert notification \'%s\' alread exists', name) } if( data )

  payload = {
    name: name,
    type: type,
    isDefault: default,
    settings: settings
  }
  payload.reject!{ |_k, v| v.nil? }

  endpoint = '/api/alert-notifications'

#       puts endpoint
#       puts payload

  post(endpoint, payload.to_json)
end

#delete_alert_notification(alert_id) ⇒ Hash

Delete alert notification

Examples:

delete_alert_notification( 1 )
delete_alert_notification( 'foo' )

Parameters:

  • alert_id (Mixed) —

    Alertname (String) or Alertid (Integer)

Returns:

Raises:

  • (ArgumentError) 


312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
 
# File 'lib/grafana/alerts.rb', line 312

def delete_alert_notification( alert_id )

  if( alert_id.is_a?(String) && alert_id.is_a?(Integer) )
    raise ArgumentError.new(format('wrong type. user \'alert_id\' must be an String (for an Alert name) or an Integer (for an Alert Id), given \'%s\'', alert_id.class.to_s))
  end
  raise ArgumentError.new('missing \'alert_id\'') if( alert_id.size.zero? )

  id = alert_notification_id(alert_id)
  return { 'status' => 404, 'message' => format( 'alert notification \'%s\' not exists', alert_id) } if( id.nil? )

  endpoint = format('/api/alert-notifications/%d', alert_id )
  logger.debug( "Deleting alert id #{alert_id} (DELETE #{endpoint})" ) if @debug

  delete( endpoint )
end

#update_alert_notification(params) ⇒ Hash

Update alert notification

Examples:

params = {
  alert_id: 1
  name: 'new alert notification',
  type:  'email',
  default: false,
  settings: {
    addresses: '[email protected];[email protected]'
  }
}
update_alert_notification( params )

params = {
  alert_id: 'new alert notification'
  name: 'new alert notification',
  type:  'email',
  default: false,
  settings: {
   addresses: '[email protected];[email protected]'
  }
}
update_alert_notification( params )

Parameters:

  • params (Hash)
  • alert_id (Mixed) —

    Alertname (String) or Alertid (Integer) to change

Options Hash (params):

  • name (String) —

    short description - required

  • type (String) — default: 'email' —

    • required

  • default (Boolean) — default: false
  • settings (Hash)

Returns:

Raises:

  • (ArgumentError) 


262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
 
# File 'lib/grafana/alerts.rb', line 262

def update_alert_notification( params )

  raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
  raise ArgumentError.new('missing params') if( params.size.zero? )

  # TODO
  # type are 'email'
  # and the other possible values?
  alert_id = validate( params, required: true, var: 'alert_id' )
  name     = validate( params, required: true, var: 'name', type: String )
  type     = validate( params, required: true, var: 'type', type: String ) || 'email'
  default  = validate( params, required: false, var: 'default', type: Boolean ) || false
  settings = validate( params, required: false, var: 'settings', type: Hash )

  unless( type.nil? )
    valid_types = %w[slack pagerduty email webhook kafka hipchat victorops sensu opsgenie threema pushover telegram line prometheus-alertmanager]
    raise ArgumentError.new(format('wrong notification type. only %s allowed, given \%s\'', valid_types.join(', '), type)) if( valid_types.include?(type.downcase) == false )
  end

  if( alert_id.is_a?(String) && alert_id.is_a?(Integer) )
    raise ArgumentError.new(format('wrong type. user \'alert_id\' must be an String (for an Alertname) or an Integer (for an Alert Id), given \'%s\'', alert_id.class.to_s))
  end

  alert_id = alert_notification_id(alert_id)
  return { 'status' => 404, 'message' => format( 'alert notification \'%s\' not exists', name) } if( alert_id.nil? )

  payload = {
    id: alert_id,
    name: name,
    type: type,
    isDefault: default,
    settings: settings
  }
  payload.reject!{ |_k, v| v.nil? }

  endpoint = format( '/api/alert-notifications/%d', alert_id )

  put(endpoint, payload.to_json)
end