Skip to content

Diagnostics

OptimaGPT includes two diagnostic tools for troubleshooting: System Tracing, a structured real-time trace viewer for Gateway internals, and the Node Log, which shows live output from each connected node.

Node log

The node log is the first place to look when a node is misbehaving. Open a node's detail view from the Nodes page, then find the Log panel.

Node detail view with the Log panel visible, showing timestamped log entries with colour-coded levels

Log entries are colour-coded by level:

Level Colour Meaning
Info Blue Normal operational messages
Debug Green Detailed messages useful for tracing behaviour
Warning Yellow Something unexpected, but not a failure
Error Red A failure occurred
Critical Red (bold) A serious failure that may affect operation
Gateway Purple Messages from the Gateway side of the connection

Use the Info, Warning, Error, and Debug buttons at the top of the panel to filter which levels are displayed.

System tracing

System Tracing provides structured, channel-based traces across the Gateway's internal systems. It is useful for diagnosing issues that are not visible in the node log — such as authentication failures, API routing problems, or inference pipeline issues.

Enabling system tracing

System tracing is off by default. To enable it:

  1. Open Settings → General.
  2. Toggle on Advanced Developer Features.
  3. Toggle on Enable System Tracing.

Settings General section showing the Advanced Developer Features and Enable System Tracing toggles

Tracing is not retroactive — it only captures events that occur after it is enabled. Tracing resets when the Gateway restarts. Avoid leaving it on for extended periods in production.

Using the trace viewer

The trace viewer opens as an overlay panel when tracing is active. It uses a three-column layout:

System tracing panel showing the channel list on the left, instance list in the middle, and trace detail on the right

Channels (left column) — Named categories for different subsystems, grouped by area. A channel only appears once it has received at least one trace entry. Available channels include:

Channel Area Covers
LLM Inference API Chat completions pipeline
Embedding Inference API Embedding requests
Conversation API API Conversation CRUD operations
Models API API Model listing
Auth API API Login, refresh, logout
Install Executors Executor Management Executor install operations
Start Executor Executor Lifetime Executor startup
Stop Executor Executor Lifetime Executor shutdown

Instances (middle column) — Each request or operation creates an instance within its channel. Select an instance to see its trace entries.

Trace entries (right column) — The individual log lines for the selected instance, showing subject, source, and any attached detail.

Click Clear to remove all accumulated traces and start fresh.