Scripting

Please note that following documentation is relevant to StackState version 1.14.9 and later.

Introduction

StackState supports scripting and exposes several script APIs that allow power users to access, process, and analyze data.

Groovy

The scripting language used by StackState is Groovy. The choice of Groovy is motivated by the fact that StackState is written in Scala and runs on the JVM. Currently Groovy is the best, most performant, script language for the JVM. You are not stuck to using Groovy though, but can use the Http script API to write your logic in any language.

Script executions are sandboxed to guarantee secure execution. All commands have a default (configurable) timeout of 15 seconds.

Script APIs:

All functionality that can be used through scripting is exposed via so-called script API’s. These are singleton objects that contain a number of functions that can be called. Below follows a list of script API’s:

Return types

Asynchronous script results (AsyncScriptResults)

Most API functions run asynchronously. That means they will not directly return results. Some functions are dependent on the network or other resources in order to complete, therefore they can not immediately return results. Such asynchronous functions return an AsyncScriptResult. You can not use an AsyncScriptResult directly. You need to work with asynchronous results via the then method.

For example:

asyncScriptResult = ScriptApi.asyncFunction()
asyncScriptResult.then { result -> result.toString() }

The .then method receives a lambda function as input that executes as soon as the result is gotten. This lambda function can work with the result and return either a new asynchronous script result or a simple (synchronous) result. This concept is equivalent to how promises in Javascript work.

To continue our example. The above can be shortened to:

ScriptApi.asyncFunction().then { it.toString() }

The it keyword is default Groovy keyword that you do not need to define a variable in which you receive your result. You might see this in our examples.

Multiple asynchronous script results can be chained together. For example:

ScriptApi.asyncFunction1()
  .then {  ScriptApi.asyncFunction2(it)  }
  .then {  ScriptApi.asyncFunction3(it)  }

The above means that the results of asyncFunction1 are passed to asyncFunction2, then the results of asyncFunction2 in turn are passed to asyncFunction3.

Builders

Some script functions return so-called builders. Builder objects are objects that have functions that can be used to further refine the restuls.

For example:

Topology.query("layer='hosts'")

Will return all components and the relations between them that are in the layer ‘hosts’. The return type is also a builder. So if you want only the count of the number of components on this layer (and not the relations between them) then you can use the .components() builder method followed by the .count() builder method:

Topology.query("layer='hosts'")
  .components()
  .count()

Builder methods are described per function of each script API.

Analytics Environment

StackState scripting can be used through the Analytics Environment that can be accessed from the main menu. The Analytics Environment interface consists of two components: the scripting panel on the left [1. see the screenshot below] and the results panel [2.] on the right. The user writes a script in the scripting panel and commands SackState to execute it using the “Execute Button” and receives the results of the execution in the results panel. The results can be viewed as a raw JSON string or in the form of preview generated by StackState automatically depending on the JSON objects type and content.

Analytics