Documentation

Overview

    Package label provides key and value labels.

    This package is currently in a pre-GA phase. Backwards incompatible changes may be introduced in subsequent minor version releases as we work to track the evolving OpenTelemetry specification and user feedback.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    func NewSetWithFiltered

    func NewSetWithFiltered(kvs []KeyValue, filter Filter) (Set, []KeyValue)

      NewSetWithFiltered returns a new `Set`. See the documentation for `NewSetWithSortableFiltered` for more details.

      This call includes a `Filter` to include/exclude label keys from the return value. Excluded keys are returned as a slice of label values.

      func NewSetWithSortableFiltered

      func NewSetWithSortableFiltered(kvs []KeyValue, tmp *Sortable, filter Filter) (Set, []KeyValue)

        NewSetWithSortableFiltered returns a new `Set`.

        Duplicate keys are eliminated by taking the last value. This re-orders the input slice so that unique last-values are contiguous at the end of the slice.

        This ensures the following:

        - Last-value-wins semantics - Caller sees the reordering, but doesn't lose values - Repeated call preserve last-value wins.

        Note that methods are defined on `*Set`, although this returns `Set`. Callers can avoid memory allocations by:

        - allocating a `Sortable` for use as a temporary in this method - allocating a `Set` for storing the return value of this

        constructor.
        

        The result maintains a cache of encoded labels, by label.EncoderID. This value should not be copied after its first use.

        The second `[]KeyValue` return value is a list of labels that were excluded by the Filter (if non-nil).

        Types

        type Distinct

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

          Distinct wraps a variable-size array of `KeyValue`, constructed with keys in sorted order. This can be used as a map key or for equality checking between Sets.

          func (Distinct) Valid

          func (d Distinct) Valid() bool

            Valid returns true if this value refers to a valid `*Set`.

            type Encoder

            type Encoder interface {
            	// Encode returns the serialized encoding of the label
            	// set using its Iterator.  This result may be cached
            	// by a label.Set.
            	Encode(iterator Iterator) string
            
            	// ID returns a value that is unique for each class of
            	// label encoder.  Label encoders allocate these using
            	// `NewEncoderID`.
            	ID() EncoderID
            }

              Encoder is a mechanism for serializing a label set into a specific string representation that supports caching, to avoid repeated serialization. An example could be an exporter encoding the label set into a wire representation.

              func DefaultEncoder

              func DefaultEncoder() Encoder

                DefaultEncoder returns a label encoder that encodes labels in such a way that each escaped label's key is followed by an equal sign and then by an escaped label's value. All key-value pairs are separated by a comma.

                Escaping is done by prepending a backslash before either a backslash, equal sign or a comma.

                type EncoderID

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

                  EncoderID is used to identify distinct Encoder implementations, for caching encoded results.

                  func NewEncoderID

                  func NewEncoderID() EncoderID

                    NewEncoderID returns a unique label encoder ID. It should be called once per each type of label encoder. Preferably in init() or in var definition.

                    func (EncoderID) Valid

                    func (id EncoderID) Valid() bool

                      Valid returns true if this encoder ID was allocated by `NewEncoderID`. Invalid encoder IDs will not be cached.

                      type Filter

                      type Filter func(KeyValue) bool

                        Filter supports removing certain labels from label sets. When the filter returns true, the label will be kept in the filtered label set. When the filter returns false, the label is excluded from the filtered label set, and the label instead appears in the `removed` list of excluded labels.

                        type Iterator

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

                          Iterator allows iterating over the set of labels in order, sorted by key.

                          func (*Iterator) Attribute

                          func (i *Iterator) Attribute() KeyValue

                            Attribute is a synonym for Label().

                            func (*Iterator) IndexedLabel

                            func (i *Iterator) IndexedLabel() (int, KeyValue)

                              IndexedLabel returns current index and label. Must be called only after Next returns true.

                              func (*Iterator) Label

                              func (i *Iterator) Label() KeyValue

                                Label returns current KeyValue. Must be called only after Next returns true.

                                func (*Iterator) Len

                                func (i *Iterator) Len() int

                                  Len returns a number of labels in the iterator's `*Set`.

                                  func (*Iterator) Next

                                  func (i *Iterator) Next() bool

                                    Next moves the iterator to the next position. Returns false if there are no more labels.

                                    func (*Iterator) ToSlice

                                    func (i *Iterator) ToSlice() []KeyValue

                                      ToSlice is a convenience function that creates a slice of labels from the passed iterator. The iterator is set up to start from the beginning before creating the slice.

                                      type Key

                                      type Key string

                                        Key represents the key part in key-value pairs. It's a string. The allowed character set in the key depends on the use of the key.

                                        func (Key) Array

                                        func (k Key) Array(v interface{}) KeyValue

                                          Array creates a KeyValue instance with a ARRAY Value.

                                          If creating both key and a array value at the same time, then instead of calling Key(name).String(value) consider using a convenience function provided by the api/key package - key.Array(name, value).

                                          func (Key) Bool

                                          func (k Key) Bool(v bool) KeyValue

                                            Bool creates a KeyValue instance with a BOOL Value.

                                            If creating both key and a bool value at the same time, then instead of calling Key(name).Bool(value) consider using a convenience function provided by the api/key package - key.Bool(name, value).

                                            func (Key) Defined

                                            func (k Key) Defined() bool

                                              Defined returns true for non-empty keys.

                                              func (Key) Float32

                                              func (k Key) Float32(v float32) KeyValue

                                                Float32 creates a KeyValue instance with a FLOAT32 Value.

                                                If creating both key and a float32 value at the same time, then instead of calling Key(name).Float32(value) consider using a convenience function provided by the api/key package - key.Float32(name, value).

                                                func (Key) Float64

                                                func (k Key) Float64(v float64) KeyValue

                                                  Float64 creates a KeyValue instance with a FLOAT64 Value.

                                                  If creating both key and a float64 value at the same time, then instead of calling Key(name).Float64(value) consider using a convenience function provided by the api/key package - key.Float64(name, value).

                                                  func (Key) Int

                                                  func (k Key) Int(v int) KeyValue

                                                    Int creates a KeyValue instance with either an INT32 or an INT64 Value, depending on whether the int type is 32 or 64 bits wide.

                                                    If creating both key and an int value at the same time, then instead of calling Key(name).Int(value) consider using a convenience function provided by the api/key package - key.Int(name, value).

                                                    func (Key) Int32

                                                    func (k Key) Int32(v int32) KeyValue

                                                      Int32 creates a KeyValue instance with an INT32 Value.

                                                      If creating both key and an int32 value at the same time, then instead of calling Key(name).Int32(value) consider using a convenience function provided by the api/key package - key.Int32(name, value).

                                                      func (Key) Int64

                                                      func (k Key) Int64(v int64) KeyValue

                                                        Int64 creates a KeyValue instance with an INT64 Value.

                                                        If creating both key and an int64 value at the same time, then instead of calling Key(name).Int64(value) consider using a convenience function provided by the api/key package - key.Int64(name, value).

                                                        func (Key) String

                                                        func (k Key) String(v string) KeyValue

                                                          String creates a KeyValue instance with a STRING Value.

                                                          If creating both key and a string value at the same time, then instead of calling Key(name).String(value) consider using a convenience function provided by the api/key package - key.String(name, value).

                                                          func (Key) Uint

                                                          func (k Key) Uint(v uint) KeyValue

                                                            Uint creates a KeyValue instance with either a UINT32 or a UINT64 Value, depending on whether the uint type is 32 or 64 bits wide.

                                                            If creating both key and a uint value at the same time, then instead of calling Key(name).Uint(value) consider using a convenience function provided by the api/key package - key.Uint(name, value).

                                                            func (Key) Uint32

                                                            func (k Key) Uint32(v uint32) KeyValue

                                                              Uint32 creates a KeyValue instance with a UINT32 Value.

                                                              If creating both key and a uint32 value at the same time, then instead of calling Key(name).Uint32(value) consider using a convenience function provided by the api/key package - key.Uint32(name, value).

                                                              func (Key) Uint64

                                                              func (k Key) Uint64(v uint64) KeyValue

                                                                Uint64 creates a KeyValue instance with a UINT64 Value.

                                                                If creating both key and a uint64 value at the same time, then instead of calling Key(name).Uint64(value) consider using a convenience function provided by the api/key package - key.Uint64(name, value).

                                                                type KeyValue

                                                                type KeyValue struct {
                                                                	Key   Key
                                                                	Value Value
                                                                }

                                                                  KeyValue holds a key and value pair.

                                                                  func Any

                                                                  func Any(k string, value interface{}) KeyValue

                                                                    Any creates a new key-value pair instance with a passed name and automatic type inference. This is slower, and not type-safe.

                                                                    func Array

                                                                    func Array(k string, v interface{}) KeyValue

                                                                      Array creates a new key-value pair with a passed name and a array. Only arrays of primitive type are supported.

                                                                      func Bool

                                                                      func Bool(k string, v bool) KeyValue

                                                                        Bool creates a new key-value pair with a passed name and a bool value.

                                                                        func Float32

                                                                        func Float32(k string, v float32) KeyValue

                                                                          Float32 creates a new key-value pair with a passed name and a float32 value.

                                                                          func Float64

                                                                          func Float64(k string, v float64) KeyValue

                                                                            Float64 creates a new key-value pair with a passed name and a float64 value.

                                                                            func Int

                                                                            func Int(k string, v int) KeyValue

                                                                              Int creates a new key-value pair instance with a passed name and either an int32 or an int64 value, depending on whether the int type is 32 or 64 bits wide.

                                                                              func Int32

                                                                              func Int32(k string, v int32) KeyValue

                                                                                Int32 creates a new key-value pair with a passed name and an int32 value.

                                                                                func Int64

                                                                                func Int64(k string, v int64) KeyValue

                                                                                  Int64 creates a new key-value pair with a passed name and an int64 value.

                                                                                  func String

                                                                                  func String(k, v string) KeyValue

                                                                                    String creates a new key-value pair with a passed name and a string value.

                                                                                    func Stringer

                                                                                    func Stringer(k string, v fmt.Stringer) KeyValue

                                                                                      Stringer creates a new key-value pair with a passed name and a string value generated by the passed Stringer interface.

                                                                                      func Uint

                                                                                      func Uint(k string, v uint) KeyValue

                                                                                        Uint creates a new key-value pair instance with a passed name and either an uint32 or an uint64 value, depending on whether the uint type is 32 or 64 bits wide.

                                                                                        func Uint32

                                                                                        func Uint32(k string, v uint32) KeyValue

                                                                                          Uint32 creates a new key-value pair with a passed name and a uint32 value.

                                                                                          func Uint64

                                                                                          func Uint64(k string, v uint64) KeyValue

                                                                                            Uint64 creates a new key-value pair with a passed name and a uint64 value.

                                                                                            type MergeIterator

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

                                                                                              MergeIterator supports iterating over two sets of labels while eliminating duplicate values from the combined set. The first iterator value takes precedence.

                                                                                              func NewMergeIterator

                                                                                              func NewMergeIterator(s1, s2 *Set) MergeIterator

                                                                                                NewMergeIterator returns a MergeIterator for merging two label sets Duplicates are resolved by taking the value from the first set.

                                                                                                func (*MergeIterator) Label

                                                                                                func (m *MergeIterator) Label() KeyValue

                                                                                                  Label returns the current value after Next() returns true.

                                                                                                  func (*MergeIterator) Next

                                                                                                  func (m *MergeIterator) Next() bool

                                                                                                    Next returns true if there is another label available.

                                                                                                    type Set

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

                                                                                                      Set is the representation for a distinct label set. It manages an immutable set of labels, with an internal cache for storing label encodings.

                                                                                                      This type supports the `Equivalent` method of comparison using values of type `Distinct`.

                                                                                                      This type is used to implement: 1. Metric labels 2. Resource sets 3. Correlation map (TODO)

                                                                                                      func EmptySet

                                                                                                      func EmptySet() *Set

                                                                                                        EmptySet returns a reference to a Set with no elements.

                                                                                                        This is a convenience provided for optimized calling utility.

                                                                                                        func NewSet

                                                                                                        func NewSet(kvs ...KeyValue) Set

                                                                                                          NewSet returns a new `Set`. See the documentation for `NewSetWithSortableFiltered` for more details.

                                                                                                          Except for empty sets, this method adds an additional allocation compared with calls that include a `*Sortable`.

                                                                                                          func NewSetWithSortable

                                                                                                          func NewSetWithSortable(kvs []KeyValue, tmp *Sortable) Set

                                                                                                            NewSetWithSortable returns a new `Set`. See the documentation for `NewSetWithSortableFiltered` for more details.

                                                                                                            This call includes a `*Sortable` option as a memory optimization.

                                                                                                            func (*Set) Encoded

                                                                                                            func (l *Set) Encoded(encoder Encoder) string

                                                                                                              Encoded returns the encoded form of this set, according to `encoder`. The result will be cached in this `*Set`.

                                                                                                              func (*Set) Equals

                                                                                                              func (l *Set) Equals(o *Set) bool

                                                                                                                Equals returns true if the argument set is equivalent to this set.

                                                                                                                func (*Set) Equivalent

                                                                                                                func (l *Set) Equivalent() Distinct

                                                                                                                  Equivalent returns a value that may be used as a map key. The Distinct type guarantees that the result will equal the equivalent Distinct value of any label set with the same elements as this, where sets are made unique by choosing the last value in the input for any given key.

                                                                                                                  func (*Set) Filter

                                                                                                                  func (l *Set) Filter(re Filter) (Set, []KeyValue)

                                                                                                                    Filter returns a filtered copy of this `Set`. See the documentation for `NewSetWithSortableFiltered` for more details.

                                                                                                                    func (*Set) Get

                                                                                                                    func (l *Set) Get(idx int) (KeyValue, bool)

                                                                                                                      Get returns the KeyValue at ordered position `idx` in this set.

                                                                                                                      func (*Set) HasValue

                                                                                                                      func (l *Set) HasValue(k Key) bool

                                                                                                                        HasValue tests whether a key is defined in this set.

                                                                                                                        func (*Set) Iter

                                                                                                                        func (l *Set) Iter() Iterator

                                                                                                                          Iter returns an iterator for visiting the labels in this set.

                                                                                                                          func (*Set) Len

                                                                                                                          func (l *Set) Len() int

                                                                                                                            Len returns the number of labels in this set.

                                                                                                                            func (*Set) MarshalJSON

                                                                                                                            func (l *Set) MarshalJSON() ([]byte, error)

                                                                                                                              MarshalJSON returns the JSON encoding of the `*Set`.

                                                                                                                              func (*Set) ToSlice

                                                                                                                              func (l *Set) ToSlice() []KeyValue

                                                                                                                                ToSlice returns the set of labels belonging to this set, sorted, where keys appear no more than once.

                                                                                                                                func (*Set) Value

                                                                                                                                func (l *Set) Value(k Key) (Value, bool)

                                                                                                                                  Value returns the value of a specified key in this set.

                                                                                                                                  type Sortable

                                                                                                                                  type Sortable []KeyValue

                                                                                                                                    Sortable implements `sort.Interface`, used for sorting `KeyValue`. This is an exported type to support a memory optimization. A pointer to one of these is needed for the call to `sort.Stable()`, which the caller may provide in order to avoid an allocation. See `NewSetWithSortable()`.

                                                                                                                                    func (*Sortable) Len

                                                                                                                                    func (l *Sortable) Len() int

                                                                                                                                      Len implements `sort.Interface`.

                                                                                                                                      func (*Sortable) Less

                                                                                                                                      func (l *Sortable) Less(i, j int) bool

                                                                                                                                        Less implements `sort.Interface`.

                                                                                                                                        func (*Sortable) Swap

                                                                                                                                        func (l *Sortable) Swap(i, j int)

                                                                                                                                          Swap implements `sort.Interface`.

                                                                                                                                          type Type

                                                                                                                                          type Type int

                                                                                                                                            Type describes the type of the data Value holds.

                                                                                                                                            const (
                                                                                                                                            	// INVALID is used for a Value with no value set.
                                                                                                                                            	INVALID Type = iota
                                                                                                                                            	// BOOL is a boolean Type Value.
                                                                                                                                            	BOOL
                                                                                                                                            	// INT32 is a 32-bit signed integral Type Value.
                                                                                                                                            	INT32
                                                                                                                                            	// INT64 is a 64-bit signed integral Type Value.
                                                                                                                                            	INT64
                                                                                                                                            	// UINT32 is a 32-bit unsigned integral Type Value.
                                                                                                                                            	UINT32
                                                                                                                                            	// UINT64 is a 64-bit unsigned integral Type Value.
                                                                                                                                            	UINT64
                                                                                                                                            	// FLOAT32 is a 32-bit floating point Type Value.
                                                                                                                                            	FLOAT32
                                                                                                                                            	// FLOAT64 is a 64-bit floating point Type Value.
                                                                                                                                            	FLOAT64
                                                                                                                                            	// STRING is a string Type Value.
                                                                                                                                            	STRING
                                                                                                                                            	// ARRAY is an array Type Value used to store 1-dimensional slices or
                                                                                                                                            	// arrays of bool, int, int32, int64, uint, uint32, uint64, float,
                                                                                                                                            	// float32, float64, or string types.
                                                                                                                                            	ARRAY
                                                                                                                                            )

                                                                                                                                            func (Type) String

                                                                                                                                            func (i Type) String() string

                                                                                                                                            type Value

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

                                                                                                                                              Value represents the value part in key-value pairs.

                                                                                                                                              func ArrayValue

                                                                                                                                              func ArrayValue(v interface{}) Value

                                                                                                                                                ArrayValue creates an ARRAY value from an array or slice. Only arrays or slices of bool, int, int32, int64, uint, uint32, uint64, float, float32, float64, or string types are allowed. Specifically, arrays and slices can not contain other arrays, slices, structs, or non-standard types. If the passed value is not an array or slice of these types an INVALID value is returned.

                                                                                                                                                func BoolValue

                                                                                                                                                func BoolValue(v bool) Value

                                                                                                                                                  BoolValue creates a BOOL Value.

                                                                                                                                                  func Float32Value

                                                                                                                                                  func Float32Value(v float32) Value

                                                                                                                                                    Float32Value creates a FLOAT32 Value.

                                                                                                                                                    func Float64Value

                                                                                                                                                    func Float64Value(v float64) Value

                                                                                                                                                      Float64Value creates a FLOAT64 Value.

                                                                                                                                                      func Int32Value

                                                                                                                                                      func Int32Value(v int32) Value

                                                                                                                                                        Int32Value creates an INT32 Value.

                                                                                                                                                        func Int64Value

                                                                                                                                                        func Int64Value(v int64) Value

                                                                                                                                                          Int64Value creates an INT64 Value.

                                                                                                                                                          func IntValue

                                                                                                                                                          func IntValue(v int) Value

                                                                                                                                                            IntValue creates either an INT32 or an INT64 Value, depending on whether the int type is 32 or 64 bits wide.

                                                                                                                                                            func StringValue

                                                                                                                                                            func StringValue(v string) Value

                                                                                                                                                              StringValue creates a STRING Value.

                                                                                                                                                              func Uint32Value

                                                                                                                                                              func Uint32Value(v uint32) Value

                                                                                                                                                                Uint32Value creates a UINT32 Value.

                                                                                                                                                                func Uint64Value

                                                                                                                                                                func Uint64Value(v uint64) Value

                                                                                                                                                                  Uint64Value creates a UINT64 Value.

                                                                                                                                                                  func UintValue

                                                                                                                                                                  func UintValue(v uint) Value

                                                                                                                                                                    UintValue creates either a UINT32 or a UINT64 Value, depending on whether the uint type is 32 or 64 bits wide.

                                                                                                                                                                    func (Value) AsArray

                                                                                                                                                                    func (v Value) AsArray() interface{}

                                                                                                                                                                      AsArray returns the array Value as an interface{}.

                                                                                                                                                                      func (Value) AsBool

                                                                                                                                                                      func (v Value) AsBool() bool

                                                                                                                                                                        AsBool returns the bool value. Make sure that the Value's type is BOOL.

                                                                                                                                                                        func (Value) AsFloat32

                                                                                                                                                                        func (v Value) AsFloat32() float32

                                                                                                                                                                          AsFloat32 returns the float32 value. Make sure that the Value's type is FLOAT32.

                                                                                                                                                                          func (Value) AsFloat64

                                                                                                                                                                          func (v Value) AsFloat64() float64

                                                                                                                                                                            AsFloat64 returns the float64 value. Make sure that the Value's type is FLOAT64.

                                                                                                                                                                            func (Value) AsInt32

                                                                                                                                                                            func (v Value) AsInt32() int32

                                                                                                                                                                              AsInt32 returns the int32 value. Make sure that the Value's type is INT32.

                                                                                                                                                                              func (Value) AsInt64

                                                                                                                                                                              func (v Value) AsInt64() int64

                                                                                                                                                                                AsInt64 returns the int64 value. Make sure that the Value's type is INT64.

                                                                                                                                                                                func (Value) AsInterface

                                                                                                                                                                                func (v Value) AsInterface() interface{}

                                                                                                                                                                                  AsInterface returns Value's data as interface{}.

                                                                                                                                                                                  func (Value) AsString

                                                                                                                                                                                  func (v Value) AsString() string

                                                                                                                                                                                    AsString returns the string value. Make sure that the Value's type is STRING.

                                                                                                                                                                                    func (Value) AsUint32

                                                                                                                                                                                    func (v Value) AsUint32() uint32

                                                                                                                                                                                      AsUint32 returns the uint32 value. Make sure that the Value's type is UINT32.

                                                                                                                                                                                      func (Value) AsUint64

                                                                                                                                                                                      func (v Value) AsUint64() uint64

                                                                                                                                                                                        AsUint64 returns the uint64 value. Make sure that the Value's type is UINT64.

                                                                                                                                                                                        func (Value) Emit

                                                                                                                                                                                        func (v Value) Emit() string

                                                                                                                                                                                          Emit returns a string representation of Value's data.

                                                                                                                                                                                          func (Value) MarshalJSON

                                                                                                                                                                                          func (v Value) MarshalJSON() ([]byte, error)

                                                                                                                                                                                            MarshalJSON returns the JSON encoding of the Value.

                                                                                                                                                                                            func (Value) Type

                                                                                                                                                                                            func (v Value) Type() Type

                                                                                                                                                                                              Type returns a type of the Value.