Debug worker instances using logs

Introduction

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 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

How you enable worker logging depends on which SDK language you use, but the general flow is the same: you need to configure your connection parameters with one or more log sinks.

  • For each log sink, choose its type. A log sink can log its messages to a rotating set of files, stdout or stderr (both with optional support for ANSI terminal color coding), or to a custom callback where you can process messages yourself.
  • For each log sink, choose a filter. A filter generally consists of a log level and one or more log categories. However, for more advanced use cases, you can also provide a custom filter callback to configure which logs should be sent to the log sink.
    • For the log level, we recommend that you select INFO or a more restrictive level. DEBUG is likely to be very verbose and is not required under most circumstances.
    • The log categories determine what kind of logs you want to generate. To generate user-level op logs, include the API category. For protocol logs, select both NETWORK_STATUS and NETWORK_TRAFFIC.

For specific information about how to set these parameters, see the API reference for C, C++, C#, or C# bindings.

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.

Updated about a year ago


Debug worker instances using logs


Suggested Edits are limited on API Reference Pages

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