Bandwidth Monitoring

Bandwidth Monitoring tracks network throughput on every physical and virtual interface of your managed devices. The Breeze agent collects per-interface byte counters on each heartbeat, computes delta-based rates (bytes per second in and out), and reports both aggregate and per-interface statistics to the API. Historical bandwidth data is stored in the device_metrics table alongside CPU, RAM, and disk metrics, enabling long-term trending, capacity planning, and threshold-based alerting.

Bandwidth data is collected automatically — no additional configuration is required. As soon as a device enrolls and begins sending heartbeats, its network interfaces are tracked. The agent filters out loopback, container, and bridge interfaces so that only meaningful physical and virtual adapters appear in the data.

---

Collected Metrics

Aggregate Metrics

Aggregate bandwidth metrics represent the total throughput across all tracked interfaces on the device:

| Metric | Type | Description | |--------|------|-------------| | networkInBytes | bigint | Total bytes received since the last collection interval | | networkOutBytes | bigint | Total bytes sent since the last collection interval | | bandwidthInBps | bigint | Aggregate inbound throughput in bytes per second | | bandwidthOutBps | bigint | Aggregate outbound throughput in bytes per second |

Per-Interface Metrics

Each tracked interface reports detailed statistics in the interfaceStats JSONB column:

| Field | Type | Description | |-------|------|-------------| | name | string | Operating system interface name (e.g., eth0, en0, Ethernet) | | inBytesPerSec | number | Inbound throughput in bytes per second | | outBytesPerSec | number | Outbound throughput in bytes per second | | inBytes | number | Cumulative bytes received (absolute counter from OS) | | outBytes | number | Cumulative bytes sent (absolute counter from OS) | | inPackets | number | Cumulative packets received | | outPackets | number | Cumulative packets sent | | inErrors | number | Cumulative inbound errors (CRC, framing, etc.) | | outErrors | number | Cumulative outbound errors | | speed | number | Link speed in bits per second (0 if unknown). Queried from the OS and cached for 5 minutes. |

Note

The inBytes and outBytes fields are cumulative OS counters, not deltas. The agent computes the inBytesPerSec and outBytesPerSec rates by taking the difference between consecutive collections and dividing by the elapsed time. If the counter wraps (reboot or overflow), the agent skips the rate calculation for that interval to avoid reporting a false spike.

Utilization Calculation

Interface utilization can be derived from the per-interface data when the speed field is available:

utilization_percent = ((inBytesPerSec + outBytesPerSec) * 8 / speed) * 100

The speed field reports the interface’s negotiated link speed in bits per second (e.g., 1000000000 for a 1 Gbps link). A value of 0 means the OS could not determine the link speed, which is common for Wi-Fi adapters on some platforms.

---

Data Collection

Collection Cycle

Bandwidth data is collected as part of the agent’s regular metrics cycle:

1. Agent heartbeat fires — The agent sends a heartbeat to the API at its configured interval (default: 60 seconds).

2. Metrics collector runs — The Go metrics collector (agent/internal/collectors/metrics.go) gathers system metrics including network I/O counters.

3. Aggregate bandwidth computed — The collector reads total bytes received and sent via net.IOCounters(false), computes the delta from the previous collection, and divides by elapsed time to produce bandwidthInBps and bandwidthOutBps.

4. Per-interface bandwidth computed — The collector reads per-interface counters via net.IOCounters(true), computes per-interface deltas and rates, queries link speed from the OS, and builds the interfaceStats array.

5. Data sent to API — The heartbeat payload includes all metrics. The API writes a row to device_metrics with the aggregate bandwidth columns and the interface_stats JSONB column.

Rate Calculation Guards

The agent applies several safeguards to prevent reporting incorrect bandwidth data:

| Guard | Behavior | |-------|----------| | Minimum elapsed time | Rates are only computed when at least 1 second has elapsed since the last collection. Prevents division by near-zero intervals. | | Maximum elapsed time | If more than 300 seconds (5 minutes) have elapsed, rates are skipped for that interval. Large gaps produce misleading averages. | | Counter wrap protection | If the current counter value is less than the previous value (reboot or 32-bit overflow), the rate is set to 0 for that interval. | | First collection | On the first heartbeat after agent start, no previous data exists. Rates are reported as 0 and absolute counters are recorded for the next interval. |

Interface Filtering

The agent skips interfaces that would add noise to bandwidth data:

| Filtered Interface | Platform | Reason | |-------------------|----------|--------| | lo, lo0 | All | Loopback — internal traffic only | | veth* | Linux | Virtual Ethernet pairs for containers | | docker* | Linux | Docker bridge interfaces | | br-* | Linux | Linux bridge interfaces | | vEther* | Windows | Hyper-V virtual Ethernet | | isatap* | Windows | IPv6 transition tunnels | | Teredo* | Windows | IPv6 Teredo tunnels |

Tip

Interfaces that appear and disappear between collections (e.g., VPN adapters) are tracked dynamically. The agent prunes stale interface entries when they are no longer reported by the OS, so disconnected VPN interfaces stop appearing in interfaceStats after one collection cycle.

Link Speed Detection

Link speed is queried from the OS using platform-specific mechanisms:

| Platform | Method | |----------|--------| | Linux | Reads /sys/class/net/<iface>/speed (returns Mbps, converted to bps) | | macOS | Uses networksetup -getMedia or IOKit to read negotiated speed | | Windows | Queries Win32_NetworkAdapter WMI class for Speed property |

Link speed values are cached per interface for 5 minutes (speedCacheTTL) to avoid repeated system calls on every collection cycle.

---

Viewing Bandwidth Data

Device Detail Page

Bandwidth data is displayed on the device detail page in the network section. The UI shows:

• Aggregate throughput chart — Inbound and outbound bytes per second over time, plotted on a time-series graph.
• Per-interface breakdown — A table listing each tracked interface with its current throughput, cumulative bytes, packet counts, error counts, and link speed.
• Historical trending — Select time ranges from 1 hour to 30 days to view bandwidth patterns and identify peak usage periods.

Metrics API

Bandwidth data is returned as part of the standard device metrics endpoint:

GET /devices/:deviceId/metrics?range=24h

The response includes bandwidth fields in each time-series data point:

{
  "data": [
    {
      "timestamp": "2026-02-23T10:00:00.000Z",
      "cpu": 24.5,
      "ram": 67.2,
      "networkIn": 1048576,
      "networkOut": 524288,
      "bandwidthInBps": 17476,
      "bandwidthOutBps": 8738,
      "processCount": 142
    }
  ],
  "interval": "5m",
  "startDate": "2026-02-22T10:00:00.000Z",
  "endDate": "2026-02-23T10:00:00.000Z",
  "timezone": "America/Denver"
}

Time Range and Aggregation

The metrics endpoint supports multiple time ranges and automatically selects an appropriate aggregation interval:

| Range | Default Interval | Data Points (approx.) | |-------|-----------------|----------------------| | 1h | 1m | 60 | | 6h | 5m | 72 | | 24h | 5m | 288 | | 7d | 1h | 168 | | 30d | 1d | 30 |

You can override the interval using the interval query parameter (1m, 5m, 1h, 1d). Within each aggregation bucket:

• bandwidthInBps and bandwidthOutBps are averaged across data points in the bucket.
• networkIn and networkOut are summed (total bytes transferred in the period).

Note

Per-interface interfaceStats data is stored in the device_metrics table but is not included in the aggregated metrics API response. To access per-interface data, query the raw metrics table directly or use the device detail page in the UI.

---

Alerting

Bandwidth metrics can be used with Breeze alert rules to notify you when throughput crosses a threshold. Common alerting scenarios include:

Bandwidth threshold alerts

Create alert rules that fire when aggregate bandwidth exceeds a defined threshold:

| Alert Scenario | Metric | Condition | Example Threshold | |---------------|--------|-----------|-------------------| | High inbound traffic | bandwidthInBps | Greater than | 100,000,000 (100 MB/s) | | High outbound traffic | bandwidthOutBps | Greater than | 50,000,000 (50 MB/s) | | Sustained high utilization | bandwidthInBps + bandwidthOutBps | Greater than for N minutes | 80% of link speed | | Interface errors | interfaceStats[].inErrors | Greater than | 100 errors per interval |

Setting up a bandwidth alert

1. Navigate to Alerts — Open the alert rules configuration for your organization.

2. Create a new rule — Select the metric type (device performance metrics) and choose bandwidthInBps or bandwidthOutBps as the metric.

3. Set the threshold — Define the condition (greater than, less than) and the threshold value in bytes per second.

4. Configure scope — Apply the rule to specific devices, device groups, sites, or the entire organization.

5. Set notification — Choose notification channels (email, Slack, webhook) and severity level.

Playbook integration

Bandwidth alerts can trigger Playbooks for automated remediation. For example, a playbook could:

• Diagnose which process is consuming bandwidth
• Restart a misbehaving service
• Apply a QoS policy
• Notify the network team

Configure the playbook’s triggerConditions.alertTypes to include your bandwidth alert type and set autoExecute based on your confidence in the remediation workflow.

---

API Reference

Bandwidth data is accessed through the standard device metrics endpoints. There are no separate bandwidth-specific endpoints — bandwidth is part of the unified metrics pipeline.

| Method | Path | Description | |--------|------|-------------| | GET | /devices/:id/metrics | Get device metrics including bandwidth data |

Query Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | range | string | No | Predefined range: 1h, 6h, 24h, 7d, 30d | | startDate | ISO 8601 | No | Custom range start (overrides range) | | endDate | ISO 8601 | No | Custom range end (defaults to now) | | interval | string | No | Aggregation interval: 1m, 5m, 1h, 1d (auto-selected from range if omitted) |

Response Bandwidth Fields

Each data point in the data array includes:

| Field | Type | Description | |-------|------|-------------| | networkIn | number | Total bytes received in the aggregation bucket | | networkOut | number | Total bytes sent in the aggregation bucket | | bandwidthInBps | number | Average inbound throughput (bytes/sec) across the bucket | | bandwidthOutBps | number | Average outbound throughput (bytes/sec) across the bucket |

Database Schema

Bandwidth data is stored in the device_metrics table:

| Column | Type | Description | |--------|------|-------------| | network_in_bytes | bigint | Delta bytes received | | network_out_bytes | bigint | Delta bytes sent | | bandwidth_in_bps | bigint | Inbound rate in bytes/sec | | bandwidth_out_bps | bigint | Outbound rate in bytes/sec | | interface_stats | jsonb | Per-interface InterfaceBandwidth[] array |

---

Troubleshooting

Bandwidth data shows 0 for the first data point after agent restart. This is expected behavior. The agent needs two consecutive metric collections to compute a delta. On the first collection after startup, absolute counters are recorded but rates cannot be calculated because there is no previous value to subtract from. The next collection (typically 60 seconds later) will report accurate rates.

Interface not appearing in per-interface data. The agent filters out loopback, container, and bridge interfaces by default. If the interface name starts with lo, veth, docker, br-, vEther, isatap, or Teredo, it is excluded. Physical adapters and non-filtered virtual interfaces should appear automatically. Verify the interface is active and has traffic by checking the OS network counters directly on the device.

Link speed shows 0 for an interface. The speed field depends on the OS reporting a negotiated link speed. Wi-Fi adapters on some platforms do not expose speed through the standard system interfaces. On Linux, verify that /sys/class/net/<iface>/speed returns a valid value. A speed of 0 means utilization percentage cannot be calculated for that interface, but throughput data (bytes per second) is still collected accurately.

Large gap in bandwidth data. If the agent was offline or unable to reach the API for more than 300 seconds (5 minutes), the rate calculation is skipped for that interval to avoid reporting misleading averages. The gap appears as missing data points in the chart. Once the agent reconnects and resumes heartbeats, data collection resumes normally.

Bandwidth spikes at unusual times. Check whether the spike correlates with backup windows, software deployments, or patch installations. Use the per-interface breakdown on the device detail page to identify which interface carried the traffic. Cross-reference with the device’s command history and automation run logs to identify automated activities.

Metrics API returns bandwidthInBps: 0 but networkIn has a value. The bandwidthInBps field is an average rate (bytes per second), while networkIn is a sum of bytes transferred. At larger aggregation intervals (1 hour, 1 day), the averaged rate can appear low even when total bytes transferred is significant. This is mathematically correct — a device that transfers 1 GB over an hour averages approximately 291 KB/s. Use the raw networkIn / networkOut totals for volume analysis and bandwidthInBps / bandwidthOutBps for throughput analysis.

Per-interface data not available in metrics API response. The aggregated metrics API endpoint (GET /devices/:id/metrics) returns aggregate bandwidth fields but does not include the per-interface interfaceStats breakdown in its response. Per-interface data is stored in the device_metrics table and is accessible through the device detail page in the UI or by querying the database directly.