LibreQoS/docs/v2.0/insight.md

LibreQoS Insight (Insight)

About Insight

Learn more about Insight on our website, here.

Insight UI

Taskbar

If you have more than one LibreQoS shaper box, you can select the shaper box you want to view using the Shaper Nodes dropdown box (located just below the search box).

Time Selector

By clicking the time selector (Last 24 Hours by default) you can set the time range for data display anywhere from 15 minutes to 28 days. You can also specify custom time periods (Now minus X minutes) or highly-specific detailed time periods.

Dashboard

You can see which shaper box "perspective" is in use by the listed shpaer box name at the top-left corner next to "Select a destination".

The dashboard for LibreQoS Insight is widget-based, and has multiple tabs - each of which can be edited.

Traffic Overview Tab

The default tab is the Traffic Overview tab - which displays both Live traffic levels as well as top-traffic endpoints - both by ASN and by Node.

Shaper Tab

The Shaper tab shows high-level stats for a particular LibreQoS shaper box.

• Active Circuit Count: The number of active customer circuits observed - based on the subscriber's traffic movement.
• Throughput: Shaper box throughput
• Shaper Packets: Packet-per-second rate of the Shaper box over time.
• Shaper TCP Retransmits Percentage: The percentage of TCP packets observed that were retransmitted. Consider this a proxy for packet loss. This value should typically remain below 1 % across the network.
• Shaper CAKE Activity: How active the CAKE shapers are on the network over time.
• Shaper Round Trip Time: The Round Trip Time average of traffic moving across the network.
• Shaper Round Trip Time Histogram: The Round Trip Time average of traffic moving across the network in histogram format.
• Shaper CPU Utilization: The peak and average CPU utilization of the shaper box over time.
• Shaper Memory Utilization: The RAM utilization of the shaper box over time.

Children Tab

• Shaper Child Throughput: The throughput of each top-level child node on the shaper box.
• Shaper Child TCP Retransmits: This can be used to spot outliers top-level nodes with regard to Retransmits (packet loss).
• Shaper Child Round Trip Time: This can be used to spot outliers top-level nodes with regard to Round Trip Time.

Heatmaps

This view shows the Round Trip Time, Retransmit, and Capacity heatmaps for the top-level nodes on this shaper box.

Site Rankings

This tab shows the health of Sites / Access Points / etc across the network in terms of their Round Trip Time, TCP Retransmits, and Capacity in each direction.

Node Map

This view allows you to identify the general topology of the network from LibreQoS Insight's perspective. If you hover over the bands between nodes, it will display the current throughput and TCP retransmits for that leg of the network.

Libby (AI Assistant)

Libby is an assistive chat interface for Insight operations and documentation lookup.

Operational guidance:

• Treat Libby output as assistive guidance, not an authoritative change command.
• Validate recommendations against current node status, logs, and documented procedures before making production changes.
• For sensitive/impactful actions, confirm with standard operator workflows (service status, scheduler state, and rollback path).

Site Heatmap

This view provides RTT, Retransmit, and Capacity heatmaps for every Access Point, OLT, and Site across your network in one view. This allows you to quickly spot trouble points on your network.

Tree History

The Tree History is based on the Tree Overview display from the LibreQoS WebUI, and displays the sankey over time to help quickly identify network bottlenecks impacting performance.

Reports

LibreQoS Insight enables you to trigger AI-generated reports on specific subscriber circuits. These reports draw in from the customer's last 7 days of network activity - including per-ASN performance characteristics, network topology context, and geographic context. The report identifies the User Profile, Key Findings, Critical Issues, Performance Trends, an Upgrade Recommendation, and suggestions for items to manually review.

Alerts

The Alerts section provides you with automated warnings of out-of-norm performance for nodes across the network (Access Points, OLTs, Sites).

Insight Licensing Behavior (Node-side)

Local key material and offline grants

LibreQoS stores Insight key material under:

<lqos_directory>/.keys/

Current builds can cache signed license grants locally so nodes can continue operating through temporary connectivity loss to Insight control services. Grant validity and expiration are enforced locally.

Operational notes:

• Keep .keys/ persistent across reboots.
• Treat .keys/ as sensitive local key material.
• If grant or key state is invalid, lqosd logs will show license/grant errors.

Mapped circuit limits and license state

Recent builds enforce mapped-circuit limits based on license state.

If your node is unlicensed/invalid, LibreQoS can enforce a default mapped-circuit cap. When the cap is exceeded, logs include messages such as:

• Mapped circuit limit reached
• Bakery mapped circuit cap enforced

When this occurs, check:

1. Insight license status in the UI.
2. journalctl -u lqosd for requested/allowed/dropped mapped counts.
3. Whether the number of mapped circuits exceeds your licensed allowance.