{"id":20980693,"url":"https://github.com/statful/statful-client-ruby","last_synced_at":"2026-03-04T18:03:55.346Z","repository":{"id":56896750,"uuid":"67700355","full_name":"statful/statful-client-ruby","owner":"statful","description":"Statful client for Ruby applications.","archived":false,"fork":false,"pushed_at":"2016-10-26T14:13:48.000Z","size":22,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-12-05T04:38:49.404Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/statful.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-09-08T12:17:07.000Z","updated_at":"2016-10-26T14:13:49.000Z","dependencies_parsed_at":"2022-08-21T01:50:10.328Z","dependency_job_id":null,"html_url":"https://github.com/statful/statful-client-ruby","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/statful/statful-client-ruby","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statful%2Fstatful-client-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statful%2Fstatful-client-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statful%2Fstatful-client-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statful%2Fstatful-client-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/statful","download_url":"https://codeload.github.com/statful/statful-client-ruby/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statful%2Fstatful-client-ruby/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30088344,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T15:40:14.053Z","status":"ssl_error","status_checked_at":"2026-03-04T15:40:13.655Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-19T05:29:39.563Z","updated_at":"2026-03-04T18:03:55.328Z","avatar_url":"https://github.com/statful.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"Statful Client for Ruby\n==============\n\n[![Build Status](https://travis-ci.org/statful/statful-client-ruby.svg?branch=master)](https://travis-ci.org/statful/statful-client-ruby)\n[![Gem Version](https://badge.fury.io/rb/statful-client.svg)](https://badge.fury.io/rb/statful-client)\n\nStaful client for Ruby. This client is intended to gather metrics and send them to Statful.\n\n## Table of Contents\n\n* [Supported Versions of Ruby](#supported-versions-of-ruby)\n* [Installation](#installation)\n* [Quick Start](#quick-start)\n* [Examples](#examples)\n* [Reference](#reference)\n* [Development](#development)\n* [Authors](#authors)\n* [License](#license)\n\n## Supported Versions of Ruby\n\n| Tested Ruby versions  |\n|:---|\n|  `2.1.8`, `2.2.4`, `2.3.0` |\n\n## Installation\n\n```bash\n$ gem install statful-client\n```\n\n## Quick start\n\nAfter installing Statful Client you are ready to use it. The quickest way is to do the following:\n\n```ruby\nrequire 'statful-client'\n\nconfig = {\n  :transport =\u003e 'http',\n  :token =\u003e 'test_token',\n}\n\nstatful = StatfulClient.new(config)\n```\n\n\u003e **IMPORTANT:** This configuration uses the default **host** and **port**. You can learn more about configuration in [Reference](#reference).\n\n## Examples\n\nYou 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.\n\n### UDP Configuration\n\nCreates a simple UDP configuration for the client.\n\n```ruby\nrequire 'statful-client'\n\nconfig = {\n  :transport =\u003e 'udp',\n  :host =\u003e 'in_premises_statful_relay',\n  :tags =\u003e { :test_tag =\u003e 'test_tag_value' },\n  :flush_size =\u003e 10\n}\n\nstatful = StatfulClient.new(config)\n```\n\n\u003e **IMPORTANT:** UDP transport is only available by using an in-premises [statful-relay](https://github.com/statful/statful-relay).\n\n### HTTP Configuration\n\nCreates a simple HTTP API configuration for the client.\n\n```ruby\nrequire 'statful-client'\n\nconfig = {\n  :transport =\u003e 'http',\n  :token =\u003e 'test_token',\n  :tags =\u003e { :test_tag =\u003e 'test_tag_value' },\n  :flush_size =\u003e 10\n}\n\nstatful = StatfulClient.new(config)\n```\n\n### Logger configuration\n\nCreates a simple client configuration and adds your favourite logger to the client.\n\n**Just assure that logger object supports, at least, warn, debug and error methods**.\n\n```ruby\nrequire 'statful-client'\nrequire 'logger'\n\nlogger = Logger.new(STDOUT)\nlogger.level = Logger::DEBUG\n\nconfig = {\n  :transport =\u003e 'http',\n  :token =\u003e 'test_token',\n  :tags =\u003e { :test_tag =\u003e 'test_tag_value' },\n  :logger =\u003e logger,\n  :flush_size =\u003e 10\n}\n\nstatful = StatfulClient.new(config)\n```\n\n### Defaults Configuration Per Method\n\nCreates a configuration for the client with custom default options per method.\n\n```ruby\nrequire 'statful-client'\n\nconfig = {\n  :transport =\u003e 'http',\n  :token =\u003e 'test_token',\n  :tags =\u003e { :test_tag =\u003e 'test_tag_value' },\n  :flush_size =\u003e 10,\n  :defaults =\u003e {\n    :counter =\u003e { :agg =\u003e %w(avg), :aggFreq =\u003e 180 },\n    :gauge =\u003e { :agg =\u003e %w(first), :aggFreq =\u003e 180 },\n    :timer =\u003e { :tags =\u003e { :cluster =\u003e 'test' }, :agg =\u003e %s(count), :aggFreq =\u003e 180 }\n  }\n}\n\nstatful = StatfulClient.new(config)\n```\n\n### Mixed Complete Configuration\n\nCreates a mixed configuration for possible real scenario.\n\n```ruby\nrequire 'statful-client'\nrequire 'logger'\n\nlogger = Logger.new(STDOUT)\nlogger.level = Logger::DEBUG\n\nconfig = {\n  :transport =\u003e 'http',\n  :token =\u003e 'test_token',\n  :tags =\u003e { :test_tag =\u003e 'test_tag_value' },\n  :dryrun =\u003e true,\n  :logger =\u003e logger,\n  :flush_size =\u003e 10,\n  :namespace =\u003e 'my_test_app',\n  :defaults =\u003e {\n    :counter =\u003e { :agg =\u003e %w(avg), :aggFreq =\u003e 180 },\n    :gauge =\u003e { :agg =\u003e %w(first), :aggFreq =\u003e 180 },\n    :timer =\u003e { :tags =\u003e { :cluster =\u003e 'test' }, :agg =\u003e %s(count), :aggFreq =\u003e 180 }\n  }\n}\n\nstatful = StatfulClient.new(config)\n```\n\n### Add metrics\n\nCreates a simple client configuration and use it to send some metrics.\n\n```ruby\nrequire 'statful-client'\n\nconfig = {\n  :transport =\u003e 'http',\n  :token =\u003e 'test_token',\n  :tags =\u003e { :test_tag =\u003e 'test_tag_value' },\n  :flush_size =\u003e 1\n}\n\nstatful = StatfulClient.new(config)\n\n# Send three different metrics (timer, counter and gauge)\nstatful.timer(\"test_timer\", 100)\nstatful.counter(\"test_counter\", 1)\nstatful.gauge(\"test_gauge\", 33)\n\n# Send a timer with custom aggregations\nstatful.timer(\"test_timer\", 100, { :agg =\u003e %w(p50), :aggFreq =\u003e 60 })\n\n# Send a timer with custom tags\nstatful.timer(\"test_timer\", 100, { :tags =\u003e {:host =\u003e 'test_host', :status =\u003e 'SUCCESS' } }\n```\n\n## Reference\n\nDetailed reference if you want to take full advantage from Statful.\n\n### Global configuration\n\nThe custom options that can be set on config param are detailed below.\n\n| Option | Description | Type | Default | Required |\n|:---|:---|:---|:---|:---|\n| _host_ | Defines the host name to where the metrics should be sent. | `String` | `api.statful.com` | **NO** |\n| _port_ | Defines the port. | `Integer` | `443` | **NO** |\n| _transport_ | Defines the transport layer to be used to send metrics.\u003cbr\u003e\u003cbr\u003e **Valid Transports:** `udp, http` | `String` | `http` | **NO** |\n| _timeout_ | Defines the timeout for the transport layers in **miliseconds**. | `Integer` | `2000` | **NO** |\n| _token_ | Defines the token to be used. | `String` | **none** | **YES if using HTTP transport** |\n| _app_ | Defines the application global name. If specified sets a global tag `app=setValue`. | `String` | **none** | **NO** |\n| _dryrun_ | Defines if metrics should be output to the logger instead of being sent. | `Boolean` | `false` | **NO** |\n| _logger_ | Defines logger object. | `Object` | **none** | **NO** |\n| _tags_ | Defines the global tags. | `Hash` | `{}` | **NO** |\n| _sample_rate_ | Defines the rate sampling. **Should be a number between [1, 100]**. | `Integer` | `100` | **NO** |\n| _flush_size_ | Defines the maximum buffer size before performing a flush. | `Integer` | `5` | **NO** |\n| _thread_pool_size_ | Defines the maximum thread pool size. | `Integer` | `5` | **NO** |\n| _namespace_ | Defines the global namespace. | `String` | `application` | **NO** |\n| _default_ | Object to set methods options. | `Object` | `{}` | **NO** |\n\n### Methods\n\n```ruby\n- staful.counter('myCounter', 1, { :agg =\u003e ['sum'] });\n- staful.gauge('myGauge', 10, { :tags =\u003e { :host =\u003e 'localhost' } });\n- staful.timer('myTimer', 200, { :namespace =\u003e 'sandbox' });\n- staful.put('myCustomMetric', 200, { :timestamp =\u003e '1471519331' });\n```\n\n| Option | Description | Type | Default for Counter | Default for Gauge | Default for Timer | Default for Put |\n|:---|:---|:---|:---|:---|:---|:---|:---|\n| _agg_ | Defines the aggregations to be executed. These aggregations are merged with the ones configured globally, including method defaults.\u003cbr\u003e\u003cbr\u003e **Valid Aggregations:** `avg, count, sum, first, last, p90, p95, min, max` | `Array` | `['avg', 'p90']` | `[last]` | `['avg', 'p90', 'count']` | `[]` |\n| _aggFreq_ | Defines the aggregation frequency in **seconds**. It overrides the global aggregation frequency configuration.\u003cbr\u003e\u003cbr\u003e **Valid Aggregation Frequencies:** `10, 30, 60, 120, 180, 300` | `Integer` | `10` | `10` | `10` | `10` |\n| _namespace_ | Defines the namespace of the metric. It overrides the global namespace configuration. | `String` | `application` | `application` | `application` | `application` |\n| _tags_ | Defines the tags of the metric. These tags are merged with the ones configured globally, including method defaults. | `Object` | `{}` | `{}` | `{ unit: 'ms' }` | `{}` |\n| _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` |\n\n## Development\n\n### Dependencies\n\nUse bundle to install all dev dependencies:\n\n```\n$ bundle install\n```\n\n### Tests\n\nIt uses [rspec](http://rspec.info/) and [minitest](http://docs.seattlerb.org/minitest/) to specify the unit tests suite.\n\nThere's a rake task which runs the specs:\n\n```\n$ rake spec\n```\n\n### Build\n\nUse gem to build a gem according to the spec if required:\n\n```\n$ gem build statful-ruby.gemspec\n```\n\n### Docs\n\nIt uses [yard](http://yardoc.org/) to generate documentation.\n\nThere's a rake task which generates the doc directory with the output:\n\n```\n$ rake yard\n```\n\n## Authors\n\n[Mindera - Software Craft](https://github.com/Mindera)\n\n## License\n\nStatful Ruby Client is available under the MIT license. See the [LICENSE](https://raw.githubusercontent.com/statful/statful-client-ruby/master/LICENSE) file for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatful%2Fstatful-client-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstatful%2Fstatful-client-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatful%2Fstatful-client-ruby/lists"}