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 lowercase to uppercase, - and .to _ (if any), and prefixing with PROMSCALE_. For example, db.host can be set as an environment variable as PROMSCALE_DB_HOST.

Configuration file

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.

  2. # config.yml
  4. db.ssl-mode: disable
  6. db.user: postgres
  8. db.port: 5432
  10. db.password: password
  12. db.name: 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.

Arguments

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

General flags

FlagTypeDefaultDescription
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 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.
thanos.store-api.server-addressstring“” (disabled)Address to listen on for Thanos Store API endpoints.
tracing.otlp.server-addressstring:9202Address to listen on for OTLP GRPC server.

Auth flags

FlagTypeDefaultDescription
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

FlagTypeDefaultDescription
db.appstring[email protected]{version}‘app’ sets applicationname in database connection string. This is helpful during debugging when looking at pgstat_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.
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.
db.portint5432Port for TimescaleDB.
db.read-onlybooleanfalseRead-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-modestringrequireTimescaleDB 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 URI. Example:postgres://postgres:<a href=”https://docs.timescale.com/cdn-cgi/l/email-protection“ class=”__cf_email“ data-cfemail=”a8d8c9dbdbdfc7dacce8c4c7cbc9c4c0c7dbdc”>[email protected]:5432/timescale?sslmode=require
db.userstringpostgresTimescaleDB user.

Telemetry flags (for telemetry generated by the Promscale connector)

FlagTypeDefaultDescription
telemetry.log.formatstringlogfmtLog format to use from [ “logfmt”, “json” ].
telemetry.log.levelstringdebugLog level to use from [ “error”, “warn”, “info”, “debug” ].
telemetry.log.throughput-report-intervalduration0 secondsInterval 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-endpointstring“” (empty)OpenTelemetry tracing collector GRPC URL endpoint to send telemetry to otel-collector:4317
telemetry.trace.otel-tls-cert-filestring“” (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-filestring“” (empty)TLS Key file for client authentication against the OTEL tracing collector GRPC endpoint. Leave blank to disable TLS.
telemetry.trace.jaeger-endpointstring“” (empty)Jaeger tracing collector thrift HTTP URL endpoint to send telemetry to (for example: https://jaeger-collector:14268/api/traces).
telemetry.trace.sample-ratiofloat1.0Trace sampling ratio, amount of spans to send to collector. Valid values from 0.0 (none) to 1.0 (all).

Metrics specific flags

FlagTypeDefaultDescription
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 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 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-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, equal to (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.

Recording and Alerting rules flags

FlagTypeDefaultDescription
metrics.alertmanager.notification-queue-capacityinteger10000The capacity of the queue for pending Alertmanager notifications.
metrics.rules.alert.for-grace-periodduration10 minutesMinimum 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-toleranceduration1 hourMax time to tolerate Promscale outage for restoring “for” state of alert.
metrics.rules.alert.resend-delayduration1 minuteMinimum amount of time to wait before resending an alert to Alertmanager.
metrics.rules.config-filestring“”Path to configuration file in Prometheus-format, containing rule_files and optional alerting and global fields. For more details, see https://prometheus.io/docs/prometheus/latest/configuration/configuration/. 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.

Startup process flags

FlagTypeDefaultDescription
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

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