You are viewing documentation for version 3 of the AWS SDK for Ruby. Version 2 documentation can be found here.

Class: Aws::CloudWatch::Alarm

Inherits:
Object
  • Object
show all
Defined in:
gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb

Defined Under Namespace

Classes: Collection

Actions collapse

Associations collapse

Read-Only Attributes collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, options = {}) ⇒ Alarm #initialize(options = {}) ⇒ Alarm

Returns a new instance of Alarm

Overloads:

  • #initialize(name, options = {}) ⇒ Alarm

    Parameters:

    • name (String)

    Options Hash (options):

  • #initialize(options = {}) ⇒ Alarm

    Options Hash (options):

    • :name (required, String)
    • :client (Client)


19
20
21
22
23
24
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 19

def initialize(*args)
  options = Hash === args.last ? args.pop.dup : {}
  @name = extract_name(args, options)
  @data = options.delete(:data)
  @client = options.delete(:client) || Client.new(options)
end

Instance Method Details

#actions_enabledBoolean

Indicates whether actions should be executed during any changes to the alarm state.

Returns:

  • (Boolean)


55
56
57
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 55

def actions_enabled
  data[:actions_enabled]
end

#alarm_actionsArray<String>

The actions to execute when this alarm transitions to the ALARM state from any other state. Each action is specified as an Amazon Resource Name (ARN).

Returns:

  • (Array<String>)


71
72
73
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 71

def alarm_actions
  data[:alarm_actions]
end

#alarm_arnString

The Amazon Resource Name (ARN) of the alarm.

Returns:

  • (String)


36
37
38
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 36

def alarm_arn
  data[:alarm_arn]
end

#alarm_configuration_updated_timestampTime

The time stamp of the last update to the alarm configuration.

Returns:

  • (Time)


48
49
50
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 48

def alarm_configuration_updated_timestamp
  data[:alarm_configuration_updated_timestamp]
end

#alarm_descriptionString

The description of the alarm.

Returns:

  • (String)


42
43
44
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 42

def alarm_description
  data[:alarm_description]
end

#clientClient

Returns:



192
193
194
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 192

def client
  @client
end

#comparison_operatorString

The arithmetic operation to use when comparing the specified statistic and threshold. The specified statistic value is used as the first operand.

Returns:

  • (String)


168
169
170
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 168

def comparison_operator
  data[:comparison_operator]
end

#dataTypes::MetricAlarm

Returns the data for this Aws::CloudWatch::Alarm. Calls Client#describe_alarms if #data_loaded? is false.

Returns:



212
213
214
215
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 212

def data
  load unless @data
  @data
end

#data_loaded?Boolean

Returns true if this resource is loaded. Accessing attributes or #data on an unloaded resource will trigger a call to #load.

Returns:

  • (Boolean)

    Returns true if this resource is loaded. Accessing attributes or #data on an unloaded resource will trigger a call to #load.



220
221
222
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 220

def data_loaded?
  !!@data
end

#delete(options = {}) ⇒ EmptyStructure

Examples:

Request syntax with placeholder values


alarm.delete()

Parameters:

  • options (Hash) (defaults to: {})

    ({})

Returns:

  • (EmptyStructure)


357
358
359
360
361
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 357

def delete(options = {})
  options = Aws::Util.deep_merge(options, alarm_names: [@name])
  resp = @client.delete_alarms(options)
  resp.data
end

#describe_history(options = {}) ⇒ Types::DescribeAlarmHistoryOutput

Examples:

Request syntax with placeholder values


alarm.describe_history({
  history_item_type: "ConfigurationUpdate", # accepts ConfigurationUpdate, StateUpdate, Action
  start_date: Time.now,
  end_date: Time.now,
  max_records: 1,
  next_token: "NextToken",
})

Parameters:

  • options (Hash) (defaults to: {})

    ({})

Options Hash (options):

  • :history_item_type (String)

    The type of alarm histories to retrieve.

  • :start_date (Time, DateTime, Date, Integer, String)

    The starting date to retrieve alarm history.

  • :end_date (Time, DateTime, Date, Integer, String)

    The ending date to retrieve alarm history.

  • :max_records (Integer)

    The maximum number of alarm history records to retrieve.

  • :next_token (String)

    The token returned by a previous call to indicate that there is more data available.

Returns:



385
386
387
388
389
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 385

def describe_history(options = {})
  options = options.merge(alarm_name: @name)
  resp = @client.describe_alarm_history(options)
  resp.data
end

#dimensionsArray<Types::Dimension>

The dimensions for the metric associated with the alarm.

Returns:



135
136
137
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 135

def dimensions
  data[:dimensions]
end

#disable_actions(options = {}) ⇒ EmptyStructure

Examples:

Request syntax with placeholder values


alarm.disable_actions()

Parameters:

  • options (Hash) (defaults to: {})

    ({})

Returns:

  • (EmptyStructure)


396
397
398
399
400
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 396

def disable_actions(options = {})
  options = Aws::Util.deep_merge(options, alarm_names: [@name])
  resp = @client.disable_alarm_actions(options)
  resp.data
end

#enable_actions(options = {}) ⇒ EmptyStructure

Examples:

Request syntax with placeholder values


alarm.enable_actions()

Parameters:

  • options (Hash) (defaults to: {})

    ({})

Returns:

  • (EmptyStructure)


407
408
409
410
411
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 407

def enable_actions(options = {})
  options = Aws::Util.deep_merge(options, alarm_names: [@name])
  resp = @client.enable_alarm_actions(options)
  resp.data
end

#evaluate_low_sample_count_percentileString

Used only for alarms based on percentiles. If ignore, the alarm state does not change during periods with too few data points to be statistically significant. If evaluate or this parameter is not used, the alarm is always evaluated and possibly changes state no matter how many data points are available.

Returns:

  • (String)


185
186
187
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 185

def evaluate_low_sample_count_percentile
  data[:evaluate_low_sample_count_percentile]
end

#evaluation_periodsInteger

The number of periods over which data is compared to the specified threshold.

Returns:

  • (Integer)


154
155
156
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 154

def evaluation_periods
  data[:evaluation_periods]
end

#exists?(options = {}) ⇒ Boolean

Returns true if the Alarm exists.

Parameters:

  • options (Hash) (defaults to: {})

    ({})

Returns:

  • (Boolean)

    Returns true if the Alarm exists.



227
228
229
230
231
232
233
234
235
236
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 227

def exists?(options = {})
  begin
    wait_until_exists(options.merge(max_attempts: 1))
    true
  rescue Aws::Waiters::Errors::UnexpectedError => e
    raise e.error
  rescue Aws::Waiters::Errors::WaiterFailed
    false
  end
end

#extended_statisticString

The percentile statistic for the metric associated with the alarm. Specify a value between p0.0 and p100.

Returns:

  • (String)


129
130
131
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 129

def extended_statistic
  data[:extended_statistic]
end

#insufficient_data_actionsArray<String>

The actions to execute when this alarm transitions to the INSUFFICIENT_DATA state from any other state. Each action is specified as an Amazon Resource Name (ARN).

Returns:

  • (Array<String>)


79
80
81
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 79

def insufficient_data_actions
  data[:insufficient_data_actions]
end

#loadself Also known as: reload

Loads, or reloads #data for the current Aws::CloudWatch::Alarm. Returns self making it possible to chain methods.

alarm.reload.data

Returns:

  • (self)


202
203
204
205
206
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 202

def load
  resp = @client.describe_alarms(alarm_names: [@name])
  @data = resp.metric_alarms[0]
  self
end

#metricMetric?

Returns:



439
440
441
442
443
444
445
446
447
448
449
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 439

def metric
  if data[:namespace] && data[:metric_name]
    Metric.new(
      namespace: data[:namespace],
      name: data[:metric_name],
      client: @client
    )
  else
    nil
  end
end

#metric_nameString

The name of the metric associated with the alarm.

Returns:

  • (String)


109
110
111
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 109

def metric_name
  data[:metric_name]
end

#nameString Also known as: alarm_name

Returns:

  • (String)


29
30
31
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 29

def name
  @name
end

#namespaceString

The namespace of the metric associated with the alarm.

Returns:

  • (String)


115
116
117
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 115

def namespace
  data[:namespace]
end

#ok_actionsArray<String>

The actions to execute when this alarm transitions to the OK state from any other state. Each action is specified as an Amazon Resource Name (ARN).

Returns:

  • (Array<String>)


63
64
65
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 63

def ok_actions
  data[:ok_actions]
end

#periodInteger

The period, in seconds, over which the statistic is applied.

Returns:

  • (Integer)


141
142
143
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 141

def period
  data[:period]
end

#set_state(options = {}) ⇒ EmptyStructure

Examples:

Request syntax with placeholder values


alarm.set_state({
  state_value: "OK", # required, accepts OK, ALARM, INSUFFICIENT_DATA
  state_reason: "StateReason", # required
  state_reason_data: "StateReasonData",
})

Parameters:

  • options (Hash) (defaults to: {})

    ({})

Options Hash (options):

  • :state_value (required, String)

    The value of the state.

  • :state_reason (required, String)

    The reason that this alarm is set to this specific state, in text format.

  • :state_reason_data (String)

    The reason that this alarm is set to this specific state, in JSON format.

Returns:

  • (EmptyStructure)


430
431
432
433
434
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 430

def set_state(options = {})
  options = options.merge(alarm_name: @name)
  resp = @client.set_alarm_state(options)
  resp.data
end

#state_reasonString

An explanation for the alarm state, in text format.

Returns:

  • (String)


91
92
93
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 91

def state_reason
  data[:state_reason]
end

#state_reason_dataString

An explanation for the alarm state, in JSON format.

Returns:

  • (String)


97
98
99
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 97

def state_reason_data
  data[:state_reason_data]
end

#state_updated_timestampTime

The time stamp of the last update to the alarm state.

Returns:

  • (Time)


103
104
105
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 103

def state_updated_timestamp
  data[:state_updated_timestamp]
end

#state_valueString

The state value for the alarm.

Returns:

  • (String)


85
86
87
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 85

def state_value
  data[:state_value]
end

#statisticString

The statistic for the metric associated with the alarm, other than percentile. For percentile statistics, use ExtendedStatistic.

Returns:

  • (String)


122
123
124
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 122

def statistic
  data[:statistic]
end

#thresholdFloat

The value to compare with the specified statistic.

Returns:

  • (Float)


160
161
162
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 160

def threshold
  data[:threshold]
end

#treat_missing_dataString

Sets how this alarm is to handle missing data points. If this parameter is omitted, the default behavior of missing is used.

Returns:

  • (String)


175
176
177
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 175

def treat_missing_data
  data[:treat_missing_data]
end

#unitString

The unit of the metric associated with the alarm.

Returns:

  • (String)


147
148
149
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 147

def unit
  data[:unit]
end

#wait_until(options = {}, &block) ⇒ Resource

Deprecated.

Use [Aws::CloudWatch::Client] #wait_until instead

Note:

The waiting operation is performed on a copy. The original resource remains unchanged

Waiter polls an API operation until a resource enters a desired state.

Basic Usage

Waiter will polls until it is successful, it fails by entering a terminal state, or until a maximum number of attempts are made.

# polls in a loop until condition is true
resource.wait_until(options) {|resource| condition}

Example

instance.wait_until(max_attempts:10, delay:5) {|instance| instance.state.name == 'running' }

Configuration

You can configure the maximum number of polling attempts, and the delay (in seconds) between each polling attempt. The waiting condition is set by passing a block to #wait_until:

# poll for ~25 seconds
resource.wait_until(max_attempts:5,delay:5) {|resource|...}

Callbacks

You can be notified before each polling attempt and before each delay. If you throw :success or :failure from these callbacks, it will terminate the waiter.

started_at = Time.now
# poll for 1 hour, instead of a number of attempts
proc = Proc.new do |attempts, response|
  throw :failure if Time.now - started_at > 3600
end

  # disable max attempts
instance.wait_until(before_wait:proc, max_attempts:nil) {...}

Handling Errors

When a waiter is successful, it returns the Resource. When a waiter fails, it raises an error.

begin
  resource.wait_until(...)
rescue Aws::Waiters::Errors::WaiterFailed
  # resource did not enter the desired state in time
end

attempts attempt in seconds invoked before each attempt invoked before each wait

Parameters:

  • options (Hash) (defaults to: {})

    a customizable set of options

Options Hash (options):

  • :max_attempts (Integer) — default: 10

    Maximum number of

  • :delay (Integer) — default: 10

    Delay between each

  • :before_attempt (Proc) — default: nil

    Callback

  • :before_wait (Proc) — default: nil

    Callback

Returns:

  • (Resource)

    if the waiter was successful

Raises:

  • (Aws::Waiters::Errors::FailureStateError)

    Raised when the waiter terminates because the waiter has entered a state that it will not transition out of, preventing success.

    yet successful.

  • (Aws::Waiters::Errors::UnexpectedError)

    Raised when an error is encountered while polling for a resource that is not expected.

  • (NotImplementedError)

    Raised when the resource does not



333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 333

def wait_until(options = {}, &block)
  self_copy = self.dup
  attempts = 0
  options[:max_attempts] = 10 unless options.key?(:max_attempts)
  options[:delay] ||= 10
  options[:poller] = Proc.new do
    attempts += 1
    if block.call(self_copy)
      [:success, self_copy]
    else
      self_copy.reload unless attempts == options[:max_attempts]
      :retry
    end
  end
  Aws::Waiters::Waiter.new(options).wait({})
end

#wait_until_exists(options = {}) ⇒ Alarm

Parameters:

  • options (Hash) (defaults to: {})

    ({})

Options Hash (options):

  • :max_attempts (Integer) — default: 40
  • :delay (Float) — default: 5
  • :before_attempt (Proc)
  • :before_wait (Proc)

Returns:



244
245
246
247
248
249
250
251
252
253
# File 'gems/aws-sdk-cloudwatch/lib/aws-sdk-cloudwatch/alarm.rb', line 244

def wait_until_exists(options = {})
  options, params = separate_params_and_options(options)
  waiter = Waiters::AlarmExists.new(options)
  yield_waiter_and_warn(waiter, &Proc.new) if block_given?
  waiter.wait(params.merge(alarm_names: [@name]))
  Alarm.new({
    name: @name,
    client: @client
  })
end