atsd 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9025f64163ec30e20c4a242935de58d36956fdee
+  data.tar.gz: f9d451cb22a9b1c1cd8ee7cbb09d916538019543
+SHA512:
+  metadata.gz: efd37ea4a310e612b2df8b8417b8ae09fc5990703f8b569f33c1efbdd014d293f324cb9db6181c05eb6d1a092186cb0c3ac73b3e1e11613e0f5fe280dec643ab
+  data.tar.gz: e73b69f0c386d4f073f3df4ce77418bc00f75df5d93d3599e73078ffbb39b05ddd13d5f5f2d050765f96a0de54331b5d7e1ec6e9ad24eb0386c817227f94536f

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+.idea
+/spec/config.yml

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require helpers/spec_helper

data/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in atsd.gemspec
+gemspec
+
+group :development do
+  gem 'vcr', github: 'vcr/vcr', ref: '572f1974b269c2bcb53fdf9a464011ed97758a6f' # fixes for Faraday
+end

data/README.md

@@ -0,0 +1,365 @@
+# Axibase Time-Series Database Client for Ruby
+
+The ATSD Client for Ruby enables Ruby developers 
+to easily read and write statistics and metadata 
+from Axibase Time-Series Database.
+
+API documentation: https://axibase.com/atsd/api
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'atsd'
+```
+
+Then execute:
+
+    $ bundle
+
+Or install manually:
+
+    $ gem install atsd
+    
+## Implemented Methods
+
+### Data API
+- Series
+    - Query
+    - Insert
+    - CSV Insert
+- Properties
+    - Query
+    - Insert
+    - Batch
+- Alerts 
+    - Query
+    - Update
+    - History Query
+    
+### Meta API
+- Metrics 
+    - List
+    - Get
+    - Create or replace
+    - Update
+    - Delete
+    - Entities and tags
+- Entities
+    - List
+    - Get
+    - Create or replace
+    - Update
+    - Delete
+- Entity Group 
+    - List
+    - Get
+    - Create or replace
+    - Update
+    - Delete
+    - Get entities
+    - Add entities
+    - Set entities
+    - Delete entities
+
+## Usage
+
+To start using the gem you need to create an ATSD instance:
+
+```ruby
+atsd = ATSD.new :url => '#{API_ENDPOINT}/api/v1', 
+                :basic_auth => '#{LOGIN}:#{PASSWORD}', 
+                :logger => true
+```
+
+### Configuration
+
+#### Authorization
+In order to use the API you need to specify `:basic_auth` option in one
+of the following forms:
+
+- `"login:password"`
+- `{ :login => 'login', :password => 'password' }`
+
+#### SSL 
+ATSD requires a little extra configuration for users who want to use SSL/HTTPS. 
+See [Faraday Wiki](https://github.com/lostisland/faraday/wiki/Setting-up-SSL-certificates) on how
+to setup SSL. As a quickfix you can specify `ssl: { verify: false }` option in the client.
+
+#### Logging
+
+- To use a custom logger specify it in the `:logger` option. 
+- To use default STDOUT logger set `:logger` option to `true`. 
+
+#### Faraday Middleware
+
+```ruby
+ATSD.new url: end_point, basic_auth: basic_auth do |builder|
+  builder.insert_after(FaradayMiddleware::ParseJson, VCR::Middleware::Faraday)
+  # ... 
+end
+```
+
+### Services
+Once you instantiated the ATSD class, you can use different services. 
+Each service represents a particular entity in Axibase Time Series Database.
+There are 6 services: series, properties, alerts, metrics, entities and
+entity groups.
+
+See documentation for all available methods.
+
+#### Query builders
+Query objects created by some services (e.g. Series) provide convenient methods to build complex queries.
+They support method chaining and automatically translate snake_styled properties 
+to CamelCase used in the API. For example, `end_time` property in ruby code becomes `endTime` in json request.
+
+#### Series Service
+
+Simple query:
+
+```ruby
+series = atsd.series
+# => #<ATSD::SeriesService:0x007f82a4446c08
+
+query = series.query('ubuntu', 'meminfo.memfree')
+# => {:entity=>"ubuntu", :metric=>"meminfo.memfree"}
+
+query.class
+# => ATSD::SeriesQuery
+
+query.end_time(Time.now)
+# => {:entity=>"ubuntu", :metric=>"meminfo.memfree", :end_time=>1428303004000}
+
+query.execute
+# => [{:entity=>"ubuntu",
+#    :metric=>"meminfo.memfree",
+#    :tags=>{},
+#    :type=>"HISTORY",
+#    :aggregate=>{"type"=>"DETAIL"},
+#    :data=>
+#     [{"t"=>1428301869000, "v"=>78728.0},
+#      {"t"=>1428301884000, "v"=>68676.0},
+#      {"t"=>1428301899000, "v"=>66716.0},
+# ...
+
+query.result
+# same result
+
+s = query.result.first
+s.entity
+# => "ubuntu"
+```
+
+Complex query:
+
+```ruby
+query.aggregate(types:[ATSD::SeriesQuery::AggregateType::AVG], interval:{count:1, unit:ATSD::SeriesQuery::Interval::HOUR})
+# => {:entity=>"ubuntu",
+#  :metric=>"meminfo.memfree",
+#  :end_time=>1428303004000,
+#  :aggregate=>{:types=>["AVG"], :interval=>{:count=>1, :unit=>"HOUR"}}}
+
+query.execute
+# => [{:entity=>"ubuntu",
+#   :metric=>"meminfo.memfree",
+#   :tags=>{},
+#   :type=>"HISTORY",
+#   :aggregate=>{"type"=>"AVG", "interval"=>{"count"=>1, "unit"=>"HOUR"}},
+#   :data=>[{"t"=>1428300000000, "v"=>82615.05263157895}]}]
+```
+
+Data Insertion:
+
+```ruby
+s = ATSD::Series.new
+s.entity = 'ubuntu'
+s.metric = 'meminfo.memfree'
+s.data = [ {t: 100000000, v: 512} ]
+series.insert(s)
+```
+
+**CSV Insert**
+
+data.csv contents:
+```plain
+time, mem.info.memfree, meminfo.memused
+1414789200000,  0.8,     0.0
+1414789230000,  1.6,     1.0
+1414789800000,  2.4,    -3.0
+1414800000000,  3.2,    23.0
+1414861200000,  4.0,     7.0
+1415134800000,  0.0,     0.8
+1415800800000,  1.0,     1.6
+1417244400000, -3.0,     2.4
+1433106000000, 23.0,     3.2
+1446238800000,  7.0,     4.0
+```
+
+Inserting csv data example:
+```ruby
+series.csv_insert('ubuntu', File.read('/path/to/data.csv'), { :user => 'beta' })
+```
+
+#### Properties Service
+
+```ruby
+props = atsd.properties
+# => #<ATSD::PropertiesService:0x007f82a456e6f8
+
+property = ATSD::Property.new
+property.entity = 'ubuntu'
+property.type = 'system'
+property.key = {"server_name":"server","user_name":"system"}
+property.tags = {"name.1": "value.1"}
+props.insert(property)
+
+props.query('ubuntu', 'system').execute
+# => [{:type=>"system",
+#  :entity=>"ubuntu",
+#  :key=>{"server_name"=>"server", "user_name"=>"system"},
+#  :timestamp=>1428304255068,
+#  :tags=>{"name.1"=>"value.1"}}]
+
+props.delete(property)
+props.query('ubuntu', 'system').execute
+# => []
+```
+
+#### Alerts Service
+
+```ruby
+a = atsd.alerts
+# => #<ATSD::AlertsService:0x007faf7c0efdc0
+
+a.query.execute
+# => [{:value=>447660.0,
+#     :id=>4,
+#     :text_value=>"447660",
+#     :tags=>{},
+#     :metric=>"meminfo.active",
+#     :entity=>"ubuntu",
+#     :severity=>3,
+#     :rule=>"My rule!",
+#     :repeat_count=>5,
+#     :open_time=>1428330612667,
+#     :open_value=>445144.0,
+#     :acknowledged=>false,
+#     :last_event_time=>1428330687440},
+#    {:value=>447660.0,
+#     :id=>6,
+#     :text_value=>"447660",
+#     :tags=>{},
+#     :metric=>"meminfo.active",
+#     :entity=>"ubuntu",
+#     :severity=>3,
+# ...
+```
+#### Metrics Service
+
+```ruby
+ms = atsd.metrics
+# => #<ATSD::MetricsService:0x007fbb548d9548
+
+ms.list
+# => [{:name=>"activemq_metrics_count",
+#     :enabled=>true,
+#     :data_type=>"FLOAT",
+#     :counter=>false,
+#     :persistent=>true,
+#     :time_precision=>"MILLISECONDS",
+#     :retention_interval=>0,
+#     :invalid_action=>"NONE",
+#     :last_insert_time=>1428328861848},
+#    {:name=>"activemq_properties_count",
+#     :enabled=>true,
+#     :data_type=>"FLOAT",
+#     :counter=>false,
+#     :persistent=>true,
+# ...
+
+ms.entity_and_tags('df.disk_size')
+# => [{:entity=>"ubuntu", :tags=>{"file_system"=>"/dev/sda1", "mount_point"=>"/"}, :last_insert_time=>1428328928000},
+#  {:entity=>"ubuntu",
+#   :tags=>{"file_system"=>"none", "mount_point"=>"/sys/fs/cgroup"},
+#   :last_insert_time=>1428328928000},
+#  {:entity=>"ubuntu", :tags=>{"file_system"=>"none", "mount_point"=>"/run/lock"}, :last_insert_time=>1428328928000},
+#  {:entity=>"ubuntu", :tags=>{"file_system"=>"none", "mount_point"=>"/run/shm"}, :last_insert_time=>1428328928000},
+#  {:entity=>"ubuntu", :tags=>{"file_system"=>"none", "mount_point"=>"/run/user"}, :last_insert_time=>1428328928000},
+#  {:entity=>"ubuntu", :tags=>{"file_system"=>"udev", "mount_point"=>"/dev"}, :last_insert_time=>1428328928000},
+#  {:entity=>"ubuntu", :tags=>{"file_system"=>"tmpfs", "mount_point"=>"/run"}, :last_insert_time=>1428328928000}]
+```
+
+#### Entities Service
+
+```ruby
+ent = atsd.entities
+# => #<ATSD::EntitiesService:0x007f82a45b40b8
+
+ent.list
+# => [{:name=>"atsd", :enabled=>true, :last_insert_time=>1428304482631},
+#  {:name=>"mine", :enabled=>true},
+#  {:name=>"test_entity", :enabled=>true, :last_insert_time=>1000000000},
+#  {:name=>"ubuntu", :enabled=>true, :last_insert_time=>1428304489000}]
+
+ent.get('ubuntu')
+# => {:name=>"ubuntu", :enabled=>true, :last_insert_time=>1428304499000, :tags=>{}}
+
+ent.metrics('ubuntu')
+# => [{:name=>"df.disk_size",
+#   :enabled=>true,
+#   :data_type=>"FLOAT",
+#   :counter=>false,
+#   :persistent=>true,
+#   :time_precision=>"MILLISECONDS",
+#   :retention_interval=>0,
+#   :invalid_action=>"NONE",
+#   :last_insert_time=>1428304499000},
+#  {:name=>"df.disk_used",
+#   :enabled=>true,
+# ...
+
+ent.delete(ent.get('mine')) # or ent.delete('mine')
+ent.list
+# => [{:name=>"atsd", :enabled=>true, :last_insert_time=>1428304482631},
+#  {:name=>"test_entity", :enabled=>true, :last_insert_time=>1000000000},
+#  {:name=>"ubuntu", :enabled=>true, :last_insert_time=>1428304489000}]
+```
+#### Entity Groups Service 
+
+```ruby
+eg = atsd.entity_groups
+# => #<ATSD::EntityGroupsService:0x007fb1b2a0d7f8
+
+eg.create_or_replace('group1')
+eg.list
+# => [{:name=>"group1"}]
+
+eg.add_entities('group1', [{name:'entity1'},{name:'entity2'}])
+eg.entities(eg.get('group1'))
+# => [{:name=>"entity1", :enabled=>true}, {:name=>"entity2", :enabled=>true}]
+
+eg.delete_all_entities('group1')
+eg.entities('group1')
+# => []
+```
+
+### Errors
+If the request wasn't completed successfully then an `ATSD::APIError` exception is raised. You can get a message and HTTP status code using the `message` and `status`
+fields.
+
+### Low-level API Client
+Gem also provides an `ATSD::Client` class. It is a simple API wrapper 
+which uses [Faraday](https://github.com/lostisland/faraday) to handle HTTP-related routines. 
+All services are built on top of it. 
+Client has 1-to-1 mapping for all REST methods specified on https://axibase.com/atsd/api.
+
+You can access `Faraday::Connection` object using the `connection` field of the client if necessary.
+
+## Development
+
+After checking out the repository, run `bin/setup` to install dependencies. 
+Then 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`. 
+

data/Rakefile

@@ -0,0 +1,16 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'yard'
+require 'atsd/version'
+
+RSpec::Core::RakeTask.new
+
+task :default => :spec
+task :test => :spec
+
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb']
+  t.options = %w[ -m markdown -M redcarpet -r README.md ]
+  t.stats_options = []
+end
+

data/atsd.gemspec

@@ -0,0 +1,36 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'atsd/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'atsd'
+  spec.version       = ATSD::VERSION
+  spec.license       = 'Apache-2.0'
+  spec.authors       = ['Axibase Corporation']
+  spec.email         = ['atsd-api@axibase.com']
+
+  spec.summary       = %q{Axibase Time-Series Database Client for Ruby.}
+  spec.description   = %q{Axibase Time-Series Database Client for Ruby is an easy-to-use client for interfacing with ATSD metadata and data REST API services.}
+  spec.homepage      = 'https://github.com/axibase/atsd-api-ruby/'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.7'
+  spec.add_development_dependency 'rake', '~> 10.4'
+  spec.add_development_dependency 'pry', '~> 0.10'
+  spec.add_development_dependency 'rspec', '~> 3.2'
+  spec.add_development_dependency 'vcr', '~> 2.9'
+  spec.add_development_dependency 'yard', '~> 0.8'
+  spec.add_development_dependency 'redcarpet'
+  spec.add_development_dependency 'geminabox'
+  spec.add_development_dependency 'multi_json'
+
+  spec.add_dependency 'faraday', '~> 0.9'
+  spec.add_dependency 'faraday_middleware', '~> 0.9'
+  spec.add_dependency 'hashie', '~> 3.4'
+  spec.add_dependency 'activesupport', '~> 4.0'
+end