client

README

prom-metrics-client

A simple client that fetches and parses metrics from a prometheus /metrics endpoint.

https://prometheus.io/docs/instrumenting/exposition_formats/

Install

go get github.com/alanshaw/prom-metrics-client

Usage

Example

package main

import (
	pmc "github.com/alanshaw/prom-metrics-client"
)

func main() {
	c := pmc.PromMetricsClient{
		URL: "http://localhost:8888/metrics",
	}

	ms, _ := c.GetMetrics() // returns []*Metric

	for _, m := range ms {
		// histogram and summary metrics can be upgraded to "richer" types
		if m.Type == HistogramType {
			hm, _ := c.UpgradeHistogram(m)
			fmt.Printf("%+v\n", hm)
		} else if m.Type == SummaryType {
			sm, _ := c.UpgradeSummary(m)
			fmt.Printf("%+v\n", sm)
		} else {
			fmt.Printf("%+v\n", m)
		}
	}
}

/*
Example output:

&{Name:http_requests_total Description:The total number of HTTP requests. Type:counter Samples:[0xc00033e8a0 0xc00033e960]}
&{Name:msdos_file_access_time_seconds Description: Type: Samples:[0xc00033ea20]}
&{Name:metric_without_timestamp_and_labels Description: Type: Samples:[0xc00033eae0]}
&{Name:something_weird Description: Type: Samples:[0xc00033eb40]}
&{Metric:{Name:http_request_duration_seconds Description:A histogram of the request duration. Type:histogram Samples:[0xc00033ebd0 0xc00033ec60 0xc00033ecf0 0xc00033ed80 0xc00033ee10 0xc00033eea0 0xc00033ef30 0xc00033ef90]} Buckets:[0xc000015520 0xc000015530 0xc000015540 0xc000015550 0xc000015560 0xc000015570] Sum:53423 Count:144320}
&{Metric:{Name:rpc_duration_seconds Description:A summary of the RPC duration in seconds. Type:summary Samples:[0xc00033eff0 0xc00033f080 0xc00033f110 0xc00033f1a0 0xc00033f230 0xc00033f2c0 0xc00033f320]} Quantiles:[0xc0000155d0 0xc0000155e0 0xc0000155f0 0xc000015600 0xc000015610] Sum:1.7560473e+07 Count:2693}
*/

API

GoDoc Reference

Contribute

Feel free to dive in! Open an issue or submit PRs.

License

MIT © Alan Shaw

Documentation

Index

• Constants
• Variables
• type HistogramBucket
• type HistogramMetric
  • func UpgradeHistogram(m *Metric) (*HistogramMetric, error)
• type Metric
  • func Parse(r io.Reader) ([]*Metric, error)
• type MetricType
• type PromMetricsClient
  • func (c *PromMetricsClient) GetMetrics() ([]*Metric, error)
• type Sample
• type SummaryMetric
  • func UpgradeSummary(m *Metric) (*SummaryMetric, error)
• type SummaryQuantile

Constants

const (
	// Untyped is the metric type of metrics that have no specified type
	Untyped MetricType = ""
	// CounterType is a cumulative metric that represents a single monotonically increasing counter whose value can only increase or be reset to zero on restart.
	CounterType = "counter"
	// GaugeType is a metric that represents a single numerical value that can arbitrarily go up and down.
	GaugeType = "gauge"
	// HistogramType samples observations (usually things like request durations or response sizes) and counts them in configurable buckets.
	HistogramType = "histogram"
	// SummaryType samples observations (usually things like request durations and response sizes). While it also provides a total count of observations and a sum of all observed values, it calculates configurable quantiles over a sliding time window.
	SummaryType = "summary"
)

Variables

var ErrParseFail = fmt.Errorf("failed to parse line")

ErrParseFail is returned when parsing of metrics data fails

var ErrUnexpectedHTTPStatusCode = fmt.Errorf("unexpected HTTP status code")

ErrUnexpectedHTTPStatusCode is returned when the HTTP status is not 200

Types

type HistogramBucket

type HistogramBucket struct {
	LE    float64
	Value float64
}

HistogramBucket define the upper bound and value

type HistogramMetric

type HistogramMetric struct {
	Metric
	Buckets []*HistogramBucket
	Sum     float64
	Count   float64
}

HistogramMetric is a metric of type HistogramType

func UpgradeHistogram

func UpgradeHistogram(m *Metric) (*HistogramMetric, error)

UpgradeHistogram upgrades a Metric of type HistorgramType to a HistogramMetric

type Metric

type Metric struct {
	Name        string
	Description string
	Type        MetricType
	Samples     []*Sample
}

Metric is a parsed metric from the endpoint.

func Parse

func Parse(r io.Reader) ([]*Metric, error)

Parse reads raw metrics data from the reader, parses it and returns the result

type MetricType

type MetricType string

MetricType describes the type of the metric that was collected. See https://prometheus.io/docs/concepts/metric_types/

type PromMetricsClient

type PromMetricsClient struct {
	URL string
}

PromMetricsClient is a simple client that fetches and parses metrics from a prometheus /metrics endpoint.

func (*PromMetricsClient) GetMetrics

func (c *PromMetricsClient) GetMetrics() ([]*Metric, error)

GetMetrics retrieves metrics from the stored URL

type Sample

type Sample struct {
	Name      string
	Labels    map[string]string
	Value     float64
	Timestamp int64
}

Sample is a sample taken for a particular metric.

type SummaryMetric

type SummaryMetric struct {
	Metric
	Quantiles []*SummaryQuantile
	Sum       float64
	Count     float64
}

SummaryMetric is a metric of type SummaryType

func UpgradeSummary

func UpgradeSummary(m *Metric) (*SummaryMetric, error)

UpgradeSummary upgrades a Metric of type SummaryType to a SummaryMetric

type SummaryQuantile

type SummaryQuantile struct {
	Quantile float64
	Value    float64
}

SummaryQuantile defines the cut point and value