Analyze your game’s performance with Session Frontend

You can use Unreal Editor’s Session Frontend profiler to monitor your server-worker instances’ performance in a cloud deployment. You can also use Session Frontend to test your game with Unreal console commands on a remote machine.

To debug your running worker instances in the cloud, do the following:

  1. Enable Messaging for the server-worker types you want to monitor.
    Each server-worker listens to the same port on address (localhost does not work).
  2. Set up the connections from your local machine to the server-workers:
    a. Connect to a local address.
    b. Make a tunneling connection to the chosen worker.

Image: Connecting to server-workers from a local machine.

Session Frontend contains a profiler tool you can use to monitor game performance. It uses the Message Bus to collect debug data from your server-worker or client-worker instances.

Each worker has its own Message Bus, which enables communication between parts of the application with message passing. You can use the TcpMessaging plugin to create a Message Bridge between your local machine and your workers in the cloud.

For more information, see the following:

  • IMessageBus in the Unreal documentation
  • Unreal Message Bus overview
  • 1. Enable messaging

    To enable messaging (the Message Bus, Message Bridge and other components), you must add the flag -messaging to the server-worker configuration. To do this:

    1. Open the file <ProjectRoot>/spatial/workers/unreal/spatialos.UnrealWorker.worker.json. See <ProjectRoot> for more information.
    2. In the linux worker, add the flag -messaging as follows:

    Next, specify the port you want the server-worker to listen on. There are two ways to do this:

    • Option 1: With the Unreal Editor settings
    • Option 2: In the DefaultEngine.ini file

    Option 1: With the Unreal Editor settings

    1. In the GDK toolbar, open the Start Deployment drop-down menu.
    2. Select Runtime Settings.
    3. In Plugins > TCP Messaging > Listen Endpoint, enter<port number>, for example
    1. Rebuild your project in Visual Studio.
    2. Upload your project’s assemblies to your cloud deployment. The easiest way to do this is to select Build and Upload Assembly in the Cloud Deployment Configuration dialog.

    Option 2: In the DefaultEngine.ini file

    1. Open the folder <ProjectRoot>/spatial/build/assembly/worker. See <ProjectRoot> for more information.
    2. Unzip the file [email protected].
    3. Open the unzipped files and open <YourProject>/Config/DefaultEngine.ini (see <YourProject> for more information) in a text editor:
    1. Add the following details to the ini file. In this example, we use port number 6667.
    1. Upload the assemblies. You do not need to rebuild your project.

    When you deploy your game, the Unreal Editor’s output console displays a log entry similar to the following:

    2. Set up the connections

    You must set up your local Unreal Editor’s connection to each of your server-workers. In the Editor, you first specify the port for each server-worker you want to debug, and then you set up the tunneling.

    For each server-worker you want to debug, do the following:

    1. In the Unreal Editor’s GDK toolbar, open the dropdown menu next to Start/Stop Deployment and select Runtime Settings.
    2. Open Plugins > TCP Messaging.
    3. Next to Connect to Endpoints, click + to add a new element.
    4. In the new element, enter<port number>, where <port number> is the listening port of the server-worker. For example, you might enter
    5. Repeat steps 3-4 for each additional server-worker you want to debug. The following image shows a configuration for two server-workers:
    1. Open a command-line window and navigate to <ProjectRoot>/spatial/. See <ProjectRoot> for more information.
    2. For each worker you want to debug, run the following command:
    spatial project deployment worker port-forward -d=<deployment_name> -w=<<worker_id> -p=<port_number>

    For example:

    When you deploy your game, in the Editor’s log window you see a message that indicates that a bridge connection is established:

    When you use Spatial TCP port forwarding, you avoid several problems associated with connecting to the cloud with a raw IP address. For example, you do not need to find the right IP address or deal with firewalls.

    The port-forward command allows you to connect to the cloud deployment directly through localhost.

    When a bridge is established, worker sessions appear in the Session Frontend. In the Unreal Editor’s Window menu, select Developer Tools > Session Frontend.

    Image: Session Frontend

    Remote commands

    You can run Unreal console commands on a remote machine in Session Frontend to analyze your game’s performance.

    Example remote commands:

    • log <log category name> <log verbosity>: Dynamically changes log verbosity for the given category. For example, log LogGameState off disables logging for the GameState log category.
    • obj gc: Triggers a garbage collection sweep.
    • memreport: Displays a detailed breakdown of memory usage per system.

    Enable remote commands

    To enable remote commands, you must add your Windows username to the list of authorized users.

    You can find out your username in Visual Studio’s debug mode. To do that, check the value in FApp::GetSessionOwner().

    Image: Use FApp::GetSessionOwner() to find out your username

    In FEngineService::FEngineService() add the following lines of code (where <username> is your user name):

    // always grant access to session owner

    Add the code as follows:

    When you deploy the game, you can use remote commands:

    Run a remote command

    To run a remote command:

    1. In Unreal Editor, select Windows > Developer Tools > Session Frontend.
    2. In the command line box at the bottom of the Session Frontend window, enter your command.
    1. Click Send Command.

    See also

    2021-01-14 Page updated with editorial review: fixed the Connect to Endpoints address
    2020-09-23 Page added with editorial review.

    Updated 8 months ago

    Analyze your game’s performance with Session Frontend

    Suggested Edits are limited on API Reference Pages

    You can only suggest edits to Markdown body content, but not to the API spec.