Network Info Collector - antimetal/system-agent GitHub Wiki

Network Info Collector

Overview

The Network Info Collector is a hardware information collector in the Antimetal System Agent that gathers static network interface configuration and hardware properties from Linux systems. Unlike the Network Collector which monitors dynamic network statistics (packets, bytes, errors), this collector captures the physical and logical characteristics of network interfaces.

Why It's Important

  • Hardware Inventory: Provides a complete inventory of network interfaces and their capabilities
  • Network Configuration: Tracks MTU settings, MAC addresses, and operational states
  • Driver Information: Identifies network drivers for troubleshooting and compatibility
  • Interface Type Detection: Distinguishes between physical, virtual, wireless, and bridge interfaces
  • Link Status: Reports carrier detection and operational states

Technical Details

Property Value
MetricType MetricTypeNetworkInfo ("network_info")
Collection Mode One-shot (runs once at startup)
Data Sources /sys/class/net/

Capabilities

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

Data Sources

The collector reads network interface information from the Linux sysfs virtual filesystem:

Kernel-Standardized Data (consistent across all drivers):

  • /sys/class/net/[interface]/address - MAC address
  • /sys/class/net/[interface]/mtu - Maximum Transmission Unit
  • /sys/class/net/[interface]/operstate - Operational state
  • /sys/class/net/[interface]/carrier - Physical link status
  • /sys/class/net/[interface]/type - Interface type number (ARPHRD constants)

Driver-Dependent Data (may vary or be unavailable):

  • /sys/class/net/[interface]/speed - Link speed in Mbps
  • /sys/class/net/[interface]/duplex - Link duplex mode
  • /sys/class/net/[interface]/device/driver - Driver name

Collected Metrics

Field Type Description Example Source
Interface string Network interface name eth0, wlan0 Directory name
Type string Interface type ethernet, wireless, bridge Multiple detection methods
MACAddress string Hardware MAC address aa:bb:cc:dd:ee:ff /sys/class/net/[if]/address
Speed uint64 Link speed in Mbps 1000 (1 Gbps) /sys/class/net/[if]/speed
Duplex string Duplex mode full, half, unknown /sys/class/net/[if]/duplex
MTU uint32 Maximum Transmission Unit 1500 /sys/class/net/[if]/mtu
OperState string Operational state up, down, dormant /sys/class/net/[if]/operstate
Carrier bool Physical link status true/false /sys/class/net/[if]/carrier
Driver string Network driver name e1000e, iwlwifi /sys/class/net/[if]/device/driver

Interface Type Detection

The collector uses a hierarchical approach to determine interface types:

  1. Kernel-Standardized Detection:

    • Presence of wireless/ subdirectory --> wireless
    • Type file with ARPHRD constants --> mapped to type
    • Well-known names (e.g., lo --> loopback)

  2. Heuristic Detection (common naming conventions):

    • eth* --> ethernet
    • wlan* --> wireless
    • docker*, br-*, virbr* --> bridge
    • veth* --> virtual
    • tun* --> tunnel
    • tap* --> tap

  3. Fallback Logic:

    • Has device/ symlink --> ethernet (physical)
    • Otherwise --> virtual

Data Structure

The collector returns an array of NetworkInfo structs. See the implementation at:

Configuration

Collection Configuration

config := performance.CollectionConfig{
    HostSysPath: "/sys",  // Path to sysfs mount (required)
}

Container Configuration

When running in containers, mount the host's sysfs:

volumes:
  - /sys:/host/sys:ro
env:
  - name: HOST_SYS
    value: /host/sys

Platform Considerations

Linux Kernel Requirements

  • Minimum Kernel: 2.6.0 (sysfs network support)
  • Recommended: 3.0+ for full driver information
  • Interface Types: ARPHRD constants from if_arp.h

Container Considerations

  1. Read-only sysfs mount is sufficient
  2. No special privileges required
  3. Virtual interfaces (veth) from container networking are visible
  4. Driver information may be limited for virtual interfaces

Interface Naming

Interface names are NOT kernel-standardized and depend on:

  • udev rules (distribution-specific)
  • systemd predictable network names (e.g., enp0s3)
  • Manual configuration
  • Driver defaults

Common Issues

Troubleshooting

Issue Cause Solution
Missing speed/duplex Interface down or virtual Normal for down/virtual interfaces
Speed shows as -1 Link down Check cable/connection
No driver information Virtual interface Expected for bridges/tunnels
Interface not detected Permission issue Check sysfs mount permissions
Empty MAC address Loopback interface Normal for lo interface

Debug Commands

# List all network interfaces
ls -la /sys/class/net/

# Check interface properties
cat /sys/class/net/eth0/address
cat /sys/class/net/eth0/operstate
cat /sys/class/net/eth0/speed

# Verify driver information
readlink /sys/class/net/eth0/device/driver

Examples

Sample Output

[
  {
    "Interface": "eth0",
    "Type": "ethernet",
    "MACAddress": "52:54:00:12:34:56",
    "Speed": 1000,
    "Duplex": "full",
    "MTU": 1500,
    "OperState": "up",
    "Carrier": true,
    "Driver": "virtio_net"
  },
  {
    "Interface": "lo",
    "Type": "loopback",
    "MACAddress": "00:00:00:00:00:00",
    "Speed": 0,
    "Duplex": "",
    "MTU": 65536,
    "OperState": "unknown",
    "Carrier": true,
    "Driver": ""
  },
  {
    "Interface": "docker0",
    "Type": "bridge",
    "MACAddress": "02:42:ac:11:00:01",
    "Speed": 0,
    "Duplex": "",
    "MTU": 1500,
    "OperState": "down",
    "Carrier": false,
    "Driver": ""
  }
]

Programmatic Usage

collector, err := collectors.NewNetworkInfoCollector(logger, config)
if err != nil {
    return err
}

result, err := collector.Collect(context.Background())
if err != nil {
    return err
}

interfaces := result.([]performance.NetworkInfo)
for _, iface := range interfaces {
    fmt.Printf("Interface %s: %s (%s)\n", 
        iface.Interface, iface.Type, iface.OperState)
}

Performance Impact

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

  • CPU Usage: Negligible (one-time collection)
  • Memory Usage: ~1KB per interface
  • I/O Operations: Small reads from sysfs virtual filesystem
  • Execution Time: < 5ms typically
  • Frequency: Once at startup only
  • No network traffic generated

Related Collectors

References