class Librato::Metrics::Client

Attributes

api_key[RW]
email[RW]
proxy[RW]

Public Instance Methods

agent_identifier(*args) click to toggle source

Provide agent identifier for the developer program. See: support.metrics.librato.com/knowledgebase/articles/53548-developer-program

@example Have the gem build your identifier string

Librato::Metrics.agent_identifier 'flintstone', '0.5', 'fred'

@example Provide your own identifier string

Librato::Metrics.agent_identifier 'flintstone/0.5 (dev_id:fred)'

@example Remove identifier string

Librato::Metrics.agent_identifier ''
# File lib/librato/metrics/client.rb, line 22
def agent_identifier(*args)
  if args.length == 1
    @agent_identifier = args.first
  elsif args.length == 3
    @agent_identifier = "#{args[0]}/#{args[1]} (dev_id:#{args[2]})"
  elsif ![0,1,3].include?(args.length)
    raise ArgumentError, 'invalid arguments, see method documentation'
  end
  @agent_identifier ||= ''
end
annotator() click to toggle source
# File lib/librato/metrics/client.rb, line 33
def annotator
  @annotator ||= Annotator.new(client: self)
end
api_endpoint() click to toggle source

API endpoint to use for queries and direct persistence.

@return [String] api_endpoint

# File lib/librato/metrics/client.rb, line 41
def api_endpoint
  @api_endpoint ||= 'https://metrics-api.librato.com'
end
api_endpoint=(endpoint) click to toggle source

Set API endpoint for use with queries and direct persistence. Generally you should not need to set this as it will default to the current Librato Metrics endpoint.

# File lib/librato/metrics/client.rb, line 50
def api_endpoint=(endpoint)
  @api_endpoint = endpoint
end
authenticate(email, api_key) click to toggle source

Authenticate for direct persistence

@param [String] email @param [String] api_key

# File lib/librato/metrics/client.rb, line 58
def authenticate(email, api_key)
  flush_authentication
  self.email, self.api_key = email, api_key
end
connection() click to toggle source

Current connection object

# File lib/librato/metrics/client.rb, line 65
def connection
  # prevent successful creation if no credentials set
  raise CredentialsMissing unless (self.email and self.api_key)
  @connection ||= Connection.new(client: self, api_endpoint: api_endpoint,
                                 adapter: faraday_adapter, proxy: self.proxy)
end
create_snapshot(options = {}) click to toggle source

Create a snapshot of an instrument

@example Take a snapshot of the instrument at metrics-api.librato.com/v1/instruments/42 using a

duration of 3 hours and ending at now.
Librato::Metrics.snapshot(subject: {instrument: {href: "https://metrics-api.librato.com/v1/instruments/42"}},
                          duration: 3.hours, end_time: Time.now)

@param Hash options Params for the snapshot @options options [Hash] :subject An object representing the subject of the snapshot. For now, only instruments are supported @options options [Numeric] :duration Time interval over which to take the snapshot, defaults to 1 hour @options options [Numeric, Time] :end_time Snapshot the time period of the duration, ending with end_time. Default is “now”.

# File lib/librato/metrics/client.rb, line 393
def create_snapshot(options = {})
  url = "snapshots"
  response = connection.post do |request|
    request.url connection.build_url(url)
    request.body = SmartJSON.write(options)
  end
  parsed = SmartJSON.read(response.body)
end
custom_user_agent() click to toggle source
# File lib/librato/metrics/client.rb, line 81
def custom_user_agent
  @user_agent
end
custom_user_agent=(agent) click to toggle source

Overrride user agent for this client's connections. If you are trying to specify an agent identifier for developer program, see agent_identifier.

# File lib/librato/metrics/client.rb, line 76
def custom_user_agent=(agent)
  @user_agent = agent
  @connection = nil
end
delete_metrics(*metric_names) click to toggle source

Completely delete metrics with the given names. Be careful with this, this is instant and permanent.

@example Delete metric 'temperature'

Librato::Metrics.delete_metrics :temperature

@example Delete metrics 'foo' and 'bar'

Librato::Metrics.delete_metrics :foo, :bar

@example Delete metrics that start with 'foo' except 'foobar'

Librato::Metrics.delete_metrics names: 'foo*', exclude: ['foobar']
# File lib/librato/metrics/client.rb, line 97
def delete_metrics(*metric_names)
  raise(NoMetricsProvided, 'Metric name missing.') if metric_names.empty?
  if metric_names[0].respond_to?(:keys) # hash form
    params = metric_names[0]
  else
    params = { names: metric_names.map(&:to_s) }
  end
  connection.delete do |request|
    request.url connection.build_url("metrics")
    request.body = SmartJSON.write(params)
  end
  # expects 204, middleware will raise exception otherwise.
  true
end
faraday_adapter() click to toggle source

Return current adapter this client will use. Defaults to Metrics.faraday_adapter if set, otherwise Faraday.default_adapter

# File lib/librato/metrics/client.rb, line 115
def faraday_adapter
  @faraday_adapter ||= default_faraday_adapter
end
faraday_adapter=(adapter) click to toggle source

Set faraday adapter this client will use

# File lib/librato/metrics/client.rb, line 120
def faraday_adapter=(adapter)
  @faraday_adapter = adapter
end
flush_authentication() click to toggle source

Purge current credentials and connection.

# File lib/librato/metrics/client.rb, line 248
def flush_authentication
  self.email = nil
  self.api_key = nil
  @connection = nil
end
get_composite(definition, options={}) click to toggle source

Retrieve measurements for a given composite metric definition. :start_time and :resolution are required options, :end_time is optional.

@example Get 5m moving average of 'foo'

measurements = Librato::Metrics.get_composite
  'moving_average(mean(series("foo", "*"), {size: "5"}))',
  start_time: Time.now.to_i - 60*60, resolution: 300

@param [String] definition Composite definition @param [hash] options Query options

# File lib/librato/metrics/client.rb, line 135
def get_composite(definition, options={})
  unless options[:start_time] && options[:resolution]
    raise "You must provide a :start_time and :resolution"
  end
  query = options.dup
  query[:compose] = definition
  url = connection.build_url("metrics", query)
  response = connection.get(url)
  parsed = SmartJSON.read(response.body)
  # TODO: pagination support
  parsed
end
get_measurements(metric_name, options = {}) click to toggle source

Retrieve data points for a specific metric

@example Get 20 most recent data points for metric

data = Librato::Metrics.get_measurements :temperature, count: 20

@example Get 20 most recent data points for a specific source

data = Librato::Metrics.get_measurements :temperature, count: 20,
                                         source: 'app1'

@example Get the 20 most recent 15 minute data point rollups

data = Librato::Metrics.get_measurements :temperature, count: 20,
                                         resolution: 900

@example Get data points for the last hour

data = Librato::Metrics.get_measurements start_time: Time.now-3600

@example Get 15 min data points from two hours to an hour ago

data = Librato::Metrics.get_measurements start_time: Time.now-7200,
                                         end_time: Time.now-3600,
                                         resolution: 900

A full list of query parameters can be found in the API documentation: {dev.librato.com/v1/get/metrics/:name}

@param [Symbol|String] metric_name Metric name @param [Hash] options Query options

# File lib/librato/metrics/client.rb, line 241
def get_measurements(metric_name, options = {})
  raise ArgumentError, "you must provide at least a :start_time or :count" if options.empty?
  get_metric(metric_name, options)["measurements"]
end
get_metric(name, options = {}) click to toggle source

Retrieve a specific metric by name, optionally including data points

@example Get attributes for a metric

metric = Librato::Metrics.get_metric :temperature

@example Get a metric and its 20 most recent data points

metric = Librato::Metrics.get_metric :temperature, count: 20
metric['measurements'] # => {...}

A full list of query parameters can be found in the API documentation: {dev.librato.com/v1/get/metrics/:name}

@param [Symbol|String] name Metric name @param [Hash] options Query options

# File lib/librato/metrics/client.rb, line 162
def get_metric(name, options = {})
  query = options.dup
  if query[:start_time].respond_to?(:year)
    query[:start_time] = query[:start_time].to_i
  end
  if query[:end_time].respond_to?(:year)
    query[:end_time] = query[:end_time].to_i
  end
  unless query.empty?
    query[:resolution] ||= 1
  end
  # expects 200
  url = connection.build_url("metrics/#{name}", query)
  response = connection.get(url)
  parsed = SmartJSON.read(response.body)
  # TODO: pagination support
  parsed
end
get_series(metric_name, options={}) click to toggle source

Retrieve series of measurements for a given metric

@example Get series for metric

series = Librato::Metrics.get_series :requests, resolution: 1, duration: 3600

@example Get series for metric grouped by tag

query = { duration: 3600, resolution: 1, group_by: "environment", group_by_function: "sum" }
series = Librato::Metrics.get_series :requests, query

@example Get series for metric grouped by tag and negated by tag filter

query = { duration: 3600, resolution: 1, group_by: "environment", group_by_function: "sum", tags_search: "environment=!staging" }
series = Librato::Metrics.get_series :requests, query

@param [Symbol|String] metric_name Metric name @param [Hash] options Query options

# File lib/librato/metrics/client.rb, line 196
def get_series(metric_name, options={})
  raise ArgumentError, ":resolution and :duration or :start_time must be set" if options.empty?
  query = options.dup
  if query[:start_time].respond_to?(:year)
    query[:start_time] = query[:start_time].to_i
  end
  if query[:end_time].respond_to?(:year)
    query[:end_time] = query[:end_time].to_i
  end
  query[:resolution] ||= 1
  unless query[:start_time] || query[:end_time]
    query[:duration] ||= 3600
  end
  url = connection.build_url("measurements/#{metric_name}", query)
  response = connection.get(url)
  parsed = SmartJSON.read(response.body)
  parsed["series"]
end
get_snapshot(id) click to toggle source

Retrive a snapshot, to check its progress or find its image_href

@example Get a snapshot identified by 42

Librato::Metrics.get_snapshot 42

@param [Integer|String] id

# File lib/librato/metrics/client.rb, line 408
def get_snapshot(id)
  url = "snapshots/#{id}"
  response = connection.get(url)
  parsed = SmartJSON.read(response.body)
end
get_source(name) click to toggle source

Retrieve a single source by name. See dev.librato.com/v1/get/sources/:name

@example Get the source for a particular EC2 instance from Cloudwatch

Librato::Metrics.get_source "us-east-1b.i-f1bc8c9c"

@param String name

# File lib/librato/metrics/client.rb, line 361
def get_source(name)
  url = connection.build_url("sources/#{name}")
  response = connection.get(url)
  parsed = SmartJSON.read(response.body)
end
metrics(options={}) click to toggle source

List currently existing metrics

@example List all metrics

Librato::Metrics.metrics

@example List metrics with 'foo' in the name

Librato::Metrics.metrics name: 'foo'

@param [Hash] options

# File lib/librato/metrics/client.rb, line 263
def metrics(options={})
  query = {}
  query[:name] = options[:name] if options[:name]
  offset = 0
  path = "metrics"
  Collection.paginated_metrics(connection, path, query)
end
new_queue(options={}) click to toggle source

Create a new queue which uses this client.

@return [Queue]

# File lib/librato/metrics/client.rb, line 274
def new_queue(options={})
  options[:client] = self
  Queue.new(options)
end
persistence() click to toggle source

Persistence type to use when saving metrics. Default is :direct.

@return [Symbol]

# File lib/librato/metrics/client.rb, line 283
def persistence
  @persistence ||= :direct
end
persistence=(persist_method) click to toggle source

Set persistence type to use when saving metrics.

@param [Symbol] persist_method

# File lib/librato/metrics/client.rb, line 290
def persistence=(persist_method)
  @persistence = persist_method
end
persister() click to toggle source

Current persister object.

# File lib/librato/metrics/client.rb, line 295
def persister
  @queue ? @queue.persister : nil
end
sources(filter = {}) click to toggle source

List sources, optionally limited by a name. See dev.librato.com/v1/sources and dev.librato.com/v1/get/sources

@example Get sources matching “production”

Librato::Metrics.sources name: "production"

@param [Hash] filter

# File lib/librato/metrics/client.rb, line 348
def sources(filter = {})
  query = {}
  query[:name] = filter[:name] if filter.has_key?(:name)
  path = "sources"
  Collection.paginated_collection("sources", connection, path, query)
end
submit(args) click to toggle source

Submit all queued metrics.

# File lib/librato/metrics/client.rb, line 301
def submit(args)
  @queue ||= Queue.new(client: self,
                       skip_measurement_times: true,
                       clear_failures: true)
  @queue.add args
  @queue.submit
end
update_metric(metric, options = {}) click to toggle source

Update a single metric with new attributes.

@example Update metric 'temperature'

Librato::Metrics.update_metric :temperature, period: 15, attributes: { color: 'F00' }

@example Update metric 'humidity', creating it if it doesn't exist

Librato::Metrics.update_metric 'humidity', type: :gauge, period: 60, display_name: 'Humidity'
# File lib/librato/metrics/client.rb, line 317
def update_metric(metric, options = {})
  url = "metrics/#{metric}"
  connection.put do |request|
    request.url connection.build_url(url)
    request.body = SmartJSON.write(options)
  end
end
update_metrics(metrics) click to toggle source

Update multiple metrics.

@example Update multiple metrics by name

Librato::Metrics.update_metrics names: ["foo", "bar"], period: 60

@example Update all metrics that start with 'foo' that aren't 'foobar'

Librato::Metrics.update_metrics names: 'foo*', exclude: ['foobar'], display_min: 0
# File lib/librato/metrics/client.rb, line 333
def update_metrics(metrics)
  url = "metrics" # update multiple metrics
  connection.put do |request|
    request.url connection.build_url(url)
    request.body = SmartJSON.write(metrics)
  end
end
update_source(name, options = {}) click to toggle source

Update a source by name. See dev.librato.com/v1/get/sources/:name

@example Update the source display name for a particular EC2 instance from Cloudwatch

Librato::Metrics.update_source "us-east-1b.i-f1bc8c9c", display_name: "Production Web 1"

@param String name @param Hash options

# File lib/librato/metrics/client.rb, line 374
def update_source(name, options = {})
  url = "sources/#{name}"
  connection.put do |request|
    request.url connection.build_url(url)
    request.body = SmartJSON.write(options)
  end
end

Private Instance Methods

default_faraday_adapter() click to toggle source
# File lib/librato/metrics/client.rb, line 416
def default_faraday_adapter
  if Metrics.client == self
    Faraday.default_adapter
  else
    Metrics.faraday_adapter
  end
end
flush_persistence() click to toggle source
# File lib/librato/metrics/client.rb, line 424
def flush_persistence
  @persistence = nil
end