diff options
Diffstat (limited to '')
| -rw-r--r-- | addons/ot/README-func | 298 |
1 files changed, 298 insertions, 0 deletions
diff --git a/addons/ot/README-func b/addons/ot/README-func new file mode 100644 index 0000000..273c7f9 --- /dev/null +++ b/addons/ot/README-func @@ -0,0 +1,298 @@ +Here I will write down some specifics of certain parts of the source, these are +just some of my thoughts and clues and they are probably not too important for +a wider audience. + +src/parser.c +------------------------------------------------------------------------------ +The first thing to run when starting the HAProxy is the flt_ot_parse() function +which actually parses the filter configuration. + +In case of correct configuration, the function returns ERR_NONE (or 0), while +in case of incorrect configuration it returns the combination of ERR_* flags +(ERR_NONE here does not belong to that bit combination because its value is 0). + +One of the parameters of the function is <char **err> in which an error message +can be returned, if it exists. In that case the return value of the function +should have some of the ERR_* flags set. + +Let's look at an example of the following filter configuration what the function +call sequence looks like. + +Filter configuration line: + filter opentracing [id <id>] config <file> + +Function call sequence: + flt_ot_parse(<err>) { + /* Initialization of the filter configuration data. */ + flt_ot_conf_init() { + } + + /* Setting the filter name. */ + flt_ot_parse_keyword(<err>) { + flt_ot_parse_strdup(<err>) { + } + } + + /* Setting the filter configuration file name. */ + flt_ot_parse_keyword(<err>) { + flt_ot_parse_strdup(<err>) { + } + } + + /* Checking the configuration of the filter. */ + flt_ot_parse_cfg(<err>) { + flt_ot_parse_cfg_tracer() { + } + ... + flt_ot_post_parse_cfg_tracer() { + } + flt_ot_parse_cfg_group() { + } + ... + flt_ot_post_parse_cfg_group() { + } + flt_ot_parse_cfg_scope() { + } + ... + flt_ot_post_parse_cfg_scope() { + } + } + } + +Checking the filter configuration is actually much more complicated, only the +name of the main function flt_ot_parse_cfg() that does it is listed here. + +All functions that use the <err> parameter should set the error status using +that pointer. All other functions (actually these are all functions called +by the flt_ot_parse_cfg() function) should set the error message using the +ha_warning()/ha_alert() HAProxy functions. Of course, the return value (the +mentioned combination of ERR_* bits) is set in all these functions and it +indicates whether the filter configuration is correct or not. + + +src/group.c +------------------------------------------------------------------------------ +The OT filter allows the use of groups within which one or more 'ot-scope' +declarations can be found. These groups can be used using several HAProxy +rules, more precisely 'http-request', 'http-response', 'tcp-request', +'tcp-response' and 'http-after-response' rules. + +Configuration example for the specified rules: + <rule> ot-group <filter-id> <group-name> [ { if | unless } <condition> ] + +Parsing each of these rules is performed by the flt_ot_group_parse() function. +After parsing the configuration, its verification is performed via the +flt_ot_group_check() function. One parsing function and one configuration +check function are called for each defined rule. + + flt_ot_group_parse(<err>) { + } + ... + flt_ot_group_check() { + } + ... + + +When deinitializing the module, the function flt_ot_group_release() is called +(which is actually an release_ptr callback function from one of the above +rules). One callback function is called for each defined rule. + + flt_ot_group_release() { + } + ... + + +src/filter.c +------------------------------------------------------------------------------ +After parsing and checking the configuration, the flt_ot_check() function is +called which associates the 'ot-group' and 'ot-scope' definitions with their +declarations. This procedure concludes the configuration of the OT filter and +after that its initialization is possible. + + flt_ops.check = flt_ot_check; + flt_ot_check() { + } + + +The initialization of the OT filter is done via the flt_ot_init() callback +function. In this function the OpenTracing API library is also initialized. +It is also possible to initialize for each thread individually, but nothing +is being done here for now. + + flt_ops.init = flt_ot_init; + flt_ot_init() { + flt_ot_cli_init() { + } + /* Initialization of the OpenTracing API. */ + ot_init(<err>) { + } + } + + flt_ops.init_per_thread = flt_ot_init_per_thread; + flt_ot_init_per_thread() { + } + ... + + +After the filter instance is created and attached to the stream, the +flt_ot_attach() function is called. In this function a new OT runtime +context is created, and flags are set that define which analyzers are used. + + flt_ops.attach = flt_ot_attach; + flt_ot_attach() { + /* In case OT is disabled, nothing is done on this stream further. */ + flt_ot_runtime_context_init(<err>) { + flt_ot_pool_alloc() { + } + /* Initializing and setting the variable 'sess.ot.uuid'. */ + if (flt_ot_var_register(<err>) != -1) { + flt_ot_var_set(<err>) { + } + } + } + } + + +When a stream is started, this function is called. At the moment, nothing +is being done in it. + + flt_ops.stream_start = flt_ot_stream_start; + flt_ot_stream_start() { + } + + +Channel analyzers are called when executing individual filter events. +For each of the four analyzer functions, the events associated with them +are listed. + + Events: + - 1 'on-client-session-start' + - 15 'on-server-session-start' +------------------------------------------------------------------------ + flt_ops.channel_start_analyze = flt_ot_channel_start_analyze; + flt_ot_channel_start_analyze() { + flt_ot_event_run() { + /* Run event. */ + flt_ot_scope_run() { + /* Processing of all ot-scopes defined for the current event. */ + } + } + } + + + Events: + - 2 'on-frontend-tcp-request' + - 4 'on-http-body-request' + - 5 'on-frontend-http-request' + - 6 'on-switching-rules-request' + - 7 'on-backend-tcp-request' + - 8 'on-backend-http-request' + - 9 'on-process-server-rules-request' + - 10 'on-http-process-request' + - 11 'on-tcp-rdp-cookie-request' + - 12 'on-process-sticking-rules-request + - 16 'on-tcp-response' + - 18 'on-process-store-rules-response' + - 19 'on-http-response' +------------------------------------------------------------------------ + flt_ops.channel_pre_analyze = flt_ot_channel_pre_analyze; + flt_ot_channel_pre_analyze() { + flt_ot_event_run() { + /* Run event. */ + flt_ot_scope_run() { + /* Processing of all ot-scopes defined for the current event. */ + } + } + } + + + Events: + - 3 'on-http-wait-request' + - 17 'on-http-wait-response' +------------------------------------------------------------------------ + flt_ops.channel_post_analyze = flt_ot_channel_post_analyze; + flt_ot_channel_post_analyze() { + flt_ot_event_run() { + /* Run event. */ + flt_ot_scope_run() { + /* Processing of all ot-scopes defined for the current event. */ + } + } + } + + + Events: + - 13 'on-client-session-end' + - 14 'on-server-unavailable' + - 20 'on-server-session-end' +------------------------------------------------------------------------ + flt_ops.channel_end_analyze = flt_ot_channel_end_analyze; + flt_ot_channel_end_analyze() { + flt_ot_event_run() { + /* Run event. */ + flt_ot_scope_run() { + /* Processing of all ot-scopes defined for the current event. */ + } + } + + /* In case the backend server does not work, event 'on-server-unavailable' + is called here before event 'on-client-session-end'. */ + if ('on-server-unavailable') { + flt_ot_event_run() { + /* Run event. */ + flt_ot_scope_run() { + /* Processing of all ot-scopes defined for the current event. */ + } + } + } + } + + +After the stream has stopped, this function is called. At the moment, nothing +is being done in it. + + flt_ops.stream_stop = flt_ot_stream_stop; + flt_ot_stream_stop() { + } + + +Then, before the instance filter is detached from the stream, the following +function is called. It deallocates the runtime context of the OT filter. + + flt_ops.detach = flt_ot_detach; + flt_ot_detach() { + flt_ot_runtime_context_free() { + flt_ot_pool_free() { + } + } + } + + +Module deinitialization begins with deinitialization of individual threads +(as many threads as configured for the HAProxy process). Because nothing +special is connected to the process threads, nothing is done in this function. + + flt_ops.deinit_per_thread = flt_ot_deinit_per_thread; + flt_ot_deinit_per_thread() { + } + ... + + +For this function see the above description related to the src/group.c file. + + flt_ot_group_release() { + } + ... + + +Module deinitialization ends with the flt_ot_deinit() function, in which all +memory occupied by module operation (and OpenTracing API operation, of course) +is freed. + + flt_ops.deinit = flt_ot_deinit; + flt_ot_deinit() { + ot_close() { + } + flt_ot_conf_free() { + } + } |