Logs
Logging with the spatial
command-line tool
spatial
outputs information to two places: to the
console and to spatial.log
(in the current working directory).
The console
By default, the console shows information messages, warnings and errors. You can increase or decrease the amount of
information shown in the console by adding the --log_level
option.
For example, use --log_level=warn
to show only warnings and errors in the console.
The log file
The log file, spatial.log
, shows information messages, warnings, errors, and additional debugging information.
It’ll always contain all this information, regardless of the --log_level
value you use in the console.
The file contains a rotation of previous logs, so some history is preserved. Each run is prefixed by ==========>
and the time and date spatial
was started. You can always find the latest run of the tool at the end of the file.
If the file gets too big (around 16MB), it will be emptied and restarted.
Adding more information
You can add call stacks to lines printed to the log file with the --log_callstack_level
option. This will help
Support diagnose more complex issues.
For example, --log_callstack_level=warn
will output additional information for each message at the warning level
or above.
Changing log file location
You can change the location and name of the log file using the --log_file
command line option. Set the value to the name
of the file you want to use. For example:
spatial worker build --log_file=./temp/other_log_file.log
Cloud deployments
For cloud deployments, SpatialOS outputs all logs to a web-based logging interface available from each deployment’s overview page:
This interface provides an easy way to explore logs:
To filter by time, select part of the timeline:
Or click on the start or end date to open a more detailed time period picker:
Drag a section of the timeline to filter by time, and use the sidebar to filter by:
- Message contents
- Log level:
INFO
,WARN
,ERROR
node_name
logger_name
Each log can then be expanded and its contents copied.
Finally, note the nifty Gmail-like keyboard shortcuts!
Launcher logs
Logs for the Launcher can be found at:
- Windows -
C:\Users{username}\AppData\Roaming\SpatialOS\Launch\logs
- Mac -
/Users/{username}/Library/Application Support/SpatialOS/Launch/logs
Interpreting logs
The logs have entries of levels Info, Warning, and Error. Roughly, these mean:
Error
These always indicate something going wrong. A single log entry of this type should be grounds for concern and should be investigated and resolved.
Warning
These indicate that, possibly temporarily, the application was in an unexpected state. However, the application is intended to recover from these states autonomously. As such, warnings are only cause for concern if they are sustained over time, or if they occur together with errors.
Info
These don’t indicate that anything is going wrong and shouldn’t be cause for concern. By default, these aren’t shown when running locally. You can turn the log level up or down by passing
-DFABRIC_LOG_LEVEL=<level>
as a JVM argument when running locally, where<level>
is one ofDEBUG
,INFO
,WARN
, orERROR
.