Diagnostics
Rotating log files, an adjustable log level, and a support bundle you download in one step, for the server and every bridge. Diagnose a problem without shell access to any host.
Requires role: Admin (Viewers and Operators can't open this page or use its actions) Related: Support Access, License Enforcement, Bridge Configuration, Security Architecture
Overview
The server and each bridge keep a rotating log file, in addition to what your container platform captures from standard output. The file survives events the standard-output copy may not, such as a database outage during the window you need to review. You choose how long the files are kept, and you can turn on detailed logging for a fixed time without a restart.
The Diagnostics page (Admin > Diagnostics) brings this together. From it you can:
- Change the log level for the server and every bridge.
- Read and search the server's log, or follow it live.
- Fetch a bridge's log on demand, over the bridge's existing connection to the server.
- Download a support bundle for a GraphnAI Support engineer.
Nothing on this page uploads anything. Every download, the support bundle included, goes from the server straight to your browser.
The page keeps working when your license has expired and the rest of the platform is read-only. That's often when you need it, for example to find out why a renewal isn't applying.
Prerequisites
- Role: Admin. Every action on the page returns a permission error for Viewer and Operator accounts.
- Nothing to configure. Log files, the default log level and default retention are active from first boot.
- A connected bridge, to fetch that bridge's logs or include them in a support bundle. A disconnected bridge's log stays on its host. See Troubleshooting.
Step-by-step instructions
Opening the page
Go to Admin > Diagnostics. The Log level and Support bundle cards sit side by side at the top. Below them is a row of tabs: Server, then one tab per bridge. Each bridge tab shows the bridge's ID (for example, lab-01) rather than the domains it syncs.
Changing the log level
The Log level card lists the current level of the server and of each bridge. Each bridge also shows when it last reported in, or "Not connected".
To change the level:
- Choose Debug, Info, Warning or Error from Level.
- If you chose Debug, choose how long from For: 15 minutes, 1 hour, 4 hours or 24 hours.
- Select Apply.
Debug adds detail while you work a problem. It always has an end time, because left on it only fills the disk. While it runs, the card shows "Debug ends in" with a countdown. When the time is up, the level goes back to Info by itself. That happens even if nobody has the page open, or the server restarted in the meantime.
The new level reaches every connected bridge at once. If a bridge couldn't be reached, the card names it: "Not pushed to: <bridge ID>. It will pick up the level when it reconnects." You don't need to apply it again. The server sends the current level when the bridge reconnects.
Setting how long logs are kept
On the same card, Keep logs for and Size cap control retention:
- Keep logs for: how many days of rotated log files to keep before deleting them. Enter 1 to 90 days. The default is 14.
- Size cap: the most disk space one component's logs can use, for the server or for one bridge. When logs pass it, the oldest rotated files are deleted first. Enter 100 to 20,480 MB. The default is 1,024 MB (1 GB).
Enter the new values and select Apply. A value outside the range is refused on the spot ("Enter a number between X and Y …"), never rounded. The hint under the fields shows the defaults. The change applies at once, with no restart. It also reaches every connected bridge, the same way a level change does, so every component keeps the same retention.
Reading and searching server logs
The Server tab shows the server's own log file:
- Window: Last 15 minutes, Last hour, Last 24 hours, or Custom (choose a start and end time).
- Minimum level: shows only lines at or above the level you choose.
- Search logs: plain text search. Case doesn't matter.
- Follow: turns the table into a live view of new lines as the server writes them, filtered by your level and search. Follow works for the server only. Bridge tabs show "Live tail is available for the server only", because a bridge sends its log only when you fetch it.
- Download window: downloads every line in the window at or above the minimum level as one compressed file (
.jsonl.gz). The search text doesn't apply, and there's no row limit.
Select a row to see every field logged for that line. Select Copy to paste it into a ticket.
A search reads up to 5,000 rows or 256 MB of log data, whichever comes first. When it stops early, one of two messages appears:
- "Showing the first 5,000 lines. Narrow the window or download it." The row limit was reached.
- "Stopped after scanning 256 MB. Narrow the window or download it." The data limit was reached, however few lines matched.
Narrow the window or the search to get a complete result, or download the whole window.
Each Admin can run two live views at once, and the server allows eight in total. A third from the same account shows "Live tail limit reached. Close another tail first." Turn Follow off on another view, or close its browser tab, to free a slot.
Fetching logs from a bridge
A bridge's log stays on the bridge's host until you ask for it. Open the bridge's tab and use the Bridge log fetch panel:
- Choose the window and the minimum level.
- Select Fetch bridge logs.
The bridge sends the window back over its existing outbound connection. Bridges never accept inbound connections, so this opens no port on the bridge host. While the fetch runs, a progress bar shows "Fetching… N MB received". When it finishes, the status reads Ready and a Download button appears.
Fetch history keeps each bridge's last 10 fetches for 24 hours. Select a row to load that fetch's lines into the table below. A fetch that stopped early or was refused says why. See A bridge fetch didn't finish cleanly.
Fetch bridge logs is disabled while the bridge is disconnected, and its tooltip says why.
Downloading a support bundle
The Support bundle card builds one file for a GraphnAI Support engineer to work from.
- Choose a Window.
- Select Download support bundle.
- Review the dialog.
- Select Download bundle.
The dialog shows three things before anything downloads:
- A notice that says what the bundle holds, and that it's built on this server and downloaded to your browser only. Nothing is sent to GraphnAI.
- Every file the bundle will hold, grouped under Server and Bridges.
- Any bridge left out, with the reason. See A bridge is missing from the support bundle.
If a bridge is left out only because nobody fetched its logs recently, the dialog offers Fetch bridge logs first. It opens that bridge's tab with the fetch panel ready. The bundle downloads as one .zip file named with the server's timestamp, for example graphnai-support-bundle-20260907-1830.zip.
A support bundle contains:
- The product version and build.
- Health and readiness status.
- The license state, without the license file.
- Bridge connection status and heartbeats.
- A summary of the last 50 syncs.
- A copy of the platform configuration with passwords, keys, tokens and encrypted values removed.
- A snapshot of running goroutines and memory use, with current runtime metrics.
- The server's log for the window you chose.
- Every bridge log fetch that finished in the last 24 hours.
The logs can include user names, computer names, domain names and IP addresses. Review the bundle before you share it.
A bundle never contains the license file, remediation credentials, encryption keys, session-signing keys, certificate private keys, or any bridge's stored connection secret. No option adds them.
Configuration options
You set retention days and the size cap on the page (see above). They apply at once, with no restart.
Whoever deploys the platform can set a few more values in the server's configuration. They apply at startup only: the retention and size cap defaults used until an Admin saves values on the page, the size and idle timeout of a bridge log fetch, the largest log slice a support bundle holds, and where log files are written. A value outside its allowed range is moved to the nearest limit, and the log records a warning that names it.
Once you save retention or the size cap on the page, the saved value replaces the deployment default, including after a restart.
Troubleshooting
"Bridge is offline. Logs stay on the bridge host."
You tried to fetch logs from a bridge that isn't connected, or to include it in a bundle. Nothing is lost. The bridge's log is still on its host at /app/data/logs/bridge.log, and you can read it there with shell access. Otherwise, reconnect the bridge and fetch again.
"Live tail limit reached. Close another tail first."
Your account already has two live views open, or the server has eight across all Admins. Close one you're not using: turn Follow off on that tab, or close its browser tab. Then try again.
A search or download stopped early
"Showing the first 5,000 lines…" or "Stopped after scanning 256 MB…" means the window was too dense or too long for one search. Narrow the window, search for something more specific, or select Download window to get the whole range as a file.
A bridge is missing from the support bundle
Open the bundle dialog and check the reason next to the bridge:
| Reason shown | What it means | What to do |
|---|---|---|
| no recent log fetch | Nobody fetched this bridge's logs in the last 24 hours | Select Fetch bridge logs first in the dialog, or fetch from the bridge's tab, then open the bundle dialog again |
| offline | The bridge isn't connected | Reconnect the bridge, fetch its logs, then open the bundle dialog again |
| last fetch failed | The bridge's last fetch didn't finish | Fetch again from the bridge's tab |
| fetch still running | A fetch for this bridge is in progress | Wait for it to finish, then open the bundle dialog again |
| over the bundle size cap | This bridge's log would push the bundle past its size limit | Fetch a shorter window for that bridge, then open the bundle dialog again |
A bridge fetch didn't finish cleanly
The fetch panel's status says what happened:
- "The bridge stopped sending after 10 minutes. Check the bridge log on its host." The bridge went quiet mid-transfer. Check its connection and try again.
- "The window was cut at N MB. Narrow the range and fetch again." The transfer reached its size limit before the end of the window. Ask for a shorter window.
- "The bridge sent more than the N MB limit. Narrow the range and fetch again." The bridge had more to send than a fetch allows. Ask for a shorter window.
- "The bridge couldn't read its log. Check the bridge log on its host." The bridge couldn't open its own log file.
- Any other message is the bridge's own reason for refusing, shown as the bridge reported it. For example, a fetch may already be running for that bridge.
A log line shows the level "Unknown"
Every log line is written as one JSON record. A line that doesn't read back as one shows the level Unknown, no time, and its text exactly as the file holds it. The usual cause is a second copy of the server started on the same data directory while the first was still running. Both then write the same file, and one overwrites the start of the other's lines.
A second copy started that way no longer writes the file. It waits up to 5 seconds for the first copy to exit. Then it logs Another process is writing this log file; file logging disabled, stdout continues and writes to standard output only. If you see that message, another server process still holds the log file. Stop it before you start the new one. A damaged line already in the file stays readable in raw form until the file ages out.
The message file logging continues without the duplicate-writer guard means the log file is being written normally, but the platform can't detect a second copy. Either the data directory's storage doesn't support file locks, or another account owns the lock file next to the log. Nothing is lost. Don't start two copies on that directory.