Get SpatialOS

Sites

Menu
These are the docs for 13.6, an old version of SpatialOS. The docs for this version are frozen: we do not correct, update or republish them. 13.7 is the newest →

Try out the new modular Inspector (alpha) and let us know what you think!

The Inspector

The Inspector is a web-based tool that you use to explore the internal state of a SpatialOS world. It gives you a real time view of what’s happening in a deployment, locally or in the cloud. Among other things, it displays:

  • which SpatialOS entities are in the world, and what their components’ properties are
  • which worker instances are connected to the deployment, and how much load each one is under
  • the load balancing strategies of the worker instances
  • the area of authority and area of interest for each worker instance

This makes the Inspector a crucial companion to monitoring and debugging SpatialOS deployments.

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. When running locally, the Inspector automatically downloads and caches the latest Inspector Client from the internet. If it can’t download the latest version (for example, because there is no internet connection or because of the firewall configuration), it uses the latest cached version instead.

  • For a cloud deployment, access the Inspector from your deployment’s Overview page by clicking Inspect:

    Inspect button

Connectivity message

The Inspector has a connectivity message on the top left to indicate whether there are any delays in the ‘freshness’ of the deployment data being displayed.

Entities and their components

When you have selected an entity, either by finding it in the world or entering its ID, the entity sidebar populates:

Selected entity showing sidebar

From here, you can:

  • Delete an entity: remove it from your deployment.
  • Jump to an entity: center the view on it.
  • Observe all of the entity’s component properties in real time. The components are presented either in tree structure or in JSON, and you can filter them. All values are sampled approximately every second.
  • Observe which worker instances have write access to components on this entity.

Workers and load balancing

The top right-hand side of the Inspector shows a list of the worker instances currently connected to your deployment:

From this list, you can select a particular worker instance to center the view on that instance.

Much like selecting entities, clicking on a worker instance’s name brings up its information in the sidebar:

Selected worker instance sidebar

From here, you can:

  • Stop the worker instance.
  • Jump to a worker instance: center the view on its region of write access.
  • Go to the Logs viewer or the raw worker logs page.
  • Observe a number of useful worker metrics, such as FPS, Send/Receive Queue sizes, and counts of entities the worker instance is acting on broken down by entity type.

You can also view the load balancing strategy and areas of interest and authority for particular worker instances. Select one or more worker instances by clicking the checkbox next to the instance name, then use the “Show me” box to choose what you want to see:

Load balancing strategy Load balancing strategy

Authority area and interest area Interest and authority areas

Settings

From the Settings tab, you can:

  • Change the grid units from world units to chunks
  • Turn on the ability to jump to an entity
  • Change the maximum zoom level to use until heatmap mode kicks in (see Performance impact)
  • Import and export your entity coloring settings

Settings

Performance impact

Using the Inspector can impact the performance of the deployment you’re inspecting.

As a rule of thumb, the more information the Inspector is displaying, the greater the performance impact. For example, zooming out a lot causes a large performance impact, because it vastly increases the number of entities shown.

Changing the maximum zoom level 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:

Heatmap mode

Turning on heatmap mode doesn’t remove the performance impact completely, though. It still runs entity.find operations which also impact performance. You can track these operations in the “Debug entities and commands” dashboard of the Metrics viewer.

Why is there a performance impact?

To display the state of your deployment, the Inspector accesses a real-time stream of the entities in the area being inspected, and their components’ properties/values, along with all worker instances, 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.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums