ChangeLog

ChangeLog
=========

Release notes are grouped by the filter version.  Entries summarise individual
commits, with directly related commits folded into a single bullet, and the
git log keeps the full descriptions.


Version 2.3.0 (2026-09-14)
--------------------------

The samples of a span that the sampler leaves out are no longer evaluated.  The
SDK discards the attributes, events, links, status and exceptions of such a
span, so each span is created before its samples and asked whether it records,
and the ones that do not skip the evaluation.  The span itself is still created,
the injected 'traceparent' carries the trace with the sampled flag cleared, and
the baggage samples are evaluated whatever the decision was.  A sample builds
its string in a trash buffer and keeps a copy of the produced size, instead of
a zeroed buffer of tune.bufsize bytes held until the scope data is freed.  The
speed test gained an 'unsampled' level that measures that path.

How often each keyword of the configuration file may be written is now stated
in README-implementation and enforced by the parser and the configuration check.
The words 'if' and 'unless' are refused as names, an identifier may run to 127
characters, an ACL name is unique within its section, and a condition may mix
the ACLs of the otel-scope, the instrumentation and the proxy.  The sections
may stand in any order, every line lives inside a top-level OTel scope, each
otel-instrumentation keyword is written once, and every otel-group must be named
on a 'groups' line.  A key of 'attribute', 'event', 'baggage', 'set-var' or
'set-var-ctx' may repeat once per condition with the first match applied, 'link'
takes a condition and repeats, 'otel-stop' repeats, and the create lines of one
instrument name share a single owner.  The inject and extract context names,
the span and context names of every reference, the root span marks, the metric
instrument name and unit and the W3C key of a context field are checked when the
configuration is loaded; a scope that never runs, an event the filter placement
never fires and a rejected event pairing are reported where they stand.  A new
parser test runs one 'haproxy -c' per case against those rules.

A scope whose event condition did not match no longer disables the whole session
because one of its spans carries the 'root' mark.  A request fetch on a stream
lifecycle event, such as 'path' on 'on-backend-set', read the response side
and returned nothing; those events now carry a usable direction.  An aborted
parse left the section pointers dangling, so the next filter line made the check
read freed memory; the pointers are cleared now.  A filter of a backend section
arms its idle timer and no longer re-runs the frontend's http-request rules,
and 'on-server-unavailable' fires only when no server was reached.  The 'config'
parse error names its keyword, a sample expression is no longer measured as a
name, the same expression may stand twice in one value, and an 'id' written
after 'config' on the filter line selects the scope.  A 'baggage' line whose
sample yielded nothing no longer costs the span its other pairs.

The GNU General Public License, version 2 was added as the LICENSE file and
the headers moved from the LGPL to the GPL, so the whole filter is under one
license.  The keyword guides were corrected and completed, the warnings of the
configuration check are described where the keyword is, test/README.md gives an
overview of the tests, and README-implementation no longer repeats itself from
chapter to chapter.  The required wrapper version is raised to 3.4.0, whose
header exposes the debug level list in every build, so the 'debug-level' value
is checked in a release build as well.

  * MEDIUM: Skipped the samples of a span that records nothing; each span is now
    created before its samples are evaluated and asked whether it records, while
    the injected 'traceparent' and the baggage stay in place.
  * MINOR: Evaluated the samples in a trash buffer and kept a copy of the size
    produced, instead of a zeroed tune.bufsize buffer per value.
  * MINOR: Added the 'unsampled' level to the speed test, whose sampler drops
    every trace.
  * LICENSE: Added the LICENSE file and moved the headers from the LGPL to the
    GPL.
  * CLEANUP: Collected the session disabling into one function.
  * BUG/MINOR: Kept the session alive when a scope holding a root-marked span
    is skipped by its event condition.
  * MINOR: Checked 'extract use-headers' against the scope event, since the
    stream start and stop events carry no readable channel.
  * CLEANUP: Used the span event dump macro where the events are handled.
  * BUG/MINOR: Gave the events that run on no channel a usable fetch direction,
    so a request fetch on 'on-backend-set' reads the request side.
  * BUG/MINOR: Cleared the section state after an aborted parse, which left
    'haproxy -c' reading freed memory on the next filter line.
  * MINOR: Required every otel-group to be named on a 'groups' line.
  * BUG/MINOR: Armed the idle timer for a filter of a backend section, which
    never received the stream-start callback.
  * BUG/MINOR: Fired on-server-unavailable only when no server was reached,
    instead of whenever no response analyser ran.
  * BUG/MINOR: Kept a backend filter from re-running the frontend rules, which
    applied the http-request rules a second time.
  * MINOR: Warned about the events the filter placement never fires.
  * CLEANUP: Replaced the words 'gate' and 'verbatim' in the comments and the
    guides.
  * DOC: Added the keyword definition rules to README-implementation and updated
    the guides.
  * MINOR: test: Added the configuration parser test, one 'haproxy -c' run per
    case.
  * CLEANUP: Collected the repeated error messages into macros and added the
    entry traces to the functions that lacked them.
  * CLEANUP: Compared the baggage carrier key without case folding.
  * BUG/MINOR: Named the 'config' keyword in its own parse error.
  * BUG/MINOR: Stopped measuring a sample expression as a name, which refused
    one past 63 characters as too long.
  * BUG/MINOR: Allowed a repeated sample expression in one value.
  * BUG/MINOR: Read the whole filter line before its configuration, so an 'id'
    written after 'config' selects the scope.
  * MINOR: Named the sample key where the value stands on its own, so that no
    argument of a 'time', 'message' or 'value' clause is taken for one.
  * MINOR: Refused the reserved words 'if' and 'unless' as names and raised the
    identifier limit to 127 characters.
  * BUG/MINOR: Allowed a condition to mix ACLs of the otel-scope, the
    instrumentation and the proxy.
  * MINOR: Made an ACL name unique within its section.
  * MINOR: Rejected a bare 'if' or 'unless' with no ACL term.
  * MINOR: Allowed the configuration sections in any order.
  * MINOR: Required the configuration to live inside a top-level OTel scope
    with a unique name.
  * MINOR: Allowed each otel-instrumentation keyword only once, accepted the
    'default' prefix on 'option' and 'log', and checked the 'debug-level' value
    in every build.
  * MINOR: Checked the metric instrument name and unit against the SDK rules.
  * MINOR: Separated a repeated span line from a redefinition.
  * MINOR: Ended a sample list at a repeated clause of the same line.
  * MINOR: Allowed the 'otel-stop' keyword to be repeated once per condition.
  * MINOR: Gave the 'link' keyword a condition and let it repeat.
  * MINOR: Let a key of the 'attribute', 'event', 'baggage', 'set-var' and the
    'set-var-ctx' keywords repeat once per condition, first match applied.
  * MINOR: Bound the instrument lines of one name to a single owner, so only
    one otel-scope creates the instrument.
  * MINOR: Enforced the rules of the inject and extract context names.
  * MINOR: Validated the span and context names of every reference.
  * MINOR: Enforced the root span rules.
  * MINOR: Warned about an otel-scope that never runs.
  * MINOR: Reported the event pairings on the line that completes them.
  * DOC: Added an overview of the tests in test/README.md.
  * MINOR: Checked the context field key against the W3C rules.
  * CLEANUP: Described the invalid-character check modes and marked the code
    that cannot run with a NOTE comment.
  * DOC: Corrected and completed the keyword guides, corrected stale statements
    across the guides and notes, and added the load-time warnings.
  * DOC: Completed the stream stop notes and the function reference.
  * BUG/MINOR: Left a baggage pair whose sample yielded nothing out, which had
    cost the span every other pair.
  * DOC: Shortened the repeated passages of README-implementation and corrected
    the metric instrument claim the chapter below it contradicts.
  * VERSION: Bumped the filter version to 2.3.0.


Version 2.2.0 (2026-08-17)
--------------------------

Fixes a crash that a single request could trigger: a span entry is listed before
the OpenTelemetry span behind it is created, and when that creation failed,
ending the entry read the operations table through a null pointer and killed
the process.  The contexts already had this guard; now the spans have it too.

An unreachable exporter no longer stalls the proxy.  The CLI 'flush' command
shares one time budget across the visited signals instead of five seconds for
each, and the handles are flushed under a short shared budget before they are
destroyed at shutdown.  The 'noflush' instrumentation option, also settable
at runtime with the new 'flt-otel noflush' CLI command, skips the final flush
altogether and drops the buffered telemetry, so a shutdown or a reload proceeds
at once.

The configuration check is stricter, and the bytes a peer sends are handled
more carefully.  The OpenTelemetry YAML is validated at configuration parse
time, so a broken YAML file fails the 'haproxy -c' check instead of the later
startup, and a directory or a device given as a configuration file is rejected.
A header whose name is exactly the context extract prefix is skipped instead of
being read far past its end, and the runtime error text is escaped before it is
written to the log, so a quoted sample value cannot reach a terminal verbatim.

The filter now builds against HAProxy 3.2 as well as 3.4.  The required wrapper
version is raised to 3.3.0, which provides the YAML validation and the flush
timeout operations.

  * BUILD: Adapted the ACL condition conflict check to HAProxy 3.2.
  * BUILD: Guarded the descriptor name release on older HAProxy.
  * BUILD: Adapted the HTTP header addition to HAProxy 3.2.
  * MINOR: Rejected non-regular configuration files, as a directory or a device
    was parsed as an empty configuration with a misleading alert.
  * MINOR: Validated the OpenTelemetry YAML at configuration parse time, so a
    broken YAML configuration fails the 'haproxy -c' check instead of the later
    startup.
  * MINOR: Freed the CLI messages on the defensive NULL-appctx path.
  * DOC: Refreshed the error-handling and shutdown documentation.
  * MINOR: Unified the repeated message strings into macro definitions.
  * BUG/MEDIUM: Skipped the header whose name is only the extract prefix, which
    left an empty key and read the HTX buffer far past the header.
  * BUG/MINOR: Escaped the runtime error text written to the log, so the bytes
    a peer sent cannot reach a terminal verbatim.
  * BUG/MEDIUM: Bounded the time the CLI 'flush' command may block with one
    budget shared by all the visited signals.
  * BUG/MAJOR: Guarded the span whose creation failed before ending it, which
    killed the process on the first request.
  * MINOR: Added the 'noflush' instrumentation option, which skips the final
    flush and drops the buffered telemetry, so a shutdown proceeds at once.
  * DOC: Completed the instrumentation field table.
  * VERSION: Bumped the filter version to 2.2.0.


Version 2.1.2 (2026-08-13)
--------------------------

Fixes a memory leak that grew with every HTTP request handled: on HAProxy 3.4
vars_check_arg() duplicates the variable name into the descriptor it returns,
and the filter discarded that descriptor on return without releasing the copy.
The registration of sess.otel.uuid leaked one copy per stream attach and the
variable context injection leaked one more per injected key, until the worker
was OOM-killed under production load.

Two further fixes matter at runtime.  The extraction of a context stored in
variables iterated one of the two rotating trash chunks, which every variable
fetch of its own callback recycled, so the entries after the first were misread
and a propagated tracestate disappeared from the resulting spans.  A context
variable overwritten with a non-string type was read as a string pointer; such a
variable is now reported and rejected.

A scoped configuration file whose section header line fell outside the matching
scope crashed the 'haproxy -c' run, because the keyword handlers ran with no
open section object; such lines are now rejected with an error.  The remaining
changes clear a bounds pointer that the section cleanup freed twice, tighten
the variable-name and parser checks, correct or complete the debug output, and
add the filter version to the 'haproxy -vv' build options line.  The required
wrapper version stays at 3.2.0.

  * BUG/MEDIUM: Released the variable-name copy that vars_check_arg() allocates
    on HAProxy 3.4, which leaked one copy per request until the worker was
    OOM-killed.
  * BUG/MEDIUM: Iterated the context tracking buffer from a private copy, which
    the variable fetches of the extraction cannot disturb.
  * BUG/MINOR: Cleared the bounds pointer on a failed allocation, so the section
    cleanup no longer frees the released array a second time.
  * CLEANUP: Removed the unused flt_otel_pool_strndup() helper.
  * MINOR: Skipped the instrument evaluation on an attribute failure, instead of
    evaluating a value that the error guard then discarded.
  * BUG/MEDIUM: Rejected keyword lines that arrive with no open section object,
    which crashed 'haproxy -c' on a scoped configuration file.
  * BUG/MINOR: Validated the first character of a variable name, which must
    be a letter or an underscore.
  * MINOR: Resolved minor parser inconsistencies around the explicit section
    name, a duplicate 'inject' line and the proxy argument context.
  * DOC: Described the by-name grouping of span 'event' lines into a single span
    event.
  * BUG/MINOR: Fixed the truncated debug level in the 'flt-otel status' report.
  * BUG/MINOR: Rejected non-string context variables in the extraction.
  * BUG/MINOR: Corrected invalid or misleading debug output.
  * MINOR: Completed and hardened the structure dump macros.
  * VERSION: Bumped the filter version to 2.1.2.


Version 2.1.1 (2026-08-11)
--------------------------

Fixes a crash of the configuration check: the 'require-context' check ran on
the instrumentation pointer without any test, so an OTel configuration file
that defines nothing for the filter, an empty file included, segfaulted the
'haproxy -c' run instead of failing it with the error it had just reported.

The other fixes stop a sample evaluation on the first conversion error, keep
the DEBUG_OTEL variable dump from reading a scalar variable as a string pointer,
take the context tracking buffer ownership from the buffer state instead of
the add helper's return offset, and clear the converted instrument value so
its type tag is meaningful on every return path.

A new dummy subtree reproduces the OTel C wrapper API as a build-only stand-in,
which lets the filter compile and link without the wrapper and even without
the OpenTelemetry C++ SDK; an executable built this way still runs but produces
no telemetry at all.  The required wrapper version stays at 3.2.0.

  * BUILD: Added a build-only stand-in for the OTel C wrapper, which lets the
    filter compile and link without the wrapper and the OpenTelemetry C++ SDK.
  * BUG/MINOR: Stopped the sample evaluation on a conversion error, in the
    expression list loop as well as in the span and instrument attribute
    collection.
  * DOC: Documented that the response-channel HTTP events fire only for a real
    server response, and the soft-error behavior of each output type.
  * BUG/MEDIUM: Guarded the require-context check on a missing instrumentation,
    which crashed 'haproxy -c' on an OTel configuration file that defines
    nothing for the filter.
  * BUG/MINOR: Guarded the debug variable dump by the sample type, so a scalar
    variable is no longer read as a string pointer.
  * BUG/MINOR: Freed the context tracking buffer only when it was ours, taking
    the ownership from the buffer state before the add call.
  * MINOR: Initialized the output value in the sample conversion, so the type
    tag is meaningful on every return.
  * VERSION: Bumped the filter version to 2.1.1.


Version 2.1.0 (2026-08-05)
--------------------------

Requires the OTel C wrapper version 3.2.0 and adds the 'require-context' option,
which holds all telemetry of a stream back until a valid trace context has been
extracted from the request, so a downstream HAProxy never originates a trace of
its own.  The option is off by default, which preserves the earlier behavior of
the filter.

The runtime CLI commands now accept an optional '@<filter>' token that addresses
a single filter instance by its id, and the dump commands have been rebuilt as
iterative io_handlers: a report larger than tune.bufsize is no longer silently
discarded, and the quadratic string rebuilding that could stall a thread into a
watchdog panic is gone.  The status report shows the suppressed runtime log
lines as a pending count and as a lifetime total, with its section titles and
head-block value columns aligned.

A metric instrument name may also be repeated in create form, typically gated
by an 'if' or 'unless' condition selecting which measurement is recorded; an
update-form entry binds the nearest preceding create of the same name, and the
configuration check enforces type consistency instead of uniqueness.

  * BUG/MINOR: Closed the outer quote of the message printed when the
    filter id falls back to the default.
  * BUG/MEDIUM: Made the status, scopes and instruments CLI commands
    iterative io_handlers, replacing the single memprintf() report that a
    full buffer silently discarded.
  * MINOR: Added the optional '@<filter>' target token to the CLI commands,
    which restricts a command to the one instance named by its filter id.
  * MINOR: Added the 'require-context' option that suppresses all telemetry
    for a stream without a valid extracted trace context.
  * MINOR: Allowed repeated creates of a metric instrument name; an update
    binds the nearest preceding create, and the checks enforce type
    consistency instead of uniqueness.
  * MINOR: Added a lifetime total of the suppressed runtime log lines,
    shown by 'flt-otel status' and kept across 'flt-otel reset-errors'.
  * MINOR: Polished the CLI status dump formatting: aligned section titles,
    shared head-block value columns and colons on the bare titles.
  * DOC: Required the OTel C wrapper version 3.2.0 on the OpenTelemetry C++
    SDK 1.26.0 or newer, and refreshed the sample version strings of the
    build and CLI status outputs.
  * VERSION: Bumped the filter version to 2.1.0.


Version 2.0.2 (2026-07-30)
--------------------------

Adapts the filter to the HAProxy 3.5 global proxy list, which has replaced the
singly linked 'proxies_list' with the doubly linked 'main_proxies'.  The three
iteration sites now go through a single macro whose form Makefile.mk selects
from the list type that it detects in the HAProxy headers, so the filter still
compiles against HAProxy 3.4 as well.

  * BUILD: Adapted the proxy list iteration to HAProxy 3.5 behind a macro
    that Makefile.mk selects from the detected list type, so the 3.4 build
    keeps working.
  * VERSION: Bumped the filter version to 2.0.2.


Version 2.0.1 (2026-07-30)
--------------------------

Requires the OTel C wrapper version 3.1.0 and otherwise only fixes bugs.  The
main one crashed HAProxy on the span context propagation over the HTTP headers
on a TCP proxy: a scope bound to a non-HTTP event ran the header walk on a raw
channel, where the HTX view holds garbage once the buffer carries data.  The
header get and set operations now bail out when the stream is not HTX, and the
configuration check rejects a header inject or extract whose event fires on a
non-HTTP proxy.

The remaining fixes cover the startup and the teardown paths.  A failed library
initialization no longer leaks the created OTel context, the instrumentation
loggers are released with free_logger() instead of a bare ha_free, a log-record
'id 0' is reported as out of range rather than silently ignored, and a map error
stops the whole variable extraction scan.

  * BUG/MINOR: Freed the partial state after a failed library init, which
    aborts startup without running the deinit callback.
  * BUG/MINOR: Rejected a log-record event id of zero, the wrapper's 'omit'
    sentinel, which was accepted but did nothing.
  * BUG/MEDIUM: Guarded the HTTP header operations on a non-HTX channel and
    rejected a header inject or extract on a non-HTTP proxy at the check.
  * MINOR: Aborted the variable extraction scan fully on error, instead of
    leaving the inner name-bucket loop only.
  * BUG/MINOR: Freed the instrumentation loggers with free_logger(), which
    releases the members that a bare ha_free left behind.
  * DOC: Required the OTel C wrapper version 3.1.0 and refreshed the sample
    version strings of the build and CLI status outputs.
  * VERSION: Bumped the filter version to 2.0.1.


Version 2.0.0 (2026-07-20)
--------------------------

Requires the OTel C wrapper version 3.0.0 and adapts the filter to its library
context API; the filter no longer compiles against the 2.x wrapper releases.
Several filter instances, each holding its own library context, now operate
simultaneously in one HAProxy process, and the old single active configuration
limitation is gone.

The 'config' keyword takes an optional signals context name that selects one
of the named contexts of the YAML configuration, and the filter line takes an
optional section name so filters with distinct ids can share one section of
the OTel configuration file.  The tracer, meter and logger are created only
for the signals the YAML document provides: an absent signal section is skipped,
the legacy flat layout and the 'default' fallback get a warning, and a context
name that matches nothing fails the startup.

The benchmarks moved to HAProxy's haterm dummy server as the default backend
and all speed-test results were re-collected at saturating load; the speed test
now also preserves each level's filter CLI state in a per-level HAProxy runner
log.

  * MINOR: Adapted the filter to the OTel C wrapper 3.0.0 API: the library
    context threads through init, create, statistics and deinit, the CLI
    keywords register once per process, and the YAML configuration closes
    after the per-thread start.
  * MINOR: Added the optional signals context argument to the 'config'
    keyword and wrapped the test YAML signals under a 'default' context.
  * MINOR: Added haterm as the default speed-test backend behind a new '-b'
    option, with the wrk load parameters set per backend type.
  * DOC: Published the haterm-collected benchmark results for every test
    configuration, together with the test system specification.
  * MINOR: Created only the signals the YAML configuration provides; the
    span, instrument and log-record processors report an unconfigured
    signal instead of dereferencing a NULL handle.
  * MINOR: Added the optional section name argument to the filter line,
    shown by the CLI status next to the configuration file name.
  * MINOR: Dumped the 'flt-otel scopes', 'flt-otel instruments' and
    'flt-otel status' CLI output into the per-level runner log before each
    HAProxy stop; the runners take the log file as a third argument.
  * VERSION: Bumped the filter version to 2.0.0.


Version 1.0.0 (initial release, 2026-01-27 .. 2026-07-15)
---------------------------------------------------------

Initial public release of the HAProxy OpenTelemetry filter, a stream filter
that emits traces, metrics and logs from HAProxy through the OpenTelemetry C
wrapper library.  A section-based configuration file defines the telemetry model
(scopes, groups, spans, metric instruments and log records driven by stream
events), while a YAML file configures the SDK pipeline.  The filter runs on
HTTP and TCP proxies, samples streams through a rate limit, propagates span
contexts over the HTTP headers or HAProxy variables, and is managed at runtime
through the CLI.  Requires the OTel C wrapper version 2.2.1 and HAProxy 3.4
or later.

Filter

  * MEDIUM: Built the filter core: the skeleton, the configuration and
    utility layer, the section parser with its event model and post-parse
    checks, the memory pools, the runtime scope layer, and the filter
    callbacks with the event dispatcher.
  * MEDIUM: Wired the OTel C wrapper integration and the scope execution
    with span management; the SDK starts once through an atomic claim.
  * MEDIUM: Added span context propagation through carrier interfaces, over
    HTTP headers or HAProxy variables, with prefix-based variable scanning
    and an automatic inject context name.
  * MEDIUM: Added the group action for rule-based scope execution from the
    HAProxy TCP/HTTP rules.
  * MEDIUM: Extended tracing to TCP-mode proxies, counting the forwarded
    payload through the otel.bytes_in and otel.bytes_out sample fetches.
  * MEDIUM: Logged runtime errors and warnings per instance, edge-triggered
    and rate-limited, so a recurring fault does not flood syslog.
  * MINOR: Added span links with attributes, the span 'kind', per-event
    timestamps, exceptions, and several conditional status lines per span.
  * MINOR: Added the metric instruments (counter, histogram, up-down
    counter and gauge) with the create/update value-binding model.
  * MINOR: Added the log-record signal with severities, an explicit 'time'
    option and the wall-clock observed time.
  * MINOR: Bound the keyword values to sample expressions with log-format
    support across attributes, instruments and log records.
  * MINOR: Gated the scope directives on an optional if/unless condition
    through a shared helper.
  * MINOR: Added the set-var, set-var-ctx and unset-var scope directives
    and the by-name variable helpers.
  * MINOR: Added the 'otel-stop' keyword, the on-http-tarpit-request scope
    event, the idle-timeout handling and the 'otel.context' sample fetch.
  * MINOR: Added the CLI management commands: enable/disable, error modes,
    rate limit, logging, reset-errors, flush, and the status, instruments
    and scopes introspection built on a column-oriented table builder that
    shows the export-pipeline state.
  * MINOR: Validated the configuration at load: fetch and condition
    validity at the scope's event, location checks for scopes and group
    actions, and warnings for the documented limitations.
  * BUG: Hardened the runtime paths: the idle timer no longer clobbers the
    stream analyse timeout and runs off the stream task expiry, injection
    failures do not leak, header removal and variable registration
    tolerate NULL, and the string buffers are bounds-checked.

Build

  * BUILD: Built as a standalone addon: the Makefile.mk fragment plugs
    into the HAProxy build through EXTRA_MAKE, with OTEL_STATIC for static
    linking, a clean-target hook and a .gitignore.

Tests and documentation

  * MINOR: Added the test and benchmark suite: the per-configuration
    runners unified into one symlinked script, the speed-test harness with
    option parsing and system CPU sampling, the OTLP/HTTP recorder and
    replay helpers, and the sa, full, cmp, ctx, fe/be, tcp, updown, err
    and empty configurations.
  * DOC: Added the manuals: the README, the configuration guide, the
    implementation review, the design patterns document, the README.md
    overview and the test guides with benchmark results; documented the
    best-effort delivery and the single-filter-instance limitation.
  * DOC: Required the OTel C wrapper version 2.2.1.