Skip to main content

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

batch​

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​

Configure the time to keep points in memory before writing to Cassandra

caution

This value must be the same between all SquirrelDB.

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​

The cassandra block configures the Cassandra server used by SquirrelDB to store points.

cassandra.addresses​

List of Cassandra servers to connect to.

Default: ["localhost:9042"]

cassandra.username​

Username used to connect to Cassandra. When empty, the connection is done without using credentials.

Default: ""

cassandra.password​

Password used to connect to Cassandra.

Default: ""

cassandra.cert_path​

Path to the TLS certificate used to connect to Cassandra. Optional depending on your server configuration.

Default: ""

cassandra.key_path​

Path to the TLS key used to connect to Cassandra. Optional depending on your server configuration.

Default: ""

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​

Whether to verify the hostname and server certificate.

Default: true

cassandra.keyspace​

Cassandra keyspace used to create tables.

Default: squirreldb

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.

note

This value is only used when creating the keyspace.

Default: 1

cassandra.default_time_to_live​

Metric points are automatically deleted after this delay in seconds.

caution

The expiration is set when points is written, changing this value will only impact points written after the change.

Valid time units are ns, us (or µs), ms, s, m, h.

Default: 8760h (one year)

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​

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

log​

The log block configures logging.

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​

If true, don't use color in logs.

Default: false

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​

The promql block configures the behavior of the PromQL endpoint at /api/v1/query and /api/v1/query_range.

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​

Maximum number of series one PromQL may evaluate. Once reached, it will abort the query. 0 means no limit.

Default: 0

redis​

The redis allows to configure Redis to store batch of points instead of the default in-memory store.

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​

Username used to connect to Redis. When empty, the connection is done without using credentials.

Default: ""

redis.password​

Password used to connect to Redis.

Default: ""

redis.keyspace​

Prefix used on all Redis keys.

Default: ""

redis.ssl​

Enable SSL.

Default: false

redis.ssl_insecure​

Whether SquirrelDB should ignore SSL certificate errors.

Default: false

redis.cert_path​

Path to the TLS certificate used to connect to Redis. Optional depending on your server configuration.

Default: ""

redis.key_path​

Path to the TLS key used to connect to Redis. Optional depending on your server configuration.

Default: ""

redis.ca_path​

Path to the TLS certificate authority used to connect to Redis. Optional depending on your server configuration.

Default: ""

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​

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​

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​

sentry.dsn​

Errors and panics are sent to Sentry if the DSN is configured.

Default: ""

telemetry​

telemetry.enabled​

Enable telemetry.

Default: true

tenant_label_name​

Label used to differentiate metrics from multiple tenants, see multi tenancy for details.

Default: __account_id