Network Topology Guide
Learn how to use the Network Topology (Net3D) screen, which visualizes your servers, databases, and the connections between them as a 3D space.
⚠️ Scope of this document
This document covers how to use the screen only. The formats for submitting data yourself (tKVS
kFactor/kKey/kValue) are not described here, so this document alone is not enough to insert data.
- To submit data yourself → Network Topology (Net3D) API Reference
- To display arbitrary non-network data (order flows, org charts, service dependencies and the like) in this 3D layout → see the "Appendix: Displaying Non-Network Data in This Layout" section of the API reference. Simply changing
kFactorto an arbitrary value and pushing it into tKVS does not work (the write succeeds, but nothing is displayed on screen).
📋 Overview
Network Topology renders the servers and databases belonging to your current project (CSN) as a 3D graph. The links between nodes represent actual SQL communication, and their color and particle-flow speed change in real time according to load. Data is loaded based on the CSN of your logged-in session.
🔍 Screen Layout
1. Nodes
- Servers appear as spheres and databases as cylinders.
- Node color reflects status: blue/green for healthy, red when load exceeds the threshold, a red tone when active queries exceed the threshold, and orange when there is an open transaction.
- A custom color assigned directly to a node takes priority.
2. Links
The lines connecting nodes are SQL communication paths. They shift from green → yellow → orange → red based on CPU load, and links with recent SQL activity show faster directional particles.
3. Node Detail Bubble
Clicking a node moves the camera to it and opens a detail bubble. Servers show host details and an IP list; databases show DB details. From the bubble you can save a custom color and memo, or open the server/DB edit modal via the Modify button.
4. Search & Auto-Refresh
Use the on-screen search box to find a node by name and focus it instantly. Enabling the Auto-Refresh toggle periodically reloads the data.
5. Known Nodes (External Node Management)
Unregistered external nodes are managed as Known Nodes. From the list modal you can delete a node or unlink its IP address.
6. Timeline & Time Travel (History Mode)
Selecting a past point on the timeline at the bottom of the screen rewinds the topology to that moment (History mode). When active, HISTORY MODE and the target time are shown in the lower-right corner.
7. Settings (Thresholds)
In the settings modal you can adjust the node/link load warning threshold and the active query critical threshold. Color criteria are recomputed immediately and reflected in the graph.
🛠️ Tips
- The current node count and link count are shown in the lower-right corner.
- If there are no nodes or data, a [Register Machine] or [Register Database] prompt appears; clicking it navigates to the corresponding registration page.
- When the total of nodes and links is large (roughly over 700), particle effects are automatically reduced for performance.
💡 Important Notes
- This page requires login and displays data based on your session's CSN.
- If saving a custom color or memo fails, the error is logged to the browser console.
Troubleshooting
| Symptom | Cause | Resolution |
|---|---|---|
| No nodes shown, only a registration prompt | No servers/DBs are registered under the current CSN | Click [Register Machine] or [Register Database] to register assets first. |
| Stuck at "Loading Universe..." | Data load delay or expired session | Enable auto-refresh or reload the page, and log in again if needed. |
| An Error message is displayed | The data-fetch API call failed | Retry after a moment; if it persists, check the CSN and network status. |
| Custom color/memo does not save | The save API response was not success (200) | Check the browser console for errors and retry. |
| Node colors look unexpected | Caused by the load / active-query threshold settings | Adjust the thresholds in the settings modal. |
Version: 1.1
Last Updated: 2026-09-14
Source: giipv3/public/help/network-topology.en.md