SquirrelDB Configuration
The configuration is a YAML file. By default, SquirrelDB reads the file
squirreldb.conf in the current directory. You can provide another
configuration file with the flag --config /path/to/file.conf.
All configuration options can be overridden by environment variables. To find the environment variable associated to a setting, you can follow these rules:
- The 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.
The batch block configures batch writes.
For performance reasons, SquirrelDB does not write points immediately in Cassandra. SquirrelDB receive points by timestamp, usually multiple metrics for the same timestamp. But in Cassandra, it write points by metrics. One batch of points for the same metrics and multiple timestamp. To perform this conversion, SquirrelDB needs to store pending points in memory and write them to Cassandra periodically.
batch.size
Section titled “batch.size”Configure the time to keep points in memory before writing to Cassandra
Smaller value means:
- less memory usage,
- fewer points in memory (less data loss in case of crash)
- less performance
- more disk usage
Valid time units are ns, us (or µs), ms, s, m, h.
Default: 15m
cassandra
Section titled “cassandra”The cassandra block configures the Cassandra server used by SquirrelDB to
store points.
cassandra.addresses
Section titled “cassandra.addresses”List of Cassandra servers to connect to.
Default: ["localhost:9042"]
cassandra.username
Section titled “cassandra.username”Username used to connect to Cassandra. When empty, the connection is done without using credentials.
Default: ""
cassandra.password
Section titled “cassandra.password”Password used to connect to Cassandra.
Default: ""
cassandra.cert_path
Section titled “cassandra.cert_path”Path to the TLS certificate used to connect to Cassandra. Optional depending on your server configuration.
Default: ""
cassandra.key_path
Section titled “cassandra.key_path”Path to the TLS key used to connect to Cassandra. Optional depending on your server configuration.
Default: ""
cassandra.ca_path
Section titled “cassandra.ca_path”Path to the TLS certificate authority used to connect to Cassandra. Optional depending on your server configuration.
Default: ""
cassandra.enable_host_verification
Section titled “cassandra.enable_host_verification”Whether to verify the hostname and server certificate.
Default: true
cassandra.keyspace
Section titled “cassandra.keyspace”Cassandra keyspace used to create tables.
Default: squirreldb
cassandra.replication_factor
Section titled “cassandra.replication_factor”Replication factor. This must be 1 for a single server Cassandra. It should be 3 when your Cassandra cluster contains at least 3 servers.
Default: 1
cassandra.default_time_to_live
Section titled “cassandra.default_time_to_live”Metric points are automatically deleted after this delay in seconds.
Valid time units are ns, us (or µs), ms, s, m, h.
Default: 8760h (one year)
cassandra.aggregate.intended_duration
Section titled “cassandra.aggregate.intended_duration”To improve queries over large period of time, SquirrelDB does some pre-aggregation of the points.
To avoid overloading the system, SquirrelDB allows to throttle the aggregation. This setting configures the target time for aggregating one day of data. The aggregation will take at least this amount of time.
With a long duration, SquirrelDB will take longer to catch-up any aggregation lag (e.g. if SquirrelDB is stopped for multiple days). With a small duration, the aggregation will cause more visible stress on SquirrelDB and Cassandra. If the duration is too short, SquirrelDB will perform the aggregation without throttling.
We recommend to keep the default short duration if the stress caused by the aggregation is not an issue. If you want to increase the duration, 4h is a good value to reduce the stress on Cassandra and still be fast enough to allow some catch-up if needed.
Valid time units are ns, us (or µs), ms, s, m, h.
Default: 10m
listen_address
Section titled “listen_address”The Prometheus API listen address, used for remote storage and PromQL requests. A Prometheus exporter (of SquirrelDB internal metrics) will be exported on /metrics.
Default: localhost:9201
The log block configures logging.
log.level
Section titled “log.level”For debugging, you may lower the log level. Only the messages that have a greater or equal level than the chosen one are shown.
The supported levels are -1 (trace), 0 (debug), 1 (info), 2 (warn), 3 (error)
Default: 1
log.disable_color
Section titled “log.disable_color”If true, don’t use color in logs.
Default: false
max_request_body_size
Section titled “max_request_body_size”Maximum body size of incoming requests (in MiB). If a body exceeds this limit, the request will be rejected.
Default: 64 (MiB)
promql
Section titled “promql”The promql block configures the behavior of the PromQL endpoint at
/api/v1/query and /api/v1/query_range.
promql.max_evaluated_points
Section titled “promql.max_evaluated_points”Maximum number of points one PromQL may evaluate. Once reached, it will abort the query. 0 means no limit.
Default: 0
promql.max_evaluated_series
Section titled “promql.max_evaluated_series”Maximum number of series one PromQL may evaluate. Once reached, it will abort the query. 0 means no limit.
Default: 0
The redis allows to configure Redis to store batch of points instead of the
default in-memory store.
redis.addresses
Section titled “redis.addresses”Addresses of your Redis servers.
If empty, Redis is not used. If set to a single address (e.g. [“localhost:6379”]) then Redis will be used, as a Redis cluster if possible or a simple single-node Redis. If set to more than one address, Redis cluster is used.
Default: []
redis.username
Section titled “redis.username”Username used to connect to Redis. When empty, the connection is done without using credentials.
Default: ""
redis.password
Section titled “redis.password”Password used to connect to Redis.
Default: ""
redis.keyspace
Section titled “redis.keyspace”Prefix used on all Redis keys.
Default: ""
redis.ssl
Section titled “redis.ssl”Enable SSL.
Default: false
redis.ssl_insecure
Section titled “redis.ssl_insecure”Whether SquirrelDB should ignore SSL certificate errors.
Default: false
redis.cert_path
Section titled “redis.cert_path”Path to the TLS certificate used to connect to Redis. Optional depending on your server configuration.
Default: ""
redis.key_path
Section titled “redis.key_path”Path to the TLS key used to connect to Redis. Optional depending on your server configuration.
Default: ""
redis.ca_path
Section titled “redis.ca_path”Path to the TLS certificate authority used to connect to Redis. Optional depending on your server configuration.
Default: ""
remote_storage
Section titled “remote_storage”The remote_storage block configures the Prometheus remote storage API used to
read and write to SquirrelDB. The endpoints are at /api/v1/read and
/api/v1/write. See the
remote storage documentation
for details.
remote_storage.max_concurrent_requests
Section titled “remote_storage.max_concurrent_requests”Maximum number of concurrent remote read and write calls. If set to N, allows
2*N concurrent requests, with N reads and N writes. If set to 0, defaults to
2 * number of CPUs.
Default: 0
require_tenant_header
Section titled “require_tenant_header”You may want to require all requests to set the
tenant header. When this setting is
true, SquirrelDB will return an error to queries and write requests that don’t
provide the tenant header.
Default: false
sentry
Section titled “sentry”sentry.dsn
Section titled “sentry.dsn”Errors and panics are sent to Sentry if the DSN is configured.
Default: ""
telemetry
Section titled “telemetry”telemetry.enabled
Section titled “telemetry.enabled”Enable telemetry.
Default: true
tenant_label_name
Section titled “tenant_label_name”Label used to differentiate metrics from multiple tenants, see multi tenancy for details.
Default: __account_id