labels

package
v0.308.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 16, 2025 License: Apache-2.0 Imports: 18 Imported by: 1,106

Documentation

Index

Constants

View Source 
const (
	// MetricName is a special label name that represent a metric name.
	//
	// Deprecated: Use schema.Metadata structure and its methods.
	MetricName = "__name__"

	AlertName   = "alertname"
	BucketLabel = "le"
)

Variables

This section is empty.

Functions

func Compare 

func Compare(a, b Labels) int

Compare compares the two label sets. The result will be 0 if a==b, <0 if a < b, and >0 if a > b.

func Equal 

func Equal(ls, o Labels) bool

Equal returns whether the two label sets are equal.

func FormatOpenMetricsFloat added in v0.308.0 

func FormatOpenMetricsFloat(f float64) string

FormatOpenMetricsFloat works like the usual Go string formatting of a float but appends ".0" if the resulting number would otherwise contain neither a "." nor an "e".

func SizeOfLabels added in v0.301.0 

func SizeOfLabels(name, value string, n uint64) uint64

SizeOfLabels returns the approximate space required for n copies of a label.

func StableHash added in v0.51.0 

func StableHash(ls Labels) uint64

StableHash is a labels hashing implementation which is guaranteed to not change over time. This function should be used whenever labels hashing backward compatibility must be guaranteed.

Types

type Builder 

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

Builder allows modifying Labels.

func NewBuilder 

func NewBuilder(base Labels) *Builder

NewBuilder returns a new LabelsBuilder.

func NewBuilderWithSymbolTable added in v0.51.0 

func NewBuilderWithSymbolTable(*SymbolTable) *Builder

NewBuilderWithSymbolTable creates a Builder, for api parity with dedupelabels.

func (*Builder) Del 

func (b *Builder) Del(ns ...string) *Builder

Del deletes the label of the given name.

func (*Builder) Get added in v0.43.0 

func (b *Builder) Get(n string) string

func (*Builder) Keep added in v0.37.0 

func (b *Builder) Keep(ns ...string) *Builder

Keep removes all labels from the base except those with the given names.

func (*Builder) Labels 

func (b *Builder) Labels() Labels

Labels returns the labels from the builder. If no modifications were made, the original labels are returned.

func (*Builder) Range added in v0.43.0 

func (b *Builder) Range(f func(l Label))

Range calls f on each label in the Builder.

func (*Builder) Reset 

func (b *Builder) Reset(base Labels)

Reset clears all current state for the builder.

func (*Builder) Set 

func (b *Builder) Set(n, v string) *Builder

Set the name/value pair as a label. A value of "" means delete that label.

type FastRegexMatcher 

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

func NewFastRegexMatcher 

func NewFastRegexMatcher(v string) (*FastRegexMatcher, error)

func (*FastRegexMatcher) GetRegexString 

func (m *FastRegexMatcher) GetRegexString() string

func (*FastRegexMatcher) IsOptimized added in v0.52.0 

func (m *FastRegexMatcher) IsOptimized() bool

IsOptimized returns true if any fast-path optimization is applied to the regex matcher.

func (*FastRegexMatcher) MatchString 

func (m *FastRegexMatcher) MatchString(s string) bool

func (*FastRegexMatcher) SetMatches added in v0.52.0 

func (m *FastRegexMatcher) SetMatches() []string

type Label 

type Label struct {
	Name, Value string
}

Label is a key/value a pair of strings.

type Labels 

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

Labels is implemented by a single flat string holding name/value pairs. Each name and value is preceded by its length, encoded as a single byte for size 0-254, or the following 3 bytes little-endian, if the first byte is 255. Maximum length allowed is 2^24 or 16MB. Names are in order.

func EmptyLabels added in v0.39.0 

func EmptyLabels() Labels

EmptyLabels returns an empty Labels value, for convenience.

func FromMap 

func FromMap(m map[string]string) Labels

FromMap returns new sorted Labels from the given map.

func FromStrings 

func FromStrings(ss ...string) Labels

FromStrings creates new labels from pairs of strings.

func New 

func New(ls ...Label) Labels

New returns a sorted Labels from the given labels. The caller has to guarantee that all label names are unique.

func ReadLabels 

func ReadLabels(fn string, n int) ([]Labels, error)

ReadLabels reads up to n label sets in a JSON formatted file fn. It is mostly useful to load testing data.

func (Labels) ByteSize added in v0.306.0 

func (ls Labels) ByteSize() uint64

ByteSize returns the approximate size of the labels in bytes. String header size is ignored because it should be amortized to zero because it may be shared across multiple copies of the Labels.

func (Labels) Bytes 

func (ls Labels) Bytes(buf []byte) []byte

Bytes returns an opaque, not-human-readable, encoding of ls, usable as a map key. Encoding may change over time or between runs of Prometheus.

func (Labels) BytesWithLabels added in v0.37.0 

func (ls Labels) BytesWithLabels(buf []byte, names ...string) []byte

BytesWithLabels is just as Bytes(), but only for labels matching names. 'names' have to be sorted in ascending order.

func (Labels) BytesWithoutLabels added in v0.37.0 

func (ls Labels) BytesWithoutLabels(buf []byte, names ...string) []byte

BytesWithoutLabels is just as Bytes(), but only for labels not matching names. 'names' have to be sorted in ascending order.

func (Labels) Copy 

func (ls Labels) Copy() Labels

Copy returns a copy of the labels.

func (*Labels) CopyFrom added in v0.42.0 

func (ls *Labels) CopyFrom(b Labels)

CopyFrom will copy labels from b on top of whatever was in ls previously, reusing memory or expanding if needed.

func (Labels) DropMetricName deprecated added in v0.50.0 

func (ls Labels) DropMetricName() Labels

DropMetricName returns Labels with the "__name__" removed.

Deprecated: Use DropReserved instead.

func (Labels) DropReserved added in v0.305.0 

func (ls Labels) DropReserved(shouldDropFn func(name string) bool) Labels

DropReserved returns Labels without the chosen (via shouldDropFn) reserved (starting with underscore) labels.

func (Labels) Get 

func (ls Labels) Get(name string) string

Get returns the value for the label with the given name. Returns an empty string if the label doesn't exist.

func (Labels) Has 

func (ls Labels) Has(name string) bool

Has returns true if the label with the given name is present.

func (Labels) HasDuplicateLabelNames 

func (ls Labels) HasDuplicateLabelNames() (string, bool)

HasDuplicateLabelNames returns whether ls has duplicate label names. It assumes that the labelset is sorted.

func (Labels) Hash 

func (ls Labels) Hash() uint64

Hash returns a hash value for the label set. Note: the result is not guaranteed to be consistent across different runs of Prometheus.

func (Labels) HashForLabels 

func (ls Labels) HashForLabels(b []byte, names ...string) (uint64, []byte)

HashForLabels returns a hash value for the labels matching the provided names. 'names' have to be sorted in ascending order.

func (Labels) HashWithoutLabels 

func (ls Labels) HashWithoutLabels(b []byte, names ...string) (uint64, []byte)

HashWithoutLabels returns a hash value for all labels except those matching the provided names. 'names' have to be sorted in ascending order.

func (*Labels) InternStrings added in v0.42.0 

func (*Labels) InternStrings(func(string) string)

InternStrings is a no-op because it would only save when the whole set of labels is identical.

func (Labels) IsEmpty added in v0.42.0 

func (ls Labels) IsEmpty() bool

IsEmpty returns true if ls represents an empty set of labels.

func (Labels) IsValid added in v0.41.0 

func (ls Labels) IsValid(validationScheme model.ValidationScheme) bool

IsValid checks if the metric name or label names are valid.

func (Labels) IsZero added in v0.305.0 

func (ls Labels) IsZero() bool

IsZero implements yaml.IsZeroer - if we don't have this then 'omitempty' fields are always omitted.

func (Labels) Len 

func (ls Labels) Len() int

Len returns the number of labels; it is relatively slow.

func (Labels) Map 

func (ls Labels) Map() map[string]string

Map returns a string map of the labels.

func (Labels) MarshalJSON 

func (ls Labels) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (Labels) MarshalYAML 

func (ls Labels) MarshalYAML() (any, error)

MarshalYAML implements yaml.Marshaler.

func (Labels) MatchLabels 

func (ls Labels) MatchLabels(on bool, names ...string) Labels

MatchLabels returns a subset of Labels that matches/does not match with the provided label names based on the 'on' boolean. If on is set to true, it returns the subset of labels that match with the provided label names and its inverse when 'on' is set to false. TODO: This is only used in printing an error message.

func (Labels) Range added in v0.42.0 

func (ls Labels) Range(f func(l Label))

Range calls f on each label.

func (Labels) ReleaseStrings added in v0.42.0 

func (Labels) ReleaseStrings(func(string))

ReleaseStrings is a no-op for the same reason as InternStrings.

func (Labels) String 

func (ls Labels) String() string

func (Labels) StringNoSpace added in v0.307.0 

func (ls Labels) StringNoSpace() string

StringNoSpace is like String but does not add a space after commas.

func (*Labels) UnmarshalJSON 

func (ls *Labels) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler.

func (*Labels) UnmarshalYAML 

func (ls *Labels) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML implements yaml.Unmarshaler.

func (Labels) Validate added in v0.42.0 

func (ls Labels) Validate(f func(l Label) error) error

Validate calls f on each label. If f returns a non-nil error, then it returns that error cancelling the iteration.

func (Labels) WithoutEmpty 

func (ls Labels) WithoutEmpty() Labels

WithoutEmpty returns the labelset without empty labels. May return the same labelset.

type MatchType 

type MatchType int

MatchType is an enum for label matching types. 

const (
	MatchEqual MatchType = iota
	MatchNotEqual
	MatchRegexp
	MatchNotRegexp
)

Possible MatchTypes.

func (MatchType) String 

func (m MatchType) String() string

type Matcher 

type Matcher struct {
	Type  MatchType
	Name  string
	Value string
	// contains filtered or unexported fields
}

Matcher models the matching of a label.

func MustNewMatcher 

func MustNewMatcher(mt MatchType, name, val string) *Matcher

MustNewMatcher panics on error - only for use in tests!

func NewMatcher 

func NewMatcher(t MatchType, n, v string) (*Matcher, error)

NewMatcher returns a matcher object.

func (*Matcher) GetRegexString 

func (m *Matcher) GetRegexString() string

GetRegexString returns the regex string.

func (*Matcher) Inverse 

func (m *Matcher) Inverse() (*Matcher, error)

Inverse returns a matcher that matches the opposite.

func (*Matcher) IsRegexOptimized added in v0.52.0 

func (m *Matcher) IsRegexOptimized() bool

IsRegexOptimized returns whether regex is optimized.

func (*Matcher) Matches 

func (m *Matcher) Matches(s string) bool

Matches returns whether the matcher matches the given string value.

func (*Matcher) Prefix added in v0.52.0 

func (m *Matcher) Prefix() string

Prefix returns the required prefix of the value to match, if possible. It will be empty if it's an equality matcher or if the prefix can't be determined.

func (*Matcher) SetMatches added in v0.52.0 

func (m *Matcher) SetMatches() []string

SetMatches returns a set of equality matchers for the current regex matchers if possible. For examples the regexp `a(b|f)` will returns "ab" and "af". Returns nil if we can't replace the regexp by only equality matchers.

func (*Matcher) String 

func (m *Matcher) String() string

type ScratchBuilder added in v0.42.0 

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

ScratchBuilder allows efficient construction of a Labels from scratch.

func NewScratchBuilder added in v0.42.0 

func NewScratchBuilder(n int) ScratchBuilder

NewScratchBuilder creates a ScratchBuilder initialized for Labels with n entries.

func NewScratchBuilderWithSymbolTable added in v0.51.0 

func NewScratchBuilderWithSymbolTable(_ *SymbolTable, n int) ScratchBuilder

NewScratchBuilderWithSymbolTable creates a ScratchBuilder, for api parity with dedupelabels.

func (*ScratchBuilder) Add added in v0.42.0 

func (b *ScratchBuilder) Add(name, value string)

Add a name/value pair. Note if you Add the same name twice you will get a duplicate label, which is invalid. The values must remain live until Labels() is called.

func (*ScratchBuilder) Assign added in v0.42.0 

func (b *ScratchBuilder) Assign(l Labels)

Assign is for when you already have a Labels which you want this ScratchBuilder to return.

func (*ScratchBuilder) Labels added in v0.42.0 

func (b *ScratchBuilder) Labels() Labels

Labels returns the name/value pairs added as a Labels object. Calling Add() after Labels() has no effect. Note: if you want them sorted, call Sort() first.

func (*ScratchBuilder) Overwrite added in v0.44.0 

func (b *ScratchBuilder) Overwrite(ls *Labels)

Overwrite will write the newly-built Labels out to ls, reusing an internal buffer. Callers must ensure that there are no other references to ls, or any strings fetched from it.

func (*ScratchBuilder) Reset added in v0.42.0 

func (b *ScratchBuilder) Reset()

func (*ScratchBuilder) SetSymbolTable added in v0.51.0 

func (*ScratchBuilder) SetSymbolTable(*SymbolTable)

func (ScratchBuilder) SetUnsafeAdd added in v0.308.0 

func (ScratchBuilder) SetUnsafeAdd(bool)

SetUnsafeAdd allows turning on/off the assumptions that added strings are unsafe for reuse. ScratchBuilder implementations that do reuse strings, must clone the strings.

StringLabels implementation copies all strings when Labels() is called, so this operation is noop.

func (*ScratchBuilder) Sort added in v0.42.0 

func (b *ScratchBuilder) Sort()

Sort the labels added so far by name.

type Selector 

type Selector []*Matcher

Selector holds constraints for matching against a label set.

func (Selector) Matches 

func (s Selector) Matches(labels Labels) bool

Matches returns whether the labels satisfy all matchers.

type Slice 

type Slice []Labels

Slice is a sortable slice of label sets.

func (Slice) Len 

func (s Slice) Len() int

func (Slice) Less 

func (s Slice) Less(i, j int) bool

func (Slice) Swap 

func (s Slice) Swap(i, j int)

type StringMatcher added in v0.52.0 

type StringMatcher interface {
	Matches(s string) bool
}

StringMatcher is a matcher that matches a string in place of a regular expression.

type SymbolTable added in v0.51.0 

type SymbolTable struct{}

SymbolTable is no-op, just for api parity with dedupelabels.

func NewSymbolTable added in v0.51.0 

func NewSymbolTable() *SymbolTable

func (*SymbolTable) Len added in v0.51.0 

func (*SymbolTable) Len() int

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.