Tutorial 156: Watch a Running Game in the Inspector

CNA Tutorials  ·  CNA snapshot 009d40f5

Before you start

• A CNA checkout of the next branch (git clone -b next https://github.com/libcna/cna.git, with sharp-runtime also on next and the sibling checkouts from Tutorial 02).
• A browser on the same machine. The UI is served by a local bridge, loads no CDN assets and needs no network.
• Ideally, Tutorial 155: the Inspector shows what Diagnostics collects, so it only makes sense when CNA_DIAGNOSTICS is STATS or FULL.

Configure and build

Two options switch the feature on. CNA_DIAGNOSTICS=FULL gives the Inspector CPU zones and an event log (STATS gives metrics and resources only); CNA_BUILD_INSPECTOR=ON builds the agent library, the bridge and, because CNA_BUILD_EXAMPLES is on by default, the demo.

cd cna
cmake -S . -B build -DCNA_DIAGNOSTICS=FULL -DCNA_BUILD_INSPECTOR=ON
cmake --build build --target cna_inspector_demo cna-inspector -j"$(nproc)"

With no display, add -DCNA_PLATFORM=HEADLESS -DCNA_GRAPHICS_RENDERER=HEADLESS -DCNA_AUDIO_PLATFORM=NULL to the configure line; the demo “runs under any platform, including HEADLESS”, and the Inspector needs no particular renderer. The demo executable lands in the build root, build/cna_inspector_demo; the bridge lands in build/modules/inspector/cna-inspector.

Start the demo game

The demo is a small game that draws 48 sprites into a render target, composes them over a background, burns a little CPU each update, and creates and destroys a texture every two seconds so that resources come and go. It starts the Inspector agent before Game::Run() and prints the two values the bridge needs:

build/cna_inspector_demo --port 47001 --seconds 300
# Inspector port: 47001
# Inspector token: <a long random token>

--port is optional (without it the operating system picks a free port, which is what gets printed) and --seconds N ends the demo after N seconds (the default, 0, runs until you close it). Leave this terminal alone; in a second terminal, put the token in a file only you can read, so it never appears on a command line or in your shell history:

umask 077
printf '%s' 'PASTE-THE-TOKEN-HERE' > inspector.token

Start the bridge

cd cna
build/modules/inspector/cna-inspector --agent-port 47001 --token-file inspector.token
# CNA Inspector is available at http://127.0.0.1:<port>/
# The bridge is localhost-only. Press Ctrl+C to stop it.

The bridge needs the agent’s port and a token (from --token, --token-file or the CNA_INSPECTOR_TOKEN environment variable; prefer the file or the variable, because a --token argument is visible in the process list). It picks a free browser port unless you pass --http-port, and it always binds to 127.0.0.1. Open the printed URL.

A tour of the eight views

The page polls every 500 ms. A status light in the top bar reads connected while it works and reconnecting when a request fails. What you should find, view by view, given how the demo is written:

If a warning banner about discontinuities appears, the UI has detected events that were lost since it connected (dropped or overwritten before they could be read). That is a statement about the log, not a fault in your game. Nothing you click changes the running game.

When the demo’s --seconds elapse (or you close its window) the status light turns to reconnecting; start the demo again with the same port and a new token and restart the bridge with the new token to watch another run.

Add the Inspector to your own game

The Inspector is never automatic: it exists only if your code starts an agent. Link the module next to CNA and start the agent before you run the game, keeping the returned pointer alive for the whole run. This function was checked to compile against the snapshot’s headers:

// Start the Inspector agent explicitly, before Game::Run(), and keep it alive for the whole run.
#include "CNA/Inspector/Agent.hpp"

#include <cstdio>
#include <memory>
#include <string>

std::unique_ptr<CNA::Inspector::Agent> StartInspector()
{
    CNA::Inspector::AgentConfiguration configuration;
    configuration.applicationName = "My game";
    configuration.port = 0;                       // 0 = let the OS choose; read it back below
    configuration.metadata = {
        {"Resolution", "640x360"},
        {"Build", "tutorial"},
    };

    std::string error;
    std::unique_ptr<CNA::Inspector::Agent> agent =
        CNA::Inspector::Agent::Start(configuration, error);
    if (!agent)
    {
        std::fprintf(stderr, "Inspector did not start: %s\n", error.c_str());
        return nullptr;
    }
    std::printf("Inspector port: %u\n", static_cast<unsigned>(agent->GetPort()));
    // The token is a secret: hand it to the developer over a local channel, not to shared logs.
    std::printf("Inspector token: %s\n", agent->GetAuthenticationToken().c_str());
    std::fflush(stdout);
    return agent;
}

int main()
{
    std::unique_ptr<CNA::Inspector::Agent> inspector = StartInspector();
    if (!inspector)
        return 1;
    // ... construct your Game and call Run() here; the agent stops when `inspector` is destroyed.
    return 0;
}

target_link_libraries(my_game PRIVATE CNA CNA::Inspector)

Configure your project with -DCNA_BUILD_INSPECTOR=ON and a Diagnostics level of at least STATS. Agent::Start returns null and fills error if it cannot start (for example, a non-loopback address without allowRemote). Give the developer the port and the token over a local channel; do not log the token in a build you share. Then run exactly as above: your game prints the values, you start cna-inspector with them, and you open the URL.

Inspecting another machine

The agent binds to 127.0.0.1 by default, and the agent–bridge protocol is plaintext TCP that carries the token in its handshake. Do not switch on allowRemote to reach a game across a network. Tunnel the loopback port instead, so the bridge on your machine still talks to a loopback address:

ssh -N -L 47001:127.0.0.1:47001 user@game-machine     # first terminal
build/modules/inspector/cna-inspector --agent-port 47001 --token-file inspector.token   # second terminal

Troubleshooting

Next steps

• Inspector reference — configuration table, security model, wire protocol and limits.
• Diagnostics reference — what the Inspector is reading.
• Tutorial 155 — instrument your own metrics and read them in code.