measurement

package
v0.9.7 Latest Latest
Warning

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

 Go to latest Published: Mar 7, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

Documentation

Overview

Package measurement provides types and utilities for collecting, comparing, and filtering system measurements from various sources (Kubernetes, GPU, OS, SystemD).

Core Types

The package defines a hierarchical structure for measurements:

  • Type: Enum identifying the measurement source (K8s, GPU, OS, SystemD)
  • Measurement: Contains a Type and a slice of Subtypes
  • Subtype: Named collection of key-value data (e.g., "cluster", "node")
  • Reading: Interface for type-safe scalar values (int, float64, string, bool, etc.)

Creating Measurements

Use convenience constructors to create readings: 

m := &Measurement{
    Type: TypeK8s,
    Subtypes: []Subtype{
        {
            Name: "cluster",
            Data: map[string]Reading{
                "version": Str("1.28.0"),
                "nodes":   Int(3),
                "ready":   Bool(true),
            },
        },
    },
}

Or use the builder pattern for cleaner code: 

m := NewMeasurement(TypeK8s).
    WithSubtype(
        NewSubtypeBuilder("cluster").
            Set("version", Str("1.28.0")).
            Set("nodes", Int(3)).
            Build(),
    )

Accessing Data

Use type-safe getters to retrieve values: 

version, err := m.GetSubtype("cluster").GetString("version")
nodes, err := m.GetSubtype("cluster").GetInt64("nodes")
ready, err := m.GetSubtype("cluster").GetBool("ready")

Filtering Data

Filter sensitive or unwanted keys using wildcard patterns: 

// Remove all keys containing "password" or starting with "secret"
filtered := FilterOut(readings, []string{"*password*", "secret*"})

// Keep only version and count fields
kept := FilterIn(readings, []string{"version", "count"})

Serialization

Measurements support JSON and YAML marshaling/unmarshaling: 

data, _ := json.Marshal(m)
yaml, _ := yaml.Marshal(m)

The Reading interface is automatically marshaled to its underlying value, avoiding wrapper structures in the output.

Index

Constants

View Source 
const (
	// Kubernetes measurement keys
	KeyVersion     = "version"
	KeyNodes       = "nodes"
	KeyPods        = "pods"
	KeyNamespace   = "namespace"
	KeyClusterName = "cluster-name"
	KeyReady       = "ready"

	// GPU measurement keys
	KeyGPUDriver = "driver"
	KeyGPUModel  = "model"
	KeyGPUCount  = "gpu-count"
	KeyGPUMemory = "memory"
	KeyGPUTemp   = "temperature"
	KeyGPUPower  = "power"
	KeyGPUUUID   = "uuid"

	// OS measurement keys
	KeyOSName    = "name"
	KeyOSVersion = "os-version"
	KeyKernel    = "kernel"
	KeyArch      = "architecture"
	KeyHostname  = "hostname"

	// SystemD measurement keys
	KeyServiceName   = "service-name"
	KeyServiceState  = "state"
	KeyServiceStatus = "status"
	KeyEnabled       = "enabled"
	KeyActive        = "active"
)

Common measurement keys exported for consistency and type safety.

Variables

View Source 
var Types = []Type{
	TypeK8s,
	TypeGPU,
	TypeOS,
	TypeSystemD,
	TypeNodeTopology,
}

Types is the list of all supported measurement types.

Functions

func FilterIn 

func FilterIn(readings map[string]Reading, keys []string) map[string]Reading

FilterIn returns a new map with only keys that match the provided patterns. This is the complement of FilterOut. Supports the same wildcard patterns as FilterOut:

  • "prefix*" matches keys starting with "prefix"
  • "*suffix" matches keys ending with "suffix"
  • "*contains*" matches keys containing "contains"
  • "exact" matches keys exactly

func FilterOut 

func FilterOut(readings map[string]Reading, keys []string) map[string]Reading

FilterOut returns a new map with keys filtered out based on the provided patterns. Supports wildcard patterns:

  • "prefix*" matches keys starting with "prefix"
  • "*suffix" matches keys ending with "suffix"
  • "*contains*" matches keys containing "contains"
  • "exact" matches keys exactly

Types

type AllowedScalar 

type AllowedScalar interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64 |
		~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 |
		~float32 | ~float64 |
		~bool |
		~string
}

AllowedScalar is a constraint (compile-time) for what we allow as readings.

type Measurement 

type Measurement struct {
	Type     Type      `json:"type" yaml:"type"`
	Subtypes []Subtype `json:"subtypes,omitempty" yaml:"subtypes,omitempty"`
}

Measurement represents collected data of a specific type with multiple subtypes. Each measurement contains a category (Type) and one or more Subtypes with their associated data.

func (*Measurement) GetOrCreateSubtype 

func (m *Measurement) GetOrCreateSubtype(name string) *Subtype

GetOrCreateSubtype retrieves a subtype by name, creating it if it doesn't exist. This simplifies dynamic measurement building by avoiding manual check-and-append logic.

func (*Measurement) GetSubtype 

func (m *Measurement) GetSubtype(name string) *Subtype

GetSubtype retrieves a subtype by name, returning nil if not found.

func (*Measurement) HasSubtype 

func (m *Measurement) HasSubtype(name string) bool

HasSubtype checks if a subtype with the given name exists.

func (*Measurement) Merge 

func (m *Measurement) Merge(other *Measurement) error

Merge combines two measurements by adding or updating subtypes from other into m. If a subtype exists in both measurements, the data is merged (other's values take precedence). Returns an error if the measurements have different types.

func (*Measurement) SubtypeNames 

func (m *Measurement) SubtypeNames() []string

SubtypeNames returns all subtype names.

func (*Measurement) Validate 

func (m *Measurement) Validate() error

Validate checks if the measurement is properly formed.

type MeasurementBuilder 

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

MeasurementBuilder provides a fluent API for building Measurement instances.

func NewMeasurement 

func NewMeasurement(t Type) *MeasurementBuilder

NewMeasurement creates a new MeasurementBuilder with the given type.

func (*MeasurementBuilder) Build 

func (b *MeasurementBuilder) Build() *Measurement

Build constructs and returns the Measurement.

func (*MeasurementBuilder) WithSubtype 

func (b *MeasurementBuilder) WithSubtype(st Subtype) *MeasurementBuilder

WithSubtype adds a subtype to the measurement.

func (*MeasurementBuilder) WithSubtypeBuilder 

func (b *MeasurementBuilder) WithSubtypeBuilder(builder *SubtypeBuilder) *MeasurementBuilder

WithSubtypeBuilder adds a subtype using a SubtypeBuilder.

type Reading 

type Reading interface {
	Any() any
	String() string

	json.Marshaler
	json.Unmarshaler
	yaml.Marshaler
	yaml.Unmarshaler
	// contains filtered or unexported methods
}

Reading is a *runtime* interface (so it can be stored in a map with mixed types).

func Bool 

func Bool(v bool) Reading

func Float64 

func Float64(v float64) Reading

func Int 

func Int(v int) Reading

Convenience constructors for each allowed scalar type.

func Int64 

func Int64(v int64) Reading

func Str 

func Str(v string) Reading

func ToReading 

func ToReading(v any) Reading

ToReading creates a Reading from any allowed scalar type. If the type is not allowed, it returns a string representation.

func ToReadingWithType 

func ToReadingWithType(v any) (Reading, bool)

ToReadingWithType converts a value to a Reading and returns whether the conversion was lossy (i.e., converted to string via fmt.Sprintf). This allows callers to detect if unexpected types were encountered.

func Uint 

func Uint(v uint) Reading

func Uint64 

func Uint64(v uint64) Reading

type Scalar 

type Scalar[T AllowedScalar] struct {
	V T
}

Scalar wraps an allowed scalar type. This is how we keep compile-time constraints while still using a runtime interface.

func (Scalar[T]) Any 

func (s Scalar[T]) Any() any

func (Scalar[T]) MarshalJSON 

func (s Scalar[T]) MarshalJSON() ([]byte, error)

MarshalJSON makes the JSON value be the underlying scalar (not an object wrapper).

func (Scalar[T]) MarshalYAML 

func (s Scalar[T]) MarshalYAML() (any, error)

MarshalYAML makes the YAML value be the underlying scalar (not an object wrapper).

func (Scalar[T]) String 

func (s Scalar[T]) String() string

String returns the string representation of the underlying scalar value.

func (*Scalar[T]) UnmarshalJSON 

func (s *Scalar[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals a JSON value into the underlying scalar.

func (*Scalar[T]) UnmarshalYAML 

func (s *Scalar[T]) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML unmarshals a YAML value into the underlying scalar.

type Subtype 

type Subtype struct {
	Name    string             `json:"subtype,omitempty" yaml:"subtype,omitempty"`
	Data    map[string]Reading `json:"data" yaml:"data"`
	Context map[string]string  `json:"context,omitempty" yaml:"context,omitempty"`
}

Subtype represents a specific subcategory of measurement with associated data. Data contains the actual measurements as key-value pairs. Context provides additional metadata about the measurement environment.

func (*Subtype) Get 

func (st *Subtype) Get(key string) Reading

Get retrieves a reading by key, returning nil if not found.

func (*Subtype) GetBool 

func (st *Subtype) GetBool(key string) (bool, error)

GetBool attempts to retrieve a bool value, returning an error if not found or wrong type.

func (*Subtype) GetFloat64 

func (st *Subtype) GetFloat64(key string) (float64, error)

GetFloat64 attempts to retrieve a float64 value, returning an error if not found or wrong type.

func (*Subtype) GetInt64 

func (st *Subtype) GetInt64(key string) (int64, error)

GetInt64 attempts to retrieve an int64 value, returning an error if not found or wrong type.

func (*Subtype) GetString 

func (st *Subtype) GetString(key string) (string, error)

GetString attempts to retrieve a string value, returning an error if not found or wrong type.

func (*Subtype) GetUint64 

func (st *Subtype) GetUint64(key string) (uint64, error)

GetUint64 attempts to retrieve a uint64 value, returning an error if not found or wrong type.

func (*Subtype) Has 

func (st *Subtype) Has(key string) bool

Has checks if a key exists in the subtype data.

func (*Subtype) Keys 

func (st *Subtype) Keys() []string

Keys returns all keys in the subtype data.

func (*Subtype) UnmarshalJSON 

func (st *Subtype) UnmarshalJSON(data []byte) error

UnmarshalJSON custom unmarshaler for Subtype to handle Reading interface

func (*Subtype) UnmarshalYAML 

func (st *Subtype) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML custom unmarshaler for Subtype to handle Reading interface

func (*Subtype) Validate 

func (st *Subtype) Validate() error

Validate checks if the subtype is properly formed.

type SubtypeBuilder 

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

SubtypeBuilder provides a fluent API for building Subtype instances.

func NewSubtypeBuilder 

func NewSubtypeBuilder(name string) *SubtypeBuilder

NewSubtypeBuilder creates a new SubtypeBuilder with the given name.

func (*SubtypeBuilder) Build 

func (b *SubtypeBuilder) Build() Subtype

Build constructs and returns the Subtype.

func (*SubtypeBuilder) Set 

func (b *SubtypeBuilder) Set(key string, value Reading) *SubtypeBuilder

Set adds or updates a key-value pair in the subtype data.

func (*SubtypeBuilder) SetBool 

func (b *SubtypeBuilder) SetBool(key string, value bool) *SubtypeBuilder

SetBool is a convenience method for adding bool values.

func (*SubtypeBuilder) SetFloat64 

func (b *SubtypeBuilder) SetFloat64(key string, value float64) *SubtypeBuilder

SetFloat64 is a convenience method for adding float64 values.

func (*SubtypeBuilder) SetInt 

func (b *SubtypeBuilder) SetInt(key string, value int) *SubtypeBuilder

SetInt is a convenience method for adding int values.

func (*SubtypeBuilder) SetInt64 

func (b *SubtypeBuilder) SetInt64(key string, value int64) *SubtypeBuilder

SetInt64 is a convenience method for adding int64 values.

func (*SubtypeBuilder) SetString 

func (b *SubtypeBuilder) SetString(key, value string) *SubtypeBuilder

SetString is a convenience method for adding string values.

func (*SubtypeBuilder) SetUint 

func (b *SubtypeBuilder) SetUint(key string, value uint) *SubtypeBuilder

SetUint is a convenience method for adding uint values.

func (*SubtypeBuilder) SetUint64 

func (b *SubtypeBuilder) SetUint64(key string, value uint64) *SubtypeBuilder

SetUint64 is a convenience method for adding uint64 values.

type Type 

type Type string

Type represents the category of a measurement (e.g., Kubernetes, GPU, OS, SystemD). 

const (
	TypeK8s          Type = "K8s"
	TypeGPU          Type = "GPU"
	TypeOS           Type = "OS"
	TypeSystemD      Type = "SystemD"
	TypeNodeTopology Type = "NodeTopology"
)

func ParseType 

func ParseType(s string) (Type, bool)

ParseType parses a string into a measurement Type. Returns the Type and true if parsing succeeds, or empty Type and false if the string is invalid.

func (Type) String 

func (mt Type) String() string

String returns the string representation of the measurement Type.

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.