prometheus

package
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 8, 2026 License: MIT Imports: 17 Imported by: 0

README

Prometheus plugin

The Prometheus plugin runs PromQL queries against a Prometheus-compatible API (such as Prometheus itself or VictoriaMetrics), so services can be checked using metrics that are already being collected.

The plugin must be configured with the URL of the API, and can optionally authenticate, send extra headers, and use custom TLS settings:

plugin prometheus {
  # URL is required
  url = "https://prometheus.example.com/"

  # Basic authentication
  auth {
    username = "goplum"
    password = "hunter2"
  }

  # Or a bearer token
  bearer_token = "abc123"

  # Additional headers, such as a tenant ID for Mimir or Cortex
  headers = ["X-Scope-OrgID: tenant-1"]

  tls {
    # CA certificate(s) to verify the server with, instead of the system's
    ca_file = "/etc/goplum/prometheus-ca.pem"

    # Client certificate and key, for mutual TLS
    cert_file = "/etc/goplum/client.pem"
    key_file = "/etc/goplum/client-key.pem"
  }
}

Only one of auth and bearer_token may be specified. Headers are given in "Name: Value" format, and a header may be repeated to send multiple values. cert_file and key_file must be specified together, and all TLS files must be PEM-encoded.

Checks

prometheus.query
check prometheus.query "example" {
  query = "up{job='example'}"
}

Runs an instant query, which should describe the healthy state of the service. The check passes if the query returns at least one series and every value is non-zero. It fails if:

  • the query returns no series, so a metric that has disappeared fails without needing absent();
  • any series has a value of zero (or NaN); or
  • the query is invalid, or the API can't be reached.

This means a plain up{job='example'} works as expected: up remains present with a value of zero when a scrape fails. Comparisons also work, as they filter out series that don't match:

check prometheus.query "backup ran" {
  query = "time() - backup_last_success_timestamp_seconds < 86400"
  interval = 10m
}

When a query matches several series, a series that vanishes won't be noticed as long as others remain. To make sure all of them are present, count them:

check prometheus.query "all hosts reporting" {
  query = "count(up{job='node'} == 1) == 3"
}

PromQL accepts single-quoted label values, so queries don't need to escape Goplum's double quotes.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Credentials

type Credentials struct {
	Username string
	Password string
}

type Plugin

type Plugin struct {
	Url         string
	Auth        Credentials
	BearerToken string `config:"bearer_token"`
	Headers     []string
	TLS         TLSConfig `config:"tls"`
	// contains filtered or unexported fields
}

func (*Plugin) Alert

func (p *Plugin) Alert(_ string) goplum.Alert

func (*Plugin) Check

func (p *Plugin) Check(kind string) goplum.Check

func (*Plugin) Validate

func (p *Plugin) Validate() error

type QueryCheck

type QueryCheck struct {
	Query string
	// contains filtered or unexported fields
}

func (QueryCheck) Execute

func (q QueryCheck) Execute(ctx context.Context) goplum.Result

func (QueryCheck) Validate

func (q QueryCheck) Validate() error

type TLSConfig

type TLSConfig struct {
	CAFile   string `config:"ca_file"`
	CertFile string `config:"cert_file"`
	KeyFile  string `config:"key_file"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL