expfmt

Documentation

Overview

Package expfmt contains tools for reading and writing Prometheus metrics.

Index

• Constants
• func FinalizeOpenMetrics(w io.Writer) (written int, err error)
• func MetricFamilyToOpenMetrics(out io.Writer, in *dto.MetricFamily) (written int, err error)
• func MetricFamilyToText(out io.Writer, in *dto.MetricFamily) (written int, err error)
• type Closer
• type Encoder
  • func NewEncoder(w io.Writer, format Format) Encoder
• type Format
  • func Negotiate(h http.Header) Format
  • func NegotiateIncludingOpenMetrics(h http.Header) Format

Constants

const (
	TextVersion        = "0.0.4"
	ProtoType          = `application/vnd.google.protobuf`
	ProtoProtocol      = `io.prometheus.client.MetricFamily`
	ProtoFmt           = ProtoType + "; proto=" + ProtoProtocol + ";"
	OpenMetricsType    = `application/openmetrics-text`
	OpenMetricsVersion = "0.0.1"

	// The Content-Type values for the different wire protocols.
	FmtUnknown      Format = `<unknown>`
	FmtText         Format = `text/plain; version=` + TextVersion + `; charset=utf-8`
	FmtProtoDelim   Format = ProtoFmt + ` encoding=delimited`
	FmtProtoText    Format = ProtoFmt + ` encoding=text`
	FmtProtoCompact Format = ProtoFmt + ` encoding=compact-text`
	FmtOpenMetrics  Format = OpenMetricsType + `; version=` + OpenMetricsVersion + `; charset=utf-8`
)

Constants to assemble the Content-Type values for the different wire protocols.

Functions

func FinalizeOpenMetrics

func FinalizeOpenMetrics(w io.Writer) (written int, err error)

FinalizeOpenMetrics writes the final `# EOF\n` line required by OpenMetrics.

func MetricFamilyToOpenMetrics

func MetricFamilyToOpenMetrics(out io.Writer, in *dto.MetricFamily) (written int, err error)

MetricFamilyToOpenMetrics converts a MetricFamily proto message into the OpenMetrics text format and writes the resulting lines to 'out'. It returns the number of bytes written and any error encountered. The output will have the same order as the input, no further sorting is performed. Furthermore, this function assumes the input is already sanitized and does not perform any sanity checks. If the input contains duplicate metrics or invalid metric or label names, the conversion will result in invalid text format output.

This function fulfills the type 'expfmt.encoder'.

Note that OpenMetrics requires a final `# EOF` line. Since this function acts on individual metric families, it is the responsibility of the caller to append this line to 'out' once all metric families have been written. Conveniently, this can be done by calling FinalizeOpenMetrics.

The output should be fully OpenMetrics compliant. However, there are a few missing features and peculiarities to avoid complications when switching from Prometheus to OpenMetrics or vice versa:

• Counters are expected to have the `_total` suffix in their metric name. In the output, the suffix will be truncated from the `# TYPE` and `# HELP` line. A counter with a missing `_total` suffix is not an error. However, its type will be set to `unknown` in that case to avoid invalid OpenMetrics output.

• No support for the following (optional) features: `# UNIT` line, `_created` line, info type, stateset type, gaugehistogram type.

• The size of exemplar labels is not checked (i.e. it's possible to create exemplars that are larger than allowed by the OpenMetrics specification).

• The value of Counters is not checked. (OpenMetrics doesn't allow counters with a `NaN` value.)

func MetricFamilyToText

func MetricFamilyToText(out io.Writer, in *dto.MetricFamily) (written int, err error)

MetricFamilyToText converts a MetricFamily proto message into text format and writes the resulting lines to 'out'. It returns the number of bytes written and any error encountered. The output will have the same order as the input, no further sorting is performed. Furthermore, this function assumes the input is already sanitized and does not perform any sanity checks. If the input contains duplicate metrics or invalid metric or label names, the conversion will result in invalid text format output.

This method fulfills the type 'prometheus.encoder'.

Types

type Closer

type Closer interface {
	Close() error
}

Closer is implemented by Encoders that need to be closed to finalize encoding. (For example, OpenMetrics needs a final `# EOF` line.)

Note that all Encoder implementations returned from this package implement Closer, too, even if the Close call is a no-op. This happens in preparation for adding a Close method to the Encoder interface directly in a (mildly breaking) release in the future.

type Encoder

type Encoder interface {
	Encode(*dto.MetricFamily) error
}

Encoder types encode metric families into an underlying wire protocol.

func NewEncoder

func NewEncoder(w io.Writer, format Format) Encoder

NewEncoder returns a new encoder based on content type negotiation. All Encoder implementations returned by NewEncoder also implement Closer, and callers should always call the Close method. It is currently only required for FmtOpenMetrics, but a future (breaking) release will add the Close method to the Encoder interface directly. The current version of the Encoder interface is kept for backwards compatibility.

type Format

type Format string

Format specifies the HTTP content type of the different wire protocols.

func Negotiate

func Negotiate(h http.Header) Format

Negotiate returns the Content-Type based on the given Accept header. If no appropriate accepted type is found, FmtText is returned (which is the Prometheus text format). This function will never negotiate FmtOpenMetrics, as the support is still experimental. To include the option to negotiate FmtOpenMetrics, use NegotiateOpenMetrics.

func NegotiateIncludingOpenMetrics

func NegotiateIncludingOpenMetrics(h http.Header) Format

NegotiateIncludingOpenMetrics works like Negotiate but includes FmtOpenMetrics as an option for the result. Note that this function is temporary and will disappear once FmtOpenMetrics is fully supported and as such may be negotiated by the normal Negotiate function.