1### Plugin
2
3Plugin feature for the log collector is to load a user python functions at runtime by the engine and execute it.
4
5The design infrastructure allows user to extend or call their existing python scripts without needing to expose
6the implementation.  This enriches the log collection and mechanize the work flow as per user driven as per
7their requirement,
8
9### Understanding Plugin
10The plugin works like any stand-alone piece of python script or library function.
11
12The main components in plugin infrastructure are:
13
14- plugin directory
15- plugin directive in YAML
16- plugin parser in the collector engine
17
18### Plugin Directory
19Python module script are added or copied to `plugins` directory and the log engine loads these plugins during
20runtime and on demand from the YAML else they are not invoked automatically.
21
22Example:
23```
24plugins/
25├── foo_func.py
26├── ssh_execution.py
27└── telnet_execution.py
28
29```
30
31### Plugin Template Example
32
33plugins/foo_func.py
34```
35# Sample for documentation plugin
36
37def print_vars(var):
38    print(var)
39
40def return_vars():
41    return 1
42```
43
44You can add your own plugin modules to extend further.
45
46Test your plugin:
47```
48python3 plugins/foo_func.py
49```
50
51### YAML Syntax
52
53Plugin function without return statement.
54```
55    - plugin:
56        - plugin_name: plugin.foo_func.print_vars
57        - plugin_args:
58            - "Hello plugin"
59```
60
61Plugin function with return statement.
62```
63    - plugin:
64        - plugin_name: return_value = plugin.foo_func.return_vars
65        - plugin_args:
66```
67
68when the return directive is used by implying "=" , the `return_value`
69can be accessed within the same block by another following plugins
70by using the variable name directly.
71
72Example:
73```
74    - plugin:
75        - plugin_name: plugin.foo_func.print_vars
76        - plugin_args:
77            - return_value
78```
79
80To accept multiple return values by using coma  "," separated statement
81```
82     - plugin_name:  return_value1,return_value2 = plugin.foo_func.print_vars
83```
84
85### Plugin execution output for sample
86
87
88```
89        [PLUGIN-START]
90        Call func: plugin.foo_func.print_vars("Hello plugin")
91        Hello plugin
92        return: None
93        [PLUGIN-END]
94
95        [PLUGIN-START]
96        Call func: plugin.foo_func.return_vars()
97        return: 1
98        [PLUGIN-END]
99```
100
101### Plugin FILES Direcive
102
103Rules:
104
105If in the YAML with Plugin module called and corresponding file order
106
107plugin response if there is any will be written to named file, if
108
109```
110    FILES:
111        -'name_file.txt'
112```
113
114Else, plugin response will be skipped and not written to any file.
115```
116    FILES:
117        - None
118```
119