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
33Stand-alone functions: plugins/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
44Class function(s): plugins/plugin_class.py
45```
46class  plugin_class:
47
48    @staticmethod
49    def plugin_print_msg(msg):
50        print(msg)
51```
52
53This is to avoid passing object self in plugin args YAML when calling the class function(s).
54
55You can add your own plugin modules to extend further.
56
57Test your plugin:
58```
59python3 plugins/foo_func.py
60```
61
62### YAML Syntax
63
64Plugin function without return statement.
65```
66    - plugin:
67        - plugin_name: plugin.foo_func.print_vars
68        - plugin_args:
69            - "Hello plugin"
70```
71
72Plugin function with return statement.
73```
74    - plugin:
75        - plugin_name: return_value = plugin.foo_func.return_vars
76        - plugin_args:
77```
78
79when the return directive is used by implying "=" , the `return_value`
80can be accessed within the same block by another following plugins
81by using the variable name directly.
82
83Example:
84```
85    - plugin:
86        - plugin_name: plugin.foo_func.print_vars
87        - plugin_args:
88            - return_value
89```
90
91To accept multiple return values by using coma  "," separated statement
92```
93     - plugin_name:  return_value1,return_value2 = plugin.foo_func.print_vars
94```
95
96### Plugin execution output for sample
97
98
99```
100        [PLUGIN-START]
101        Call func: plugin.foo_func.print_vars("Hello plugin")
102        Hello plugin
103        return: None
104        [PLUGIN-END]
105
106        [PLUGIN-START]
107        Call func: plugin.foo_func.return_vars()
108        return: 1
109        [PLUGIN-END]
110```
111
112### Plugin FILES Direcive
113
114Rules:
115
116If in the YAML with Plugin module called and corresponding file order
117
118plugin response if there is any will be written to named file, if
119
120```
121    FILES:
122        -'name_file.txt'
123```
124
125Else, plugin response will be skipped and not written to any file.
126```
127    FILES:
128        - None
129```
130
131### Plugin ERROR directive Direcive
132
133Error directive on plugin supported
134- exit_on_error       : If there was an error in a plugin stacked, the subsequent
135                        plugin would not be executed if this is declared.
136- continue_on_error   : If there was an error and user declare this directive,
137                        then the plugin block will continue to execute.
138
139Example:
140```
141    - plugin:
142        - plugin_name: plugin.foo_func.print_vars
143        - plugin_args:
144            - return_value
145        - plugin_error: exit_on_error
146```
147
148This error directive would come into force only if there is an error detected
149by the plugin during execution and not the error response returned from the plugin
150function in general.
151