### Plugin

Plugin feature for the log collector is to load a user python functions at
runtime by the engine and execute it.

The design infrastructure allows user to extend or call their existing python
scripts without needing to expose the implementation. This enriches the log
collection and mechanize the work flow as per user driven as per their
requirement,

### Understanding Plugin

The plugin works like any stand-alone piece of python script or library
function.

The main components in plugin infrastructure are:

- plugin directory
- plugin directive in YAML
- plugin parser in the collector engine

### Plugin Directory

Python module script are added or copied to `plugins` directory and the log
engine loads these plugins during runtime and on demand from the YAML else they
are not invoked automatically.

Example:

```
plugins/
├── foo_func.py
├── ssh_execution.py
└── telnet_execution.py

```

### Plugin Template Example

Stand-alone functions: plugins/foo_func.py

```
# Sample for documentation plugin

def print_vars(var):
    print(var)

def return_vars():
    return 1
```

Class function(s): plugins/plugin_class.py

Example:

```
class  plugin_class:

    def plugin_print_msg(msg):
        print(msg)
```

In YAML plugin, you will need to pass self object as part of the arguments.

Static Class function(s): plugins/plugin_class.py

Example:

```
class  plugin_class:

    @staticmethod
    def plugin_print_msg(msg):
        print(msg)
```

This is to avoid passing object self in plugin args YAML when calling the class
function(s). However python class static method has its own limitation, do not
use unless needed.

You can add your own plugin modules to extend further.

Test your plugin:

```
python3 plugins/foo_func.py
```

### YAML Syntax

Plugin function without return statement.

```
    - plugin:
        - plugin_name: plugin.foo_func.print_vars
        - plugin_args:
            - "Hello plugin"
```

Plugin function with return statement.

```
    - plugin:
        - plugin_name: return_value = plugin.foo_func.return_vars
        - plugin_args:
```

when the return directive is used by implying "=" , the `return_value` can be
accessed within the same block by another following plugins by using the
variable name directly.

Example:

```
    - plugin:
        - plugin_name: plugin.foo_func.print_vars
        - plugin_args:
            - return_value
```

To accept multiple return values by using coma "," separated statement

```
     - plugin_name:  return_value1,return_value2 = plugin.foo_func.print_vars
```

Accessing a class method:

The rule remains same as other functions, however for a class object plugin
syntax

```
        - plugin_name: plugin.<file_name>.<class_object>.<class_method>
```

Example: (from the class example previously mentioned)

```
    - plugin:
        - plugin_name: plugin.plugin_class.plugin_class.plugin_print_msg
        - plugin_args:
            - self
            - "Hello Plugin call"
```

### Plugin execution output for sample

```
        [PLUGIN-START]
        Call func: plugin.foo_func.print_vars("Hello plugin")
        Hello plugin
        return: None
        [PLUGIN-END]

        [PLUGIN-START]
        Call func: plugin.foo_func.return_vars()
        return: 1
        [PLUGIN-END]
```

### Plugin FILES Direcive

Rules:

If in the YAML with Plugin module called and corresponding file order

plugin response if there is any will be written to named file, if

```
    FILES:
        -'name_file.txt'
```

Else, plugin response will be skipped and not written to any file.

```
    FILES:
        - None
```

### Plugin ERROR Direcive

Error directive on plugin supported

- exit_on_error : If there was an error in a plugin stacked, the subsequent
  plugin would not be executed if this is declared.
- continue_on_error : If there was an error and user declare this directive,
  then the plugin block will continue to execute.

Example:

```
    - plugin:
        - plugin_name: plugin.foo_func.print_vars
        - plugin_args:
            - return_value
        - plugin_error: exit_on_error
```

This error directive would come into force only if there is an error detected by
the plugin during execution and not the error response returned from the plugin
function in general.

To go further, there is another directive for plugin to check if the plugin
function returned a valid data or not.

The directive statement is

```
    - plugin_expects_return: <data type>
```

Example:

```
    - plugin:
    - plugin:
      - plugin_name: plugin.ssh_execution.ssh_execute_cmd
      - plugin_args:
        - ${hostname}
        - ${username}
        - ${password}
        - cat /etc/os-release
        - 3
      - plugin_expects_return: str
```

The above example states that, the plugin function is expecting a return data of
type string. If the plugin function does not return data or the returned data is
not of type string, then it would throw an error and sets the plugin_error flag
exit_on_error as True.

This directive helps in validating plugin return data to handle different plugin
blocks stacked together which are depending on the success of the previous
plugin execution to do further processing correctly.