# LibreQoS Insight
## About Insight
Learn more about Insight on our website, [here](https://libreqos.io/insight/).
## 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:
`/.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
`ShapedDevices.csv` can contain unlimited entries. In current v2.0 builds, admission into active shaping state depends on valid Insight license state.
Without a valid Insight subscription/license, LibreQoS admits only the first 1000 valid mapped circuits into active shaping state. Additional valid mapped circuits remain outside active shaping until valid Insight licensing is restored.
A valid Insight subscription/license enables mapped-circuit counts above the default 1000 limit.
The default 1000-limit behavior applies when Insight is:
- missing
- expired
- otherwise invalid
- operating with offline-invalid local grant state
When the limit is reached, operators will typically see:
- a prominent warning in WebUI
- a left-nav usage indicator showing proximity to the limit
- `lqosd` log 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 your node is operating at the default 1000 mapped-circuit limit because the current Insight/license state is invalid.