Prometheus Connector¶

The Prometheus connector allows reading Prometheus.metrics as tables in Presto.

The mechanism for querying Prometheus is to use the Prometheus HTTP API. Specifically, all queries are resolved to Prometheus Instant queries with a form like: http://localhost:9090/api/v1/query?query=up[21d]&time=1568229904.000” In this case the up metric is taken from the Presto query table name. 21d is the duration of the query. The Prometheus time value corresponds to the timestamp field. Presto queries are translated from their use of the timestamp field to a duration and time value as needed. Presto splits are generated by dividing the query range into attempted equal chunks.

Configuration¶

Create etc/catalog/prometheus.properties to mount the Prometheus connector as the prometheus catalog, replacing the properties as appropriate:

connector.name=prometheus
prometheus.uri=http://localhost:9090
prometheus.query-chunk-duration=1d
prometheus.max-query-duration=1h
prometheus.cache-ttl=30s
prometheus.tls.enabled=true
prometheus.tls.truststore-path=/path/to/truststore
prometheus.tls.truststore-password=truststorePassword
verify-host-name=true

Configuration Properties¶

The following configuration properties are available:

Property Name	Description
`prometheus.uri`	Prometheus coordinator host address
`prometheus.query-chunk-duration`	The duration of each query to Prometheus
`prometheus.max-query-duration`	Width of overall query to Prometheus, will be divided into query-chunk-duration queries
`prometheus.cache-ttl`	How long the config values are cached
`prometheus.bearer-token-file`	File holding bearer token for access to Prometheus
`prometheus.auth.user`	Username for Basic authentication to Prometheus
`prometheus.auth.password`	Password for Basic authentication to Prometheus
`prometheus.tls.enabled`	Enable or disable TLS for securing communication with Prometheus
`prometheus.tls.truststore-path`	Path to the trust store containing the SSL certificates
`prometheus.tls.truststore-password`	Password to access the trust store for TLS verification
`verify-host-name`	Enable or disable hostname verification in the SSL certificate
`case-sensitive-name-matching`	Enable or disable case-sensitive matching for table names. The default is `false`.

Not Exhausting Your Presto Available Heap¶

The prometheus.query-chunk-duration and prometheus.max-query-duration are values to protect Presto from fetching too much data from Prometheus. The prometheus.max-query-duration is the item of particular interest.

On a Prometheus instance that has been running for awhile and depending on data retention settings, 21d might be far too much. Perhaps 1h might be a more reasonable setting. In the case of 1h it might be then useful to set prometheus.query-chunk-duration to 10m, dividing the query window into 6 queries each of which can be handled in a Presto split.

Primarily query issuers can limit the amount of data returned by Prometheus by taking advantage of WHERE clause limits on timestamp, setting an upper bound and lower bound that define a relatively small window. For instance:

SELECT * FROM prometheus.default.up WHERE timestamp > (NOW() - INTERVAL '10' second);

If the query does not include a WHERE clause limit, these config settings are meant to protect against an unlimited query.

Authentication¶

The connector supports three mutually exclusive authentication modes. Choose one of the following options:

No authentication (default)

No additional properties are required when Prometheus is accessible without authentication.

Bearer token authentication

Prometheus can be configured to require an Authorization header for every query. Set prometheus.bearer-token-file to a file containing the bearer token:

prometheus.bearer-token-file=/path/to/bearer/token/file

The token is read from the file for each request. The file must contain only the raw token value.

Basic authentication

Prometheus 2.24.0 and later can be configured to require HTTP Basic authentication. Set both prometheus.auth.user and prometheus.auth.password:

prometheus.auth.user=admin
prometheus.auth.password=password

The following rules apply to Basic authentication:

Both prometheus.auth.user and prometheus.auth.password must be set together. Setting only one of them causes the connector to fail at startup.
Basic authentication cannot be combined with prometheus.bearer-token-file. Configuring both causes the connector to fail at startup.
prometheus.auth.user must not contain a colon (:) character.

Case-Sensitive Name Matching¶

By default, Prometheus metric names (which appear as table names in Presto) are treated as case-insensitive. This means that querying up or UP would refer to the same metric. However, since Prometheus itself is case-sensitive, you can enable case-sensitive name matching to preserve the exact case of metric names.

To enable case-sensitive name matching, add the following property to your prometheus.properties file:

case-sensitive-name-matching=true

When case-sensitive name matching is enabled:

Table names must exactly match the case of the corresponding Prometheus metric name.
Queries using a different case than the actual metric name will fail with a Table not found error.

This is useful when you have metrics with similar names that differ only by case.

For example, with case-sensitive name matching enabled:

-- This will work if the metric name is exactly "up"
SELECT * FROM prometheus.default.up;

-- This will fail if the metric name is "up" (not "UP")
SELECT * FROM prometheus.default.UP;