Documentation
¶
Overview ¶
Package promquery provides a simplified interface for executing Prometheus queries. This interface is suitable for usecases where applications only need to collect single values or sets of values without additional label information.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsErrNoRows ¶
IsErrNoRows checks whether the given error is a NoRowsError.
Types ¶
type BulkQuery ¶
type BulkQuery[K comparable, V any] struct { // The PromQL query returning the bulk data. Query string // A user-readable description for this dataset that can be interpolated into log messages. Description string // Computes the cache key for each sample returned by the query. Keyer func(*model.Sample) K // Fills data from this sample into the cache entry. Filler func(*V, *model.Sample) // Usually, it is an error for a BulkQuery to not return any data. // This protects against an outage on the Prometheus or metrics collection level to be misinterpreted as zero-valued metrics. // Set this flag if a query can legitimately have zero results during normal operation. ZeroResultsIsNotAnError bool }
BulkQuery is a query that can be executed by type BulkQueryCache (see there for details).
type BulkQueryCache ¶
type BulkQueryCache[K comparable, V any] struct { // contains filtered or unexported fields }
BulkQueryCache queries Prometheus in bulk and caches the result.
When certain simple Prometheus queries need to be executed repeatedly with different parameters, it's usually more efficient to request the entire data set in bulk instead of querying for each individual values. For example, querying 100 times for
sum(filesystem_capacity_bytes{hostname="%s"})
sum(filesystem_used_bytes{hostname="%s"})
for different hostnames can be optimized by querying once for
sum by (hostname) (filesystem_capacity_bytes) sum by (hostname) (filesystem_used_bytes)
and using this cached result. BulkQueryCache provides the reusable infrastructure for this access pattern. It is parametrized on a cache key (K) which identifies a single record to be retrieved, and the cached value (V) containing such a single record. In this expanded example, K and V are instantiated as HostName and HostFilesystemMetrics, respectively:
Example ¶
// SPDX-FileCopyrightText: 2023 SAP SE or an SAP affiliate company
// SPDX-License-Identifier: Apache-2.0
package main
import (
"context"
"fmt"
"os"
"time"
"github.com/prometheus/common/model"
"github.com/sapcc/go-bits/must"
"github.com/sapcc/go-bits/promquery"
)
type HostName string
type HostFilesystemMetrics struct {
CapacityBytes int
UsedBytes int
}
var keyer = func(sample *model.Sample) HostName {
return HostName(sample.Metric["hostname"])
}
var queries = []promquery.BulkQuery[HostName, HostFilesystemMetrics]{
{
Query: "sum by (hostname) (filesystem_capacity_bytes)",
Description: "filesystem capacity data",
Keyer: keyer,
Filler: func(entry *HostFilesystemMetrics, sample *model.Sample) {
entry.CapacityBytes = int(sample.Value)
},
},
{
Query: "sum by (hostname) (filesystem_used_bytes)",
Description: "filesystem usage data",
Keyer: keyer,
Filler: func(entry *HostFilesystemMetrics, sample *model.Sample) {
entry.UsedBytes = int(sample.Value)
},
},
}
func main() {
client := must.Return(promquery.ConfigFromEnv("PROMETHEUS").Connect())
cache := promquery.NewBulkQueryCache(queries, 5*time.Minute, client)
for _, arg := range os.Args[1:] {
hostName := HostName(arg)
entry := must.Return(cache.Get(context.Background(), hostName))
usagePercent := 100 * float64(entry.UsedBytes) / float64(entry.CapacityBytes)
fmt.Printf("disk usage on %s is %g%%\n", hostName, usagePercent)
}
}
func NewBulkQueryCache ¶
func NewBulkQueryCache[K comparable, V any](queries []BulkQuery[K, V], refreshInterval time.Duration, client Client) *BulkQueryCache[K, V]
NewBulkQueryCache initializes a BulkQueryCache that executes the given queries once per refresh interval.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client provides API access to a Prometheus server. It is constructed through the Connect method on type Config.
func (Client) API ¶
API returns the underlying API client from the Prometheus library. This should only be used if the simplified APIs in this package do not suffice.
func (Client) GetSingleValue ¶
func (c Client) GetSingleValue(ctx context.Context, queryStr string, defaultValue *float64) (float64, error)
GetSingleValue executes a Prometheus query and returns the result value. If the query produces multiple values, only the first value will be returned.
If the query produces no values, the `defaultValue` will be returned if one was supplied. Otherwise, the returned error will be of type NoRowsError. That condition can be checked with `promquery.IsErrNoRows(err)`.
type Config ¶
type Config struct {
// Required: Main URL of Prometheus instance.
ServerURL string `json:"url" yaml:"url"`
// Optional: To check validity of TLS server certificate.
ServerCACertificatePath string `json:"ca_cert" yaml:"ca_cert"`
// Optional: TLS client certificate to present while connecting.
ClientCertificatePath string `json:"cert" yaml:"cert"`
// Required if ClientCertificatePath is given: Private key for TLS client certificate.
ClientCertificateKeyPath string `json:"key" yaml:"key"`
// contains filtered or unexported fields
}
Config contains the set of configuration parameters that are required for establishing a connection to a Prometheus instance's API.
func ConfigFromEnv ¶
ConfigFromEnv fills a Config object from the following environment variables:
${envPrefix}_URL - required
${envPrefix}_CACERT - optional
${envPrefix}_CERT - optional
${envPrefix}_KEY - optional (required if client cert is given)
This function exits through logg.Fatal() if a required value is missing.
type NoRowsError ¶
type NoRowsError struct {
Query string
}
NoRowsError is returned by PrometheusClient.GetSingleValue() if there were no result values at all.
func (NoRowsError) Error ¶
func (e NoRowsError) Error() string
Error implements the builtin/error interface.
Source Files