EsperTech Esper EPL Extension README
This extension is for use with EsperTech Esper. Esper provides Complex Event Processing (CEP), Streaming Analytics and Streaming SQL. For more information on Esper please navigate to Esper Home Page. The Esper license is GPLv2. The VSCode extension license is below.
This extension provides the following features:
For diagnostics and running scenarios you must start the language server. The language server is a Java program that communicates with VSCode. Please following the instructions at Running the Language Server.
This extension contributes the following settings:
0.0.1 released Aug. 28, 2020
0.1.0 released Jan. 27, 2021
All files with the
All files with the
The language server compiles all EPL files in the workspace folder(s) and adds all EPL files in the workspace to the EPL compiler path.
The compilation errors appear in the PROBLEMS panel (
You may add scenario files that have the
The explorer menu contains the
You can right-click on a scenario and choose
After running a scenario with right-click and
The language server automatically deploys all EPL files in the workspace when running the scenario.
The extension allows you to debug EPL. Here's a list of supported debugging features:
The debugger requires a scenario file that provides the event and time input. The debugger is not suitable to debugging a Java application that embeds EPL.
Debugging EPL - Install
The EPL debugger requires that the Language Server is running, since the language server also hosts the debug adapter.
Optionally, for the debugger to work with Java files, we recommend installing the Java Extension Pack, which bundles the Language Support for Java(TM) by Red Hat. Note that the Language Support for Java(TM) by Red Hat requires Java 11 and higher.
Debugging EPL - Configure And Launch
You may open a scenario file and use the
If you would like to create a launch configuration, click on the Debug view (
The launch configuration has:
Launching the debugger requires that all EPL files within the project compile error-free. The debugger deploys all EPL files within the folder to the runtime.
The debugger produces an output file in the markdown format (
The Debug Console (
Debugging EPL - Breakpoints
You can set breakpoints on:
You can set above breakpoints before launching or after launching when the debugger is stopped.
Debugging EPL - Breakpoints on EPL
You can open an EPL file and set breakpoints on individual EPL statements.
The debugger stops when the runtime processes an event or time for the EPL statement(s) that have a breakpoint.
You can only set a breakpoint on the whole EPL statement. It is not possible to set a breakpoint on specific parts of the EPL statement, i.e. it is not possible to set a breakpoint on a specific subquery, stream or pattern expression, for example. You can use the trace breakpoints for this purpose.
The debugger validates breakpoints upon launching, or if launched already the debugger validates breakpoints immediately. EPL breakpoints cannot be set on create-schema, create-variable, create-table or create-window and all other create-object EPL.
Debugging EPL - Breakpoints on Scenario
You can open a Scenario file and set breakpoints on individual Scenario items.
The debugger stops when the runtime processes an event or time for the scenario item(s) that have a breakpoint. The allows you to set a breakpoint on a specific event and on time advancing.
Debugging EPL - Breakpoints on Trace
The debugger, before launching, deploys the EPL and executes the scenario and produces a trace file in in text format. This file lives in the VSCode storage area. A link to the file can be found among the debugger output in the debug console. When the debugger is stopped, the Call Stack (left, part of Debug View) under
The trace file contains the procedural execution trace of all workspace EPL when feeding events and time according to the scenario. Within the trace file you can find all steps with nested steps indented. After launching with stop-on-entry (true by default), you can navigate to the trace file and set additional breakpoints.
The debugger stops when the runtime processes a trace step that has a breakpoint. The allows you to set a breakpoint on specific processing steps.
A trace file breakpoint causes the debugger to stop when it reaches that specific point of processing. The debugger stops only once for each trace file breakpoint.
Debugging EPL - Breakpoints on Java Code
If you know specific Java classes that you want to set a breakpoint on, you may look up the class using symbol lookup (
Upon launching the debugger validates and activates breakpoints when Java classes with breakpoints are loaded.
Debugging EPL - Call Stack
Upon stopping the Debug view (
The Call Stack has three sections:
The Java section contains the JVM execution stack of Java classes. You can click on each class to open the class code and to and see the variables in scope.
The Trace section contains the stack as processing steps in the trace file (see above). You can click on each trace step to position to the trace file and to see the trace information in scope.
The EPL and Scenario section contains up to three entries:
The EPL entry only appears when the current stack is specific to a given EPL statement. You can click on this entry to position to the EPL file (empty variable scope). If the current stack is not specific to any EPL statement, such as for example when the runtime evaluates which EPL statements must process a given event or a given time, the EPL entry does not appear.
The Scenario entry only appears when the current stack is specific to a given scenario item. You can click on this entry to position to the Scenario file (empty variable scope). If the current stack is not specific to a scenario item, such as for example when the runtime sets the start time, the Scenario entry does not appear.
The Output entry is a link to the output file that the debugger appends to when the runtime delivers output to listeners. You can click on this entry to open to the Output file (empty variable scope).
Debugging EPL - Example (1) - Aggregation Functions
This example walks you through debugging EPL that has aggregation functions. First create an empty folder and create an EPL file and a scenarion file.
Create an EPL file by name "portcount.epl" and enter:
Create a Scenario file by name "portcount_test.scenario" and enter:
With the scenario file open, press
In the debug view under Call Stack click on
The trace file should be similar to:
Set a breakpoint, for instance, on
Debugging EPL - Example (2) - Intermediate Stream and Table Example
The folder that contains this example is part of the language server under
Running the Language Server
The language server is part of Esper Enterprise Edition and is free to use. It is licensed under the terms of Esper Enterprise Edition.
The language server also contains the debug adapter. By running the language server the server exposes a port that speaks the Language Server Protocol and a second port that speaks the Debug Adapter Protocol.
You can download Esper Enterprise Edition which includes the language server (a Java server-side program) at Download. You must provide a company or university email address when registering for the download.
After unpacking the distribution, the commands to run the language server are:
The default settings for the language server are below. You may change language server settings by passing command line parameters.
The language server can run as a daemon and the
A language server that starts successfully produces output similar to below:
The VSCode extension communicates with the language server and for debugging with the debug adapter.
If the connection to the language server fails, the extension displays the following message in