Class: Scout::Metric

Inherits:
Hashie::Mash
  • Object
show all
Defined in:
lib/scout_api/metric.rb

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(hash, ignore = nil) ⇒ Metric

2nd parameter is ignored/a hack because of this open Hashie issue: github.com/intridea/hashie/issues/14



5
6
7
8
9
10
11
12
13
 
# File 'lib/scout_api/metric.rb', line 5

def initialize(hash, ignore=nil) #:nodoc:
  super(hash)
  @avg_calc = Scout::MetricCalculation.new(self,:AVG)
  @avg_calc.metric_name = identifier
  @min_calc = Scout::MetricCalculation.new(self,:MIN)
  @min_calc.metric_name = identifier
  @max_calc = Scout::MetricCalculation.new(self,:MAX)
  @max_calc.metric_name = identifier
end

Instance Attribute Details

#plugin ⇒ Object

Returns the value of attribute plugin.



2
3
4
 
# File 'lib/scout_api/metric.rb', line 2

def plugin
  @plugin
end

#server ⇒ Object

Returns the value of attribute server.



2
3
4
 
# File 'lib/scout_api/metric.rb', line 2

def server
  @server
end

Class Method Details

.all(options = {}) ⇒ Array

Finds all metrics that match the conditons specified via options. Scout::MetricProxy uses this method to search for metrics. Refer to Scout::MetricProxy#all for examples.

Returns:

Raises:



48
49
50
51
52
 
# File 'lib/scout_api/metric.rb', line 48

def self.all(options = {})
  raise Scout::Error, "A finder condition is required" if options.empty?
  response = Scout::Account.get("/descriptors.xml?name=#{CGI.escape(options[:name].to_s)}&ids=&plugin_ids=#{options[:plugin_ids]}&server_ids=#{options[:server_ids]}&group_ids=#{options[:group_ids]}")
  response['ar_descriptors'] ? response['ar_descriptors'].map { |descriptor| Scout::Metric.new(descriptor) } : Array.new
end

.average(id_or_name, options = {}) ⇒ Hash

The average value of a metric by ID or name (ex: 'disk_used'). If the metric couldn’t be found AND/OR hasn’t reported since options[:start], a [Scout::Error] is raised.

A 3-element Hash is returned with the following keys:

  • :value

  • :units

  • :label

Options:

  • :start - The start time for grabbing metrics. Default is 1 hour ago. Times will be converted to UTC.

  • :end - The end time for grabbing metrics. Default is Time.now.utc. Times will be converted to UTC.

  • :aggregate - Whether the metrics should be added together or an average across each metric should be returned. Default is false. Note that total is not necessary equal to the value on each server * num of servers.

When to use :aggregate?

If you have a number of web servers, you may be interested in the total throughput for your application, not just the average on each server. For example:

  • Web Server No. 1 Average Throughput => 100 req/sec

  • Web Server No. 2 Average Throughput => 150 req/sec

:aggregate => true will return ~ 250 req/sec, giving the total throughput for your entire app. The default, :aggregate => false, will return ~ 125 req/sec, giving the average throughput across the web servers.

:aggregate => true likely doesn’t make sense for any metric that is on a 0-100 scale (like CPU Usage, Disk Capacity, etc.).

Examples:

# What is the average request time across my servers?
Scout::Metric.average('request_time') => {:value => 0.20, :units => 'sec', :label => 'Request Time'}

# What is the average TOTAL throughput across my servers?
Scout::Metric.average('request_rate', :aggregate => true)

# How much average memory did my servers use yesterday?
# Scout::Metric.average('Memory Used', :start => Time.now-(24*60*60)*2, :end => Time.now-(24*60*60))

Returns:

  • (Hash) 


94
95
96
 
# File 'lib/scout_api/metric.rb', line 94

def self.average(id_or_name,options = {})
  calculate('AVG',id_or_name,options)
end

.first(id_or_options = nil) ⇒ Scout::Metric

Finds a single metric that meets the given conditions. Possible parameter formats:

  • Scout::Metric.first => Finds the metric

  • Scout::Metric.first(1) => Finds the metric with ID=1

  • Scout::Metric.first(:name => 'request_rate') => Finds the first metric where name=~‘request_rate’

For the :name, a MySQL-formatted Regex can be used.

Returns:



24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/scout_api/metric.rb', line 24

def self.first(id_or_options = nil)
  if id_or_options.nil?
    response = Scout::Account.get("/descriptors.xml?limit=1")
    Scout::Metric.new(response['ar_descriptors'].first)
  elsif id_or_options.is_a?(Hash)
    if name=id_or_options[:name]
      response = Scout::Account.get("/descriptors.xml?name=#{CGI.escape(name)}")
      raise Scout::Error, 'Not Found' if response['ar_descriptors'].nil?
      Scout::Metric.new(response['ar_descriptors'].first)
    else
      raise Scout::Error, "Invalid finder condition"
    end
  elsif id_or_options.is_a?(Fixnum)
    response = Scout::Account.get("/descriptors/#{id_or_options}.xml")
    Scout::Metric.new(response['ar_descriptor'])
  else
    raise Scout::Error, "Invalid finder condition"
  end
end

.maximum(id_or_name, options = {}) ⇒ Hash

The maximum value of a metric by ID or name (ex: 'last_minute').

Uses the same parameters as average. See average for options and examples.

Returns:

  • (Hash) 


103
104
105
 
# File 'lib/scout_api/metric.rb', line 103

def self.maximum(id_or_name,options = {})
  calculate('MAX',id_or_name,options)
end

.minimum(id_or_name, options = {}) ⇒ Hash

The minimum value of a metric by ID or name (ex: 'last_minute').

Uses the same parameters as average. See average for options and examples.

Returns:

  • (Hash) 


112
113
114
 
# File 'lib/scout_api/metric.rb', line 112

def self.minimum(id_or_name,options = {})
  calculate('MIN',id_or_name,options)
end

.to_array(function, id_or_name, options = {}) ⇒ Array

Returns time series data.

Returns:

  • (Array) —

    This is a two-dimensional array. The 1st element is the [Time] in UTC. The 2nd element is the value at that time as a [Float].



119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/scout_api/metric.rb', line 119

def self.to_array(function,id_or_name,options = {})
  start_time,end_time=format_times(options)
  consolidate,name,ids=series_options(id_or_name,options)
  
  response = Scout::Account.get("/descriptors/series.xml?name=#{CGI.escape(name.to_s)}&ids=#{ids}&function=#{function}&consolidate=#{consolidate}&plugin_ids=#{options[:plugin_ids]}&server_ids=#{options[:server_ids]}&group_ids=#{options[:group_ids]}&start=#{start_time}&end=#{end_time}")
  if response['records']
    response['records'].values.flatten.map { |r| [Time.parse(r['time']),r['value'].to_f] }
  else
    []
  end
end

.to_sparkline(function, id_or_name, options = {}) ⇒ String

Generates a URL to a Google chart sparkline representation of the time series data.

Options:

  • :size - The size of the image in pixels. Default is '200x30'.

  • :line_color - The color of the line. Default is '0077cc' (blue).

  • :line_width - The width of the line in pixels. Default is <tt>2</t>.

Returns:

  • (String) 


140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/scout_api/metric.rb', line 140

def self.to_sparkline(function,id_or_name,options = {})
  start_time,end_time=format_times(options)
  consolidate,name,ids=series_options(id_or_name,options)
  response = Scout::Account.get("/descriptors/sparkline?name=#{CGI.escape(name.to_s)}&ids=#{ids}&function=#{function}&consolidate=#{consolidate}&plugin_ids=#{options[:plugin_ids]}&server_ids=#{options[:server_ids]}&group_ids=#{options[:group_ids]}&start=#{start_time}&end=#{end_time}&size=#{options[:size]}&line_color=#{options[:line_color]}&line_width=#{options[:line_width]}")

  if response['error']
    raise Scout::Error, response['error']
  else
    response.body
  end
end

Instance Method Details

#average(opts = {}) ⇒ Hash Also known as: avg

The average value for this metric. See #average for a list of options.

Returns:

  • (Hash) 


155
156
157
158
 
# File 'lib/scout_api/metric.rb', line 155

def average(opts = {})
  @avg_calc.options = opts
  @avg_calc
end

#identifier ⇒ Object

Metrics are identified by either their given ID or their name. Prefers ID.



180
181
182
 
# File 'lib/scout_api/metric.rb', line 180

def identifier #:nodoc:
  id? ? id : name
end

#maximum(opts = {}) ⇒ Hash Also known as: max

The maximum value for this metric. See #average for a list of options.

Returns:

  • (Hash) 


164
165
166
167
 
# File 'lib/scout_api/metric.rb', line 164

def maximum(opts = {})
   @max_calc.options = opts
   @max_calc
end

#minimum(opts = {}) ⇒ Hash Also known as: min

The minimum value for this metric. See #average for a list of options.

Returns:

  • (Hash) 


173
174
175
176
 
# File 'lib/scout_api/metric.rb', line 173

def minimum(opts = {})
   @min_calc.options = opts
   @min_calc
end

#options_for_relationship(opts = {}) ⇒ Object

Used to apply finder conditions



185
186
187
188
189
190
191
192
193
194
195
 
# File 'lib/scout_api/metric.rb', line 185

def options_for_relationship(opts = {}) #:nodoc:
  relationship_options = {}
  if id?
    relationship_options[:ids] = id
  elsif plugin
    relationship_options[:plugin_ids] = plugin.id
  elsif server
    relationship_options[:server_ids] = server.id
  end
  opts.merge(relationship_options)
end