Getting Started - palkan/influxer GitHub Wiki

Installation

Add 'influxer' to your Gemfile:

gem "influxer", "~>0.3.0"

And run bundle install.

Configuration

Influxer uses anyway_config to load configuration. You can set config params:

in a separate config file

# <Rails root>/config/influxdb.yml
development:
  username: root
  password: root
production:
 ...
test:
 ...

as secrets.yml entry for influxdb

# secrets.yml
production:
  ...
  influxdb:
    password: 123456
...

from env variables

INFLUXDB_USER=root INFLUXDB_PASSWORD=root rails s

or using

Influxer.configure do |config|
... 
end

Configuration parameters

See defaults and full list of parameters here.

Basic configuration:

# database name
database: 'db'
# influxdb api endpoint
host: 'localhost'
port: 8083

# influxdb user name and password (plain)
# Please, beware of using root user as API user in production
username: root
password: root

Time Precision

By default, Influxer uses 'ns' precision.

NOTE: if you want to use other precision than 'ns', 'ms' or 's', you should convert Time-like values yourself (into epoch_time, i.e. numeric values).

For InfluxDB >= 1.3 you can specify config.time_duration_suffix_enabled = true to make Influxer use timestamp values with suffixes (i.e. time > 1420070400000000000ns).

Read'n'write

To start working with InfluxDB data you should create metrics class.

class MyMetrics < Influxer::Metrics
  # set series name (string or regexp)
  set_series :data
end

MyMetrics.all #=> select * from data

You can pass several series to 'set_series'

class MyMetrics < Influxer::Metrics
  set_series :data_1, :data_2
end

MyMetrics.all #=> select * from merge(data_1,data_2)

You can even set series name as a Proc (but it make sense only in case of integrating with ActiveRecord).

Write data points

Before you can write data points to InfluxDB you should add attributes and (optionally) tags to your class.

class MyMetrics < Influxer::Metrics
  set_series :data
  # generates getters/setters for tags and store tag names as `MyMetrics.tag_names` 
  tags :user_id, :server
  # generates getters/setters for attributes
  attributes :load_time
end

Now you can build and write points. Moreover, Influxer::Metrics include ActiveModel validations and callbacks (only for write method, i.e. before_write, after_write).

class MyMetrics < Influxer::Metrics
  set_series :data
  tags :user_id, :server
  attributes :load_time

  validates :load_time, :server, presence: true

  before_write :normalize_load_time

  def normalize_load_time
    self.load_time = self.load_time.round(2)
  end
end

# build point (but not write to db)
point = MyMetrics.new user_id: 1, load_time: 123, server: 'eu'
point.user_id #=> 1
point.load_time = 100 #=> 100

# you can access tags and values separately
point.tags #=> { server: 'eu', user_id: 1 }
point.values #=> { load_time: 123 }

# and then you can write your data
point.write #=> returns point

# you can write point only once
point.write! #=> raise Influxer::MetricsError

# you can write data without build
MyMetrics.write(user_id: 1, load_time: 200, server: 'eu') #=> returns new point

point2 = MyMetrics.build user_id: 1, load_time: 0
point2.write! #=> raise Influxer::MetricsInvalid 

point2.load_time = 33.333333
point2.write

point2.load_time #=> 33.4

Read data

Once you have metrics you can query data.