Class: ATSD::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/atsd/client.rb

Overview

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

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options, &block) ⇒ Client

See ATSD.new



17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/atsd/client.rb', line 17

def initialize(options, &block)
  options = options.symbolize_keys
  , 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 , 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

Instance Attribute Details

#connection ⇒ Faraday::Connection (readonly)

Returns faraday connection object.

Returns:

  • (Faraday::Connection) —

    faraday connection object



11
12
13
 
# File 'lib/atsd/client.rb', line 11

def connection
  @connection
end

#logger ⇒ Logger (readonly)

Returns logger to use.

Returns:

  • (Logger) —

    logger to use



14
15
16
 
# File 'lib/atsd/client.rb', line 14

def logger
  @logger
end

Instance Method Details

#alerts_history_query(queries = nil) ⇒ Array<Hash>

Alerts history query

Parameters:

  • queries (Hash, Array<Hash>) (defaults to: nil) —

    query or array of queries

Returns:

  • (Array<Hash>) —

    history records

Raises:



175
176
177
178
 
# File 'lib/atsd/client.rb', line 175

def alerts_history_query(queries = nil)
  response = @connection.post 'alerts/history', :queries => Utils.ensure_array(queries)
  response.body
end

#alerts_query(queries = nil) ⇒ Array<Hash>

Query alerts

Parameters:

  • queries (Hash, Array<Hash>) (defaults to: nil) —

    query or array of queries

Returns:

  • (Array<Hash>) —

    alerts

Raises:



155
156
157
158
 
# File 'lib/atsd/client.rb', line 155

def alerts_query(queries = nil)
  response = @connection.post 'alerts', :queries => Utils.ensure_array(queries)
  response.body
end

#alerts_update(actions) ⇒ true

(De-)acknowledge and delete alerts

Parameters:

  • actions (Hash, Array<Hash>) —

    action or array of actions

Returns:

  • (true)

Raises:



165
166
167
168
 
# File 'lib/atsd/client.rb', line 165

def alerts_update(actions)
  @connection.patch 'alerts', Utils.ensure_array(actions)
  true
end

#entities_create_or_replace(entity, body) ⇒ true

Create or replace entity.

Parameters:

  • entity (String)
  • body (Hash)

Returns:

  • (true)

Raises:



278
279
280
281
 
# File 'lib/atsd/client.rb', line 278

def entities_create_or_replace(entity, body)
  @connection.put "entities/#{entity}", body
  true
end

#entities_delete(entity) ⇒ true

Delete entity.

Parameters:

  • entity (String)

Returns:

  • (true)

Raises:



299
300
301
302
 
# File 'lib/atsd/client.rb', line 299

def entities_delete(entity)
  @connection.delete "entities/#{entity}"
  true
end

#entities_get(entity) ⇒ Hash

Entity details

Parameters:

  • entity (String)

Returns:

Raises:



267
268
269
270
 
# File 'lib/atsd/client.rb', line 267

def entities_get(entity)
  response = @connection.get "entities/#{entity}"
  response.body
end

#entities_list(parameters = {}) ⇒ Array<Hash>

List of entities

Parameters:

  • parameters (Hash) (defaults to: {})

Returns:

Raises:



257
258
259
260
 
# File 'lib/atsd/client.rb', line 257

def entities_list(parameters = {})
  response = @connection.get 'entities', parameters
  response.body
end

#entities_metrics(entity, parameters = {}) ⇒ Array

Metrics for entity

Parameters:

  • entity (String)
  • parameters (Hash) (defaults to: {})

Returns:

  • (Array)

Raises:



321
322
323
324
 
# File 'lib/atsd/client.rb', line 321

def entities_metrics(entity, parameters = {})
  response = @connection.get "entities/#{entity}/metrics", parameters
  response.body
end

#entities_property_types(entity, parameters = {}) ⇒ Array

Property types for entity

Parameters:

  • entity (String)
  • parameters (Hash) (defaults to: {})

Returns:

  • (Array)

Raises:



310
311
312
313
 
# File 'lib/atsd/client.rb', line 310

def entities_property_types(entity, parameters = {})
  response = @connection.get "entities/#{entity}/property-types", parameters
  response.body
end

#entities_update(entity, body) ⇒ true

Update entity.

Parameters:

  • entity (String)
  • body (Hash)

Returns:

  • (true)

Raises:



289
290
291
292
 
# File 'lib/atsd/client.rb', line 289

def entities_update(entity, body)
  @connection.patch "entities/#{entity}", body
  true
end

#entity_groups_add_entities(entity_group, entities, parameters = {}) ⇒ true

Add entities to entity group.

Parameters:

  • entity_group (String)
  • entities (Array)
  • parameters (Hash) (defaults to: {})

Returns:

  • (true)

Raises:



396
397
398
399
400
401
402
 
# File 'lib/atsd/client.rb', line 396

def entity_groups_add_entities(entity_group, entities, parameters = {})
  @connection.patch "entity-groups/#{entity_group}/entities", [
      parameters.merge(:action => 'add',
                       :entities => entities)
  ]
  true
end

#entity_groups_create_or_replace(entity_group, body) ⇒ true

Create or replace entity group.

Parameters:

  • entity_group (String)
  • body (Hash)

Returns:

  • (true)

Raises:



352
353
354
355
 
# File 'lib/atsd/client.rb', line 352

def entity_groups_create_or_replace(entity_group, body)
  @connection.put "entity-groups/#{entity_group}", body
  true
end

#entity_groups_delete(entity_group) ⇒ true

Delete entity group.

Parameters:

  • entity_group (String)

Returns:

  • (true)

Raises:



373
374
375
376
 
# File 'lib/atsd/client.rb', line 373

def entity_groups_delete(entity_group)
  @connection.delete "entity-groups/#{entity_group}"
  true
end

#entity_groups_delete_all_entities(entity_group) ⇒ true

Delete all entities in entity group.

Parameters:

  • entity_group (String)

Returns:

  • (true)

Raises:



434
435
436
437
438
439
 
# File 'lib/atsd/client.rb', line 434

def entity_groups_delete_all_entities(entity_group)
  @connection.patch "entity-groups/#{entity_group}/entities", [
      {:action => 'delete-all'}
  ]
  true
end

#entity_groups_delete_entities(entity_group, entities) ⇒ true

Delete entities in entity group.

Parameters:

  • entity_group (String)
  • entities (Array)

Returns:

  • (true)

Raises:



422
423
424
425
426
427
 
# File 'lib/atsd/client.rb', line 422

def entity_groups_delete_entities(entity_group, entities)
  @connection.patch "entity-groups/#{entity_group}/entities", [
      {:action => 'delete', :entities => entities}
  ]
  true
end

#entity_groups_get(entity_group) ⇒ Hash

Entity group info

Parameters:

  • entity_group (String)

Returns:

Raises:



341
342
343
344
 
# File 'lib/atsd/client.rb', line 341

def entity_groups_get(entity_group)
  response = @connection.get "entity-groups/#{entity_group}"
  response.body
end

#entity_groups_get_entities(entity_group, parameters = {}) ⇒ Array

List entity group entities.

Parameters:

  • entity_group (String)
  • parameters (Hash) (defaults to: {})

Returns:

  • (Array)

Raises:



384
385
386
387
 
# File 'lib/atsd/client.rb', line 384

def entity_groups_get_entities(entity_group, parameters = {})
  response = @connection.get "entity-groups/#{entity_group}/entities", parameters
  response.body
end

#entity_groups_list(parameters = {}) ⇒ Array

Entity groups list.

Parameters:

  • parameters (Hash) (defaults to: {})

Returns:

  • (Array)

Raises:



331
332
333
334
 
# File 'lib/atsd/client.rb', line 331

def entity_groups_list(parameters = {})
  response = @connection.get 'entity-groups', parameters
  response.body
end

#entity_groups_replace_entities(entity_group, entities, parameters = {}) ⇒ true

Replace entities in entity group.

Parameters:

  • entity_group (String)
  • entities (Array)
  • parameters (Hash) (defaults to: {})

Returns:

  • (true)

Raises:



411
412
413
414
 
# File 'lib/atsd/client.rb', line 411

def entity_groups_replace_entities(entity_group, entities, parameters = {})
  @connection.put "entity-groups/#{entity_group}/entities", entities
  true
end

#entity_groups_update(entity_group, body) ⇒ true

Update entity group.

Parameters:

  • entity_group (String)
  • body (Hash)

Returns:

  • (true)

Raises:



363
364
365
366
 
# File 'lib/atsd/client.rb', line 363

def entity_groups_update(entity_group, body)
  @connection.patch "entity-groups/#{entity_group}", body
  true
end

#metrics_create_or_replace(metric, body) ⇒ true

Note:

If only a subset of fields is provided for an existing metric, the remaining properties and tags will be deleted.

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

Parameters:

  • metric (String)
  • body (Hash)

Returns:

  • (true)

Raises:



210
211
212
213
 
# File 'lib/atsd/client.rb', line 210

def metrics_create_or_replace(metric, body)
  @connection.put "metrics/#{metric}", body
  true
end

#metrics_delete(metric) ⇒ true

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

Parameters:

  • metric (String)

Returns:

  • (true)

Raises:



235
236
237
238
 
# File 'lib/atsd/client.rb', line 235

def metrics_delete(metric)
  @connection.delete "metrics/#{metric}"
  true
end

#metrics_entity_and_tags(metric, parameters = {}) ⇒ Array

Returns a list of unique series tags for the metric. The list is based on data stored on disk for the last 24 hours.

Parameters:

  • metric (String)
  • parameters (Hash) (defaults to: {})

Returns:

  • (Array)

Raises:



247
248
249
250
 
# File 'lib/atsd/client.rb', line 247

def metrics_entity_and_tags(metric, parameters = {})
  response = @connection.get "metrics/#{metric}/entity-and-tags", parameters
  response.body
end

#metrics_get(metric) ⇒ Hash

Displays metric properties and its tags.

Parameters:

  • metric (String)

Returns:

Raises:



195
196
197
198
 
# File 'lib/atsd/client.rb', line 195

def metrics_get(metric)
  response = @connection.get "metrics/#{metric}"
  response.body
end

#metrics_list(parameters = {}) ⇒ Array<Hash>

Metrics list.

Parameters:

  • parameters (Hash) (defaults to: {})

Returns:

Raises:



185
186
187
188
 
# File 'lib/atsd/client.rb', line 185

def metrics_list(parameters = {})
  response = @connection.get 'metrics', parameters
  response.body
end

#metrics_update(metric, body) ⇒ true

Note:

Properties and tags that are not specified are left unchanged.

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

Parameters:

  • metric (String)
  • body (Hash)

Returns:

  • (true)

Raises:



224
225
226
227
 
# File 'lib/atsd/client.rb', line 224

def metrics_update(metric, body)
  @connection.patch "metrics/#{metric}", body
  true
end

#properties_batch(insert, delete, delete_matchers) ⇒ Object

Insert keys and delete keys by id or by partial key match in one request.

Parameters:

  • insert (Hash, Array<Hash>) —

    properties to insert

  • delete (Hash, Array<Hash>) —

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

  • delete_matchers (Hash, Array<Hash>) —

    delete rows that partially match the specified key. ‘createdBeforeTime’ specifies an optional time condition. The server should delete all keys that have been created before the specified time. ’createdBeforeTime’ is specified in unix milliseconds.

Returns:

  • true

Raises:



123
124
125
126
127
128
129
130
 
# File 'lib/atsd/client.rb', line 123

def properties_batch(insert, delete, delete_matchers)
  @connection.patch 'properties', [
      { :action => 'insert', :properties => Utils.ensure_array(insert) },
      { :action => 'delete', :properties => Utils.ensure_array(delete) },
      { :action => 'delete-match', :matchers => Utils.ensure_array(delete_matchers) }
  ].select { |action| (action[:properties] || action[:matchers]).count > 0 }
  true
end

#properties_delete(properties) ⇒ Object

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

Parameters:

Returns:

  • true

Raises:



137
138
139
 
# File 'lib/atsd/client.rb', line 137

def properties_delete(properties)
  properties_batch [], properties, []
end

#properties_delete_match(matchers) ⇒ Object

Delete rows that partially match the specified key

Parameters:

Returns:

  • true

Raises:



146
147
148
 
# File 'lib/atsd/client.rb', line 146

def properties_delete_match(matchers)
  properties_batch [], [], matchers
end

#properties_for_entity_and_type(entity, type) ⇒ Array<Hash>

Returns properties for entity and type.

Parameters:

  • entity (String)
  • type (String)

Returns:

  • (Array<Hash>) —

    array of properties

Raises:



97
98
99
100
 
# File 'lib/atsd/client.rb', line 97

def properties_for_entity_and_type(entity, type)
  response = @connection.get "properties/#{entity}/types#{type}"
  response.body
end

#properties_insert(properties) ⇒ Object

Insert properties

Parameters:

  • properties (Hash, Array<Hash>) —

    property or array of properties

Returns:

  • true

Raises:



107
108
109
110
 
# File 'lib/atsd/client.rb', line 107

def properties_insert(properties)
  @connection.post 'properties/insert', Utils.ensure_array(properties)
  true
end

#properties_query(queries = nil) ⇒ Array<Hash>

Query properties

Parameters:

  • queries (Hash, Array<Hash>) (defaults to: nil) —

    query or array of queries

Returns:

  • (Array<Hash>) —

    array of properties

Raises:



86
87
88
89
 
# File 'lib/atsd/client.rb', line 86

def properties_query(queries = nil)
  response = @connection.post 'properties', :queries => Utils.ensure_array(queries)
  response.body
end

#series_csv_insert(entity, data, tags = {}) ⇒ true

Series CSV: Insert

Parameters:

  • entity (String)
  • data (String) —

    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.

  • tags (Hash) (defaults to: {}) —

    tag=value hash

Returns:

  • (true)

Raises:



70
71
72
73
74
75
76
77
78
79
 
# File 'lib/atsd/client.rb', line 70

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

  @connection.builder.build_response(@connection, request)
  true
end

#series_insert(series) ⇒ Object

Insert time series

Parameters:

  • series (Hash, Array<Hash>) —

    series or array of series

Returns:

  • true

Raises:



55
56
57
58
 
# File 'lib/atsd/client.rb', line 55

def series_insert(series)
  @connection.post 'series/insert', Utils.ensure_array(series)
  true
end

#series_query(queries) ⇒ Array<Hash>

Query time series

Parameters:

  • queries (Hash, Array<Hash>) —

    query or array of queries

Returns:

  • (Array<Hash>) —

    time series

Raises:



45
46
47
48
 
# File 'lib/atsd/client.rb', line 45

def series_query(queries)
  response = @connection.post 'series', :queries => Utils.ensure_array(queries)
  response.body['series']
end