text

Documentation

Overview

Package text contains helper functions to parse and create text-based exchange formats. The package currently supports (only) version 0.0.4 of the exchange format. Should other versions be supported in the future, some versioning scheme has to be applied. Possibilities include separate packages or separate functions. The best way depends on the nature of future changes, which is the reason why no versioning scheme has been applied prematurely here.

Index

• func MetricFamilyToText(out io.Writer, in *dto.MetricFamily) (int, error)
• func WriteProtoCompactText(w io.Writer, p *dto.MetricFamily) (int, error)
• func WriteProtoDelimited(w io.Writer, p *dto.MetricFamily) (int, error)
• func WriteProtoText(w io.Writer, p *dto.MetricFamily) (int, error)
• type ParseError
  • func (e ParseError) Error() string
• type Parser
  • func (p *Parser) TextToMetricFamilies(in io.Reader) (map[string]*dto.MetricFamily, error)

Functions

func MetricFamilyToText

func MetricFamilyToText(out io.Writer, in *dto.MetricFamily) (int, 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. This function does not perform checks on the content of the metric and label names, i.e. invalid metric or label names will result in invalid text format output. This method fulfills the type 'prometheus.encoder'.

func WriteProtoCompactText

func WriteProtoCompactText(w io.Writer, p *dto.MetricFamily) (int, error)

WriteProtoCompactText writes the MetricFamily to the writer in compact text format and returns the number of bytes written and any error encountered.

func WriteProtoDelimited

func WriteProtoDelimited(w io.Writer, p *dto.MetricFamily) (int, error)

WriteProtoDelimited writes the MetricFamily to the writer in delimited protobuf format and returns the number of bytes written and any error encountered.

func WriteProtoText

func WriteProtoText(w io.Writer, p *dto.MetricFamily) (int, error)

WriteProtoText writes the MetricFamily to the writer in text format and returns the number of bytes written and any error encountered.

Types

type ParseError

type ParseError struct {
	Line int
	Msg  string
}

ParseError signals errors while parsing the simple and flat text-based exchange format.

func (ParseError) Error

func (e ParseError) Error() string

Error implements the error interface.

type Parser

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

Parser is used to parse the simple and flat text-based exchange format. Its nil value is ready to use.

func (*Parser) TextToMetricFamilies

func (p *Parser) TextToMetricFamilies(in io.Reader) (map[string]*dto.MetricFamily, error)

TextToMetricFamilies reads 'in' as the simple and flat text-based exchange format and creates MetricFamily proto messages. It returns the MetricFamily proto messages in a map where the metric names are the keys, along with any error encountered.

If the input contains duplicate metrics (i.e. lines with the same metric name and exactly the same label set), the resulting MetricFamily will contain duplicate Metric proto messages. Similar is true for duplicate label names. Checks for duplicates have to be performed separately, if required. Also note that neither the metrics within each MetricFamily are sorted nor the label pairs within each Metric. Sorting is not required for the most frequent use of this method, which is sample ingestion in the Prometheus server. However, for presentation purposes, you might want to sort the metrics, and in some cases, you must sort the labels, e.g. for consumption by the metric family injection hook of the Prometheus registry.

Summaries and histograms are rather special beasts. You would probably not use them in the simple text format anyway. This method can deal with summaries and histograms if they are presented in exactly the way the text.Create function creates them.

This method must not be called concurrently. If you want to parse different input concurrently, instantiate a separate Parser for each goroutine.