Class: Librato::Metrics::Annotator

Inherits:
Object
  • Object
show all
Defined in:
lib/librato/metrics/annotator.rb

Overview

Read & write annotation streams for a given client connection.

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Annotator

Returns a new instance of Annotator.

Parameters:

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

    a customizable set of options

Options Hash (options):

  • :client (Client) —

    Client instance used to connect to Metrics



7
8
9
 
# File 'lib/librato/metrics/annotator.rb', line 7

def initialize(options={})
  @client = options[:client] || Librato::Metrics.client
end

Instance Method Details

#add(stream, title, options = {}) ⇒ Object

Creates a new annotation on the annotation stream

Examples:

Simple annotation

annotator.add :deployments, 'deployed v45'

Annotation with start and end times

annotator.add :deployments, 'deployed v56', start_time: start,
              end_time: end_time

Annotation with a specific source

annotator.add :deployments, 'deployed v60', source: 'app12'

Annotation with a description

annotator.add :deployments, 'deployed v61',
              description: '9b562b2: shipped new feature foo!'

Annotate with automatic start and end times

annotator.add(:deployments, 'deployed v62') do
  # do work..
end


32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
 
# File 'lib/librato/metrics/annotator.rb', line 32

def add(stream, title, options={})
  options[:title] = title
  options[:start_time] = (options[:start_time] || Time.now).to_i
  if options[:end_time]
    options[:end_time] = options[:end_time].to_i
  end
  payload = SmartJSON.write(options)
  response = connection.post("annotations/#{stream}", payload)
  # will raise exception if not 200 OK
  event = SmartJSON.read(response.body)
  if block_given?
    yield
    update_event stream, event['id'], end_time: Time.now.to_i
    # need to get updated representation
    event = fetch_event stream, event['id']
  end
  event
end

#client ⇒ Object

client instance used by this object



52
53
54
 
# File 'lib/librato/metrics/annotator.rb', line 52

def client
  @client
end

#delete(stream) ⇒ Object

Delete an annotation stream

Examples:

Delete the ‘deployment’ annotation stream

annotator.delete :deployment


61
62
63
64
65
66
67
 
# File 'lib/librato/metrics/annotator.rb', line 61

def delete(stream)
  connection.delete do |request|
    request.url connection.build_url("annotations/#{stream}")
  end
  # expects 204, middleware will raise exception otherwise
  true
end

#delete_event(stream, id) ⇒ Object

Delete an event from a given annotation stream

Examples:

Delete event with id 42 from ‘deployment’

annotator.delete_event :deployment, 42


74
75
76
77
78
79
80
 
# File 'lib/librato/metrics/annotator.rb', line 74

def delete_event(stream, id)
  connection.delete do |request|
    request.url connection.build_url("annotations/#{stream}/#{id}")
  end
  # expects 204, middleware will raise exception otherwise
  true
end

#fetch(stream, options = {}) ⇒ Object

Get a list of annotation events on a given annotation stream

Examples:

See properties of the ‘deployments’ annotation stream

annotator.fetch :deployments

Get events on ‘deployments’ between start and end times

annotator.fetch :deployments, start_time: start,
                end_time: end_time

Source-limited listing

annotator.fetch :deployments, sources: ['foo','bar','baz'],
                start_time: start, end_time: end_time


95
96
97
98
 
# File 'lib/librato/metrics/annotator.rb', line 95

def fetch(stream, options={})
  response = connection.get("annotations/#{stream}", options)
  SmartJSON.read(response.body)
end

#fetch_event(stream, id) ⇒ Object

Get properties for a given annotation stream event

Examples:

Get event

annotator.fetch :deployments, 23


105
106
107
108
 
# File 'lib/librato/metrics/annotator.rb', line 105

def fetch_event(stream, id)
  response = connection.get("annotations/#{stream}/#{id}")
  SmartJSON.read(response.body)
end

#list(options = {}) ⇒ Object

List currently existing annotation streams

Examples:

List all annotation streams

streams = annotator.list

List annotator streams with ‘deploy’ in the name

deploy_streams = annotator.list name: 'deploy'


118
119
120
121
 
# File 'lib/librato/metrics/annotator.rb', line 118

def list(options={})
  response = connection.get("annotations", options)
  SmartJSON.read(response.body)
end

#update_event(stream, id, options = {}) ⇒ Object

Update an event’s properties

Examples:

Set an end time for a previously submitted event

annotator.update_event 'deploys', 'v24', end_time: end_time


128
129
130
131
132
133
134
135
 
# File 'lib/librato/metrics/annotator.rb', line 128

def update_event(stream, id, options={})
  url = "annotations/#{stream}/#{id}"
  connection.put do |request|
    request.url connection.build_url(url)
    request.body = SmartJSON.write(options)
  end
  # expects 204 will raise exception otherwise
end