Documentation
¶
Overview ¶
Package prometheus implements providers.MetricsProvider against the Prometheus HTTP API — also spoken by VictoriaMetrics — for instant and range PromQL queries.
Index ¶
- type Client
- func (c *Client) DetectFlavor(ctx context.Context) Flavor
- func (c *Client) Flavor() Flavor
- func (c *Client) LabelValues(ctx context.Context, label string, matchers []string, w providers.TimeWindow) ([]string, error)
- func (c *Client) Query(ctx context.Context, promql string, at time.Time) (providers.Samples, error)
- func (c *Client) QueryRange(ctx context.Context, promql string, w providers.TimeWindow, step time.Duration) (providers.Matrix, error)
- func (c *Client) WithFlavor(f Flavor) *Client
- type Flavor
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client queries a Prometheus-compatible metrics backend.
func NewWithAuth ¶ added in v0.3.0
NewWithAuth builds a client that adds optional auth to every request. tokenEnv names an env var holding a bearer token (empty, or pointing at an unset/empty var, ⇒ no Authorization header); headers are static request headers (e.g. "X-Scope-OrgID" for a multi-tenant backend). The token is read from the environment at request-build time and is never logged.
func (*Client) DetectFlavor ¶ added in v0.9.0
DetectFlavor probes the backend's build-info endpoint once and records the detected Flavor on the client, returning it. It FAILS SAFE: any error, non-200, or unrecognized payload leaves the flavor FlavorUnknown (no MetricsQL claims) and returns a nil error — detection is best-effort, never fatal to startup. A flavor already pinned (via WithFlavor) short-circuits the probe.
VictoriaMetrics is identified by the case-insensitive substring "victoria" in the build-info response (its version/short_version strings carry it); Prometheus is recorded when the payload is a well-formed build-info envelope that is NOT VictoriaMetrics, so its own guidance (no MetricsQL) is explicit rather than merely "unknown".
func (*Client) Flavor ¶ added in v0.9.0
Flavor returns the detected/configured backend flavor, or FlavorUnknown when it was never set or auto-detection failed. Callers use it to decide whether to advertise MetricsQL-only guidance.
func (*Client) LabelValues ¶ added in v0.9.0
func (c *Client) LabelValues(ctx context.Context, label string, matchers []string, w providers.TimeWindow) ([]string, error)
LabelValues lists the values of a label across series matching matchers, within the window — the metric/label discovery path so the agent can find real names instead of guessing (label "__name__" enumerates metric names). It hits GET /api/v1/label/<label>/values?match[]=…&start=…&end=…, scoping by matcher + window so it stays cheap on a big TSDB. Values are returned as the backend orders them (Prometheus sorts; VictoriaMetrics may not) — callers that need a stable order sort themselves.
func (*Client) QueryRange ¶
func (c *Client) QueryRange(ctx context.Context, promql string, w providers.TimeWindow, step time.Duration) (providers.Matrix, error)
QueryRange runs a range PromQL query over a window. If (end-start)/step would exceed maxRangePoints, the step is raised so the request stays within the backend's point cap — a last-resort guard; the range tool clamps earlier and annotates the coarsening for the operator.
func (*Client) WithFlavor ¶ added in v0.9.0
WithFlavor pins the backend flavor, bypassing auto-detection (config.metrics.flavor). An unknown/empty value leaves the flavor as-is so a stray config value never downgrades a good detection to FlavorUnknown. It returns the client for chaining.
type Flavor ¶ added in v0.9.0
type Flavor string
Flavor identifies the metrics backend implementation behind the shared Prometheus HTTP API. Both Prometheus and VictoriaMetrics speak PromQL over the same endpoints, but VictoriaMetrics ALSO accepts MetricsQL (a PromQL superset) — knowing the flavor lets the query tools advertise MetricsQL-only helpers without risking an invalid query against real Prometheus.
const ( FlavorUnknown Flavor = "" FlavorPrometheus Flavor = "prometheus" FlavorVictoriaMetrics Flavor = "victoriametrics" )
The known metrics-backend flavors. FlavorUnknown is the fail-safe default: it makes NO MetricsQL claims, so a failed/ambiguous probe degrades to generic Prometheus behaviour rather than advertising a dialect the backend may reject.
Source Files