[Feature Bounty] Network Metrics

[elibosley]

Feature Request: Network Interfaces & Metrics (Read-Only)

Motivation

Users need better visibility into the system’s networking environment for diagnostics, monitoring, and performance tracking. Currently, the API does not expose details about available network interfaces or live network performance metrics. Providing this data will allow for better system health dashboards, troubleshooting, and integration with monitoring tools.

This feature should be read-only only — no mutations — to prevent accidental or malicious configuration changes to network interfaces.

---

Proposed Solution

Queries

• networkInterfaces

  • Returns static details about all detected network interfaces.
  • Data source: systeminformation.networkInterfaces().
  • Fields to include (based on systeminformation schema):
    • id (alias of iface)
    • name
    • macAddress
    • mtu
    • speed (Mbps)
    • duplex (half/full)
    • internal (boolean)
    • ipv4Addresses (array of address + netmask)
    • ipv6Addresses (array of address + prefixLength)
    • vlanId
    • virtual (boolean)
    • operstate (up/down/unknown)
    • type (wired/wireless/other)

• metrics.network

• Returns current snapshot of network statistics for all interfaces.

• Data source: systeminformation.networkStats().

• Read-only — no mutations.

Example GraphQL Query:

query {
  metrics {
    network {
      name
      bytesReceived
      bytesSent
      packetsReceived
      packetsSent
      receiveErrors
      transmitErrors
      receiveDropped
      transmitDropped
      rxSec
      txSec
      utilizationPercent
      lastUpdated
    }
  }
}

Subscriptions

• systemMetricsNetwork
  • Streams live performance metrics for all interfaces.
  • Data source: systeminformation.networkStats().
  • Collection interval: configurable, default 2 seconds.
  • Fields to include (based on systeminformation schema):
    • name (interface identifier)
    • bytesReceived (rx_bytes)
    • bytesSent (tx_bytes)
    • packetsReceived (rx_packets)
    • packetsSent (tx_packets)
    • receiveErrors (rx_errors)
    • transmitErrors (tx_errors)
    • receiveDropped (rx_dropped)
    • transmitDropped (tx_dropped)
    • rxSec (bytes/sec receive rate)
    • txSec (bytes/sec transmit rate)
    • utilizationPercent (calculated: (rx_sec + tx_sec) * 8 / (speed * 1e6) * 100)
    • lastUpdated (timestamp)

---

Alternatives Considered

• Mutations: Initially considered enabling NIC reconfiguration (e.g., setting IPs, enabling/disabling), but rejected for now to keep the scope read-only and safe.
• Embedding metrics inside networkInterfaces: Would tightly couple static and dynamic data. Chosen not to do this, as separating queries (static info) and subscriptions (dynamic metrics) keeps schema cleaner and avoids unnecessary load for one-off queries.
• Polling only via queries: Considered exposing metrics as a query polled by clients, but GraphQL subscriptions provide a more efficient, push-based model for real-time dashboards.

---

Acceptance Criteria

• A user can query networkInterfaces and receive static systeminformation-based details for all available NICs.
• A user can subscribe to systemMetricsNetwork and receive a stream of live per-interface network stats.
• Subscription updates at default 2s intervals (configurable).
• Metrics include throughput rates and utilization calculations in addition to raw counters.
• Schema field names follow the systeminformation schema as baseline, with GraphQL-friendly naming conventions.
• No mutations exist for modifying NICs.
• Subscriptions and queries can be used simultaneously without conflict.

---

Sample Payloads

Query: networkInterfaces

query {
  networkInterfaces {
    id
    name
    macAddress
    mtu
    speed
    duplex
    internal
    operstate
    type
    ipv4Addresses {
      address
      netmask
    }
    ipv6Addresses {
      address
      prefixLength
    }
    vlanId
    virtual
  }
}

Example Response:

{
  "data": {
    "networkInterfaces": [
      {
        "id": "eth0",
        "name": "Ethernet 0",
        "macAddress": "00:1a:2b:3c:4d:5e",
        "mtu": 1500,
        "speed": 1000,
        "duplex": "full",
        "internal": false,
        "operstate": "up",
        "type": "wired",
        "ipv4Addresses": [
          { "address": "192.168.1.100", "netmask": "255.255.255.0" }
        ],
        "ipv6Addresses": [
          { "address": "fe80::21a:2bff:fe3c:4d5e", "prefixLength": 64 }
        ],
        "vlanId": null,
        "virtual": false}
    ]
  }
}

---

Subscription: systemMetricsNetwork

subscription {
  systemMetricsNetwork {
    name
    bytesReceived
    bytesSent
    packetsReceived
    packetsSent
    receiveErrors
    transmitErrors
    receiveDropped
    transmitDropped
    rxSec
    txSec
    utilizationPercent
    lastUpdated
  }
}

Example Response Stream (updates every ~2s):

{
  "data": {
    "systemMetricsNetwork": {
      "name": "eth0",
      "bytesReceived": 104857600,
      "bytesSent": 52428800,
      "packetsReceived": 150000,
      "packetsSent": 120000,
      "receiveErrors": 0,
      "transmitErrors": 0,
      "receiveDropped": 0,
      "transmitDropped": 0,
      "rxSec": 204800,
      "txSec": 102400,
      "utilizationPercent": 2.5,
      "lastUpdated": "2025-08-20T20:45:00.000Z"
    }
  }
}

---

Additional Notes

• Schema should map closely to the systeminformation outputs with only naming adjustments for GraphQL conventions.
• Calculated values (e.g., utilizationPercent) should be included in the subscription payload.
• Consider future enhancements such as:
  • Retaining short-term history of metrics for charting (e.g., last 5–10 minutes in memory).
  • Filtering subscriptions by specific interface names.
  • Exposing link aggregation / bonding information if available via systeminformation.

[ruaan-deysel]

I would like to claim this

[retrozenith]

Hello. Is this already in progress or claimed ?