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
- func ParseLabels(s string) (map[string]string, error)
- func Serve(ctx context.Context, listen string, h http.Handler) error
- func ValidateLabels(labels map[string]string) error
- type List
- type Number
- type Options
- type Page
- type Writer
- func (w *Writer) At(d *prometheus.Desc, t time.Time, labels ...string)
- func (w *Writer) Counts[K ~string](d *prometheus.Desc, known []K, n map[K]int, labels ...string)
- func (w *Writer) First(kind string, labels ...string) bool
- func (w *Writer) Flag(d *prometheus.Desc, yes bool, labels ...string)
- func (w *Writer) Gauge[N Number](d *prometheus.Desc, value N, labels ...string)
- func (w *Writer) States[S ~string](d *prometheus.Desc, known []S, is S, labels ...string)
- func (w *Writer) Total[N Number](d *prometheus.Desc, value N, labels ...string)
Constants ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
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 ¶
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 ¶
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 ¶
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.