Apama Extension for Visual Studio Code

A community-developed extension for using Microsoft Visual Studio Code to develop Apama Streaming Analytics applications in EPL.

For more information about Apama and EPL please visit the Apama Community website or the Apama product documentation. To ask questions about Apama or this extension, use the Apama community forum.

This extension is provided as-is and without warranty or support. It does not constitute part of any product. Users are free to use and improve it, subject to the license agreement. We welcome contributions (though we may not include every contribution in the main project).

Features of the extension

The extension supports:

• Syntax highlighting.
• Content assistance features such as completion proposals, hovers, EPL errors in the Problems view, "Go to definition", and an Outline view. These are available when using a container or installation with a suitable version of Apama. See the Visual Studio Code topic in the Apama product documentation for more details about what is provided in the version of Apama you are using.
• Creating an "Apama project", and adding bundles to it from the Apama Projects view or the command palette (F1). This can be used for both product EPL/connectivity bundles and custom bundles such as the Analytics Builder Block SDK.
• Inserting common EPL code snippets. For example, start typing monitor, event or for and you will be prompted to automatically insert the boilerplate code for a new monitor, event declaration or for loop.

There are some known limitations; the main one is that problem markers and assistance features may not work correctly for files with non-ASCII characters.

Installation quick-start

First, install VS Code and the Remote Development Extension Pack.

The simplest way to get started is to store your Apama project in a Git repository with a .devcontainer directory (copied from the Streaming Analytics Sample Repository Template). This allows VS Code to open your repository in a Dev Container that has Apama and the EPL Apps and block SDK automatically installed. Is possible to use a local installation of Apama instead if you prefer, though there are a few more steps required with that approach.

Full instructions for setting up VS Code to use Dev Containers are in the Microsoft VS Code documentation. However here is a quick summary of the steps to get started quickly:

On Windows:

1. Install WSL by running wsl --install from an Administrator terminal. (NB: This is required for the latest Apama versions, but optional if using the older 10.15 release)
2. It is recommended to install a container engine such as Rancher Desktop so you can use the simple "Dev Container" approach. If you don't wish to do this, the alternative is to install Apama locally (inside a WSL Debian container); see below for details.
3. Make sure the container engine is configured for use with WSL. If you use Rancher Desktop, you should go to the WSL integration preferences page in Rancher and configure it to to expose Rancher Desktop's Docker socket to WSL. You should also ensure it is using the dockerd (moby) container engine, and optionally configure it to automatically start at login.

On macOS, you can install colima to run Dev Container images (x86 images only).

On Linux, follow your distribution's instructions to install a container engine and docker-compatible command line. Alternatively, you can use a local install of Apama using the instructions below.

From a web browser, it is possible to use the extension by opening any devcontainer-enabled Apama repository in GitHub Codespaces. For example you can try it out by opening our Sample repository template in a codespace.

For more detailed installation notes, see later on this page.

Opening your first Apama project as a Dev Container

If you have a Docker-compliant container engine installed on your machine, you can easily open any Apama project that has a .devcontainer configuration.

To get started, go to the Streaming Analytics Sample Repository Template, and click the button to "Use this template" to "Create a new repository" for your own application.

Then open the VS Code command palette (F1), run Dev Containers: Clone Repository in Container Volume and then enter the https:// link to your GitHub repository. This will download the Apama "builder" image, and clone the latest version of the EPL Apps Tools and Block SDK.

You can immediately open up any of the EPL files under src/ to experiment with developing Blocks and EPL apps.

If you have an existing project, you can add support for Dev Containers by simply copying the .devcontainer directory from the template project into your own repository.

Opening your first Apama project without a dev container

First ensure the Apama Extension for Visual Studio Code is installed, and that you have an installation of Apama. Where possible, Apama should be installed to the default installation directory /opt/cumulocity/Apama, so that the location can be detected automatically. If you use a different location, you will need to configure the location of Apama home in the Apama extension's settings.

If you want to create a new project, we recommend creating a new repository from the Streaming Analytics Sample Repository Template and then cloning it to a local directory. If you prefer to start from scratch, open the Command Palette and type Apama: Create Project in New Folder (alternatively you can create the empty folder outside of VS Code, add it to the workspace and click Create Project in the Apama Projects view). You can now use the Apama Projects view to add any bundles required for your project, whether product bundles (such as the Cumulocity bundle) or custom bundles (such as the Analytics Builder Block SDK or EPL Apps Tools). Then use the main menu to create one or more .mon files for your EPL application.

If you want to start with an existing Apama project you were already working on (or a clone of a sample project), simply open the Apama project folder (that is, the directory with the .project file) in your VS Code workspace. Note that the Apama project files (including .dependencies) must be in the top level of that folder. If you do not yet have a .project file (to mark the folder as an Apama project), open the Command Palette and type Apama: Create Project to create the project files.

Running your application locally during development

The most convenient way to run your application is to create automated tests using PySys. For an example see the tests/ directory in Streaming Analytics Sample Repository Template.

However it is also possible to run a correlator manually from VS Code. To do this:

• Open a Terminal window and run the correlator. If you need any connectivity plug-ins or other configuration, pass them on the command line e.g. --config connectivity.yaml. If using a Dev Container the correlator executable is on your path already; if not you need to specify the location where you installed it.
• Open in a separate Terminal, run engine_deploy --inject localhost PORT PROJECTDIR where PORT is the port the correlator was started on, and PROJECTDIR is the path of the project (e.g. .).
• When you are done or want to restart, terminate the correlator using Ctrl+C.

More details on installation options

To use all the functionality provided by this extension, you need a full installation of Apama that includes the "dev"/"builder" tooling (it must include bin/engine_deploy). If Apama is not installed, basic syntax highlighting is available but most other features will not work. It is strongly recommended to use the latest version of Apama, and the minimum recommended version is either Apama 26 or Apama 10.15.6.4. The current extension version is not intended to be used with earlier versions of Apama.

The extension can run on Linux. It can also be used on Windows, typically with WSL (Windows Subsystem for Linux). If using the older Apama 10.15 release (which has a Windows installation package) it can be used directly with a local Windows installation. The extension can also be used with a Dev Container.

If using on a Remote platform (i.e. WSL, SSH or DevContainers), the Apama extension needs to be installed on the Remote Host.

Note: if using a container with a locally installed Docker, you may find the default memory allocated by your containerization tool needs to be increased from the default. We advise having a minimum of 4GB of memory for local development.

Details - local Linux installation

Many features of this extension require installing Apama, using one of the dev packages.

For release 26.x and higher, simply install the apama (and optionally apama-python) Debian packages from the Apama Repository using the instructions given there. Remember to apt update and apt upgrade to ensure you're on the latest version of Apama.

For the older 10.15 release:

1. Identify the required package from the download site, for example apama-c8y-dev_10.15.*.*_amd64_linux.tar.gz (or apama-dev_10.15.*.*_amd64_linux.tar.gz for non-Cumulocity applications)
2. Download the package by passing this URL to wget (you may need to run sudo apt install wget first, if it is not yet installed)
3. Then unpack it to the default directory using: sudo mkdir -p /opt/cumulocity && sudo tar -xf apama-*_amd64_linux.tar.gz -C /opt/cumulocity (hint: if using WSL as described below, you will need to enter the password for the root account you created during WSL setup)

Then make sure you've installed the Apama extension into VS Code.

Details - local installation of Apama into WSL on Windows

For Apama 26.x and higher there is no Windows installation package of Apama, so you must install WSL. While we recommend using a Dev Container (as above), it is also fine to install Apama directly into WSL, and use the VS Code WSL extension.

1. Install the latest version of WSL, and add the Debian distribution of Linux. This may take some time and often requires a restart. See the WSL and also VS Code instructions for full details, but typical steps on a recent version of Windows would be:
   • Open a PowerShell terminal "as Administrator"
   • wsl --install
   • wsl --install -d Debian
2. Once installed, open a Debian WSL terminal (for example by opening Debian from the Start Menu) and install Apama using the apama package for Linux using the instructions above.
3. Open VS Code, and install the Visual Studio Code Remote Development Extension Pack.
4. Using the command palette (Ctrl+Shift+P), select Connect to WSL
5. Install the Apama Extension for VS Code. This is installed on the remote VS Code instance, so will need to be installed for every remote host that you use this on.
6. You can now create a new project, or clone an existing project from your version control system (e.g. Git). For WSL, it is recommended to use a location under your Linux home directory (~) to store your Apama projects (this provides faster performance than mounting locations such as C:\ from the Windows file system; don't worry, the Linux file system can still be accessed from Windows using \\$wsl - see the WSL documentation for details)

Details - using Lima to create a virtual machine on macOS

For users on macOS (Intel or Apple Silicon), we recommend using the lima virtualization runtime.

Once Lima has been installed, create a virtual machine with Debian as the image. If you are on 26.x and on an Apple Silicon machine, create an ARM64 VM. Otherwise, create an x86 VM.

# ARM64
limactl create --name debian template://debian-12

# x86
limactl create --name debian-x86 --arch x86_64 --rosetta template://debian-12

Once your virtual machine is created, start it up, and shell into it. Then install Apama using the instructions from "Using a Linux installation".

Use the Visual Studio Code Remote Development Extension Pack to connect to your virtual machine.

Tip: to show your Lima VMs in Remote-SSH, run echo -e "\nInclude ${LIMA_HOME:-$HOME/.lima}/debian-x86/ssh.config" >> ~/.ssh/config in a terminal (source).

Troubleshooting the extension

If you have any problems with the extension, go to the "Output" tab and select "Apama Extension Client" to view the diagnostic output from the extension.

For more advanced troubleshooting, add "apama.languageServer": {"logLevels":["DEBUG"]} to your VS Code preferences JSON, then look under "Output" tab for "Apama Lang Server". This will show the output from the language support provided by the Apama installation.

License

Copyright (c) 2020-present Cumulocity GmbH

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.