Inspector
The Inspector provides a realtime view of what is happening in a deployment: which entities are present, where they are, what their components’ properties are, which workers are connected to the deployment, what they’re responsible for, and much more.
This makes the Inspector a crucial companion to monitoring and debugging SpatialOS deployments - read on for details!
Accessing the Inspector
You can access the Inspector for local and cloud deployments.
For a local deployment, access the Inspector at http://localhost:21000/inspector.
For a cloud deployment, access the Inspector from your deployment’s page, by clicking INSPECT:
The World View
The World View is a 2D and 3D representation of all entities’ live positions.
To navigate the world, use the icons at the bottom of the page:
- Zoom in/out/reset
- 2D/3D toggle
- Pause/Resume The World (this pauses all position updates)
- Pan mode / multi-select toggle
These should help you find and select entities:
Note that entities can be colored by entity type in the sidebar of the inspector. Pro tip: you can also import/export your color preferences from the settings tab.
Finally, the World View has a Connectivity message on the top left to indicate whether there are any delays in the ‘freshness’ of the deployment data being displayed.
To bring back information about your deployment, the Inspector connects to a number of endpoints on your deployment. The connectivity message, on the top left of the world view, shows the status of these connections. You can use this to notice and diagnose any potential issues.
Connection status
| Status | Meaning |
|---|---|
 |
All connections are healthy, and you can inspect your deployment. The inspector’s view of your deployment is up to date. |
 |
One or more connections is down, and the Inspector is trying to reconnect. The inspector’s view of your deployment is not up to date. |
Subconnections
The connection status is based on the status of four subconnections:
| Name | Meaning |
|---|---|
| GSim | Connection to the GSim. If disconnected, the deployment is likely not up. |
| Chunks | Connection to the chunks endpoint, which provides information about which workers have checked out which section of the world (a collection of “chunks”). |
| Position | Connection to the entity positions stream. This connection is required to display entities in the World view. |
| Heatmap | Connection to the heatmap view of the deployment, showing an aggregate number of entities per area. This connection is only used in Heatmap mode. |
Entities and their components
When you have selected an entity, either by finding it in the world or entering its ID, the entity sidebar will populate:
From here, you can:
- Delete an entity: eradicate it from your deployment!
- Jump to an entity: center the World View on it
- Observe all of the entity’s component properties in realtime. The components are presented either in tree structure or in JSON, and can be filtered. All values are sampled every second or so.
- Observe which workers have write access to components on this entity.
Workers
The top right-hand-side of the Inspector shows a list of workers currently connected to your deployment:
The selected worker’s area of write access is outlined.
From this list, you can:
- View the Load, or utilization, that each worker is under. When a worker is under too much load, SpatialOS can automatically bring one back up if your load balancing settings are configured appropriately.
- Center the World View on a worker
Much like selecting entities, clicking on the “i” icon of a worker will bring up its information in the sidebar:
From here, you can:
- Stop the worker.
- Jump to a worker: center the World View on its region of write access
- Observe a number of useful worker metrics, such as FPS, Send/Receive Queue sizes, and counts of entities the worker is acting on broken down by Entity type.
The yellow line shown is the world boundary.
Settings
From the Settings tab, you can:
- Change the World View grid units from World units to Chunks
- Change the Maximum zoom level to use until Heatmap mode kicks in
- Import and export your entity coloring settings
Performance impact
Using the Inspector can impact the performance of the deployment being inspected.
As a rule of thumb, the more information is being displayed by the Inspector, the greater the performance impact.
For instance, zooming out a lot causes a large performance impact, because it vastly increases the number of entities shown.
Changing the maximum zoom level of the heatmap mode to a very high number can have a similar effect:
The performance impact is decreased in heatmap mode, as this mode displays ‘density’ of entities per area rather than all individual entities:
Turning on heatmap mode doesn’t remove the performance impact completely, though. It still runs entity.find
operations which will also impact performance. You can track these operations in the Entities Dashboard of the
Metrics app .
Why does this happen?
To display the state of your deployment, the Inspector accesses a realtime stream of the entities in the area being inspected, and their components’ properties/values, all workers, their checkout areas, their metrics, and more.
This information is provided by a set of APIs on an Inspection Service, located on one of the nodes running in the deployment being inspected.
To provide these APIs, the Inspection Service queries other nodes within your deployment to stream the state of entities; this therefore puts additional stress on the deployment when you use the Inspector.
How to mitigate the performance impact
Minimize the number of concurrent Inspector windows. Each Inspector window separately connects to the Inspection Service - this means the more are open, the greater the load.