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) }
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 ¶
/******************************************************************************
*
* Copyright 2023 SAP SE
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
******************************************************************************/
package main
import (
"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(hostName))
usagePercent := 100 * float64(entry.UsedBytes) / float64(entry.CapacityBytes)
fmt.Printf("disk usage on %s is %g%%\n", hostName, usagePercent)
}
}
Output:
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.
func (*BulkQueryCache[K, V]) Get ¶
func (c *BulkQueryCache[K, V]) Get(key K) (entry V, err error)
Get returns the entry for this key, or a zero-initialized entry if this key does not exist in the dataset.
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 ¶
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 `yaml:"url"`
// Optional: To check validity of TLS server certificate.
ServerCACertificatePath string `yaml:"ca_cert"`
// Optional: TLS client certificate to present while connecting.
ClientCertificatePath string `yaml:"cert"`
// Required if ClientCertificatePath is given: Private key for TLS client certificate.
ClientCertificateKeyPath string `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