RedisTimeSeries
A Ruby adapter for the RedisTimeSeries module.
This doesn't work with vanilla Redis, you need the time series module compiled and installed. Try it with Docker, and see the module setup guide for additional options.
docker run -p 6379:6379 -it --rm redislabs/redistimeseries
TL;DR
require 'redis-time-series'
ts = Redis::TimeSeries.new('foo')
ts.add 1234
=> #<Redis::TimeSeries::Sample:0x00007f8c0d2561d8 @time=2020-06-25 23:23:04 -0700, @value=0.1234e4>
ts.add 56
=> #<Redis::TimeSeries::Sample:0x00007f8c0d26c460 @time=2020-06-25 23:23:16 -0700, @value=0.56e2>
ts.add 78
=> #<Redis::TimeSeries::Sample:0x00007f8c0d276618 @time=2020-06-25 23:23:20 -0700, @value=0.78e2>
ts.range (Time.now.to_i - 100)..Time.now.to_i * 1000
=> [#<Redis::TimeSeries::Sample:0x00007f8c0d297200 @time=2020-06-25 23:23:04 -0700, @value=0.1234e4>,
#<Redis::TimeSeries::Sample:0x00007f8c0d297048 @time=2020-06-25 23:23:16 -0700, @value=0.56e2>,
#<Redis::TimeSeries::Sample:0x00007f8c0d296e90 @time=2020-06-25 23:23:20 -0700, @value=0.78e2>]
Installation
Add this line to your application's Gemfile:
gem 'redis-time-series'
And then execute:
$ bundle
Or install it yourself as:
$ gem install redis-time-series
Usage
Check out the Redis Time Series command documentation first. Should be able to do most of that.
Configuring
You can set the default Redis client for class-level calls operating on multiple series, as well as series created without specifying a client.
Redis::TimeSeries.redis = Redis.new(url: ENV['REDIS_URL'], timeout: 1)
Creating a Series
Create a series (issues TS.CREATE command) and return a Redis::TimeSeries object for further use. Key param is required, all other arguments are optional.
ts = Redis::TimeSeries.create(
'your_ts_key',
labels: { foo: 'bar' },
retention: 600,
uncompressed: false,
redis: Redis.new(url: ENV['REDIS_URL']) # defaults to Redis::TimeSeries.redis
)
You can also call .new instead of .create to skip the TS.CREATE command.
ts = Redis::TimeSeries.new('your_ts_key')
Adding Data to a Series
Add a single value
ts.add 1234
=> #<Redis::TimeSeries::Sample:0x00007f8c0ea7edc8 @time=2020-06-25 23:41:29 -0700, @value=0.1234e4>
Add a single value with a timestamp
ts.add 1234, 3.minutes.ago # Used ActiveSupport here, but any Time object works fine
=> #<Redis::TimeSeries::Sample:0x00007fa6ce05f3f8 @time=2020-06-25 23:39:54 -0700, @value=0.1234e4>
# Optionally store data uncompressed
ts.add 5678, uncompressed: true
=> #<Redis::TimeSeries::Sample:0x00007f93f43cdf68 @time=2020-07-18 23:15:29 -0700, @value=0.5678e4>
Add multiple values with timestamps
ts.madd(2.minutes.ago => 12, 1.minute.ago => 34, Time.now => 56)
=> [1593153909466, 1593153969466, 1593154029466]
Increment or decrement the most recent value
ts.incrby 2
=> 1593154222877
ts.decrby 1
=> 1593154251392
ts.increment # alias of incrby
=> 1593154255069
ts.decrement # alias of decrby
=> 1593154257344
# Optionally store data uncompressed
ts.incrby 4, uncompressed: true
=> 1595139299769
ts.get
=> #<Redis::TimeSeries::Sample:0x00007fa25f17ed88 @time=2020-06-25 23:50:57 -0700, @value=0.57e2>
ts.increment
=> 1593154290736
ts.get
=> #<Redis::TimeSeries::Sample:0x00007fa25f199480 @time=2020-06-25 23:51:30 -0700, @value=0.58e2>
Add values to multiple series
# Without timestamp (series named "foo" and "bar")
Redis::TimeSeries.madd(foo: 1234, bar: 5678)
=> [#<Redis::TimeSeries::Sample:0x00007ffb3aa32ae0 @time=2020-06-26 00:09:15 -0700, @value=0.1234e4>,
#<Redis::TimeSeries::Sample:0x00007ffb3aa326d0 @time=2020-06-26 00:09:15 -0700, @value=0.5678e4>]
# With a timestamp
Redis::TimeSeries.madd(foo: { 1.minute.ago => 1234 }, bar: { 1.minute.ago => 2345 })
=> [#<Redis::TimeSeries::Sample:0x00007fb102431f88 @time=2020-06-26 00:10:22 -0700, @value=0.1234e4>,
#<Redis::TimeSeries::Sample:0x00007fb102431d80 @time=2020-06-26 00:10:22 -0700, @value=0.2345e4>]
Querying a Series
Get the most recent value
ts.get
=> #<Redis::TimeSeries::Sample:0x00007fa25f1b78b8 @time=2020-06-25 23:51:30 -0700, @value=0.58e2>
Get a range of values
# Time range as an argument
ts.range(10.minutes.ago..Time.current)
=> [#<Redis::TimeSeries::Sample:0x00007fa25f13fc28 @time=2020-06-25 23:50:51 -0700, @value=0.57e2>,
#<Redis::TimeSeries::Sample:0x00007fa25f13db58 @time=2020-06-25 23:50:55 -0700, @value=0.58e2>,
#<Redis::TimeSeries::Sample:0x00007fa25f13d900 @time=2020-06-25 23:50:57 -0700, @value=0.57e2>,
#<Redis::TimeSeries::Sample:0x00007fa25f13d680 @time=2020-06-25 23:51:30 -0700, @value=0.58e2>]
# Time range as keyword args
ts.range(from: 10.minutes.ago, to: Time.current)
=> [#<Redis::TimeSeries::Sample:0x00007fa25dc01f00 @time=2020-06-25 23:50:51 -0700, @value=0.57e2>,
#<Redis::TimeSeries::Sample:0x00007fa25dc01d20 @time=2020-06-25 23:50:55 -0700, @value=0.58e2>,
#<Redis::TimeSeries::Sample:0x00007fa25dc01b68 @time=2020-06-25 23:50:57 -0700, @value=0.57e2>,
#<Redis::TimeSeries::Sample:0x00007fa25dc019b0 @time=2020-06-25 23:51:30 -0700, @value=0.58e2>]
# Limit number of results with count argument
ts.range(10.minutes.ago..Time.current, count: 2)
=> [#<Redis::TimeSeries::Sample:0x00007fa25dc01f00 @time=2020-06-25 23:50:51 -0700, @value=0.57e2>,
#<Redis::TimeSeries::Sample:0x00007fa25dc01d20 @time=2020-06-25 23:50:55 -0700, @value=0.58e2>]
# Apply aggregations to the range
ts.range(from: 10.minutes.ago, to: Time.current, aggregation: [:avg, 10.minutes])
=> [#<Redis::TimeSeries::Sample:0x00007fa25dc01f00 @time=2020-06-25 23:50:00 -0700, @value=0.575e2>]
Get info about the series
ts.info
=> #<struct Redis::TimeSeries::Info
series=
#<Redis::TimeSeries:0x00007ff46da9b578 @key="ts3", @redis=#<Redis client v4.2.1 for redis://127.0.0.1:6379/0>>,
total_samples=3,
memory_usage=4264,
first_timestamp=1595187993605,
last_timestamp=1595187993629,
retention_time=0,
chunk_count=1,
max_samples_per_chunk=256,
labels={"foo"=>"bar"},
source_key=nil,
rules=
[#<Redis::TimeSeries::Rule:0x00007ff46db30c68
@aggregation=#<Redis::TimeSeries::Aggregation:0x00007ff46db30c18 @duration=3600000, @type="avg">,
@destination_key="ts1",
@source=
#<Redis::TimeSeries:0x00007ff46da9b578
@key="ts3",
@redis=#<Redis client v4.2.1 for redis://127.0.0.1:6379/0>>>]>
# Each info property is also a method on the time series object
ts.memory_usage
=> 4208
ts.labels
=> {"foo"=>"bar"}
ts.total_samples
=> 3
# Total samples also available as #count, #length, and #size
ts.count
=> 3
ts.length
=> 3
ts.size
=> 3
Find series matching specific label(s)
Redis::TimeSeries.query_index('foo=bar')
=> [#<Redis::TimeSeries:0x00007fc115ba1610
@key="ts3",
@redis=#<Redis client v4.2.1 for redis://127.0.0.1:6379/0>,
@retention=nil,
@uncompressed=false>]
# Note that you need at least one "label equals value" filter
Redis::TimeSeries.query_index('foo!=bar')
=> RuntimeError: Filtering requires at least one equality comparison
# query_index is also aliased as .where for fluency
Redis::TimeSeries.where('foo=bar')
=> [#<Redis::TimeSeries:0x00007fb8981010c8
@key="ts3",
@redis=#<Redis client v4.2.1 for redis://127.0.0.1:6379/0>,
@retention=nil,
@uncompressed=false>]
Querying Multiple Series
Get all samples from matching series over a time range with mrange
[4] pry(main)> result = Redis::TimeSeries.mrange(1.minute.ago.., filter: { foo: 'bar' })
=> [#<struct Redis::TimeSeries::Multi::Result
series=
#<Redis::TimeSeries:0x00007f833e408ad0
@key="ts3",
@redis=#<Redis client v4.2.5 for redis://127.0.0.1:6379/0>>,
labels=[],
samples=
[#<Redis::TimeSeries::Sample:0x00007f833e408a58
@time=2021-06-17 20:58:33 3246391/4194304 -0700,
@value=0.1e1>,
#<Redis::TimeSeries::Sample:0x00007f833e408850
@time=2021-06-17 20:58:33 413139/524288 -0700,
@value=0.3e1>,
#<Redis::TimeSeries::Sample:0x00007f833e408670
@time=2021-06-17 20:58:33 1679819/2097152 -0700,
@value=0.2e1>]>]
[5] pry(main)> result.keys
=> ["ts3"]
[6] pry(main)> result['ts3'].values
=> [0.1e1, 0.3e1, 0.2e1]
Order them from newest to oldest with mrevrange
[8] pry(main)> Redis::TimeSeries.mrevrange(1.minute.ago.., filter: { foo: 'bar' }).first.values
=> [0.2e1, 0.3e1, 0.1e1]
Filter DSL
You can provide filter strings directly, per the time series documentation.
Redis::TimeSeries.where('foo=bar')
=> [#<Redis::TimeSeries:0x00007fb8981010c8...>]
There is also a hash-based syntax available, which may be more pleasant to work with.
Redis::TimeSeries.where(foo: 'bar')
=> [#<Redis::TimeSeries:0x00007fb89811dca0...>]
All six filter types are represented in hash format below.
{
foo: 'bar', # label=value (equality)
foo: { not: 'bar' }, # label!=value (inequality)
foo: true, # label= (presence)
foo: false, # label!= (absence)
foo: [1, 2], # label=(1,2) (any value)
foo: { not: [1, 2] } # label!=(1,2) (no values)
}
Note the special use of true and false. If you're representing a boolean value with a label, rather than setting its value to "true" or "false" (which would be treated as strings in Redis anyway), you should add or remove the label from the series.
Values can be any object that responds to .to_s:
class Person
def initialize(name)
@name = name
end
def to_s
@name
end
end
Redis::TimeSeries.where(person: Person.new('John'))
#=> TS.QUERYINDEX person=John
Compaction Rules
Add a compaction rule to a series.
# Destintation time series needs to be created before the rule is added.
other_ts = Redis::TimeSeries.create('other_ts')
# Aggregation buckets are measured in milliseconds
ts.create_rule(dest: other_ts, aggregation: [:count, 60000]) # 1 minute
# Can provide a string key instead of a time series object
ts.create_rule(dest: 'other_ts', aggregation: [:avg, 120000])
# If you're using Rails or ActiveSupport, you can provide an
# ActiveSupport::Duration instead of an integer
ts.create_rule(dest: other_ts, aggregation: [:avg, 2.minutes])
# Can also provide an Aggregation object instead of an array
agg = Redis::TimeSeries::Aggregation.new(:avg, 120000)
ts.create_rule(dest: other_ts, aggregation: agg)
# Class-level method also available
Redis::TimeSeries.create_rule(source: ts, dest: other_ts, aggregation: ['std.p', 150000])
Get existing compaction rules
ts.rules
=> [#<Redis::TimeSeries::Rule:0x00007ff46e91c728
@aggregation=#<Redis::TimeSeries::Aggregation:0x00007ff46e91c6d8 @duration=3600000, @type="avg">,
@destination_key="ts1",
@source=
#<Redis::TimeSeries:0x00007ff46da9b578 @key="ts3", @redis=#<Redis client v4.2.1 for redis://127.0.0.1:6379/0>>>]
# Get properties of a rule too
ts.rules.first.aggregation
=> #<Redis::TimeSeries::Aggregation:0x00007ff46d146d38 @duration=3600000, @type="avg">
ts.rules.first.destination
=> #<Redis::TimeSeries:0x00007ff46d8a3d60 @key="ts1", @redis=#<Redis client v4.2.1 for redis://127.0.0.1:6379/0>>
Remove an existing compaction rule
ts.delete_rule(dest: 'other_ts')
ts.rules.first.delete
Redis::TimeSeries.delete_rule(source: ts, dest: 'other_ts')
TODO
- Check the open issues on Github.
Development
After checking out the repo, run bin/setup. You need the docker daemon installed and running. This script will:
- Install gem dependencies
- Pull the latest
redislabs/redistimeseriesimage - Start a Redis server on port 6379
- Seed three time series with some sample data
- Attach to the running server and print logs to
STDOUT
With the above script running, or after starting a server manually, you can run bin/console to interact with it. The three series are named ts1, ts2, and ts3, and are available as instance variables in the console.
If you want to see the commands being executed, run the console with DEBUG=true bin/console and it will output the raw command strings as they're executed.
[1] pry(main)> @ts1.increment
DEBUG: TS.INCRBY ts1 1
=> 1593159795467
[2] pry(main)> @ts1.get
DEBUG: TS.GET ts1
=> #<Redis::TimeSeries::Sample:0x00007f8e1a190cf8 @time=2020-06-26 01:23:15 -0700, @value=0.4e1>
Use rake spec to run the test suite.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/dzunk/redis-time-series.
License
The gem is available as open source under the terms of the MIT License.