spec

package
v0.0.0-...-e70f483 Latest Latest
Warning

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

Go to latest
Published: May 21, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

README

GPU Metric Spec

This directory contains the GPU corecheck specification files:

  • gpu_metrics.yaml: metric catalog (metric names, required tagsets/custom tags, and support matrix by architecture/device mode).
  • architectures.yaml: architecture capabilities (GPM support, unsupported NVML fields by mode, and unsupported device modes such as mig/vgpu).
  • tags.yaml: reusable tag definitions (tags) and reusable tag groups (tagsets), including workload-only tagsets and regex validation for tag values.

Each YAML file has headers describing the schema.

The Go code in this package turns those YAML specs into shared validation logic used in tests and in live data validation:

  • validation.go:
    • Enumerates supported architecture/device-mode combinations via KnownGPUConfigs.
    • Computes expected metrics per config via ExpectedMetricsForConfig.
    • Validates emitted metrics/tags/values via ValidateEmittedMetricsAgainstSpec (missing, unknown, unsupported, invalid_value).
  • metrics-validator/: validates Datadog metric data against the same shared spec logic.
  • allowlist/: syncs GPU metrics from the spec into the billing allowlist.

The spec files are also validated by tests in pkg/collector/corechecks/gpu/spec/spec_test.go.

Validate the spec

Run one or more of these three validation levels:

  1. Mocked NVML against spec (TestMetricsFollowSpec):

    dda inv test --targets=./pkg/collector/corechecks/gpu -- -tags "test nvml" -run TestMetricsFollowSpec

  2. Real NVML APIs against spec (integrationtests, requires real GPU + NVML):

    dda inv test --targets=./pkg/collector/corechecks/gpu/integrationtests -- -tags "nvml"

  3. Live Datadog data against spec (spec/metrics-validator through invoke task):

    dda inv gpu.validate-metrics --lookback-seconds 3600 --org staging

Documentation

Overview

Package spec holds structures to parse the metric specification for the GPU check.

Index

Constants

This section is empty.

Variables

AllDeviceModes lists every device mode modeled by the GPU spec.

Functions

func ExpectedMetricsForConfig

func ExpectedMetricsForConfig(specs *Specs, config GPUConfig, options ValidationOptions) map[string]MetricSpec

ExpectedMetricsForConfig returns the spec metric names expected for a GPU config.

func IsModeSupportedByArchitecture

func IsModeSupportedByArchitecture(archSpec ArchitectureSpec, mode DeviceMode) bool

IsModeSupportedByArchitecture returns true when the architecture supports the device mode.

func PrefixedMetricName

func PrefixedMetricName(specs *Specs, metricName string) string

PrefixedMetricName adds the spec metric prefix to a metric name if needed.

func RequiredTagsForMetric

func RequiredTagsForMetric(tagsSpec *TagsSpec, metricSpec MetricSpec) (map[string]TagSpec, map[string]TagSpec, error)

RequiredTagsForMetric expands the required tags for a metric from tagsets and custom tags.

func TagsToKeyValues

func TagsToKeyValues(tags []string) map[string][]string

TagsToKeyValues converts Datadog-style tags to a key -> values map.

Types

type ArchitectureCapabilities

type ArchitectureCapabilities struct {
	GPM                           bool                                `yaml:"gpm"`
	UnsupportedFieldsByDeviceMode []UnsupportedFieldsByDeviceModeSpec `yaml:"unsupported_fields_by_device_mode"`
}

ArchitectureCapabilities defines capabilities and unsupported fields.

type ArchitectureSpec

type ArchitectureSpec struct {
	Capabilities           ArchitectureCapabilities `yaml:"capabilities"`
	UnsupportedDeviceModes []DeviceMode             `yaml:"unsupported_device_modes"`
}

ArchitectureSpec defines architecture capabilities and unsupported device modes.

type ArchitecturesSpec

type ArchitecturesSpec struct {
	Architectures map[string]ArchitectureSpec `yaml:"architectures"`
}

ArchitecturesSpec is the YAML architecture capability specification.

func LoadArchitecturesSpec

func LoadArchitecturesSpec() (*ArchitecturesSpec, error)

LoadArchitecturesSpec loads the canonical GPU architectures specification file.

type DeviceMode

type DeviceMode string

DeviceMode identifies the GPU device operating mode in the spec.

const (
	DeviceModePhysical DeviceMode = "physical"
	DeviceModeMIG      DeviceMode = "mig"
	DeviceModeVGPU     DeviceMode = "vgpu"
)

type GPUConfig

type GPUConfig struct {
	Architecture string     `json:"architecture"`
	DeviceMode   DeviceMode `json:"device_mode"`
}

GPUConfig identifies an architecture + device mode pair from the spec.

func KnownGPUConfigs

func KnownGPUConfigs(specs *Specs) []GPUConfig

KnownGPUConfigs returns all supported architecture + mode combinations.

func NewGPUConfigFromTags

func NewGPUConfigFromTags(architecture, slicingMode, virtualizationMode string) GPUConfig

func (*GPUConfig) Equals

func (c *GPUConfig) Equals(other GPUConfig) bool

Equals checks if two GPU configs are equal.

func (*GPUConfig) TagFilter

func (c *GPUConfig) TagFilter() string

TagFilter returns the Datadog tag filter expression for a GPU config.

type MetricMetadataSpec

type MetricMetadataSpec struct {
	MetricType  string `yaml:"metric_type,omitempty"`
	Unit        string `yaml:"unit,omitempty"`
	Description string `yaml:"description,omitempty"`
}

MetricMetadataSpec defines metadata used to generate integrations metadata.csv rows.

func (*MetricMetadataSpec) UnmarshalYAML

func (m *MetricMetadataSpec) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML validates metric metadata values while decoding.

type MetricObservation

type MetricObservation struct {
	Name       string
	MetricType string
	Tags       []string
	Value      *float64
}

MetricObservation is the normalized observation used by shared validation.

type MetricSpec

type MetricSpec struct {
	Metadata     *MetricMetadataSpec `yaml:"metadata,omitempty"`
	Tagsets      []string            `yaml:"tagsets"`
	CustomTags   []string            `yaml:"custom_tags,omitempty"`
	WorkloadOnly bool                `yaml:"workload_only,omitempty"`
	Support      MetricSupportSpec   `yaml:"support"`
	Validator    *MetricValidator    `yaml:"validator,omitempty"`
}

MetricSpec is a metric definition without the name (name is the map key).

func (MetricSpec) SupportsArchitecture

func (m MetricSpec) SupportsArchitecture(arch string) bool

SupportsArchitecture returns true if the metric is supported on this architecture.

func (MetricSpec) SupportsConfig

func (m MetricSpec) SupportsConfig(config GPUConfig) bool

SupportsConfig returns true if the metric is supported for the given GPU config.

func (MetricSpec) SupportsDeviceMode

func (m MetricSpec) SupportsDeviceMode(mode DeviceMode) bool

SupportsDeviceMode returns true if the metric's device_modes explicitly allows the mode. device_modes values are expected to be booleans; missing means unsupported.

type MetricStatus

type MetricStatus struct {
	Missing             int                    `json:"missing"`
	Unknown             int                    `json:"unknown"`
	Unsupported         int                    `json:"unsupported"`
	WrongType           int                    `json:"wrong_type"`
	InvalidValue        int                    `json:"invalid_value"`
	InvalidValueSamples []string               `json:"invalid_value_samples,omitempty"`
	TagResults          map[string]*TagSummary `json:"tag_results"`
}

func (*MetricStatus) HasFailures

func (s *MetricStatus) HasFailures() bool

HasFailures returns true when the metric status contains metric-level or tag-level failures.

type MetricSupportSpec

type MetricSupportSpec struct {
	UnsupportedArchitectures []string            `yaml:"unsupported_architectures"`
	DeviceModes              map[DeviceMode]bool `yaml:"device_modes"`
}

MetricSupportSpec defines where a metric is supported.

type MetricValidator

type MetricValidator struct {
	Range  *MetricValidatorRange `yaml:"range,omitempty"`
	Values []float64             `yaml:"values,omitempty"`
}

MetricValidator validates emitted metric values against the spec.

func (*MetricValidator) UnmarshalYAML

func (v *MetricValidator) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML parses the supported validator shapes while keeping the internal fields private.

func (*MetricValidator) Validate

func (v *MetricValidator) Validate(value float64) error

Validate checks whether the metric value matches the validator.

type MetricValidatorRange

type MetricValidatorRange struct {
	Min *float64 `yaml:"min"`
	Max *float64 `yaml:"max"`
}

MetricValidatorRange defines an inclusive numeric range validator.

type MetricsSpec

type MetricsSpec struct {
	MetricPrefix string                `yaml:"metric_prefix"`
	Metrics      map[string]MetricSpec `yaml:"metrics"`
}

MetricsSpec is the YAML metric specification.

func LoadMetricsSpec

func LoadMetricsSpec() (*MetricsSpec, error)

LoadMetricsSpec loads the canonical GPU metrics specification file.

type Specs

type Specs struct {
	Metrics       *MetricsSpec
	Tags          *TagsSpec
	Architectures *ArchitecturesSpec
}

Specs bundles all GPU spec files used by validation and tests.

func LoadSpecs

func LoadSpecs() (*Specs, error)

LoadSpecs loads all canonical GPU specification files.

type TagSpec

type TagSpec struct {
	Regex *regexp.Regexp `yaml:"-"`
}

TagSpec defines validation metadata for a reusable tag.

func (*TagSpec) UnmarshalYAML

func (s *TagSpec) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML compiles the optional regex when the tag spec is decoded.

type TagSummary

type TagSummary struct {
	WorkloadOnly        bool     `json:"workload_only,omitempty"`
	Found               int      `json:"found"`
	Missing             int      `json:"missing"`
	Unknown             int      `json:"unknown"`
	InvalidValue        int      `json:"invalid_value"`
	InvalidValueSamples []string `json:"invalid_value_samples"`
}

type TagsSpec

type TagsSpec struct {
	Tags    map[string]TagSpec    `yaml:"tags"`
	Tagsets map[string]TagsetSpec `yaml:"tagsets"`
}

TagsSpec is the YAML tags specification.

func LoadTagsSpec

func LoadTagsSpec() (*TagsSpec, error)

LoadTagsSpec loads the canonical GPU tags specification file.

type TagsetSpec

type TagsetSpec struct {
	Tags         []string `yaml:"tags"`
	WorkloadOnly bool     `yaml:"workload_only,omitempty"`
}

TagsetSpec defines a reusable tagset.

type UnsupportedFieldsByDeviceModeSpec

type UnsupportedFieldsByDeviceModeSpec struct {
	DeviceModes []DeviceMode `yaml:"device_modes"`
	Fields      []string     `yaml:"fields"`
}

UnsupportedFieldsByDeviceModeSpec groups unsupported fields by device modes.

type ValidationOptions

type ValidationOptions struct {
	WorkloadActive bool `json:"workload_active"`
}

ValidationOptions controls which spec failures should be enforced.

type ValidationResult

type ValidationResult struct {
	Metrics map[string]*MetricStatus `json:"metrics"`
}

ValidationResult holds validation failures derived from spec expectations.

func ValidateEmittedMetricsAgainstSpec

func ValidateEmittedMetricsAgainstSpec(specs *Specs, config GPUConfig, emittedMetrics map[string][]MetricObservation, knownTagValues map[string]string, options ValidationOptions) (ValidationResult, error)

ValidateEmittedMetricsAgainstSpec validates emitted metrics against the spec for a given GPU config.

func (*ValidationResult) HasFailures

func (r *ValidationResult) HasFailures() bool

HasFailures returns true when the result contains metric-level or tag-level failures.

Directories

Path Synopsis
Package main updates the billing allowlist with GPU metrics from the shared spec.
Package main updates the billing allowlist with GPU metrics from the shared spec.
Package main updates integrations-core GPU metadata from the shared spec.
Package main updates integrations-core GPU metadata from the shared spec.
Package main validates emitted GPU metrics against the shared spec.
Package main validates emitted GPU metrics against the shared spec.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL