Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Modify the UDA, UDF, and Workflow Engines

 

Overview

When creating rules, Paragon Insights (formerly HealthBot) includes the ability to run user-defined actions (UDAs) as part of a trigger. UDAs are essentially Python scripts that can be executed by a Paragon Insights rule. For example, you might configure a rule with a trigger that reacts to some critical interface going down and responds to the event by calling a function to send an SMS alert. You can write the logic to send the SMS in a UDA python script.

Starting with Paragon Insights Release 4.1.0, you can schedule UDAs and notifications. This is useful when you deploy multiple parallel instances of Paragon Insights in different locations. You can schedule UDAs to run alternatively from UDA schedulers located in different regions. In the event of a node failure, the UDA scheduler running in a parallel instance continues to execute your UDAs and notifications. For more information, see Enable UDA Scheduler in Trigger Action.

Paragon Insights also includes the ability to run user-defined functions (UDFs). Created as Python scripts, UDFs provide the ability to process incoming telemetry data from a device and store the processed value in the time-series database for that device/device-group. For example, the device may be sending FPC temperature in Celsius but you want to process it to be stored as Fahrenheit values in the database.

Starting with HealthBot Release 3.2.0, the processing of UDF/UDA fields has been moved to microservices called UDF farm. This approach allows for Paragon Insights to process multiple data points from multiple devices and fields at the same time (parallel processing). The result is a 4 to 5 times increase in processing performance for UDA/UDF.

While UDAs and UDFs provide excellent additional capabilities to Paragon Insights, there can be cases where the scripts may be importing Python modules that are not included in the default Paragon Insights installation. Given this, you need to be able to add modules as needed to the engine that runs these scripts. Paragon Insights Release 2.1.0 and later solves this challenge by allowing you to modify the UDA, UDF and Workflow engines, using a bash script that contains the instructions to install any dependencies.

Global Variables in Python Scripts

TAND executes Python scripts that use global variables. Global variables retain a value across multiple UDFs.

The following is an example function to calculate cumulative sum and store the value in global variable sum.

Using global variables in UDFs can prevent you from availing the gains in processing performance ensured by UDF farms.

Instead of global variables, you can use the Python construct **kwargs to capture values that must be retained across different functions. When Paragon Insights calls a function (defined in a UDF), it sends topic name, rule name, device group, point time, and device ID that are captured using the construct **kwargs. In case of UDAs, Paragon Insights sends topic name and rule name while executing the Python script.

Along with infrastructure values, Paragon Insights also sends a parameter called hb_store in **kwargs that fetches the last computed value for a variable.

To illustrate how hb_store works in the cumulative addition example:

Each time a function with the above code is called, it performs addition of last stored value in ’sum’ with the value of a and value of b. The new value of addition operation is displayed and stored in ’sum’.

How it Works

You can modify the UDA, UDF, or Workflow engine using the Paragon Insights CLI, as shown below.

The commands have three main options:

  • Simulate—test a script (and view its output) in the simulated UDA/UDF/Workflow engine environment without affecting the running Paragon Insights system

  • Modify—modify the actual UDA/UDF/Workflow engine using a script

  • Rollback—revert to the original version of the UDA/UDF/Workflow engine

Usage Notes

  • The bash script will run in a container running Ubuntu OS Release 16.04 or 18.04; write the script accordingly.

  • The script must be non-interactive; any questions must be pre-answered. For example, use the ‘-y’ option when installing a package using apt-get.

  • If you prefer to copy the source packages of the dependency modules onto the Paragon Insights server so the engine can manually install them instead of downloading them from the Internet, place the required source packages in the /var/local/healthbot/input directory. Then within your bash script, point to the /input directory. For example, to use a file placed in /var/local/healthbot/input/myfile.txt, set the bash script to access it at /input/myfile.txt.

  • Modifying the UDA/UDF/Workflow engine more than once is not an incremental procedure; use a new bash script that includes both the original and new instructions, and re-run the modify procedure using the new script.

  • UDA/UDF/Workflow modifications are persistent across upgrades.

Configuration

As a best practice, we recommend that you use the following workflow:

This best-practice approach ensures that you first validate your script in the simulated environment before modifying the real engine.

Note

The examples below use the UDA engine; these procedures apply equally to the UDF and Workflow engines.

Note

The procedure below assumes your Paragon Insights server is installed, including running the sudo healthbot setup command.

SIMULATE

Use the simulate feature to test your bash script in the simulated environment, without affecting the running Paragon Insights system.

To simulate modifying the UDA engine:

  1. Enter the command healthbot modify-uda-engine -s /<path>/<script-file> --simulate.
  2. The script runs and the output shows on screen, just as if you entered the script commands yourself.

MODIFY

When you are satisfied with the simulation results, go ahead with the actual modification procedure.

To modify the UDA engine:

  1. Load the desired bash script onto the Paragon Insights server.
  2. If your Paragon Insights server is fully up and running, issue the command healthbot stop -s alerta to stop the running services.
  3. Run the command healthbot modify-uda-engine -s /<path>/<script-file>.
  4. (Optional) As noted in the output, you can check the log file to further verify the script was loaded successfully.
  5. Restart the alerta service using the command healthbot start -s alerta.
  6. Once complete, verify that the alerta service is up and running using the command healthbot status.
  7. To verify that the UDA engine has been updated, use the command healthbot version -s alerta and check that the healthot_alerta container is using the <version>-custom tag.

The UDA engine is now running with the installed dependencies as per the bash script.

ROLLBACK

If you have a need or desire to remove the changes to the engine, you can revert the engine to its original state.

To rollback the UDA engine:

  1. Enter the command healthbot modify-uda-engine --rollback.

    Note that it is not necessary to restart the alerta service at this point.

  2. Once complete, verify that the alerta service is up and running using the command healthbot status.
  3. To verify that the UDA engine has reverted back, use the command healthbot version -s alerta and check that the healthot_alerta container is using the <version> tag.

The UDA engine is now running in its original state, with no additional installed dependencies.

Enable UDA Scheduler in Trigger Action

In Paragon Insights Release 4.1.0, you can schedule UDAs and notifications to be executed within a set time interval. To schedule UDAs, you must first create a discrete scheduler and then link the scheduler in the Trigger Action page.

Note

You can link only one trigger action scheduler to a Paragon Insights instance.

To know more about creating a scheduler, see Create a Scheduler Profile.

The scheduler set in Trigger Action applies to all device groups and network groups. You can disable UDA scheduling in the device group or network group configuration. To know more, see Manage Devices, Device Groups, and Network Groups.

To enable a scheduler:

  1. Go to Settings > System.
  2. Click the Trigger Action tab.

    The Trigger Action page appears.

  3. Select a scheduler profile that you want to associate with Trigger Action.
  4. Do one of the following:
    • Click Save to save the scheduler profile.

      The profile is not applied to device or network groups. This option enables you to commit or rollback the configuration changes in the platform.

    • Click Save and Deploy to deploy the configuration in your Paragon Insights instance.

      The UDAs and notifications are generated based on the time period and time interval configured in the scheduler for the application instance.

      You cannot rollback configuration changes applied through Save and Deploy. However. you can remove the scheduler profile and repeat the save and deploy option to cancel UDA scheduling.

Release History Table
Release
Description
Starting with HealthBot Release 3.2.0, the processing of UDF/UDA fields has been moved to microservices called UDF farm.