Skip to content
Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
137 lines (99 sloc) 6.74 KB

Scripting

Purpose

{solys} comes with a powerful built-in scripting engine, that allows the user to interact with the collected runtime data and the UI resources. This enables the user to aggregate and correlate data from different sources programmatically and visualize them in tables, charts or in arbitrary html views in a very easy and straight-forward manner.

The Language (Xtend)

As built-in scripting language Xtend was chosen, due to following reasons:

  • Xtend is using the Java type-system and hence allows a seamless integration into an Eclipse RCP application, what {solys} is.

  • Xtend code will be generated into Java source code on-the-fly in the background, so that no additional interpreter is needed at runtime.

  • Xtend is a hybrid language that combines object-oriented and functional programming at the same time, which allows the implementation of very expressive and concise scripts.

  • You have the full power of Java with some syntactical sugar on top.

  • Eclipse editor functionality like content-assist, code completion, referencing is the same as for Java

If you are not yet familiar with Xtend, but with Java and one of its JVM-based scripting langauges such as Groovy, Scala or Clojure you should be very fast in learning the principles of Xtend.

Visit Xtend for details, tutorials and examples.

Executing Scripts

When it comes to executing a script two concepts are important to understand:

  • How does its life-cycle work, means how can a script be started and stopped or if needed interrupted?

  • Where and when, means in which context can a script be executed?

Those two concepts are described in this chapter.

The lifecycle of a script

Similar to a JUnit-Test an {solys} script follows the paradigm, that it can undergo certain life cycle stages, where you can implement your startup and cleanup code, if needed.

@BeforeScript
def setupScript() {
    // Your setup code
}

@Execute(context=ExecutionContext.GLOBAL, description="My description")
def executeScript() {
    // Your script code
}

@AfterScript
def cleanup() {
     // Your cleanup code
}
  • Every script is invoked with the order: @BeforeScript → @Execute → @AfterScript.

  • You are free to rename your methods → the annotations are decisive.

  • If you have multiple methods tagged with @Execute in one script, then be aware, that all of them are embedded into the same lifecycle. If you need a different setup or cleanup functionality you need to distribute the execute methods into different scripts

  • The startup and cleanup methods are optional, they are only invoked if they are available.

  • The lifecycle order applies for all execution contexts (Global, Preselection and Callback) in the same way.

  • Whenever a script is stopped explicitly by the user (e.g. when ending a callback script during live-connection) the @AfterScript method is called (if available).

The execution context of a script

Scripts are developed and executed directly within {solys}, which allows very short turnaround cylces. Depending on your use case scenario you can tell {solys} how to execute your scripts. This will be achieved by annotating your methods with the tag @Execute and a corresponding context: GLOBAL, PRESELECTION and CALLBACK.

In order to explain the different execution contexts, take following use case, where you want to create a time-marker, whenever the cpu load of a process is higher than 50%.

GLOBAL

The script developer can assume to have access to all events from all channels collected by {solys} so far. This context is usually chosen in post-mortem analysis. The script is started by the user in the resource explorer and stops when the end of the executable method is reached. It can be stopped explicitly in case it is a long running script.

@Execute(context=ExecutionContext.GLOBAL, description="")
def createMarkerForHighCpuLoad() {
    // you as a developer need to indicate the channel,
    // in this case "cpu.system".channel
    getChannel("cpu.system").events.filter[value as Double > 50].
        forEach[createTimemarker("High CPU Load")]
}
PRESELECTION

The pre-selection mode differs from the global mode insofar as the context of the data where the script is to be executed is already selected by the user, e.g. in context of a channel, a timemarker or a runtime event

@Execute(context=ExecutionContext.PRESELECTION, description="")
def createMarkerForHighCpuLoad(RuntimeEventChannel<?> channel) {
    // The channel was already selected by the user within the GUI
    // and can be accessed as parameter
    channel.allEventsFromChannel.filter[value as Double > 50].
        forEach[createTimemarker("High CPU Load")]
}
CALLBACK

The callback mode is usually chosen during live connection or for big data files. The script is notified continuously after a certain time-interval with new events. The script is started and also stopped by the user explicitly. In case the Callback mode is used in conjunction with {solys} Auto the script is stopped when the end of file is reached.

@Execute(context=ExecutionContext.CALLBACK, description="")
def createMarkerForHighCpuLoad(List<RuntimeEvent<?>> events) {
    // You need to check if the list of events contain information
    // from the channel you are interested in.
    events.filter[channelName.equals("cpu.system")].
        filter[value as Double > 50].
        forEach[createTimemarker("High CPU Load")]
}

Filter Scripts

With the annotation @Filter the user is able to execute a script in the context of a table. With that you can define very powerful searches upon your log data. The convention is that you return value is boolean, whereas true means your event is matching the filter and false otherwise.

Pre-Installed and User Scripts

{solys} is shipped with a script folder named Pre-installed Scripts. This folder is containing some script with convenience and untiliy functions and also some tutorials. These scripts can also be used as a getting started reference. They are read-only in order to avoid, that they are deleted or corrupted by accident. Your own new scripts and imported scripts are automatically hosted in the folder My Scripts.

Note
{solys} scripts use UTF-8 encoding
You can’t perform that action at this time.