README-func

OpenTelemetry filter -- function reference
==========================================================================

Functions are grouped by source file.  Functions marked with [D] are only
compiled when DEBUG_OTEL is defined.


src/filter.c
----------------------------------------------------------------------

Filter lifecycle callbacks and helpers registered in flt_otel_ops.

  flt_otel_mem_malloc
      Allocator callback for the OTel C wrapper library.  Uses the HAProxy
      pool_head_otel_span_context pool.

  flt_otel_mem_free
      Deallocator callback for the OTel C wrapper library.

  flt_otel_log_handler_cb
      Diagnostic callback for the OTel C wrapper library.  Counts SDK internal
      diagnostic messages.

  flt_otel_thread_id
      Returns the current HAProxy thread ID (tid).

  flt_otel_lib_init
      Initializes the OTel C wrapper library: verifies the library version,
      constructs the configuration path, calls otelc_init(), and creates the
      tracer, meter and logger instances.

  flt_otel_is_disabled
      Checks whether the filter instance is disabled for the current stream.
      Logs the event name when DEBUG_OTEL is enabled.

  flt_otel_return_int
      Error handler for callbacks returning int.  In hard-error mode, disables
      the filter; in soft-error mode, clears the error and returns OK.

  flt_otel_return_void
      Error handler for callbacks returning void.  Same logic as
      flt_otel_return_int but without a return value.

  flt_otel_ops_init
      Filter init callback (flt_ops.init).  Called once per proxy to initialize
      the OTel library via flt_otel_lib_init() and register CLI keywords.

  flt_otel_ops_deinit
      Filter deinit callback (flt_ops.deinit).  Destroys the tracer, meter and
      logger, frees the configuration, and calls otelc_deinit().

  flt_otel_ops_check
      Filter check callback (flt_ops.check).  Validates the parsed
      configuration: checks for duplicate filter IDs, resolves group/scope
      placeholder references, verifies root span count, and sets analyzer bits.

  flt_otel_ops_init_per_thread
      Per-thread init callback (flt_ops.init_per_thread).  Starts the OTel
      tracer thread and enables HTX filtering.

  flt_otel_ops_deinit_per_thread [D]
      Per-thread deinit callback (flt_ops.deinit_per_thread).

  flt_otel_ops_attach
      Filter attach callback (flt_ops.attach).  Called when a filter instance is
      attached to a stream.  Applies rate limiting, creates the runtime context,
      and sets analyzer bits.

  flt_otel_ops_stream_start
      Stream start callback (flt_ops.stream_start).  Fires the
      on-stream-start event before any channel processing begins.  The channel
      argument is NULL.  After the event, initializes the idle timer in the
      runtime context from the precomputed minimum idle_timeout in the
      instrumentation configuration.

  flt_otel_ops_stream_set_backend
      Stream set-backend callback (flt_ops.stream_set_backend).  Fires the
      on-backend-set event when a backend is assigned to the stream.

  flt_otel_ops_stream_stop
      Stream stop callback (flt_ops.stream_stop).  Fires the
      on-stream-stop event after all channel processing ends.  The channel
      argument is NULL.

  flt_otel_ops_detach
      Filter detach callback (flt_ops.detach).  Frees the runtime context when
      the filter is detached from a stream.

  flt_otel_ops_check_timeouts
      Timeout callback (flt_ops.check_timeouts).  When the idle-timeout timer
      has expired, fires the on-idle-timeout event and reschedules the timer
      for the next interval.  Sets the STRM_EVT_MSG pending event flag on the
      stream.

  flt_otel_ops_channel_start_analyze
      Channel start-analyze callback.  Registers analyzers on the channel and
      runs the client/server session start event.  Propagates the idle-timeout
      expiry to the channel's analyse_exp so the stream task keeps waking.

  flt_otel_ops_channel_pre_analyze
      Channel pre-analyze callback.  Maps the analyzer bit to an event index and
      runs the corresponding event.

  flt_otel_ops_channel_post_analyze
      Channel post-analyze callback.  Non-resumable; called once when a
      filterable analyzer finishes.

  flt_otel_ops_channel_end_analyze
      Channel end-analyze callback.  Runs the client/server session end event.
      For the request channel, also fires the server-unavailable event if no
      response was processed.

  flt_otel_ops_http_headers
      HTTP headers callback (flt_ops.http_headers).  Fires
      on-http-headers-request or on-http-headers-response depending on the
      channel direction.

  flt_otel_ops_http_payload [D]
      HTTP payload callback (flt_ops.http_payload).

  flt_otel_ops_http_end
      HTTP end callback (flt_ops.http_end).  Fires on-http-end-request or
      on-http-end-response depending on the channel direction.

  flt_otel_ops_http_reset [D]
      HTTP reset callback (flt_ops.http_reset).

  flt_otel_ops_http_reply
      HTTP reply callback (flt_ops.http_reply).  Fires the on-http-reply event
      when HAProxy generates an internal reply.

  flt_otel_ops_tcp_payload [D]
      TCP payload callback (flt_ops.tcp_payload).


src/event.c
----------------------------------------------------------------------

Event dispatching, metrics recording and scope/span execution engine.

  flt_otel_scope_run_instrument_record
      Records a measurement for a synchronous metric instrument.  Evaluates
      update-form attributes via flt_otel_sample_eval() and
      flt_otel_sample_add_kv(), evaluates the sample expression from the
      create-form instrument (instr_ref), and submits the value to the meter
      via update_instrument_kv_n().

  flt_otel_scope_run_instrument
      Processes all metric instruments for a scope.  Runs in two passes: the
      first lazily creates create-form instruments via the meter, using
      HA_ATOMIC_CAS to guarantee thread-safe one-time initialization; the second
      iterates update-form instruments and records measurements via
      flt_otel_scope_run_instrument_record().  Instruments whose index is still
      negative (UNUSED or PENDING) are skipped.

  flt_otel_scope_run_log_record
      Emits log records for a scope.  Iterates over the configured log-record
      list, skipping entries whose severity is below the logger threshold.
      Evaluates the body from sample fetch expressions or a log-format string,
      optionally resolves a span reference against the runtime context, and
      emits the record via the logger.  A missing span is non-fatal -- the
      record is emitted without span correlation.

  flt_otel_scope_run_span
      Executes a single span: creates the OTel span on first call, adds links,
      baggage, attributes, events and status, then injects the context into HTTP
      headers or HAProxy variables.

  flt_otel_scope_run
      Executes a complete scope: evaluates ACL conditions, extracts contexts,
      iterates over configured spans (resolving links, evaluating sample
      expressions), calls flt_otel_scope_run_span for each, processes metric
      instruments via flt_otel_scope_run_instrument(), emits log records via
      flt_otel_scope_run_log_record(), then marks and finishes completed spans.

  flt_otel_event_run
      Top-level event dispatcher.  Called from filter callbacks, iterates over
      all scopes matching the event index and calls flt_otel_scope_run() for
      each.


src/scope.c
----------------------------------------------------------------------

Runtime context, span and context lifecycle management.

  flt_otel_pools_info [D]
      Logs the sizes of all registered HAProxy memory pools used by the OTel
      filter.

  flt_otel_runtime_context_init
      Allocates and initializes the per-stream runtime context.  Generates a
      UUID and stores it in the sess.otel.uuid HAProxy variable.

  flt_otel_runtime_context_free
      Frees the runtime context: ends all active spans, destroys all extracted
      contexts, and releases pool memory.

  flt_otel_scope_span_init
      Finds an existing scope span by name or creates a new one.  Resolves the
      parent reference (span or extracted context).

  flt_otel_scope_span_free
      Frees a scope span entry if its OTel span has been ended.  Refuses to free
      an active (non-NULL) span.

  flt_otel_scope_context_init
      Finds an existing scope context by name or creates a new one by extracting
      the span context from a text map.

  flt_otel_scope_context_free
      Frees a scope context entry and destroys the underlying OTel span context.

  flt_otel_scope_data_dump [D]
      Dumps scope data contents (baggage, attributes, events, links, status) for
      debugging.

  flt_otel_scope_data_init
      Zero-initializes a scope data structure and its event/link lists.

  flt_otel_scope_data_free
      Frees all scope data contents: key-value arrays, event entries, link
      entries, and status description.

  flt_otel_scope_finish_mark
      Marks spans and contexts for finishing.  Supports wildcard ("*"),
      channel-specific ("req"/"res"), and named targets.

  flt_otel_scope_finish_marked
      Ends all spans and destroys all contexts that have been marked for
      finishing by flt_otel_scope_finish_mark().

  flt_otel_scope_free_unused
      Removes scope spans with NULL OTel span and scope contexts with NULL OTel
      context.  Cleans up associated HTTP headers and variables.


src/parser.c
----------------------------------------------------------------------

Configuration file parsing for otel-instrumentation, otel-group and otel-scope
sections.

  flt_otel_parse_strdup
      Duplicates a string with error handling; optionally stores the string
      length.

  flt_otel_parse_keyword
      Parses a single keyword argument: checks for duplicates and missing
      values, then stores via flt_otel_parse_strdup().

  flt_otel_parse_invalid_char
      Validates characters in a name according to the specified type
      (identifier, domain, context prefix, variable).

  flt_otel_parse_cfg_check
      Common validation for config keywords: looks up the keyword, checks
      argument count and character validity, verifies that the parent section ID
      is set.

  flt_otel_parse_cfg_sample_expr
      Parses a single HAProxy sample expression within a sample definition.
      Calls sample_parse_expr().

  flt_otel_parse_cfg_sample
      Parses a complete sample definition (key plus one or more sample
      expressions).

  flt_otel_parse_cfg_str
      Parses one or more string arguments into a conf_str list (used for the
      "finish" keyword).

  flt_otel_parse_cfg_file
      Parses and validates a file path argument; checks that the file exists and
      is readable.

  flt_otel_parse_check_scope
      Checks whether the current config parsing is within the correct HAProxy
      configuration scope (cfg_scope filtering).

  flt_otel_parse_cfg_instr
      Section parser for the otel-instrumentation block.  Handles keywords:
      otel-instrumentation ID, log, config, groups, scopes, acl, rate-limit,
      option, debug-level.

  flt_otel_post_parse_cfg_instr
      Post-parse callback for otel-instrumentation.  Links the instrumentation
      to the config and checks that a config file is specified.

  flt_otel_parse_cfg_group
      Section parser for the otel-group block.  Handles keywords: otel-group ID,
      scopes.

  flt_otel_post_parse_cfg_group
      Post-parse callback for otel-group.  Checks that at least one scope is
      defined.

  flt_otel_parse_cfg_scope_ctx
      Parses the context storage type argument ("use-headers" or "use-vars") for
      inject/extract keywords.

  flt_otel_parse_acl
      Builds an ACL condition by trying multiple ACL lists in order
      (scope-local, instrumentation, proxy).

  flt_otel_parse_bounds
      Parses a space-separated string of numbers into a dynamically allocated
      array of doubles for histogram bucket boundaries.  Sorts the values
      internally.

  flt_otel_parse_cfg_instrument
      Parses the "instrument" keyword inside an otel-scope section.  Supports
      both "update" form (referencing an existing instrument) and "create" form
      (defining a new metric instrument with type, name, optional aggregation
      type, description, unit, value, and optional histogram bounds).

  flt_otel_parse_cfg_scope
      Section parser for the otel-scope block.  Handles keywords: otel-scope ID,
      span, link, attribute, event, baggage, status, inject, extract, finish,
      instrument, log-record, acl, otel-event.

  flt_otel_post_parse_cfg_scope
      Post-parse callback for otel-scope.  Checks that HTTP header injection is
      only used on events that support it.

  flt_otel_parse_cfg
      Parses the OTel filter configuration file.  Backs up current sections,
      registers temporary otel-instrumentation/group/scope section parsers,
      loads and parses the file, then restores the original sections.

  flt_otel_parse
      Main filter parser entry point, registered for the "otel" filter keyword.
      Parses the filter ID and configuration file path from the HAProxy config
      line.


src/conf.c
----------------------------------------------------------------------

Configuration structure allocation and deallocation.  Most init/free pairs are
generated by the FLT_OTEL_CONF_FUNC_INIT and FLT_OTEL_CONF_FUNC_FREE macros.

  flt_otel_conf_hdr_init
      Allocates and initializes a conf_hdr structure.

  flt_otel_conf_hdr_free
      Frees a conf_hdr structure and removes it from its list.

  flt_otel_conf_str_init
      Allocates and initializes a conf_str structure.

  flt_otel_conf_str_free
      Frees a conf_str structure and removes it from its list.

  flt_otel_conf_link_init
      Allocates and initializes a conf_link structure (span link).

  flt_otel_conf_link_free
      Frees a conf_link structure and removes it from its list.

  flt_otel_conf_ph_init
      Allocates and initializes a conf_ph (placeholder) structure.

  flt_otel_conf_ph_free
      Frees a conf_ph structure and removes it from its list.

  flt_otel_conf_sample_expr_init
      Allocates and initializes a conf_sample_expr structure.

  flt_otel_conf_sample_expr_free
      Frees a conf_sample_expr structure and releases the parsed sample
      expression.

  flt_otel_conf_sample_init
      Allocates and initializes a conf_sample structure.

  flt_otel_conf_sample_init_ex
      Extended sample initialization: sets the key, extra data (event name or
      status code), concatenated value string, and expression count.

  flt_otel_conf_sample_free
      Frees a conf_sample structure including its value, extra data, and all
      sample expressions.

  flt_otel_conf_context_init
      Allocates and initializes a conf_context structure.

  flt_otel_conf_context_free
      Frees a conf_context structure and removes it from its list.

  flt_otel_conf_span_init
      Allocates and initializes a conf_span structure with empty lists for
      links, attributes, events, baggages and statuses.

  flt_otel_conf_span_free
      Frees a conf_span structure and all its child lists.

  flt_otel_conf_instrument_init
      Allocates and initializes a conf_instrument structure.

  flt_otel_conf_instrument_free
      Frees a conf_instrument structure and removes it from its list.

  flt_otel_conf_log_record_init
      Allocates and initializes a conf_log_record structure with empty
      attributes and samples lists.

  flt_otel_conf_log_record_free
      Frees a conf_log_record structure: event_name, span, attributes and
      samples list.

  flt_otel_conf_scope_init
      Allocates and initializes a conf_scope structure with empty lists for
      ACLs, contexts, spans, spans_to_finish and instruments.

  flt_otel_conf_scope_free
      Frees a conf_scope structure, ACLs, condition, and all child lists.

  flt_otel_conf_group_init
      Allocates and initializes a conf_group structure with an empty placeholder
      scope list.

  flt_otel_conf_group_free
      Frees a conf_group structure and its placeholder scope list.

  flt_otel_conf_instr_init
      Allocates and initializes a conf_instr structure.  Sets the default rate
      limit to 100%, initializes the proxy_log, and creates empty ACL and
      placeholder lists.

  flt_otel_conf_instr_free
      Frees a conf_instr structure including ACLs, loggers, config path, and
      placeholder lists.

  flt_otel_conf_init
      Allocates and initializes the top-level flt_otel_conf structure with empty
      group and scope lists.

  flt_otel_conf_free
      Frees the top-level flt_otel_conf structure and all of its children
      (instrumentation, groups, scopes).


src/cli.c
----------------------------------------------------------------------

HAProxy CLI command handlers for runtime filter management.

  cmn_cli_set_msg
      Sets the CLI appctx response message and state.

  flt_otel_cli_parse_debug [D]
      CLI handler for "otel debug [level]".  Gets or sets the debug level.

  flt_otel_cli_parse_disabled
      CLI handler for "otel enable" and "otel disable".

  flt_otel_cli_parse_option
      CLI handler for "otel soft-errors" and "otel hard-errors".

  flt_otel_cli_parse_logging
      CLI handler for "otel logging [state]".  Gets or sets the logging state
      (off/on/dontlog-normal).

  flt_otel_cli_parse_rate
      CLI handler for "otel rate [value]".  Gets or sets the rate limit
      percentage.

  flt_otel_cli_parse_status
      CLI handler for "otel status".  Displays filter configuration and runtime
      state for all OTel filter instances.

  flt_otel_cli_init
      Registers the OTel CLI keywords with HAProxy.


src/otelc.c
----------------------------------------------------------------------

OpenTelemetry context propagation bridge (inject/extract) between HAProxy and
the OTel C wrapper library.

  flt_otel_text_map_writer_set_cb
      Writer callback for text map injection.  Appends a key-value pair to the
      text map.

  flt_otel_http_headers_writer_set_cb
      Writer callback for HTTP headers injection.  Appends a key-value pair to
      the text map.

  flt_otel_inject_text_map
      Injects span context into a text map carrier.

  flt_otel_inject_http_headers
      Injects span context into an HTTP headers carrier.

  flt_otel_text_map_reader_foreach_key_cb
      Reader callback for text map extraction.  Iterates over all key-value
      pairs in the text map.

  flt_otel_http_headers_reader_foreach_key_cb
      Reader callback for HTTP headers extraction.  Iterates over all key-value
      pairs in the text map.

  flt_otel_extract_text_map
      Extracts a span context from a text map carrier via the tracer.

  flt_otel_extract_http_headers
      Extracts a span context from an HTTP headers carrier via the tracer.


src/http.c
----------------------------------------------------------------------

HTTP header manipulation for context propagation.

  flt_otel_http_headers_dump [D]
      Dumps all HTTP headers from the channel's HTX buffer.

  flt_otel_http_headers_get
      Extracts HTTP headers matching a prefix into a text map.  Used by the
      "extract" keyword to read span context from incoming request headers.

  flt_otel_http_header_set
      Sets or removes an HTTP header.  Combines prefix and name into the full
      header name, removes all existing occurrences, then adds the new value
      (if non-NULL).

  flt_otel_http_headers_remove
      Removes all HTTP headers matching a prefix.  Wrapper around
      flt_otel_http_header_set() with NULL name and value.


src/vars.c
----------------------------------------------------------------------

HAProxy variable integration for context propagation and storage.  Only compiled
when USE_OTEL_VARS is defined.

  flt_otel_vars_scope_dump [D]
      Dumps all variables for a single HAProxy variable scope.

  flt_otel_vars_dump [D]
      Dumps all variables across all scopes (PROC, SESS, TXN, REQ/RES).

  flt_otel_smp_init
      Initializes a sample structure with stream ownership and optional string
      data.

  flt_otel_smp_add
      Appends a context variable name to the binary sample data buffer used for
      tracking registered context variables.

  flt_otel_normalize_name
      Normalizes a variable name: replaces dashes with 'D' and spaces with 'S',
      converts to lowercase.

  flt_otel_denormalize_name
      Reverses the normalization applied by flt_otel_normalize_name().  Restores
      dashes from 'D' and spaces from 'S'.

  flt_otel_var_name
      Constructs a full variable name from scope, prefix and name components,
      separated by dots.

  flt_otel_ctx_loop
      Iterates over all context variable names stored in the binary sample data,
      calling a callback for each.

  flt_otel_ctx_set_cb
      Callback for flt_otel_ctx_loop() that checks whether a context variable
      name already exists.

  flt_otel_ctx_set
      Registers a context variable name in the binary tracking buffer if it is
      not already present.

  flt_otel_var_register
      Registers a HAProxy variable via vars_check_arg() so it can be used at
      runtime.

  flt_otel_var_set
      Sets a HAProxy variable value.  For context-scope variables, also
      registers the name in the context tracking buffer.

  flt_otel_vars_unset_cb
      Callback for flt_otel_ctx_loop() that unsets each context variable.

  flt_otel_vars_unset
      Unsets all context variables for a given prefix and removes the tracking
      variable itself.

  flt_otel_vars_get_scope
      Resolves a scope name string ("proc", "sess", "txn", "req", "res") to the
      corresponding HAProxy variable store.

  flt_otel_vars_get_cb
      Callback for flt_otel_ctx_loop() that reads each context variable value
      and adds it to a text map.

  flt_otel_vars_get
      Reads all context variables for a prefix into a text map.  Used by the
      "extract" keyword with variable storage.


src/pool.c
----------------------------------------------------------------------

Memory pool and trash buffer helpers.

  flt_otel_pool_alloc
      Allocates memory from a HAProxy pool (if available) or from the heap.
      Optionally zero-fills the allocated block.

  flt_otel_pool_strndup
      Duplicates a string using a HAProxy pool (if available) or the heap.

  flt_otel_pool_free
      Returns memory to a HAProxy pool or frees it from the heap.

  flt_otel_trash_alloc
      Allocates a trash buffer chunk, optionally zero-filled.

  flt_otel_trash_free
      Frees a trash buffer chunk.


src/util.c
----------------------------------------------------------------------

Utility and conversion functions.

  flt_otel_args_dump [D]
      Dumps configuration arguments array to stderr.

  flt_otel_filters_dump [D]
      Dumps all OTel filter instances across all proxies.

  flt_otel_chn_label [D]
      Returns "REQuest" or "RESponse" based on channel flags.

  flt_otel_pr_mode [D]
      Returns "HTTP" or "TCP" based on proxy mode.

  flt_otel_stream_pos [D]
      Returns "frontend" or "backend" based on stream flags.

  flt_otel_type [D]
      Returns "frontend" or "backend" based on filter flags.

  flt_otel_analyzer [D]
      Returns the analyzer name string for a given analyzer bit.

  flt_otel_list_dump [D]
      Returns a summary string for a list (empty, single, count).

  flt_otel_args_count
      Counts the number of valid (non-NULL) arguments in an args array, handling
      gaps from blank arguments.

  flt_otel_args_concat
      Concatenates arguments starting from a given index into a single
      space-separated string.

  flt_otel_strtod
      Parses a string to double with range validation.

  flt_otel_strtoll
      Parses a string to int64 with range validation.

  flt_otel_sample_to_str
      Converts sample data to its string representation.  Handles bool, sint,
      IPv4, IPv6, str, and HTTP method types.

  flt_otel_sample_to_value
      Converts sample data to an otelc_value.  Preserves native types (bool,
      int64) where possible; falls back to string.

  flt_otel_sample_add_event
      Adds a sample value as a span event attribute.  Groups attributes by event
      name; dynamically grows the attribute array.

  flt_otel_sample_set_status
      Sets the span status code and description from sample data.

  flt_otel_sample_add_kv
      Adds a sample value as a key-value attribute or baggage entry.
      Dynamically grows the key-value array.

  flt_otel_sample_eval
      Evaluates all sample expressions for a configured sample definition and
      stores the result in an otelc_value.  Supports both log-format and bare
      sample expression paths.  When flag_native is true and the sample has
      exactly one expression, the native HAProxy sample type is preserved;
      otherwise results are concatenated into a string.

  flt_otel_sample_add
      Top-level sample evaluator and dispatcher.  Calls flt_otel_sample_eval()
      to evaluate the sample, then dispatches the result to the appropriate
      handler (attribute, event, baggage, status).


src/group.c
----------------------------------------------------------------------

Group action support for http-response / http-after-response / tcp-request /
tcp-response rules.

  flt_otel_group_action
      Action callback (action_ptr) for the otel-group rule.  Finds the filter
      instance on the current stream and runs all scopes defined in the group.

  flt_otel_group_check
      Check callback (check_ptr) for the otel-group rule.  Resolves filter ID
      and group ID references against the proxy's filter configuration.

  flt_otel_group_release
      Release callback (release_ptr) for the otel-group rule.

  flt_otel_group_parse
      Parses the "otel-group" action keyword from HAProxy config rules.
      Registered for tcp-request, tcp-response, http-request, http-response and
      http-after-response action contexts.