Description

RealityServer supports the V8 Inspector Protocol for remotely debugging V8 command execution. Debugging support is disabled by default and can be enabled by adding the inspector directive into a V8 user config block:

‎<user v8>
commands v8/commands
include v8/include
# enable the inspector on port 20000
inspector 20000
# also enable developer mode for live V8 command reloading.
developer_mode on
</user>

RealityServer starts a web server on the configured address that connects a web socket to the V8 engine debugger. To debug commands run Chrome on any machine that can connect to the running RealityServer and connect via the following address:

‎devtools://devtools/bundled/inspector.html?v8only=true&ws=RS_HOST:INSPECTOR_PORT

Replacing RS_HOST and INSPECTOR_PORT with the hostname and inspector port. Once connected switch to the sources tab and select the page panel. The installed V8 commands and modules can then be browsed either under the file:// or (no domain) tree. Command source can be opened, breakpoints set and when executed the debugger will pause execution to allow variable inspection and flow control tracing just like debugging regular web page JavaScript. You can even enter JavaScript into the console which will be executed on RealityServer. You cannot however execute commands in this way as the console has no command execution environment available.

Caveats And Restrictions

The inspector is only able to be associated with a single V8 isolate, so when enabled the RealityServer isolate pool is restricted to a single isolate only. This means that parallel V8 command requests are not possible and concurrent command execution will be serialized. For this reason the inspector must never be enabled in production systems as it will have a severe performance impact.

When enabled the inspector overrides the standard `console` logging implementation and forwards all log messages to the debug console rather than the RealityServer log file. This occurs even if there is no debugger connected to the inspector at the time. If you require log file logging when debugging commands use the `log` command instead.

A debug session will be terminated when the isolate being debugged is discarded, as happens when a V8 command or module is modified on disk or RealityServer is shutdown. When this occurs Chrome will display a 'WebSocket disconnected' dialog with a 'Reconnect DevTools' button. Once commands are reloaded (or RealityServer restarted) simply hit this button to resume your debug session.

It is not possible to reconnect a debugging session to the same isolate. If the Chrome DevTools page is reloaded no source files will be found. RealityServer will need to be restarted (or a command/module modified on disk if developer mode is enabled) to create a new isolate and the debug session reconnected.