metrics

package
v0.9.1 Latest Latest
Warning

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

Go to latest
Published: Oct 21, 2026 License: GPL-3.0 Imports: 18 Imported by: 0

Documentation

Overview

Package metrics is a tool's Prometheus metrics page: its own readings and nothing else, with the labels whoever runs it wants on every one, written as text or served over HTTP beside a health probe.

Index

Constants

View Source
const (
	// Path is where the page is served.
	Path = "/metrics"
	// HealthPath answers "ok" while the tool is serving, whatever state the thing it reports on is in.
	HealthPath = httpd.HealthPath
)

Variables

This section is empty.

Functions

func ParseLabels

func ParseLabels(s string) (map[string]string, error)

ParseLabels reads labels from a setting written name=value,name=value, as LEONTP_METRICS_LABELS=hostname=ntp,site=home is; spaces around a name or a value are dropped, and nothing at all is no labels. A value cannot hold a comma.

func Serve

func Serve(ctx context.Context, listen string, h http.Handler) error

Serve serves h on listen until the context ends, then lets requests under way finish. Whoever calls it ends the context on a signal.

func ValidateLabels

func ValidateLabels(labels map[string]string) error

ValidateLabels says what is wrong with the first label, by name, that a metrics store would not take: a name that is not letters, digits and underscores, one that starts with a digit or with the two underscores a store keeps for itself, or a label with no value.

Types

type List

type List struct {
	// contains filtered or unexported fields
}

List is every reading a tool's page can hold, declared in one place so its collector can name them all. A tool keeps one in a variable of its own.

func NewList

func NewList(namespace string, labels ...string) *List

NewList is an empty list of readings whose names start with namespace. Labels, when given, start every reading's labels: "card" for a tool that reports on several cards, each card's name then given to NewWriter.

func (*List) Describe

func (l *List) Describe(ch chan<- *prometheus.Desc)

Describe names every reading on the list, for a collector's own Describe to hand on.

func (*List) Reading

func (l *List) Reading(name, help string, labels ...string) *prometheus.Desc

Reading adds one reading to the list, and is what a Writer writes it with: its name after the namespace, what it is, and the labels it has beside the list's own. A name or label a metrics store would not take is refused by New, when the tool starts.

type Number

type Number interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~float32 | ~float64
}

Number is any number a reading can be given: a count, a size, a total from the kernel, a temperature.

type Options

type Options struct {
	// Name is the tool's name, "leontp-exporter": what the root of the server answers with beside its version, and what names the one reading the
	// page adds itself, which says what build wrote it: leontp_exporter_build_info.
	Name string
	// BuildInfo names that reading outright, when the tool's name will not do: "leontp_metrics_build_info" keeps a name a dashboard already uses. It
	// ends in _build_info, as every such reading's name does.
	BuildInfo string
	// Labels are put on every reading on the page: hostname=ntp say, for a store that tells one source from another by them. ParseLabels reads
	// them from a setting.
	Labels map[string]string
}

Options says what the page is.

type Page

type Page struct {
	// contains filtered or unexported fields
}

Page holds a tool's readings and writes them out. It holds none of the Go runtime's or the process's own.

func New

func New(o Options, collectors ...prometheus.Collector) (*Page, error)

New is the page of these collectors' readings, each with the labels on it, and one more that says which build wrote the page. A label under a name a reading already has is an error, as is one a metrics store would not take: said when the tool starts, not found missing on a dashboard.

func (*Page) Handler

func (p *Page) Handler() http.Handler

Handler is the routes: the page at Path, the health probe at HealthPath, and at the root a few lines saying where they are. Apart from Serve so they can be tested or mounted elsewhere without a port.

func (*Page) Write

func (p *Page) Write(w io.Writer) error

Write writes the page as text, the way a scrape reads it. A reading that cannot be written is left off and said in the error, and the rest is still written, as a scrape still gets it.

type Writer

type Writer struct {
	// contains filtered or unexported fields
}

Writer writes a collector's readings. A second reading with the same name and labels is left off: it would spoil the whole page, and what a tool reports on seldom promises that two of its things have different names.

func NewWriter

func NewWriter(ch chan<- prometheus.Metric, values ...string) *Writer

NewWriter writes to ch, the channel a collector's Collect is given. Values are for the list's own labels, in the same order: the card's name, say.

func (*Writer) At

func (w *Writer) At(d *prometheus.Desc, t time.Time, labels ...string)

At is Gauge for a moment, in seconds since 1970. The zero time, for something that has not happened, is left off.

func (*Writer) Counts

func (w *Writer) Counts[K ~string](d *prometheus.Desc, known []K, n map[K]int, labels ...string)

Counts writes how many there are of each kind: every kind known, at 0 when there is none, and any other kind there turns out to be. The kind is the last label, after the ones given.

func (*Writer) First

func (w *Writer) First(kind string, labels ...string) bool

First says whether a thing has not been seen before, and notes that it now has: a slot by its enclosure and number, say. Writing a thing's readings only the first time keeps one listed twice off the page whole, where a reading that carries its value in a label, a status, would differ.

func (*Writer) Flag

func (w *Writer) Flag(d *prometheus.Desc, yes bool, labels ...string)

Flag is Gauge for a yes or no: 1 or 0.

func (*Writer) Gauge

func (w *Writer) Gauge[N Number](d *prometheus.Desc, value N, labels ...string)

Gauge writes a reading that can go up and down.

func (*Writer) States

func (w *Writer) States[S ~string](d *prometheus.Desc, known []S, is S, labels ...string)

States writes 1 for the state something is in and 0 for each other state it could be in, so none vanishes when it is left. A state not among those known is written too, at 1: what is reported on may be newer than the tool. The state is the last label, after the ones given.

func (*Writer) Total

func (w *Writer) Total[N Number](d *prometheus.Desc, value N, labels ...string)

Total writes a reading that only goes up until whatever keeps it starts again: a count of failures, or of errors since a disk was fitted.

Jump to

Keyboard shortcuts

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