CPU Info Collector - antimetal/system-agent GitHub Wiki

CPU Info Collector

Overview

The CPU Info Collector is a hardware information collector in the Antimetal System Agent that gathers static CPU configuration details from the Linux kernel. Unlike the dynamic CPU performance collector, this collector runs once at startup to capture hardware specifications including CPU model, features, core topology, and frequency capabilities.

Why It's Important

  • Hardware Inventory: Provides essential CPU specifications for infrastructure management
  • Capacity Planning: Reports physical and logical core counts for resource allocation
  • Feature Detection: Identifies CPU capabilities (e.g., AVX-512, AES-NI) for workload optimization
  • Performance Baseline: Establishes CPU frequency ranges and cache specifications
  • NUMA Awareness: Detects NUMA topology for optimizing memory-intensive workloads

Technical Details

Property Value
MetricType MetricTypeCPUInfo ("cpu_info")
Collection Mode One-shot (runs once at startup)
Data Sources /proc/cpuinfo, /sys/devices/system/cpu/

Data Sources

  • Primary: /proc/cpuinfo - CPU specifications and topology
  • Secondary:
    • /sys/devices/system/cpu/cpu0/cpufreq/ - Frequency scaling information
    • /sys/devices/system/node/ - NUMA node detection

Capabilities

SupportsOneShot:    true
SupportsContinuous: false  (runs once at startup)
RequiresRoot:       false
RequiresEBPF:       false
MinKernelVersion:   2.6.0

Collected Metrics

Field Type Description Source
PhysicalCores int32 Number of physical CPU cores (falls back to logical cores in VMs) Calculated from unique physical/core ID pairs
LogicalCores int32 Total number of logical processors Count of processor entries
ModelName string CPU model name (e.g., "Intel(R) Core(TM) i7-8700K") model name field
VendorID string CPU vendor (e.g., "GenuineIntel", "AuthenticAMD") vendor_id field
CPUFamily int32 CPU family number cpu family field
Model int32 CPU model number model field
Stepping int32 CPU stepping/revision stepping field
Microcode string Microcode version microcode field
CPUMHz float64 Current CPU frequency in MHz cpu MHz field
CPUMinMHz float64 Minimum CPU frequency in MHz /sys/.../cpuinfo_min_freq
CPUMaxMHz float64 Maximum CPU frequency in MHz /sys/.../cpuinfo_max_freq
CacheSize string L2/L3 cache size (e.g., "12288 KB") cache size field
CacheAlignment int32 Cache line alignment in bytes cache_alignment field
Flags []string CPU feature flags (e.g., "avx2", "aes") flags or Features field
NUMANodes int32 Number of NUMA nodes Count of /sys/.../node/node*
BogoMIPS float64 Bogus MIPS performance indicator bogomips or BogoMIPS field
Cores []CPUCore Per-core topology details See CPUCore structure below

CPUCore Structure

Field Type Description
Processor int32 Logical processor number
CoreID int32 Physical core ID within socket
PhysicalID int32 Physical socket/package ID
Siblings int32 Number of sibling threads
CPUMHz float64 Current frequency for this core

Data Structure

The collector implementation is located at:

Configuration

The collector is configured via the CollectionConfig structure:

config := performance.CollectionConfig{
    HostProcPath: "/proc",     // Required: absolute path to proc filesystem
    HostSysPath:  "/sys",      // Required: absolute path to sys filesystem
}

Container Configuration

When running in containers, mount the host filesystems:

volumes:
  - /proc:/host/proc:ro
  - /sys:/host/sys:ro
env:
  - HOST_PROC=/host/proc
  - HOST_SYS=/host/sys

Platform Considerations

Architecture Support

The collector gracefully handles architecture-specific variations in /proc/cpuinfo:

x86/x86_64

  • Standard fields: vendor_id, model name, flags
  • Physical topology via physical id and core id
  • Comprehensive feature flags

ARM/ARM64

  • Uses Features (capital F) instead of flags
  • Uses BogoMIPS (different capitalization)
  • May lack vendor_id and model name
  • Different CPU identification scheme

PowerPC

  • Uses cpu instead of model name
  • Includes clock field
  • No feature flags in cpuinfo
  • Different field naming conventions

Virtualization Considerations

  • VMs may lack physical topology: Falls back to logical core count
  • Hypervisor flags: Detects virtualization via hypervisor flag
  • Microcode: May show placeholder values (e.g., 0xffffffff)
  • Physical IDs: May all be 0 in virtualized environments

Linux Kernel Requirements

  • Minimum: Linux 2.6.0
  • Frequency scaling: Requires cpufreq driver (typically 2.6.11+)
  • NUMA detection: Requires sysfs NUMA support

Common Issues

Troubleshooting

  1. Missing frequency information

    • Symptom: CPUMinMHz and CPUMaxMHz are 0
    • Cause: cpufreq driver not loaded or unavailable
    • Solution: Check /sys/devices/system/cpu/cpu0/cpufreq/ existence

  2. Incorrect physical core count in VMs

    • Symptom: PhysicalCores equals LogicalCores
    • Cause: VM doesn't expose physical topology
    • Solution: This is expected behavior; use cloud provider APIs for accurate info

  3. Missing CPU flags on ARM

    • Symptom: Different or missing feature flags
    • Cause: ARM uses different feature naming
    • Solution: Check Features field in raw cpuinfo

  4. NUMA nodes show as 1 on multi-socket systems

    • Symptom: NUMANodes is 1 despite multiple sockets
    • Cause: NUMA disabled in BIOS or kernel
    • Solution: Enable NUMA in BIOS/kernel config

Examples

Sample Output

{
  "PhysicalCores": 6,
  "LogicalCores": 12,
  "ModelName": "Intel(R) Core(TM) i7-8700K CPU @ 3.70GHz",
  "VendorID": "GenuineIntel",
  "CPUFamily": 6,
  "Model": 158,
  "Stepping": 10,
  "Microcode": "0xde",
  "CPUMHz": 3700.0,
  "CPUMinMHz": 800.0,
  "CPUMaxMHz": 4700.0,
  "CacheSize": "12288 KB",
  "CacheAlignment": 64,
  "Flags": ["fpu", "vme", "de", "pse", "tsc", "msr", "pae", "mce", "cx8", "apic", "sep", "mtrr", "pge", "mca", "cmov", "pat", "pse36", "clflush", "mmx", "fxsr", "sse", "sse2", "ht", "avx2", "aes"],
  "NUMANodes": 1,
  "BogoMIPS": 7399.70,
  "Cores": [
    {
      "Processor": 0,
      "CoreID": 0,
      "PhysicalID": 0,
      "Siblings": 12,
      "CPUMHz": 3700.0
    }
  ]
}

Detecting CPU Features

// Check for AVX-512 support
hasAVX512 := false
for _, flag := range cpuInfo.Flags {
    if strings.HasPrefix(flag, "avx512") {
        hasAVX512 = true
        break
    }
}

// Check for AES-NI support
hasAESNI := slices.Contains(cpuInfo.Flags, "aes")

Performance Impact

The CPU Info Collector has minimal performance impact as it runs only once at startup:

  • CPU Usage: Negligible (one-time collection)
  • Memory Usage: ~10KB for typical systems
  • I/O Operations: One read of /proc/cpuinfo plus few sysfs reads
  • Execution Time: < 10ms typically
  • Frequency: Once at startup only

Related Collectors