Statful Client for Ruby

Staful client for Ruby. This client is intended to gather metrics and send them to Statful.

• Supported Versions of Ruby
• Installation
• Quick Start
• Examples
• Reference
• Development
• Authors
• License

$ gem install statful-client

After installing Statful Client you are ready to use it. The quickest way is to do the following:

require 'statful-client'

config = {
  :transport => 'http',
  :token => 'test_token',
}

statful = StatfulClient.new(config)

IMPORTANT: This configuration uses the default host and port. You can learn more about configuration in Reference.

You can find here some useful usage examples of the Statful Client. In the following examples is assumed you have already installed and included Statful Client in your project.

Creates a simple UDP configuration for the client.

require 'statful-client'

config = {
  :transport => 'udp',
  :host => 'in_premises_statful_relay',
  :tags => { :test_tag => 'test_tag_value' },
  :flush_size => 10
}

statful = StatfulClient.new(config)

IMPORTANT: UDP transport is only available by using an in-premises statful-relay.

Creates a simple HTTP API configuration for the client.

require 'statful-client'

config = {
  :transport => 'http',
  :token => 'test_token',
  :tags => { :test_tag => 'test_tag_value' },
  :flush_size => 10
}

statful = StatfulClient.new(config)

Creates a simple client configuration and adds your favourite logger to the client.

Just assure that logger object supports, at least, warn, debug and error methods.

require 'statful-client'
require 'logger'

logger = Logger.new(STDOUT)
logger.level = Logger::DEBUG

config = {
  :transport => 'http',
  :token => 'test_token',
  :tags => { :test_tag => 'test_tag_value' },
  :logger => logger,
  :flush_size => 10
}

statful = StatfulClient.new(config)

Creates a configuration for the client with custom default options per method.

require 'statful-client'

config = {
  :transport => 'http',
  :token => 'test_token',
  :tags => { :test_tag => 'test_tag_value' },
  :flush_size => 10,
  :defaults => {
    :counter => { :agg => %w(avg), :aggFreq => 180 },
    :gauge => { :agg => %w(first), :aggFreq => 180 },
    :timer => { :tags => { :cluster => 'test' }, :agg => %s(count), :aggFreq => 180 }
  }
}

statful = StatfulClient.new(config)

Creates a mixed configuration for possible real scenario.

require 'statful-client'
require 'logger'

logger = Logger.new(STDOUT)
logger.level = Logger::DEBUG

config = {
  :transport => 'http',
  :token => 'test_token',
  :tags => { :test_tag => 'test_tag_value' },
  :dryrun => true,
  :logger => logger,
  :flush_size => 10,
  :namespace => 'my_test_app',
  :defaults => {
    :counter => { :agg => %w(avg), :aggFreq => 180 },
    :gauge => { :agg => %w(first), :aggFreq => 180 },
    :timer => { :tags => { :cluster => 'test' }, :agg => %s(count), :aggFreq => 180 }
  }
}

statful = StatfulClient.new(config)

Creates a simple client configuration and use it to send some metrics.

require 'statful-client'

config = {
  :transport => 'http',
  :token => 'test_token',
  :tags => { :test_tag => 'test_tag_value' },
  :flush_size => 1
}

statful = StatfulClient.new(config)

# Send three different metrics (timer, counter and gauge)
statful.timer("test_timer", 100)
statful.counter("test_counter", 1)
statful.gauge("test_gauge", 33)

# Send a timer with custom aggregations
statful.timer("test_timer", 100, { :agg => %w(p50), :aggFreq => 60 })

# Send a timer with custom tags
statful.timer("test_timer", 100, { :tags => {:host => 'test_host', :status => 'SUCCESS' } }

Detailed reference if you want to take full advantage from Statful.

The custom options that can be set on config param are detailed below.

- staful.counter('myCounter', 1, { :agg => ['sum'] });
- staful.gauge('myGauge', 10, { :tags => { :host => 'localhost' } });
- staful.timer('myTimer', 200, { :namespace => 'sandbox' });
- staful.put('myCustomMetric', 200, { :timestamp => '1471519331' });

| Option | Description | Type | Default for Counter | Default for Gauge | Default for Timer | Default for Put | |:---|:---|:---|:---|:---|:---|:---|:---| | agg | Defines the aggregations to be executed. These aggregations are merged with the ones configured globally, including method defaults.

Valid Aggregations: avg, count, sum, first, last, p90, p95, min, max | Array | ['avg', 'p90'] | [last] | ['avg', 'p90', 'count'] | [] | | aggFreq | Defines the aggregation frequency in seconds. It overrides the global aggregation frequency configuration.

Valid Aggregation Frequencies: 10, 30, 60, 120, 180, 300 | Integer | 10 | 10 | 10 | 10 | | namespace | Defines the namespace of the metric. It overrides the global namespace configuration. | String | application | application | application | application | | tags | Defines the tags of the metric. These tags are merged with the ones configured globally, including method defaults. | Object | {} | {} | { unit: 'ms' } | {} | | timestamp | Defines the timestamp of the metric. This timestamp is a POSIX/Epoch time in seconds. | String | current timestamp | current timestamp | current timestamp | current timestamp |

Use bundle to install all dev dependencies:

$ bundle install

It uses rspec and minitest to specify the unit tests suite.

There's a rake task which runs the specs:

$ rake spec

Use gem to build a gem according to the spec if required:

$ gem build statful-ruby.gemspec

It uses yard to generate documentation.

There's a rake task which generates the doc directory with the output:

$ rake yard

Mindera - Software Craft

Statful Ruby Client is available under the MIT license. See the LICENSE file for more information.