Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Modify the UDA and UDF Engines

 

Overview

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

HealthBot also includes the ability to run user-defined functions (UDFs). Also 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.

Both UDF and UDA scripts are processed by TAND, which spawns one python interpreter for each device that has a rule with a field that contains a UDF or UDA. If a rule that has two UDF fields is applied to a device group with 2 devices in it, then 4 interpreters are spawned to process the ingest traffic. Each interpreter can only process one data point at a time. When it is finished, it can then process another data point (sequential processing).

Starting with HealthBot Release 3.2.0, the processing of UDF/UDA fields has been moved to a UDF farm. This approach allows for HealthBot 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 HealthBot, there can be cases where the scripts may be importing Python modules that are not included in the default HealthBot installation. Given this, you need to be able to add modules as needed to the engine that runs these scripts. HealthBot 2.1.0 and later solves this challenge by allowing you to modify the UDA and UDF engines, using a bash script that contains the instructions to install any dependencies.

How it Works

You can modify the UDA or UDF engine using the HealthBot CLI, as shown below.

The commands have three main options:

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

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

  • Rollback—revert to the original version of the UDA/UDF 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 HealthBot 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 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 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 engine.

Note

The procedure below assumes your HealthBot 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 HealthBot 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 HealthBot server.
  2. If your HealthBot server is fully up and running, issue the command healthbot stop 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.

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