Redis 中文文档

RedisTimeSeries


logo

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:

Raw samples: each raw sample is a {time tag, value} pair.

Time tags are measured in milliseconds since January 1st, 1970, at 00:00:00.

Time tags can be specified by the client or filled automatically by the server.

64-bit floating-point values.

The intervals between time tags can be constant or variable.

Raw samples can be reported in-order or out-of-order.

Duplication policy for samples with identical time tags can be set: block/first/last/min/max/sum.

An optional configurable retention period.

Raw samples older than the retention period (relative to the raw sample with the highest time tag) are discarded.

Series Metadata: a set of name-value pairs (e.g., room = 3; sensorType = ‘xyz’).

RedisTimeSeries supports cross-time-series commands. One can, for example, aggregate data over all sensors in the same room or all sensors of the same type.

Zero or more compactions.

Compactions are an economical way to retain historical data.

Each compaction is defined by:

A timeframe. E.g., 10 minutes
An aggregator: min, max, sum, avg, …
An optional retention period. E.g., 10 year

For example, the following compaction: {10 minutes; avg; 10 years} will store the average of the raw values measured in each 10-minutes time frame - for 10 years.

Examples of time series


Sensor data: e.g., temperatures or fan velocity for a server in a server farm
Historical prices of a stock
Number of vehicles passing through a given road (count per 1-minute timeframes)

Features


High volume inserts, low latency reads
Query by start time and end-time
Aggregated queries (Min, Max, Avg, Sum, Range, Count, First, Last, STD.P, STD.S, Var.P, Var.S, twa) for any time bucket
Configurable maximum retention period
Compactions - automatically updated aggregated timeseries
Secondary index - each time series has labels (name-value pairs) which will allows to query by labels

Using with other tools metrics tools


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

Prometheus - read/write adapter to use RedisTimeSeries as backend db.
Grafana - using the Redis Data Source.
Telegraf
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:

  1. ``` shell
  2. docker run -p 6379:6379 -it --rm redis/redis-stack-server:latest
  3. ```

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 ):

  1. ``` sh
  2. mkdir ~/Redis
  3. cd ~/Redis
  4. apt-get update -y && apt-get upgrade -y
  5. apt-get install -y wget make pkg-config build-essential
  6. wget https://download.redis.io/redis-stable.tar.gz
  7. tar -xzvf redis-stable.tar.gz
  8. cd redis-stable
  9. make distclean
  10. make
  11. make install

  13. ```

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

  1. ``` sh
  2. apt-get install -y git
  3. cd ~/Redis
  4. git clone --recursive https://github.com/RedisTimeSeries/RedisTimeSeries.git
  5. cd RedisTimeSeries
  6. ./sbin/setup
  7. bash -l
  8. make

  10. ```

Then exit to exit bash.

Note:to get a specific version of RedisTimeSeries, e.g. 1.8.9, add -b v1.8.9 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:

  1. ``` sh
  2. apt-get install -y vim
  3. cd ~/Redis/redis-stable
  4. vim redis.conf

  6. ```

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:

  1. ``` sh
  2. cd ~/Redis/redis-stable
  3. redis-server redis.conf &
  4. redis-cli

  6. ```

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


  1. ``` shell
  2. $ redis-cli
  3. 127.0.0.1:6379> TS.CREATE temperature:3:11 RETENTION 60 LABELS sensor_id 2 area_id 32
  4. OK
  5. 127.0.0.1:6379> TS.ADD temperature:3:11 1548149181 30
  6. OK
  7. 127.0.0.1:6379> TS.ADD temperature:3:11 1548149191 42
  8. OK
  9. 127.0.0.1:6379>  TS.RANGE temperature:3:11 1548149180 1548149210 AGGREGATION avg 5
  10. 1) 1) (integer) 1548149180
  11.    2) "30"
  12. 2) 1) (integer) 1548149190
  13.    2) "42"
  14. ```

Client libraries


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

Project Language License Author Stars Package Comment
:--- :--- :--- :--- :--- :--- :---
jedis Java MIT Redis Maven
redis-py Python MIT Redis pypi
node-redis Node.js MIT Redis npm
nredisstack .NET MIT Redis nuget
redistimeseries-go Go Apache-2 Redis GitHub
rueidis Go Apache-2 Rueian GitHub
phpRedisTimeSeries PHP MIT Alessandro Balasco GitHub
redis-time-series JavaScript MIT Rafa Campoy GitHub
redistimeseries-js JavaScript MIT Milos Nikolovski GitHub
redis_ts Rust BSD-3 Thomas Profelt GitHub
redistimeseries Ruby MIT Eaden McKee GitHub
redis-time-series Ruby MIT Matt Duszynski GitHub

Tests


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

Unit tests

To run all unit tests, follow these steps:

  1. ``` sh
  2. $ make unit_tests

  4. ```

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:

  1. ``` sh
  2. $ mkdir -p .env
  3. $ virtualenv .env
  4. $ source .env/bin/activate
  5. $ pip install -r tests/flow/requirements.txt
  6. $ make test

  8. ```

To understand what test options are available simply run:

  1. ``` sh
  2. $ make help

  4. ```

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

  1. ``` sh
  2. $ make test TEST=test_ts_add.py

  4. ```

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).