Worker logging


Worker logging records any data exchanged between a worker instance and the deployment that it is connected to, as well as other significant events, such as network status messages.

You can enable worker logging on any worker connection. The most useful types of logs are:

  • User-level op logs
    These logs record the ops and commands exchanged between the worker instance and the deployment. They contain each method that you call on the connection and each op that you receive from the connection. User-level op logs are useful for high-level debugging of worker instances during your development process.
  • Protocol logs
    These logs record messages at a lower level than ops or the methods that you call on the connection. There is no one-to-one correspondence between protocol logs and user-level op logs, and the messages that are exchanged can change arbitrarily between SDK versions (including patch versions) and Runtime versions. These logs are primarily designed for SpatialOS engineers to help identify internal issues, and we might ask you to provide protocol logs when you report an issue.

Enable worker logging

The GDK for Unreal uses the Worker SDK user-level op and protocol logs for its worker logging. To enable user-level op logs or protocol logs, use the relevant command-line argument:

You should be cautious when you use worker logging:

  • Although the output is human readable and the prefix of each log message has a fixed format, this format can change between SDK versions (including patch versions). In particular, protocol logs don’t come in a specific format and we strongly discourage you from attempting to parse them.
  • Worker logging (especially protocol logging) incurs a cost in terms of CPU cycles.

Worker SDK op and protocol log file paths

The GDK saves Worker SDK op and protocol logging data to a file with a file path that depends on the structure of your project. Typical file paths are as follows:

  • <Project>\Game\Saved\Logs\UnrealWorker<Worker ID>-0.log (for server-workers) or
  • <Project>\Game\Saved\Logs\UnrealClient<Worker ID>-0.log (for client-workers)

The file name always contains the worker instance ID and -0.log suffix, but you can specify a custom file name prefix. This is useful when you want to distinguish the logs from multiple deployment runs. To specify a custom prefix, use the -workerSDKLoggingPrefix command-line argument.

Read worker logs

The log directory is the same for both local and cloud deployments. However, the procedure to access it is different.

Local deployments

For a local deployment, go to the log directory, as described in Worker SDK op and protocol log file paths above.

Cloud deployments

For a cloud deployment, you must access the worker directory on the cloud server.

  1. From the deployment page in the Console, select the Nodes tab.
  2. Select the worker_nanny node.
  3. Select Raw logs.

This takes you to a simple web interface for inspecting the raw worker logs for the deployment.

You can then find the raw logs for a particular worker instance in the following files:

  • UnrealWorker<Worker ID>-0.log

  • UnrealClient<Worker ID>-0.log

2020-06-04 Page created with editorial review.

Updated about a year ago

Worker logging

Suggested Edits are limited on API Reference Pages

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