push

Documentation

Overview

Package push provides functions to push metrics to a Pushgateway. It uses a builder approach. Create a Pusher with New and then add the various options by using its methods, finally calling Add or Push, like this:

// Easy case:
push.New("http://example.org/metrics", "my_job").Gatherer(myRegistry).Push()

// Complex case:
push.New("http://example.org/metrics", "my_job").
    Collector(myCollector1).
    Collector(myCollector2).
    Grouping("zone", "xy").
    Client(&myHTTPClient).
    BasicAuth("top", "secret").
    Add()

See the examples section for more detailed examples.

See the documentation of the Pushgateway to understand the meaning of the grouping key and the differences between Push and Add: https://github.com/prometheus/pushgateway

Index

• func AddCollectors(job string, grouping map[string]string, url string, ...) error
• func AddFromGatherer(job string, grouping map[string]string, url string, g prometheus.Gatherer) error
• func Collectors(job string, grouping map[string]string, url string, ...) error
• func FromGatherer(job string, grouping map[string]string, url string, g prometheus.Gatherer) error
• func HostnameGroupingKey() map[string]string
• type Pusher
  • func New(url, job string) *Pusher
  • func (p *Pusher) Add() error
  • func (p *Pusher) BasicAuth(username, password string) *Pusher
  • func (p *Pusher) Client(c *http.Client) *Pusher
  • func (p *Pusher) Collector(c prometheus.Collector) *Pusher
  • func (p *Pusher) Gatherer(g prometheus.Gatherer) *Pusher
  • func (p *Pusher) Grouping(name, value string) *Pusher
  • func (p *Pusher) Push() error

Examples

• Pusher.Add
• Pusher.Push

Functions

func AddCollectors

func AddCollectors(job string, grouping map[string]string, url string, collectors ...prometheus.Collector) error

AddCollectors works like AddFromGatherer, but it does not use a Gatherer. Instead, it collects from the provided collectors directly. It is a convenient way to push only a few metrics.

Deprecated: Please use a Pusher created with New instead.

func AddFromGatherer

func AddFromGatherer(job string, grouping map[string]string, url string, g prometheus.Gatherer) error

AddFromGatherer works like FromGatherer, but only previously pushed metrics with the same name (and the same job and other grouping labels) will be replaced. (It uses HTTP method 'POST' to push to the Pushgateway.)

Deprecated: Please use a Pusher created with New instead.

func Collectors

func Collectors(job string, grouping map[string]string, url string, collectors ...prometheus.Collector) error

Collectors works like FromGatherer, but it does not use a Gatherer. Instead, it collects from the provided collectors directly. It is a convenient way to push only a few metrics.

Deprecated: Please use a Pusher created with New instead.

func FromGatherer

func FromGatherer(job string, grouping map[string]string, url string, g prometheus.Gatherer) error

FromGatherer triggers a metric collection by the provided Gatherer (which is usually implemented by a prometheus.Registry) and pushes all gathered metrics to the Pushgateway specified by url, using the provided job name and the (optional) further grouping labels (the grouping map may be nil). See the Pushgateway documentation for detailed implications of the job and other grouping labels. Neither the job name nor any grouping label value may contain a "/". The metrics pushed must not contain a job label of their own nor any of the grouping labels.

You can use just host:port or ip:port as url, in which case 'http://' is added automatically. You can also include the schema in the URL. However, do not include the '/metrics/jobs/...' part.

Note that all previously pushed metrics with the same job and other grouping labels will be replaced with the metrics pushed by this call. (It uses HTTP method 'PUT' to push to the Pushgateway.)

Deprecated: Please use a Pusher created with New instead.

func HostnameGroupingKey

func HostnameGroupingKey() map[string]string

HostnameGroupingKey returns a label map with the only entry {instance="<hostname>"}. This can be conveniently used as the grouping parameter if metrics should be pushed with the hostname as label. The returned map is created upon each call so that the caller is free to add more labels to the map.

Deprecated: Usually, metrics pushed to the Pushgateway should not be host-centric. (You would use https://github.com/prometheus/node_exporter in that case.) If you have the need to add the hostname to the grouping key, you are probably doing something wrong. See https://prometheus.io/docs/practices/pushing/ for details.

Types

type Pusher

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

Pusher manages a push to the Pushgateway. Use New to create one, configure it with its methods, and finally use the Add or Push method to push.

func New

func New(url, job string) *Pusher

New creates a new Pusher to push to the provided URL with the provided job name. You can use just host:port or ip:port as url, in which case “http://” is added automatically. Alternatively, include the schema in the URL. However, do not include the “/metrics/jobs/…” part.

Note that until https://github.com/prometheus/pushgateway/issues/97 is resolved, a “/” character in the job name is prohibited.

func (*Pusher) Add

func (p *Pusher) Add() error

Add works like push, but only previously pushed metrics with the same name (and the same job and other grouping labels) will be replaced. (It uses HTTP method “POST” to push to the Pushgateway.)

Example

package main

import (
	"fmt"
	"time"

	"github.com/prometheus/client_golang/prometheus"
	"github.com/prometheus/client_golang/prometheus/push"
)

var (
	completionTime = prometheus.NewGauge(prometheus.GaugeOpts{
		Name: "db_backup_last_completion_timestamp_seconds",
		Help: "The timestamp of the last completion of a DB backup, successful or not.",
	})
	successTime = prometheus.NewGauge(prometheus.GaugeOpts{
		Name: "db_backup_last_success_timestamp_seconds",
		Help: "The timestamp of the last successful completion of a DB backup.",
	})
	duration = prometheus.NewGauge(prometheus.GaugeOpts{
		Name: "db_backup_duration_seconds",
		Help: "The duration of the last DB backup in seconds.",
	})
	records = prometheus.NewGauge(prometheus.GaugeOpts{
		Name: "db_backup_records_processed",
		Help: "The number of records processed in the last DB backup.",
	})
)

func performBackup() (int, error) {
	// Perform the backup and return the number of backed up records and any
	// applicable error.
	// ...
	return 42, nil
}

func main() {
	// We use a registry here to benefit from the consistency checks that
	// happen during registration.
	registry := prometheus.NewRegistry()
	registry.MustRegister(completionTime, duration, records)
	// Note that successTime is not registered.

	pusher := push.New("http://pushgateway:9091", "db_backup").Gatherer(registry)

	start := time.Now()
	n, err := performBackup()
	records.Set(float64(n))
	// Note that time.Since only uses a monotonic clock in Go1.9+.
	duration.Set(time.Since(start).Seconds())
	completionTime.SetToCurrentTime()
	if err != nil {
		fmt.Println("DB backup failed:", err)
	} else {
		// Add successTime to pusher only in case of success.
		// We could as well register it with the registry.
		// This example, however, demonstrates that you can
		// mix Gatherers and Collectors when handling a Pusher.
		pusher.Collector(successTime)
		successTime.SetToCurrentTime()
	}
	// Add is used here rather than Push to not delete a previously pushed
	// success timestamp in case of a failure of this backup.
	if err := pusher.Add(); err != nil {
		fmt.Println("Could not push to Pushgateway:", err)
	}
}

func (*Pusher) BasicAuth

func (p *Pusher) BasicAuth(username, password string) *Pusher

BasicAuth configures the Pusher to use HTTP Basic Authentication with the provided username and password. For convenience, this method returns a pointer to the Pusher itself.

func (*Pusher) Client

func (p *Pusher) Client(c *http.Client) *Pusher

Client sets a custom HTTP client for the Pusher. For convenience, this method returns a pointer to the Pusher itself.

func (*Pusher) Collector

func (p *Pusher) Collector(c prometheus.Collector) *Pusher

Collector adds a Collector to the Pusher, from which metrics will be collected to push them to the Pushgateway. The collected metrics must not contain a job label of their own.

For convenience, this method returns a pointer to the Pusher itself.

func (*Pusher) Gatherer

func (p *Pusher) Gatherer(g prometheus.Gatherer) *Pusher

Gatherer adds a Gatherer to the Pusher, from which metrics will be gathered to push them to the Pushgateway. The gathered metrics must not contain a job label of their own.

For convenience, this method returns a pointer to the Pusher itself.

func (*Pusher) Grouping

func (p *Pusher) Grouping(name, value string) *Pusher

Grouping adds a label pair to the grouping key of the Pusher, replacing any previously added label pair with the same label name. Note that setting any labels in the grouping key that are already contained in the metrics to push will lead to an error.

For convenience, this method returns a pointer to the Pusher itself.

Note that until https://github.com/prometheus/pushgateway/issues/97 is resolved, this method does not allow a “/” character in the label value.

func (*Pusher) Push

func (p *Pusher) Push() error

Push collects/gathers all metrics from all Collectors and Gatherers added to this Pusher. Then, it pushes them to the Pushgateway configured while creating this Pusher, using the configured job name and any added grouping labels as grouping key. All previously pushed metrics with the same job and other grouping labels will be replaced with the metrics pushed by this call. (It uses HTTP method “PUT” to push to the Pushgateway.)

Push returns the first error encountered by any method call (including this one) in the lifetime of the Pusher.

Example

package main

import (
	"fmt"

	"github.com/prometheus/client_golang/prometheus"
	"github.com/prometheus/client_golang/prometheus/push"
)

func main() {
	completionTime := prometheus.NewGauge(prometheus.GaugeOpts{
		Name: "db_backup_last_completion_timestamp_seconds",
		Help: "The timestamp of the last successful completion of a DB backup.",
	})
	completionTime.SetToCurrentTime()
	if err := push.New("http://pushgateway:9091", "db_backup").
		Collector(completionTime).
		Grouping("db", "customers").
		Push(); err != nil {
		fmt.Println("Could not push completion time to Pushgateway:", err)
	}
}