Home

Awesome

Release CircleCI Dockerhub codecov

RedisTimeSeries

Forum Discord

<img src="docs/docs/images/logo.svg" alt="logo" width="300"/>

RedisTimeSeries is a time-series database (TSDB) module for Redis, by Redis.

RedisTimeSeries can hold multiple time series. Each time series is accessible via a single Redis key (similar to any other Redis data structure).

What is a Redis time series?

A Redis time series comprises:

How do I Redis?

Learn for free at Redis University

Build faster with the Redis Launchpad

Try the Redis Cloud

Dive in developer tutorials

Join the Redis community

Work at Redis

Examples of time series

Features

Using with other tools metrics tools

In the RedisTimeSeries organization you can find projects that help you integrate RedisTimeSeries with other tools, including:

  1. Prometheus - read/write adapter to use RedisTimeSeries as backend db.
  2. Grafana - using the Redis Data Source.
  3. Telegraf
  4. StatsD, Graphite exports using graphite protocol.

RedisTimeSeries is part of Redis Stack.

Setup

You can either get RedisTimeSeries setup in a Docker container or on your own machine.

Docker

To quickly try out RedisTimeSeries, launch an instance using docker:

docker run -p 6379:6379 -it --rm redis/redis-stack-server:latest

Build it yourself

You can also build RedisTimeSeries on your own machine. Major Linux distributions as well as macOS are supported.

First step is to have Redis installed, of course. The following, for example, builds Redis on a clean Ubuntu docker image (docker pull ubuntu) or a clean Debian docker image (docker pull debian:stable):

mkdir ~/Redis
cd ~/Redis
apt-get update -y && apt-get upgrade -y
apt-get install -y wget make pkg-config build-essential
wget https://download.redis.io/redis-stable.tar.gz
tar -xzvf redis-stable.tar.gz
cd redis-stable
make distclean
make
make install

Next, you should get the RedisTimeSeries repository from git and build it:

apt-get install -y git
cd ~/Redis
git clone --recursive https://github.com/RedisTimeSeries/RedisTimeSeries.git
cd RedisTimeSeries
# If you forgot to clone the repo with submodules, you can fix it by running the following command
# git submodule update --init --recursive
./sbin/setup
bash -l
make

Then exit to exit bash.

Note: to get a specific version of RedisTimeSeries, e.g. 1.8.10, add -b v1.8.10 to the git clone command above.

Next, run make run -n and copy the full path of the RedisTimeSeries executable (e.g., /root/Redis/RedisTimeSeries/bin/linux-x64-release/redistimeseries.so).

Next, add RedisTimeSeries module to redis.conf, so Redis will load when started:

apt-get install -y vim
cd ~/Redis/redis-stable
vim redis.conf

Add: loadmodule /root/Redis/RedisTimeSeries/bin/linux-x64-release/redistimeseries.so under the MODULES section (use the full path copied above).

Save and exit vim (ESC :wq ENTER)

For more information about modules, go to the Redis official documentation.

Run

Run redis-server in the background and then redis-cli:

cd ~/Redis/redis-stable
redis-server redis.conf &
redis-cli

Give it a try

After you setup RedisTimeSeries, you can interact with it using redis-cli.

Here we'll create a time series representing sensor temperature measurements. After you create the time series, you can send temperature measurements. Then you can query the data for a time range on some aggregation rule.

With redis-cli

$ redis-cli
127.0.0.1:6379> TS.CREATE temperature:3:11 RETENTION 60 LABELS sensor_id 2 area_id 32
OK
127.0.0.1:6379> TS.ADD temperature:3:11 1548149181 30
OK
127.0.0.1:6379> TS.ADD temperature:3:11 1548149191 42
OK
127.0.0.1:6379>  TS.RANGE temperature:3:11 1548149180 1548149210 AGGREGATION avg 5
1) 1) (integer) 1548149180
   2) "30"
2) 1) (integer) 1548149190
   2) "42"

Client libraries

Some languages have client libraries that provide support for RedisTimeSeries commands:

ProjectLanguageLicenseAuthorStarsPackageComment
jedisJavaMITRedisStarsMaven
redis-pyPythonMITRedisStarspypi
node-redisNode.jsMITRedisStarsnpm
nredisstack.NETMITRedisStarsnuget
redistimeseries-goGoApache-2Redisredistimeseries-go-starsGitHub
rueidisGoApache-2Rueianrueidis-starsGitHub
phpRedisTimeSeriesPHPMITAlessandro BalascophpRedisTimeSeries-starsGitHub
redis-time-seriesJavaScriptMITRafa Campoyredis-time-series-starsGitHub
redistimeseries-jsJavaScriptMITMilos Nikolovskiredistimeseries-js-starsGitHub
redis_tsRustBSD-3Thomas Profeltredis_ts-starsGitHub
redistimeseriesRubyMITEaden McKeeredistimeseries-starsGitHub
redis-time-seriesRubyMITMatt Duszynskiredis-time-series-rb-starsGitHub

Tests

The module includes a basic set of unit tests and integration tests.

Unit tests

To run all unit tests, follow these steps:

$ make unit_tests

Integration tests

Integration tests are based on RLTest, and specific setup parameters can be provided to configure tests. By default the tests will be ran for all common commands, and with variation of persistency and replication.

To run all integration tests in a Python virtualenv, follow these steps:

$ mkdir -p .env
$ virtualenv .env
$ source .env/bin/activate
$ pip install -r tests/flow/requirements.txt
$ make test

To understand what test options are available simply run:

$ make help

For example, to run the tests strictly desigined for TS.ADD command, follow these steps:

$ make test TEST=test_ts_add.py

Documentation

Read the docs at http://redistimeseries.io

Mailing List / Forum

Got questions? Feel free to ask at the RedisTimeSeries forum.

License

RedisTimeSeries is licensed under the Redis Source Available License 2.0 (RSALv2) or the Server Side Public License v1 (SSPLv1).