README
¶
SquirrelDB
SquirrelDB is a scalable and highly available timeseries database (TSDB) compatible with Prometheus remote storage. Timeseries are stored in Cassandra to provide scalability and availability.
Features
- Time Series Database with Prometheus Long Term Storage
- Support pre-aggregation of data for faster read
- Rely on Cassandra, well known and reliable NoSQL database
- Support single node and cluster architectures
- Expose PromQL, remote read and write Prometheus endpoints
High Availability
SquirrelDB allows both availability and scalability:
- The long term storage availability and scalability is done by a Cassandra cluster by using a replication level > 1 (3 is recommended).
- The short term storage (by default last 15 minutes) is stored in-memory by default and can be configured to be stored in Redis. A Redis cluster will provide availability and scalability of short term storage.
- When short term storage is provided by Redis, SquirrelDB instance are stateless, scaling them is just adding more of them behind a load-balancer (like nginx).
Check out examples/squirreldb-ha for a highly available setup.
Quickstart
You can run SquirrelDB easily with Cassandra, Prometheus, Grafana and Node Exporter using the provided docker-compose:
docker compose up -d
Then go to the Grafana dashboard at http://localhost:3000/d/83ceCuenk/, and log in with the user "admin" and the password "password". You may need to wait a few minutes to see the graphs, because Cassandra starts slowly.
Single node installation
Cassandra
Cassandra must be running before starting SquirrelDB. If you don't have Cassandra, you can run it with Docker:
# The network is needed only if you run SquirrelDB with Docker.
docker network create squirreldb
docker run -d --name squirreldb-cassandra -p 127.0.0.1:9042:9042 \
--net squirreldb -e MAX_HEAP_SIZE=128M -e HEAP_NEWSIZE=24M cassandra
Binary
You can run SquirrelDB as a binary using the latest Github release for your platform at https://github.com/bleemeo/squirreldb/releases.
Docker
You can use docker to run SquirrelDB:
docker run -d --name squirreldb -p 127.0.0.1:9201:9201 \
--net squirreldb -e SQUIRRELDB_CASSANDRA_ADDRESSES=squirreldb-cassandra:9042 \
bleemeo/squirreldb
Configuration
The file squirreldb.conf contains all available configuration options. This file must be placed in the same directory as the SquirrelDB binary.
All configuration options can be overriden by environment variables. The environment variable is
- Prefixed by
SQUIRRELDB_ - All letters are converted to uppercase
- Each yaml indentation is converted to an underscore
For example, cassandra.addresses becomes SQUIRRELDB_CASSANDRA_ADDRESSES.
Contributing
See CONTRIBUTING.md.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
requestscoped
Package requestscoped implements features that rely on HTTP request headers, like applying tenant limitation, per-request limit of evaluated points/series, ...
|
Package requestscoped implements features that rely on HTTP request headers, like applying tenant limitation, per-request limit of evaluated points/series, ... |
|
appendable
|
|
|
Package batch will group points in batch to send multiple consecutive points of the same metrics to TSDB.
|
Package batch will group points in batch to send multiple consecutive points of the same metrics to TSDB. |
|
cassandra
|
|
|
mutable
Package mutable provides the Cassandra-backed implementation of the mutable label store (mutable.Store).
|
Package mutable provides the Cassandra-backed implementation of the mutable label store (mutable.Store). |
|
telemetrystore
Package telemetrystore implements the telemetry.Store backed by a types.State (for the values) and distributed locks (for ownership).
|
Package telemetrystore implements the telemetry.Store backed by a types.State (for the values) and distributed locks (for ownership). |
|
clickhouse
|
|
|
backend
Package backend owns the single ClickHouse connection shared by every ClickHouse-backed store (TSDB, mutable labels, telemetry), mirroring cassandra/backend.
|
Package backend owns the single ClickHouse connection shared by every ClickHouse-backed store (TSDB, mutable labels, telemetry), mirroring cassandra/backend. |
|
ddl
Package ddl helps the ClickHouse stores produce cluster-aware DDL from a single template, so the same schema works on a single node and on a cluster.
|
Package ddl helps the ClickHouse stores produce cluster-aware DDL from a single template, so the same schema works on a single node and on a cluster. |
|
mutable
Package mutable provides the ClickHouse-backed implementation of the mutable label store (mutable.Store).
|
Package mutable provides the ClickHouse-backed implementation of the mutable label store (mutable.Store). |
|
routing
Package routing provides a clickhouse-go driver.Conn that owns one underlying connection per host and routes every call to a healthy host.
|
Package routing provides a clickhouse-go driver.Conn that owns one underlying connection per host and routes every call to a healthy host. |
|
state
Package state provides a small, generic key/value store backed by ClickHouse.
|
Package state provides a small, generic key/value store backed by ClickHouse. |
|
telemetrystore
Package telemetrystore implements the ClickHouse-backed telemetry.Store: the shared cluster ID and a pool of per-node IDs with a crash-tolerant ownership lease.
|
Package telemetrystore implements the ClickHouse-backed telemetry.Store: the shared cluster ID and a pool of per-node IDs with a crash-tolerant ownership lease. |
|
tsdb
Package tsdb implements a SquirrelDB TSDB backend backed by ClickHouse.
|
Package tsdb implements a SquirrelDB TSDB backend backed by ClickHouse. |
|
cmd
|
|
|
import-data
command
|
|
|
prom-remote-storage-to-parquet
command
|
|
|
squirreldb-debug-tools
command
|
|
|
sstable-data-content
command
|
|
|
Package core is the storage glue of SquirrelDB: from the configured backends it composes the data-plane accessors (read, write, dual-write) that the API, the migration tool and the tests consume.
|
Package core is the storage glue of SquirrelDB: from the configured backends it composes the data-plane accessors (read, write, dual-write) that the API, the migration tool and the tests consume. |
|
processsetup
Package processsetup contains utility function to initialize & setup a SquirrelDB process
|
Package processsetup contains utility function to initialize & setup a SquirrelDB process |
|
version
Package version is just here to old few globals set during build
|
Package version is just here to old few globals set during build |
|
Package daemon contains startup function of SquirrelDB
|
Package daemon contains startup function of SquirrelDB |
|
backend
Package backend implements the "dummy" storage backend: it discards every write and serves empty reads, with no external dependency.
|
Package backend implements the "dummy" storage backend: it discards every write and serves empty reads, with no external dependency. |
|
Package export defines a backend-agnostic way to stream a TSDB's raw data out, one series-chunk at a time, with a resumable position.
|
Package export defines a backend-agnostic way to stream a TSDB's raw data out, one series-chunk at a time, with a resumable position. |
|
Package migration copies raw time series data out of one SquirrelDB backend (the source, Config.Backend) into another (the target, Config.ExtraWriteBackend) — the Cassandra→ClickHouse migration.
|
Package migration copies raw time series data out of one SquirrelDB backend (the source, Config.Backend) into another (the target, Config.ExtraWriteBackend) — the Cassandra→ClickHouse migration. |
|
Package mutable handles mutable labels.
|
Package mutable handles mutable labels. |
|
queryable
|
|
|
redis
|
|
|
tests
|
|
|
common/testcases
Package testcases provides shared test cases for backends implementations (Appender, Queryable, ...).
|
Package testcases provides shared test cases for backends implementations (Appender, Queryable, ...). |
|
remote-storage-bench
command
This produce a remote write generator.
|
This produce a remote write generator. |
|
remote-storage-test
command
|
|
|
remote-storage-test2
command
|
|
|
run-test-cases
command
|
|
|
squirreldb-cassandra-index-bench
command
|
|
|
squirreldb-cassandra-index-bench2
command
This benchmark is mostly used to test shard transition issue: * Our postings are shared by time, with each shard being 7 days long.
|
This benchmark is mostly used to test shard transition issue: * Our postings are shared by time, with each shard being 7 days long. |
|
squirreldb-cassandra-lock-bench
command
|
|
|
squirreldb-cluster-redis
command
|
|
|
squirreldb-promql-aggregate
command
|
|
|
squirreldb-promql-bench
command
|
|
|
squirreldb-telemetry
command
Command squirreldb-telemetry exercises backend.TelemetryStore() end-to-end, against whichever backend is configured (Cassandra or ClickHouse; it skips on the dummy backend).
|
Command squirreldb-telemetry exercises backend.TelemetryStore() end-to-end, against whichever backend is configured (Cassandra or ClickHouse; it skips on the dummy backend). |
|
wait-stores
command
|
|
Click to show internal directories.
Click to hide internal directories.