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.
sum = 0
def cumulative_sum (a, b):
global sum
sum = sum + a + b
return sumUsing 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:
def sum(a, b, **kwargs):
if ’sum’ not in kwargs[hb_store]:
kwargs[hb_store][’sum’] = 0 #if ’sum’ is not present in kwargs, declare the initial ’sum’ value as 0.
kwargs[hb_store][’sum’] = kwargs[hb_store][’sum’] + a + b #Store cumulative addition value in ’sum’
return kwargs[hb_store][’sum’]
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.
user@HB-server:~$ healthbot modify-uda-engine --help
usage: healthbot modify-uda-engine [-h] (-s SCRIPT | --rollback) [--simulate]
optional arguments:
-h, --help show this help message and exit
-s SCRIPT, --script SCRIPT
Run script in UDA engine
--rollback, -r Rollback UDA engine to original state
--simulate Run script in simulated UDA engine and show output
user@HB-server:~$ healthbot modify-udf-engine --help
usage: healthbot modify-udf-engine [-h] (-s SCRIPT | --rollback) [--simulate]
[--service SERVICE]
optional arguments:
-h, --help show this help message and exit
-s SCRIPT, --script SCRIPT
Run script in UDF engine
--rollback, -r Rollback UDF engine to original state
--simulate Run script in simulated UDF engine and show output
--service SERVICE Modify specific service UDF
root@davinci-master:/var/local/healthbot# healthbot modify-workflow-engine --help
usage: healthbot.py modify-workflow-engine [-h] (-s SCRIPT | --rollback)
[--simulate]
optional arguments:
-h, --help show this help message and exit
-s SCRIPT, --script SCRIPT
Run script in WORKFLOW engine
--rollback, -r Rollback WORKFLOW engine to original state
--simulate Run script in simulated WORKFLOW engine and show output
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.
The examples below use the UDA engine; these procedures apply equally to the UDF and Workflow engines.
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:
Enter the command
healthbot modify-uda-engine -s /<path>/<script-file> --simulate.The script runs and the output shows on screen, just as if you entered the script commands yourself.
user@HB-server:~$ healthbot modify-uda-engine -s /var/tmp/test-script.sh --simulate Running /var/tmp/test-script.sh in simulated alerta engine.. Get:1 http://security.ubuntu.com/ubuntu xenial-security InRelease [109 kB] ... Fetched 4296 kB in 15s (278 kB/s) Reading package lists... Building dependency tree... Reading state information… ...
MODIFY
When you are satisfied with the simulation results, go ahead with the actual modification procedure.
To modify the UDA engine:
Load the desired bash script onto the Paragon Insights server.
If your Paragon Insights server is fully up and running, issue the command
healthbot stop -s alertato stop the running services.Run the command
healthbot modify-uda-engine -s /<path>/<script-file>.user@HB-server:~$ healthbot modify-uda-engine -s /var/tmp/test-script.sh Running /var/tmp/test-script.sh in simulated alerta engine.. Success! See /tmp/.alerta_modification.log for logs Please restart alerta by issuing 'healthbot start --device-group healthbot -s alerta'
(Optional) As noted in the output, you can check the log file to further verify the script was loaded successfully.
Restart the alerta service using the command
healthbot start -s alerta.Once complete, verify that the alerta service is up and running using the command
healthbot status.To verify that the UDA engine has been updated, use the command
healthbot version -s alertaand check that the healthot_alerta container is using the<version>-customtag.user@HB-server:~$ healthbot version -s alerta {'alerta': 'healthbot_alerta:2.1.0-custom'}
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:
Enter the command
healthbot modify-uda-engine --rollback.user@HB-server:~$ healthbot modify-uda-engine --rollback Rolling back alerta engine to original state.. Successfully rolled back alerta engine Please restart alerta by issuing 'healthbot start --device-group healthbot -s alerta'
Note that it is not necessary to restart the alerta service at this point.
Once complete, verify that the alerta service is up and running using the command
healthbot status.To verify that the UDA engine has reverted back, use the command
healthbot version -s alertaand check that the healthot_alerta container is using the<version>tag.user@HB-server:~$ healthbot version -s alerta {'alerta': 'healthbot_alerta:2.1.0'}
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.
You can link only one trigger action scheduler to a Paragon Insights instance.
To know more about creating a scheduler, see Generate Reports.
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:
Go to Settings > System.
Click the Trigger Action tab.
The Trigger Action page appears.
Select a scheduler profile that you want to associate with Trigger Action.
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.