Topology navigation

The topology in StackState is likely much bigger than what you care about at any given time. StackState allows you to filter the topology to locate the part of the topology you are interested in.

Basic topology selection

The main way of filtering the topology is by using the basic filter panel, accessed using the filter icon.

When you open StackState’s topology view initially, it will show you all of the topology it can, provided it doesn’t go over the configured topology limit. If there is more topology than can be shown while still keeping the system usable, StackState shows you a warning message and suggest you apply more filters to your topology selection.

From here, you can use the basic filter panel to filter the topology on certain properties. If you select a particular property, the topology view will be updated to show only the topology that matches the selected value. Selecting multiple properties narrows down your search (ie it combines them using an AND operator). Selecting multiple values for a single property expands your search (ie it combines them using an OR operator).

Using the basic filter panel you can select a subset of your topology based on the following properties:

  • layers
  • domains
  • environments
  • health state
  • tags / labels

Layers, domains and environments are a way to organize your topology. The health state reflects how the component is functioning. Tags are a way to label your topology for easy selection.

Filter settings

In addition to specifying which components to show, the basic filter panel also allows you to specify two settings.

Root Cause Analysis automatically expands the topology selection to display the root cause of an issue. There are three settings:

  • None – don’t expand the topology selection
  • Cause Only – automatically add only the root cause to the topology selection
  • Full Cause Tree – automatically add the full cause tree to the topology selection

Show Components adds one or more specific components to the topology selection. You can search for the component by name.

Basic filtering example

Here is an example of using the basic filtering capabilities. This example shows how to filter for a particular layer (Applications) and a tag (stackstate:agent).

Query by layer and tag

The same topology selection can also be shown in list format:

Query by layer and tag (list)

Interactive navigation

It is also possible to interactively navigate the topology. Right-click on a component to bring up the component navigation menu:

Topology navigation menu

Selecting an action from the menu allows you to change your view, respective to the selected component.

Show expands the topology selection in one of the following ways:

  • Dependents (up) – adds the components depending on the selected component
  • Dependencies (down) – adds the components that the selected component depends on
  • Root Cause – if the selected component is in a non-clear state, adds the root cause tree
  • Neighbors – adds the selected component’s neighbors (1st level dependencies and dependents)

Show only with … isolates the selected component (shows only that component) and expands the topology selection in one of the following ways:

  • Root Cause – if the selected component is in a non-clear state, shows the root cause tree
  • Neighbors – shows the selected component’s neighbors (1st level dependencies and dependents)

Advanced topology selection

If you want full control over your topology selection, you can use advanced topology selection. Advanced topology selection is used via the advanced filter bar, accessed by selecting Advanced on the basic filter panel. The advanced filter bar allows you to select topology using StackState’s built-in query language.

StackState Query Language (STQL) has the following core concepts:

  • Functions; STQL uses functions as a base functions have a Typed output.
  • Boolean logic; Boolean logic can be used inside the query parameter of the components function and can be used between functions
  • Query blocks; To define group specific parts of the query and set their preference


Function always have an output type and can have have one or more arguments.

  • The function and its parameters are split with white space
  • The name and parameter of the arguments are split by an = symbol. Example: "name='DLL_DB'" or withNeighborsOf(components = (name = "myApp")).
  • If a function has multiple arguments they can be split using a ,

List of functions:

NameOutput typeDescription
componentsSet<Component>Selection of components
withNeighborsOfSet<Component>select the neighbors of (specific) components
withCauseOfSet<Component>select the (root) cause and (optional) the path to this for (specific) components.

STQL is a language which will defer execution till the moment the data is needed.


STQL is a Typed language, this means that all functions have typed input parameters and output. Not all functions work with all types. Types in STQL are inferred where possible. The following types are available:

  • Component
  • Set<Component>

Boolean logic

The boolean operators are by default executed in the following order: First NOT, then OR and as of last rule AND if you want to change the order you can use query blocks

  • AND If you want to have a rule that combines two basic filters in one rule you can use AND. AND will combine the LEFT and RIGHT basic filters as one result. Example: layer = "application" AND healthstate = "CRITICAL"

  • OR If you want to have a rule that combines the output of two basic filters in a query you can use OR. OR will combine the LEFT and RIGHT basic filters as one result. Example: layer = "application" AND healthstate = "CRITICAL"

  • NOT This rule subtracts all the results matching the right-hand side from the left-hand side. Example: NOT (name = "AppA" OR name = "AppB"). This example will select all components except the ones with the name “AppA” or “AppB”.

Query blocks

If you want to combine multiple boolean operators OR or AND combinations and control the order, you can use ( ... ) to do this. Example: (name = "AppA" OR name = "AppB") AND layer = "Application". Now the name = "AppA" OR name = "AppB" is executed first, and both will be checked for the layer = “Application”. Without the code block only “AppB” will be checked for the layer = “Application” because the default order is NOT, then AND and as of last ruleOR.

Component functions

A functions can have one ore more parameters. Parameters can be named and are typed. For example withNeighborsOf(components = (name = "DLL_DB"), levels = "10", direction = "both")


The components function is the implicit function used to select components based on a filter with support for key/value pair selection. All key-value pair filters added are implicitly filtering properties of components in your topology.

output type



filter=<basic filter>

The basic filter syntax: <key> <operator> <value>

The key can be any key from the key/value pairs which you can put on a component. Or the following special keys:

  • name, The name of the component
  • healthstate, The own healthstate of the component
  • label, Matching label(s) of the component
  • layer, Matching layers of the component
  • domain, Matching layers of the component
  • environment, Matching layers of the component

The basic filter operators are:

  • equals: =
  • in list in
  • not equals !=

Basic usage

The default behavior of a key-value filter is that it filters on properties of components:

  • name = "AppA"
  • name = "AppA" OR healthstate = "CRITICAL"

In other words: * basic = syntax of query: layer = "application" * name based selection name in ("ApplicationA", "ApplicationB")


The withNeighborsOf function is used to append the ouput of the stream with neighbouring components.

output type



direction=(optional, default=both) <direction> The direction can be up for components which depend on this component and down for dependencies. both can be used for the combination of up and down.

levels=(optional, detault=1)<levels> levels is the number of levels you want to repeat this function. Use all to continue till there are no more levels. This is limited to 15.

components=(optional, default=all components in input)<set-of-components> The component for which the neighbours should be returned


The withCauseOf function is used to append the output with the cause of a healthstate.

output type



causeOnly=(optional, default=false)<boolean> to select only the cause itself select true otherwise select false to also select all components on the path to the cause.

components=<set-of-components> The component(s) for which the cause should be returned


name = "serviceB"

layer = "application"

layer = "application" AND (healthstate = "CRITICAL" OR healthstate = "DEVIATING") OR withNeighborsOf(components = (name IN ("appA","appB")))

layer = "application" AND healthstate != "CRITICAL" OR (name in ("serviceA", "serviceB")) OR withNeighborsOf(components = (name = "AppA"), levels = "2")

layer = "application" AND (healthstate = "CRITICAL'" OR healthstate = "DEVIATING") OR withCauseOf(components = (id = "1"))

Syntax help

If you (start to)type a word at the beginning of a new code block (after the beginning of the line or after an AND or OR):

  • Autocomplete keys

If you are at the end of a key

If you (start to)type a word after a basic filter operator

  • If the key is not ‘name’; autocomplete values with a multi-select drop-down with a search to filter values down
  • If the key is ‘name’; autocomplete values starting with the typed letters (start with a minimum of 2 letters)

Advanced filter example

Advanced filter example