Statful Client for Ruby

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

Table of Contents

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

Supported Versions of Ruby

Installation

$ gem install statful-client

Quick start

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.

Examples

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.

UDP Configuration

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.

HTTP Configuration

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)

Logger configuration

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)

Defaults Configuration Per Method

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)

Mixed Complete Configuration

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)

Add metrics

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' } }

Reference

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

Global configuration

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

Methods

- 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 |

Development

Dependencies

Use bundle to install all dev dependencies:

$ bundle install

Tests

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

There's a rake task which runs the specs:

$ rake spec

Build

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

$ gem build statful-ruby.gemspec

Docs

It uses yard to generate documentation.

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

$ rake yard

Authors

Mindera - Software Craft

License

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