Documentation

Overview

    Package expfmt contains tools for reading and writing Prometheus metrics.

    Index

    Constants

    View Source
    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.

      Variables

      This section is empty.

      Functions

      func ExtractSamples

      func ExtractSamples(o *DecodeOptions, fams ...*dto.MetricFamily) (model.Vector, error)

        ExtractSamples builds a slice of samples from the provided metric families. If an error occurs during sample extraction, it continues to extract from the remaining metric families. The returned error is the last error that has occurred.

        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 DecodeOptions

                type DecodeOptions struct {
                	// Timestamp is added to each value from the stream that has no explicit timestamp set.
                	Timestamp model.Time
                }

                  DecodeOptions contains options used by the Decoder and in sample extraction.

                  type Decoder

                  type Decoder interface {
                  	Decode(*dto.MetricFamily) error
                  }

                    Decoder types decode an input stream into metric families.

                    func NewDecoder

                    func NewDecoder(r io.Reader, format Format) Decoder

                      NewDecoder returns a new decoder based on the given input format. If the input format does not imply otherwise, a text format decoder is returned.

                      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.

                                func ResponseFormat

                                func ResponseFormat(h http.Header) Format

                                  ResponseFormat extracts the correct format from a HTTP response header. If no matching format can be found FormatUnknown is returned.

                                  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 SampleDecoder

                                      type SampleDecoder struct {
                                      	Dec  Decoder
                                      	Opts *DecodeOptions
                                      	// contains filtered or unexported fields
                                      }

                                        SampleDecoder wraps a Decoder to extract samples from the metric families decoded by the wrapped Decoder.

                                        func (*SampleDecoder) Decode

                                        func (sd *SampleDecoder) Decode(s *model.Vector) error

                                          Decode calls the Decode method of the wrapped Decoder and then extracts the samples from the decoded MetricFamily into the provided model.Vector.

                                          type TextParser

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

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

                                            func (*TextParser) TextToMetricFamilies

                                            func (p *TextParser) 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.

                                              Notes

                                              Bugs

                                                • Update other names to "quantile".