Promscale command line interface (CLI) reference

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.

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


versionPrints the version information of Promscale.
helpPrints the information related to flags supported by Promscale.

General flags

cache.memory-targetunsigned-integer or percentage80%Target for max amount of memory to use. Specified in bytes or as a percentage of system memory (for example, 80%).
configstringconfig.ymlYAML configuration file path for Promscale.
enable-featurestring""Enable one or more experimental promscale features (as a comma-separated list). Current experimental features are tracing, promql-at-modifier, and promql-negative-offset. For more information, please consult the following resources: tracing, promql-at-modifier, promql-negative-offset.
migratestringtrueUpdate the Prometheus SQL schema to the latest version. Valid options are: [true, false, only]."" (disabled)Address to listen on for Thanos Store API endpoints.
tracing.otlp.server-addressstring:9202Address to listen on for OTLP GRPC server.

Auth flags

auth.tls-cert-filestring"" (disabled)TLS certificate file path for web server. To disable TLS, leave this field as blank.
auth.tls-key-filestring"" (disabled)TLS key file path for web server. To disable TLS, leave this field as blank.

Database flags

db.appstring[email protected]{version}'app' sets application_name in database connection string. This is helpful during debugging when looking at pg_stat_activity.
db.connection-timeoutduration60 secondsTimeout for establishing the connection between Promscale and TimescaleDB.
db.connections-maxinteger80% of possible connections dbMaximum 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.
db.hoststringlocalhostHost for TimescaleDB/Vanilla Postgres.
db.namestringtimescaleDatabase name.
db.num-writer-connectionsinteger1Maximum number of database connections for writing per go thread (as configured via GOMAXPROCS)
db.passwordstringPassword for connecting to TimescaleDB/Vanilla Postgres.
db.portint5432TimescaleDB/Vanilla Postgres connection password. 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-modestringrequireTimescaleDB/Vanilla Postgres connection ssl mode. If you do not want to use ssl, pass allow as value.
db.statements-cachebooleantrueWhether database connection pool should use cached prepared statements. Disable if using PgBouncer.
db.uristringTimescaleDB/Vanilla PostgresSQL URI. Example:postgres://postgres:[email protected]:5432/timescale?sslmode=require
db.userstringpostgresTimescaleDB/Vanilla Postgres user.

Logging flags

log.formatstringlogfmtLog format to use from [ "logfmt", "json" ].
log.levelstringdebugLog level to use from [ "error", "warn", "info", "debug" ].
log.throughput-report-intervalduration0 secondDuration interval at which throughput should be reported. Setting duration to 0 will disable reporting throughput, otherwise, an interval with unit must be provided, for example, 10s or 3m.

Metrics specific flags flags

metrics.async-acksbooleanfalseAcknowledge 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.sizeunsigned-integer10000Maximum 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.sizeunsigned-integer10000Maximum number of labels to cache.
metrics.cache.metrics.sizeunsigned-integer10000Maximum number of metric names to cache.
metrics.cache.series.initial-sizeunsigned-integer250000Initial number of elements in the series cache.
metrics.cache.series.max-bytesunsigned-integer or percentage50%Target for amount of memory to use for the series cache. Specified in bytes or as a percentage of the memory-target (for example, 50%).
metrics.high-availabilitybooleanfalseEnable external_labels based HA.
metrics.ignore-samples-written-to-compressed-chunksbooleanfalseIgnore/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-tenancybooleanfalseUse multi-tenancy mode in Promscale.
metrics.multi-tenancy.allow-non-tenantsbooleanfalseAllow 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-tenantsstringallow-allSets valid tenants that are allowed to be ingested/queried from Promscale. This can be set as: 'allow-all' (default) or a comma separated tenant names. 'allow-all' makes Promscale ingest or query any tenant from itself. A comma separated list will indicate only those tenants that are authorized for operations from Promscale.
metrics.promql.default-subquery-step-intervalduration1 minuteDefault 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-deltaduration5 minuteThe maximum look-back duration for retrieving metrics during expression evaluations and federation.
metrics.promql.max-points-per-tsinteger6411000Maximum number of points per time-series in a query-range request. This calculation is an estimation, that happens as (start - end)/step where start and end are the 'start' and 'end' timestamps of the query_range.
metrics.promql.max-samplesinteger6450000000Maximum 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-timeoutduration2 minutesMaximum 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.

Startup process flags

startup.install-extensionsbooleantrueInstall TimescaleDB & Promscale extensions.
startup.onlybooleanfalseOnly 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-migratebooleanfalseSkip migrating Promscale SQL schema to latest version on startup.
startup.upgrade-extensionsbooleantrueUpgrades TimescaleDB & Promscale extensions.
startup.upgrade-prerelease-extensionsbooleanfalseUpgrades to pre-release TimescaleDB, Promscale extensions.
startup.use-schema-version-leasebooleantrueUse schema version lease to prevent race conditions during migration.

Web server flags

web.auth.bearer-tokenstring"" (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-filestring"" (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.passwordstring""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-filestring""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.usernamestring""Authentication username used for web endpoint authentication. Disabled by default.
web.cors-originstring.*Regex for CORS origin. It is fully anchored. Example: 'https?://(domain1
web.enable-admin-apibooleanfalseAllow operations via API that are for advanced users. Currently, these operations are limited to deletion of series.
web.listen-addressstring:9201Address to listen on for web endpoints.
web.telemetry-pathstring/metricsWeb endpoint for exposing Promscale's Prometheus metrics.

Found an issue on this page?

Report an issue!


Related Content