class ATSD::Client

HTTP(S) Client for Axibase Time Series Database. Implements all REST methods of the API in a straightforward manner.

Attributes

connection[R]

@return [Faraday::Connection] faraday connection object

logger[R]

@return [Logger] logger to use

Public Class Methods

new(options) { |builder| ... } click to toggle source

See {ATSD#initialize ATSD.new}

# File lib/atsd/client.rb, line 18
def initialize(options, &block)
  options = options.symbolize_keys
  login, password = extract_basic_auth(options)
  @logger = extract_logger(options)
  url = options.delete(:url)
  @connection = Faraday.new url, options do |builder|
    builder.headers['User-Agent'] = "ATSD Ruby Client v#{VERSION}"
    builder.basic_auth login, password
    builder.request :json

    builder.response :errors_handler
    builder.response :json, :content_type => 'application/json'
    builder.response :logger, @logger, :bodies => true if @logger

    builder.adapter Faraday.default_adapter
  end

  if block_given?
    block.arity > 0 ? yield(@connection.builder) : @connection.builder.instance_eval(&block)
  end
  true
end

Public Instance Methods

alerts_delete(actions) click to toggle source

Delete alerts

@param [Hash, Array<Hash>] actions action or array of actions @return [true] @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/data/alerts/delete.md for details

# File lib/atsd/client.rb, line 217
def alerts_delete(actions)
  @connection.post 'alerts/delete', Utils.ensure_array(actions)
  true
end
alerts_history_query(queries = nil) click to toggle source

Alerts history query

@param [Hash, Array<Hash>] queries query or array of queries @return [Array<Hash>] history records @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/data/alerts/history-query.md for details

# File lib/atsd/client.rb, line 228
def alerts_history_query(queries = nil)
  response = @connection.post 'alerts/history/query', Utils.ensure_array(queries)
  response.body
end
alerts_query(queries = nil) click to toggle source

Query alerts

@param [Hash, Array<Hash>] queries query or array of queries @return [Array<Hash>] alerts @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/data/alerts/query.md for details

# File lib/atsd/client.rb, line 195
def alerts_query(queries = nil)
  response = @connection.post 'alerts/query', Utils.ensure_array(queries)
  response.body
end
alerts_update(actions) click to toggle source

(De-)acknowledge alerts

@param [Hash, Array<Hash>] actions action or array of actions @return [true] @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/data/alerts/update.md for details

# File lib/atsd/client.rb, line 206
def alerts_update(actions)
  @connection.post 'alerts/update', Utils.ensure_array(actions)
  true
end
entities_create_or_replace(entity, body) click to toggle source

Create or replace entity.

@param [String] entity @param [Hash] body @return [true] @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/meta/entity/create-or-replace.md for details

# File lib/atsd/client.rb, line 340
def entities_create_or_replace(entity, body)
  @connection.put "entities/#{CGI.escape(entity)}", body
  true
end
entities_delete(entity) click to toggle source

Delete entity.

@param [String] entity @return [true] @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/meta/entity/delete.md for details

# File lib/atsd/client.rb, line 363
def entities_delete(entity)
  @connection.delete "entities/#{CGI.escape(entity)}"
  true
end
entities_entity_groups(entity, parameters = {}) click to toggle source

Entity groups entity.

@param [String] entity @return [Array] @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/meta/entity/entity-groups.md for details

# File lib/atsd/client.rb, line 374
def entities_entity_groups(entity, parameters = {})
  response = @connection.get "entities/#{CGI.escape(entity)}/groups", parameters
  response.body
end
entities_get(entity) click to toggle source

Entity details

@param [String] entity @return [Hash] @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/meta/entity/get.md for details

# File lib/atsd/client.rb, line 328
def entities_get(entity)
  response = @connection.get "entities/#{CGI.escape(entity)}"
  response.body
end
entities_list(parameters = {}) click to toggle source

List of entities

@param [Hash] parameters @return [Array<Hash>] @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/meta/entity/list.md for details

# File lib/atsd/client.rb, line 317
def entities_list(parameters = {})
  response = @connection.get 'entities', parameters
  response.body
end
entities_metrics(entity, parameters = {}) click to toggle source

Metrics for entity

@param [String] entity @param [Hash] parameters @return [Array] @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/meta/entity/metrics.md for details

# File lib/atsd/client.rb, line 398
def entities_metrics(entity, parameters = {})
  response = @connection.get "entities/#{CGI.escape(entity)}/metrics", parameters
  response.body
end
entities_property_types(entity, parameters = {}) click to toggle source

Property types for entity

@param [String] entity @param [Hash] parameters @return [Array] @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/meta/entity/property-types.md for details

# File lib/atsd/client.rb, line 386
def entities_property_types(entity, parameters = {})
  response = @connection.get "entities/#{CGI.escape(entity)}/property-types", parameters
  response.body
end
entities_update(entity, body) click to toggle source

Update entity.

@param [String] entity @param [Hash] body @return [true] @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/meta/entity/update.md for details

# File lib/atsd/client.rb, line 352
def entities_update(entity, body)
  @connection.patch "entities/#{CGI.escape(entity)}", body
  true
end
entity_groups_add_entities(entity_group, entities, parameters = {}) click to toggle source

Add entities to entity group.

@param [String] entity_group @param [Array] entities @param [Hash] parameters @return [true] @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/meta/entity-group/add-entities.md for details

# File lib/atsd/client.rb, line 480
def entity_groups_add_entities(entity_group, entities, parameters = {})
  @connection.patch "entity-groups/#{CGI.escape(entity_group)}/entities", [
      parameters.merge(:action => 'add',
                       :createEntities => true,
                       :entities => entities)
  ]
  true
end
entity_groups_create_or_replace(entity_group, body) click to toggle source

Create or replace entity group.

@param [String] entity_group @param [Hash] body @return [true] @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/meta/entity-group/create-or-replace.md for details

# File lib/atsd/client.rb, line 432
def entity_groups_create_or_replace(entity_group, body)
  @connection.put "entity-groups/#{CGI.escape(entity_group)}", body
  true
end
entity_groups_delete(entity_group) click to toggle source

Delete entity group.

@param [String] entity_group @return [true] @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/meta/entity-group/delete.md for details

# File lib/atsd/client.rb, line 455
def entity_groups_delete(entity_group)
  @connection.delete "entity-groups/#{CGI.escape(entity_group)}"
  true
end
entity_groups_delete_entities(entity_group, entities) click to toggle source

Delete entities in entity group.

@param [String] entity_group @param [Array] entities @return [true] @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/meta/entity-group/delete-entities.md for details

# File lib/atsd/client.rb, line 509
def entity_groups_delete_entities(entity_group, entities)
  @connection.patch "entity-groups/#{CGI.escape(entity_group)}/entities", [
      {:action => 'delete', :entities => entities}
  ]
  true
end
entity_groups_get(entity_group) click to toggle source

Entity group info

@param [String] entity_group @return [Hash] @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/meta/entity-group/get.md for details

# File lib/atsd/client.rb, line 420
def entity_groups_get(entity_group)
  response = @connection.get "entity-groups/#{CGI.escape(entity_group)}"
  response.body
end
entity_groups_get_entities(entity_group, parameters = {}) click to toggle source

List entity group entities.

@param [String] entity_group @param [Hash] parameters @return [Array] @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/meta/entity-group/get-entities.md for details

# File lib/atsd/client.rb, line 467
def entity_groups_get_entities(entity_group, parameters = {})
  response = @connection.get "entity-groups/#{CGI.escape(entity_group)}/entities", parameters
  response.body
end
entity_groups_list(parameters = {}) click to toggle source

Entity groups list.

@param [Hash] parameters @return [Array] @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/meta/entity-group/list.md for details

# File lib/atsd/client.rb, line 409
def entity_groups_list(parameters = {})
  response = @connection.get 'entity-groups', parameters
  response.body
end
entity_groups_replace_entities(entity_group, entities, parameters = {}) click to toggle source

Replace entities in entity group.

@param [String] entity_group @param [Array] entities @param [Hash] parameters @return [true] @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/meta/entity-group/replace-entities.md for details

# File lib/atsd/client.rb, line 497
def entity_groups_replace_entities(entity_group, entities, parameters = {})
  @connection.put "entity-groups/#{CGI.escape(entity_group)}/entities", entities
  true
end
entity_groups_update(entity_group, body) click to toggle source

Update entity group.

@param [String] entity_group @param [Hash] body @return [true] @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/meta/entity-group/update.md for details

# File lib/atsd/client.rb, line 444
def entity_groups_update(entity_group, body)
  @connection.patch "entity-groups/#{CGI.escape(entity_group)}", body
  true
end
messages_insert(messages) click to toggle source

Insert messages

@param [Hash, Array<Hash>] messages message or array of messages @return true @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/data/messages/insert.md for details

# File lib/atsd/client.rb, line 117
def messages_insert(messages)
  @connection.post 'messages/insert', Utils.ensure_array(messages)
  true
end
messages_query(queries = nil) click to toggle source

Query messages

@param [Hash, Array<Hash>] queries query or array of queries @return [Array<Hash>] array of messages @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/data/messages/query.md for details

# File lib/atsd/client.rb, line 106
def messages_query(queries = nil)
  response = @connection.post 'messages/query', Utils.ensure_array(queries)
  response.body
end
messages_stat_query(parameters = {}) click to toggle source

Statistics query

@param [Hash] parameters @return [Array<Hash>] time series @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/data/messages/stats-query.md for details

# File lib/atsd/client.rb, line 128
def messages_stat_query(parameters = {})
  print parameters
  response = @connection.post 'messages/stats/query', Utils.ensure_array(parameters)
  response.body
end
metrics_create_or_replace(metric, body) click to toggle source

Create a metric with specified properties and tags or replace an existing metric. This method creates a new metric or replaces an existing metric.

@note If only a subset of fields is provided for an existing metric,

the remaining properties and tags will be deleted.

@param [String] metric @param [Hash] body @return [true] @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/meta/metric/create-or-replace.md for details

# File lib/atsd/client.rb, line 266
def metrics_create_or_replace(metric, body)
  @connection.put "metrics/#{CGI.escape(metric)}", body
  true
end
metrics_delete(metric) click to toggle source

Delete the metric. Data collected for the metric will be removed asynchronously in the background.

@param [String] metric @return [true] @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/meta/metric/delete.md for details

# File lib/atsd/client.rb, line 293
def metrics_delete(metric)
  @connection.delete "metrics/#{CGI.escape(metric)}"
  true
end
metrics_get(metric) click to toggle source

Displays metric properties and its tags.

@param [String] metric @return [Hash] @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/meta/metric/get.md for details

# File lib/atsd/client.rb, line 250
def metrics_get(metric)
  response = @connection.get "metrics/#{CGI.escape(metric)}"
  response.body
end
metrics_list(parameters = {}) click to toggle source

Metrics list.

@param [Hash] parameters @return [Array<Hash>] @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/meta/metric/list.md for details

# File lib/atsd/client.rb, line 239
def metrics_list(parameters = {})
  response = @connection.get 'metrics', parameters
  response.body
end
metrics_series(metric, parameters = {}) click to toggle source

Returns a list of series for the metric. Each series is identified with metric name, entity name, and optional series tags.

@param [String] metric @param [Hash] parameters @return [Array] @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/meta/metric/series.md for details

# File lib/atsd/client.rb, line 306
def metrics_series(metric, parameters = {})
  response = @connection.get "metrics/#{CGI.escape(metric)}/series", parameters
  response.body
end
metrics_update(metric, body) click to toggle source

Update specified properties and tags for the given metric. This method updates specified properties and tags for an existing metric.

@note Properties and tags that are not specified are left unchanged.

@param [String] metric @param [Hash] body @return [true] @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/meta/metric/update.md for details

# File lib/atsd/client.rb, line 281
def metrics_update(metric, body)
  @connection.patch "metrics/#{CGI.escape(metric)}", body
  true
end
properties_delete(properties) click to toggle source

Delete an array of properties for entity, type, and optionally for specified keys

@param [Hash, Array<Hash>] properties @return true @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/data/properties/delete.md for details

# File lib/atsd/client.rb, line 185
def properties_delete(properties)
  @connection.post 'properties/delete', Utils.ensure_array(properties)
end
properties_for_entity(entity) click to toggle source

Returns array of property types for the entity.

@param [String] entity @return [Array<Hash>] array of properties @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/data/properties/type-query.md for details

# File lib/atsd/client.rb, line 163
def properties_for_entity(entity)
  response = @connection.get "properties/#{CGI.escape(entity)}/types"
  response.body
end
properties_for_entity_and_type(entity, type) click to toggle source

Returns properties for entity and type.

@param [String] entity @param [String] type @return [Array<Hash>] array of properties @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/data/properties/url-query.md for details

# File lib/atsd/client.rb, line 152
def properties_for_entity_and_type(entity, type)
  response = @connection.get "properties/#{CGI.escape(entity)}/types/#{CGI.escape(type)}"
  response.body
end
properties_insert(properties) click to toggle source

Insert properties

@param [Hash, Array<Hash>] properties property or array of properties @return true @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/data/properties/insert.md for details

# File lib/atsd/client.rb, line 174
def properties_insert(properties)
  @connection.post 'properties/insert', Utils.ensure_array(properties)
  true
end
properties_query(queries = nil) click to toggle source

Query properties

@param [Hash, Array<Hash>] queries query or array of queries @return [Array<Hash>] array of properties @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/data/properties/query.md for details

# File lib/atsd/client.rb, line 140
def properties_query(queries = nil)
  response = @connection.post 'properties/query', Utils.ensure_array(queries)
  response.body
end
series_csv_insert(entity, data, tags = {}) click to toggle source

Series CSV: Insert

@param [String] entity @param [String] data Payload - CSV containing time column and one or multiple metric columns.

- Separator must be comma.
- Time must be specified in Unix milliseconds.
- Time column must be first, name of the time column could be arbitrary.

@param [Hash] tags tag=value hash @return [true] @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/data/series/csv-insert.md for details

# File lib/atsd/client.rb, line 89
def series_csv_insert(entity, data, tags = {})
  request = @connection.build_request(:post) do |req|
    req.url("series/csv/#{CGI.escape(entity)}", tags)
    req.headers["Content-Type"] = 'text/csv'
    req.body = data
  end

  @connection.builder.build_response(@connection, request)
  true
end
series_insert(series) click to toggle source

Insert time series

@param [Hash, Array<Hash>] series series or array of series @return true @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/data/series/insert.md for details

# File lib/atsd/client.rb, line 73
def series_insert(series)
  @connection.post 'series/insert', Utils.ensure_array(series)
  true
end
series_query(queries) click to toggle source

Query time series

@param [Hash, Array<Hash>] queries query or array of queries @return [Array<Hash>] time series @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/data/series/query.md for details

# File lib/atsd/client.rb, line 47
def series_query(queries)
  response = @connection.post 'series/query', Utils.ensure_array(queries)
  response.body
end
series_url_query(format, entity, metric, parameters ={}) click to toggle source

Retrieve series values for the specified entity, metric, and optional series tags in CSV and JSON format

@param [String] format @param [String] entity @param [String] metric @param [Hash] parameters other query parameters @return [Array<Hash>] time series @raise [APIError] @see github.com/axibase/atsd-docs/blob/master/api/data/series/url-query.md for details

# File lib/atsd/client.rb, line 61
def series_url_query(format, entity, metric, parameters ={})
  url = "series/#{CGI.escape(format)}/#{CGI.escape(entity)}/#{CGI.escape(metric)}?"
  response = @connection.get url, parameters
  response.body
end

Private Instance Methods

extract_basic_auth(options) click to toggle source
# File lib/atsd/client.rb, line 518
def extract_basic_auth(options)
  auth = options.delete :basic_auth
  case auth
    when String
      auth.split(':', 2)
    when Hash
      return auth[:login], auth[:password]
    else
      raise ArgumentError, 'Bad login/password specification'
  end
end
extract_logger(options) click to toggle source
# File lib/atsd/client.rb, line 530
def extract_logger(options)
  logger = options.delete :logger
  case logger
    when true
      require 'logger'
      ::Logger.new(STDOUT)
    when false
      nil
    else
      logger
  end
end