Promscale has been discontinued. We strongly recommend that you do not use Promscale in a production environment. Learn more.

This document gives you information about the configuration flags and arguments supported by the Promscale Connector. You can also find information on flags with promscale_<version> -help.


Flags can be set as environment variables by converting lowercase to uppercase, - and .to _ (if any), and prefixing with PROMSCALE_. For example, can be set as an environment variable as PROMSCALE_DB_HOST.

All CLI parameters can be configured with a YAML-formatted configuration file. The file must be a map of key-value pairs, with the keys being CLI flags. For example, the following config file sets some database parameters.

# config.yml
db.ssl-mode: disable
db.user: postgres
db.port: 5432
db.password: password postgres

If the file is named config.yml, Promscale will pick it up automatically, otherwise you can specify the config file with ./promscale -config /path/to/your-config.yml.

Argument Description
version Prints the version information of Promscale.
help Prints the information related to flags supported by Promscale.
Flag Type Default Description
cache.memory-target unsigned-integer or percentage 80% Target for max amount of memory to use. Specified in bytes or as a percentage of system memory (for example, 80%).
config string config.yml YAML configuration file path for Promscale.
enable-feature string "" Enable one or more experimental promscale features (as a comma-separated list). Current experimental features are promql-at-modifier, promql-negative-offset and promql-per-step-stats. For more information, please consult the following resources: promql-at-modifier, promql-negative-offset, promql-per-step-stats. string "" (disabled) Address to listen on for Thanos Store API endpoints.
tracing.otlp.server-address string :9202 Address to listen on for OTLP GRPC server.
Flag Type Default Description
auth.tls-cert-file string "" (disabled) TLS certificate file path for web server. To disable TLS, leave this field as blank.
auth.tls-key-file string "" (disabled) TLS key file path for web server. To disable TLS, leave this field as blank.
Flag Type Default Description string promscale@{version} 'app' sets application_name in database connection string. This is helpful during debugging when looking at pg_stat_activity.
db.connection-timeout duration 60 seconds Timeout for establishing the connection between Promscale and TimescaleDB.
db.connections-max integer 80% of possible connections db Maximum number of connections to the database that should be opened at once. It defaults to 80% of the maximum connections that the database can handle. string localhost Host for TimescaleDB. string timescale Database name.
db.num-writer-connections integer 1 Maximum number of database connections for writing per go thread (as configured via GOMAXPROCS)
db.password string Password for connecting to TimescaleDB.
db.port int 5432 Port for TimescaleDB. boolean false Read-only mode for the connector. Operations related to writing or updating the database are disallowed. It is used when pointing the connector to a TimescaleDB read replica.
db.ssl-mode string require TimescaleDB connection ssl mode. If you do not want to use ssl, pass allow as value.
db.statements-cache boolean true Whether database connection pool should use cached prepared statements. Disable if using PgBouncer.
db.uri string TimescaleDB URI. Example:postgres://postgres:password@localhost:5432/timescale?sslmode=require
db.user string postgres TimescaleDB user.
Flag Type Default Description
telemetry.log.format string logfmt Log format to use from [ "logfmt", "json" ].
telemetry.log.level string debug Log level to use from [ "error", "warn", "info", "debug" ].
telemetry.log.throughput-report-interval duration 0 seconds Interval at which throughput should be reported. Setting duration to 0 will disable throughput reporting. Otherwise, an interval with a unit must be provided, for example: 10s or 3m.
telemetry.trace.otel-endpoint string "" (empty) OpenTelemetry tracing collector GRPC URL endpoint to send telemetry to otel-collector:4317
telemetry.trace.otel-tls-cert-file string "" (empty) TLS Certificate file used for client authentication against the OTEL tracing collector GRPC endpoint. Leave blank to disable TLS.
telemetry.trace.otel-tls-key-file string "" (empty) TLS Key file for client authentication against the OTEL tracing collector GRPC endpoint. Leave blank to disable TLS.
telemetry.trace.jaeger-endpoint string "" (empty) Jaeger tracing collector thrift HTTP URL endpoint to send telemetry to (for example: https://jaeger-collector:14268/api/traces).
telemetry.trace.sample-ratio float 1.0 Trace sampling ratio, amount of spans to send to collector. Valid values from 0.0 (none) to 1.0 (all).
Flag Type Default Description
metrics.async-acks boolean false Acknowledge asynchronous inserts. If this is true, the inserter will not wait after insertion of metric data in the database. This increases throughput at the cost of a small chance of data loss.
metrics.cache.exemplar.size unsigned-integer 10000 Maximum number of exemplar metrics key-position to cache. It has one-to-one mapping with number of metrics that have exemplar, as key positions are saved per metric basis.
metrics.cache.labels.size unsigned-integer 10000 Maximum number of labels to cache.
metrics.cache.metrics.size unsigned-integer 10000 Maximum number of metric names to cache.
metrics.cache.series.initial-size unsigned-integer 250000 Initial number of elements in the series cache.
metrics.cache.series.max-bytes unsigned-integer or percentage 50% Target for amount of memory to use for the series cache. Specified in bytes or as a percentage of memory-target. For example, 50%.
metrics.high-availability boolean false Enable external_labels-based HA.
metrics.ignore-samples-written-to-compressed-chunks boolean false Ignore/drop samples that are being written to compressed chunks. Setting this to false allows Promscale to ingest older data by decompressing chunks that were earlier compressed. However, setting this to true will save your resources that may be required during decompression.
metrics.multi-tenancy boolean false Use multi-tenancy mode in Promscale.
metrics.multi-tenancy.allow-non-tenants boolean false Allow Promscale to ingest/query all tenants as well as non-tenants. By setting this to true, Promscale will ingest data from non multi-tenant Prometheus instances as well. If this is false, only multi-tenants (tenants listed in 'multi-tenancy-valid-tenants') are allowed for ingesting and querying data.
metrics.multi-tenancy.valid-tenants string allow-all Sets valid tenants that are allowed to be ingested/queried from Promscale. This can be set as 'allow-all' (default), or as comma separated tenant names. 'allow-all' makes Promscale ingest or query any tenant from itself. A comma separated list indicates only those tenants that are authorized for operations from Promscale.
metrics.promql.default-subquery-step-interval duration 1 minute Default step interval to be used for PromQL subquery evaluation. This value is used if the subquery does not specify the step value explicitly. Example: <metric_name>[30m:]. Note: in Prometheus this setting is set by the evaluation_interval option.
metrics.promql.lookback-delta duration 5 minute The maximum look-back duration for retrieving metrics during expression evaluations and federation.
metrics.promql.max-points-per-ts integer64 11000 Maximum number of points per time-series in a query-range request. This calculation is an estimation, equal to (start - end)/step where start and end are the 'start' and 'end' timestamps of the query_range.
metrics.promql.max-samples integer64 50000000 Maximum number of samples a single query can load into memory. Note that queries will fail if they try to load more samples than this into memory, so this also limits the number of samples a query can return.
metrics.promql.query-timeout duration 2 minutes Maximum time a query may take before being aborted. This option sets both the default and maximum value of the 'timeout' parameter in '/api/v1/query.*' endpoints.
Flag Type Default Description
metrics.alertmanager.notification-queue-capacity integer 10000 The capacity of the queue for pending Alertmanager notifications.
metrics.rules.alert.for-grace-period duration 10 minutes Minimum duration between alert and restored "for" state. This is maintained only for alerts with configured "for" time greater than the grace period.
metrics.rules.alert.for-outage-tolerance duration 1 hour Max time to tolerate Promscale outage for restoring "for" state of alert.
metrics.rules.alert.resend-delay duration 1 minute Minimum amount of time to wait before resending an alert to Alertmanager.
metrics.rules.config-file string "" Path to configuration file in Prometheus-format, containing rule_files and optional alerting and global fields. For more details, see Note: If this flag is missing or rule_files is empty, Promscale rule-manager does not start. If alertmanagers is empty, alerting is not initialized.
Flag Type Default Description
startup.install-extensions boolean true Install TimescaleDB & Promscale extensions.
startup.only boolean false Only run startup configuration with Promscale (in other words, migrate) and exit. Can be used to run promscale as an init container for HA setups.
startup.skip-migrate boolean false Skip migrating Promscale SQL schema to latest version on startup.
startup.upgrade-extensions boolean true Upgrades TimescaleDB & Promscale extensions.
startup.upgrade-prerelease-extensions boolean false Upgrades to pre-release TimescaleDB, Promscale extensions.
startup.use-schema-version-lease boolean true Use schema version lease to prevent race conditions during migration.
Flag Type Default Description
web.auth.bearer-token string "" (disabled) Bearer token (JWT) used for web endpoint authentication. Disabled by default. Mutually exclusive with bearer-token-file and basic auth methods.
web.auth.bearer-token-file string "" (disabled) Path of the file containing the bearer token (JWT) used for web endpoint authentication. Disabled by default. Mutually exclusive with bearer-token and basic auth methods.
web.auth.password string "" Authentication password used for web endpoint authentication. This flag should be set together with auth-username. It is mutually exclusive with auth-password-file and bearer-token methods.
web.auth.password-file string "" Path for auth password file containing the actual password used for web endpoint authentication. This flag should be set together with auth-username. It is mutually exclusive with auth-password and bearer-token methods.
web.auth.username string "" Authentication username used for web endpoint authentication. Disabled by default.
web.cors-origin string .* Regex for CORS origin. It is fully anchored. Example: 'https?://(domain1
web.enable-admin-api boolean false Allow operations via API that are for advanced users. Currently, these operations are limited to deletion of series.
web.listen-address string :9201 Address to listen on for web endpoints.
web.telemetry-path string /metrics Web endpoint for exposing Promscale's Prometheus metrics.