Custom algorithms

Developers and administrators can now create their own algorithms that Flow Analytics will execute routinely whenever the pre-packaged algorithms are executed. The level of complexity in a custom algorithm will vary based on the task(s) that are being performed. An indepth knowledge of Perl and Scrutinizer’s database structure are required.

There are important files and directories that are involved with creating and managing custom algorithms.

  • scrutinizer/files/algorithms is the directory where all custom algorithms are placed
  • scrutinizer/files/algorithms/example.pm is an example of a commented Perl module to help individuals understand the work flow of an algorithm
  • Interactive scrut_util is used to add and remove custom algorithms from the Flow Analytics engine, and also display a list of custom algorithms
  • scrutinizer/bin/fa_cli.exe is used to test custom algorithms

A Perl installation on the Scrutinizer server is not required to write algorithms.

Creating a custom algorithm

Start by making a copy of example.pm and pasting it into the scrutinizer/files/algorithms directory. Rename the file to something that is unique to help identify the custom algorithm. For purposes of an example, this documentation will reference the custom algorithm as customAlgo1.pm.

Modify customAlgo1.pm to perform the actions intended for this algorithm. Change the package name at the top of the example script to match the file name of the new algorithm module. When complete, save the file. To test the algorithm, it first must be added to the Flow Analytics engine.

It is up to the algorithm to send out alerts. There is an example of how this is accomplished in the example.pm file.

Adding a custom algorithm

Before a custom algorithm can be tested or executed on a regular basis, it must first be added to the Flow Analytics Engine. This is accomplished by running the following command from the Interactive scrut_util prompt.

To open the Interactive scrut_util prompt, enter:

/home/plixer/scrutinizer/bin/scrut_util

At the SCRUTINIZER> prompt, enter:

SCRUTINIZER> enable custom_algorithm customAlgo1 My_Custom_Algorithm

Note

Do not include the file extension for ‘customAlgo1’ in the command and the custom algorithm name (My_Custom_Algorithm) cannot contain spaces.

To verify that the custom algorithm has been added, launch the Flow Analytics Configuration Manager (Admin Tab -> Settings -> Flow Analytics Configuration)

Testing a custom algorithm

During the testing phase, it is highly recommended that debug is added to ensure everything is working as intended. For production environments, comment out any debug code.

To test a custom algorithm, execute the following command:

/home/plixer/scrutinizer/bin/fa_cli.exe --debug 1

Configuring a custom algorithm

At any time during production use or testing, custom algorithm settings can be managed from the User Interface by launching the Flow Analytics Configuration Manager (Admin Tab -> Settings -> Flow Analytics Configuration).

Settings available to custom algorithms are:

  • Threshold
  • Exporters to include
  • Hosts to exclude
  • Enable/Disable Alerts
  • Enable/Disable Syslogs
  • Enable/Disable Algorithm

Running a custom algorithm in production

When algorithms are run routinely in production, the Flow Analytics Engine manages the execution and exporting of violation count and the time taken to execute the algorithm. Flow Analytics will terminate any algorithm that is taking too long to execute. The Flow Analytics Configuration Manager will indicate if any algorithm, including custom algorithms, were terminated before completion.

Creating a policy for a custom algorithm

Once the custom algorithm is violating and sending alerts that show up in the Scrutinizer Orphan View, a policy can be created to match violations and send alerts using notifications. (See Alarm section for more details).

Follow the steps below to create policies for custom algorithms (e.g. customAlgo1):

  1. Navigate to Alarms > Configuration > Policy Manager
  2. Click New Policy
  3. Give the policy a Name
  4. Under Filter and to the right of Message, paste in FA:userCustom_customAlgo1 in the box below where it says: Logical AND=&& Logical OR=||
  5. Set the other options for this policy (for more details, reference the Policy Manager section of the documentation)

Note

Remember to replace customAlgo1 with the name of the custom algorithm.

The next time a violation occurs, the policy will trigger and perform whatever actions were configured in the policy.

Disabling a custom algorithm

Custom algorithms can be disabled from the Flow Analytics Configuration Manager (Admin Tab -> Settings -> Flow Analytics Configuration) by checking the Disable checkbox for the Custom Algorithm.

Deleting a custom algorithm

Custom Flow Analytics algorithms can be deleted from the Flow Analytics engine by executing the following interactive scrut_util command.

/home/plixer/scrutinizer/bin/scrut_util

SCRUTINIZER> delete custom_algorithm custom_algo1

To verify that the Algorithm has been deleted, launch the Flow Analytics Configuration Manager (Admin Tab -> Settings -> Flow Analytics Configuration).

Display a list of custom algorithms

To display a list of custom algorithms available and whether they are enabled, execute the following command from the Interactive scrut_util interface:

SCRUTINIZER> show custom_algorithms