fredfeng033/vortex-tsdb repository overview

⁠Vortex TSDB

Lightweight. Replicated. Real-time.

A lightweight distributed time series database for real-time metrics. Write numeric samples over HTTP; read per-minute aggregates (count, highest, lowest, total, average), the latest value of every series, and tumbling or sliding windows over any range. Every node holds a full replica in memory; the nodes elect a leader, replicate and snapshot by themselves.

⁠Tags

⁠Quick start: a 3-node cluster

The compose file starts 3 nodes, the web console and a Traefik gateway:

curl -fsSLO https://raw.githubusercontent.com/paganini2008/vortex/main/deploy/docker-compose.yml
docker compose up -d

curl -X POST 'http://localhost:9080/tsd/push?t=long&c=car&d=speed&v=44'
curl 'http://localhost:9080/tsd/last?t=long&c=car&d=speed'
# {"code":1,"msg":"ok","data":{"value":44,"timestamp":1791176481490}, ...}
curl 'http://localhost:9080/tsd/query?t=long&c=car&d=speed&range=6h&step=5&window=15'

docker compose down keeps the data in volumes; docker compose down -v deletes it.

⁠Using your own Redis (optional)

Each node keeps at most VORTEX_CACHE_MAX_KEYS keys (10,000 by default) in memory. Without Redis the least recently used beyond that are deleted; with Redis they move there and are read back on demand (only the leader writes to Redis). No Redis is started for you.

With the compose file, set them in the environment or in a .env file beside it:

# Redis on the Docker host. host.docker.internal works on Docker Desktop, Rancher Desktop and
# OrbStack; on Linux, uncomment extra_hosts in the compose file first
VORTEX_REDIS_HOST=host.docker.internal VORTEX_REDIS_PASSWORD=secret docker compose up -d

# Or any reachable Redis, with more keys kept in memory
cat > .env <<EOF
VORTEX_REDIS_HOST=redis.internal.example
VORTEX_REDIS_PASSWORD=secret
VORTEX_CACHE_MAX_KEYS=50000
EOF
docker compose up -d

Reading a key that moved to Redis costs a network round trip, so size VORTEX_CACHE_MAX_KEYS to keep the series you query in memory. One series at 1-minute buckets and 24-hour retention is up to 1,440 keys.

⁠A single node

docker run -d --name vortex-tsdb -p 30080:30080 -v vortex-data:/data fredfeng033/vortex-tsdb
curl 'http://localhost:30080/tsd/cluster'

⁠Running a cluster yourself

Each node needs to know where its peers are and the address they reach it at:

Give each node a fixed address (the compose file uses a subnet with static IPs). Membership is fixed at start: to change the number of nodes, restart all of them.

⁠Configuration

⁠Ports, volumes and health

⁠Limits

• Writes are serialised on the leader: about 1,000 samples/s sustained, 1,500 at peak (4 CPUs).
• Data lives in memory; if every node is killed at once, data after the last snapshot is lost.
• Writes in flight when the leader crashes fail and should be retried by the client.
• No query language, alerting or authentication: put it behind your own network controls.