push

Documentation

Overview

Package push provides functions to push metrics to a Pushgateway. The metrics to push are either collected from a provided registry, or from explicitly listed collectors.

See the documentation of the Pushgateway to understand the meaning of the grouping parameters and the differences between push.Registry and push.Collectors on the one hand and push.AddRegistry and push.AddCollectors on the other hand: 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

Examples

• AddFromGatherer
• Collectors

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.

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.)

Example

// Copyright (c) 2013, The Prometheus Authors
// All rights reserved.
//
// Use of this source code is governed by a BSD-style license that can be found
// in the LICENSE file.

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() {
	registry := prometheus.NewRegistry()
	registry.MustRegister(completionTime, duration, records)
	// Note that successTime is not registered at this time.

	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 {
		// Only now register successTime.
		registry.MustRegister(successTime)
		successTime.SetToCurrentTime()
	}
	// AddFromGatherer is used here rather than FromGatherer to not delete a
	// previously pushed success timestamp in case of a failure of this
	// backup.
	if err := push.AddFromGatherer(
		"db_backup", nil,
		"http://pushgateway:9091",
		registry,
	); err != nil {
		fmt.Println("Could not push to Pushgateway:", err)
	}
}

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.

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.Collectors(
		"db_backup", push.HostnameGroupingKey(),
		"http://pushgateway:9091",
		completionTime,
	); err != nil {
		fmt.Println("Could not push completion time to Pushgateway:", err)
	}
}

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.)

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.