brharrington / spectator-rb

Netflix-Spectator-rb

⚠️ Experimental

Simple library for instrumenting code to record dimensional time series.

Description

This implements a basic Spectator library for instrumenting ruby applications, sending metrics to an Atlas aggregator service.

Instrumenting Code

require 'spectator'

class Response
  attr_accessor :status, :size

  def initialize(status, size)
    @status = status
    @size = size
  end
end

class Request
  attr_reader :country

  def initialize(country)
    @country = country
  end
end

class ExampleServer
  def initialize(registry)
    @registry = registry
    @req_count_id = registry.new_id('server.requestCount')
    @req_latency = registry.timer('server.requestLatency')
    @resp_sizes = registry.distribution_summary('server.responseSizes')
  end

  def expensive_computation(request)
    # ...
  end

  def handle_request(request)
    start = @registry.clock.monotonic_time

    # initialize response
    response = Response.new(200, 64)

    # Update the counter id with dimensions based on the request. The
    # counter will then be looked up in the registry which should be
    # fairly cheap, such as lookup of id object in a map
    # However, it is more expensive than having a local variable set
    # to the counter.
    cnt_id = @req_count_id.with_tag(:country, request.country)
                          .with_tag(:status, response.status.to_s)
    @registry.counter_with_id(cnt_id).increment

    # ...
    @req_latency.record(@registry.clock.monotonic_time - start)
    @resp_sizes.record(response.size)

    # timers can also time a given block
    # this is equivalent to:
    #  start = @registry.clock.monotonic_time
    #  expensive_computation(request)
    #  @registry.timer('server.computeTime').record(@registry.clock.monotonic_time - start)
    @registry.timer('server.computeTime').time { expensive_computation(request) }
    # ...
  end
end

config = {
  common_tags: { :'nf.app' => 'foo' },
  frequency: 0.5,
  uri: 'http://localhost:8080/api/v4/publish'
}

registry = Spectator::Registry.new(config)
registry.start

server = ExampleServer.new(registry)

# ...
# process some requests
requests = [Request.new('us'), Request.new('ar'), Request.new('ar')]
requests.each { |req| server.handle_request(req) }
sleep(2)

registry.stop

Installation

Add this line to your application's Gemfile:

gem 'spectator-rb'

And then execute:

$ bundle

Or install it yourself as:

$ gem install spectator-rb

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/Netflix/spectator-rb.