schema

Documentation

Index

• func IsMetadataLabel(name string) bool
• type IgnoreOverriddenMetadataLabelsScratchBuilder
  • func (b IgnoreOverriddenMetadataLabelsScratchBuilder) Add(name, value string)
• type Metadata
  • func NewMetadataFromLabels(ls labels.Labels) Metadata
  • func (m Metadata) AddToLabels(b *labels.ScratchBuilder)
  • func (m Metadata) IsEmptyFor(labelName string) bool
  • func (m Metadata) IsTypeEmpty() bool
  • func (m Metadata) SetToLabels(b *labels.Builder)

Functions

func IsMetadataLabel

func IsMetadataLabel(name string) bool

IsMetadataLabel returns true if the given label name is a special schema Metadata label.

Types

type IgnoreOverriddenMetadataLabelsScratchBuilder

type IgnoreOverriddenMetadataLabelsScratchBuilder struct {
	*labels.ScratchBuilder

	Overwrite Metadata
}

IgnoreOverriddenMetadataLabelsScratchBuilder is a wrapper over labels scratch builder that ignores label additions that would collide with non-empty Overwrite Metadata fields.

func (IgnoreOverriddenMetadataLabelsScratchBuilder) Add

func (b IgnoreOverriddenMetadataLabelsScratchBuilder) Add(name, value string)

Add a name/value pair, unless it would collide with the non-empty Overwrite Metadata field. Note if you Add the same name twice you will get a duplicate label, which is invalid.

type Metadata

type Metadata struct {
	// Name represents the final metric name for a Prometheus series.
	// NOTE(bwplotka): Prometheus scrape formats (e.g. OpenMetrics) define
	// the "metric family name". The Metadata.Name (so __name__ label) is not
	// always the same as the MetricFamily.Name e.g.:
	// * OpenMetrics metric family name on scrape: "acme_http_router_request_seconds"
	// * Resulting Prometheus metric name: "acme_http_router_request_seconds_sum"
	//
	// Empty string means nameless metric (e.g. result of the PromQL function).
	Name string
	// Type represents the metric type. Empty value ("") is equivalent to
	// model.UnknownMetricType.
	Type model.MetricType
	// Unit represents the metric unit. Empty string means an unitless metric (e.g.
	// result of the PromQL function).
	//
	// NOTE: Currently unit value is not strictly defined other than OpenMetrics
	// recommendations: https://prometheus.io/docs/specs/om/open_metrics_spec/#units-and-base-units
	// TODO(bwplotka): Consider a stricter validation and rules e.g. lowercase only or UCUM standard.
	// Read more in https://github.com/prometheus/proposals/blob/main/proposals/2024-09-25_metadata-labels.md#more-strict-unit-and-type-value-definition
	Unit string
}

Metadata represents the core metric schema/metadata elements that: * are describing and identifying the metric schema/shape (e.g. name, type and unit). * are contributing to the general metric/series identity. * with the type-and-unit feature, are stored as Prometheus labels.

Historically, similar information was encoded in the labels.MetricName (suffixes) and in the separate metadata.Metadata structures. However, with the type-and-unit-label feature (PROM-39), this information can be now stored directly in the special schema metadata labels, which offers better reliability (e.g. atomicity), compatibility and, in many cases, efficiency.

NOTE: Metadata in the current form is generally similar (yet different) to:

• The MetricFamily definition in OpenMetrics (https://prometheus.io/docs/specs/om/open_metrics_spec/#metricfamily). However, there is a small and important distinction around the metric name semantics for the "classic" representation of complex metrics like histograms. The Metadata.Name follows the __name__ semantics. See Name for details.
• Original metadata.Metadata entries. However, not all fields in that metadata are "identifiable", notably the help field, plus metadata does not contain Name.

func NewMetadataFromLabels

func NewMetadataFromLabels(ls labels.Labels) Metadata

NewMetadataFromLabels returns the schema metadata from the labels.

func (Metadata) AddToLabels

func (m Metadata) AddToLabels(b *labels.ScratchBuilder)

AddToLabels adds metric schema metadata as labels into the labels.ScratchBuilder. Empty Metadata fields will be ignored (not added).

func (Metadata) IsEmptyFor

func (m Metadata) IsEmptyFor(labelName string) bool

IsEmptyFor returns true if the Metadata field, represented by the given labelName is empty (not set). If the labelName in not representing any Metadata field, IsEmptyFor returns true.

func (Metadata) IsTypeEmpty

func (m Metadata) IsTypeEmpty() bool

IsTypeEmpty returns true if the metric type is empty (not set).

func (Metadata) SetToLabels

func (m Metadata) SetToLabels(b *labels.Builder)

SetToLabels injects metric schema metadata as labels into the labels.Builder. It follows the labels.Builder.Set semantics, so empty Metadata fields will remove the corresponding existing labels if they were previously set.