First public release of the HAProxy OpenTelemetry filter (OTel) -- an HAProxy addon that instruments proxied traffic with traces, metrics and logs and delivers them to any OpenTelemetry-compatible backend over OTLP, developed by HAProxy Technologies. It is the successor to the OpenTracing (OT) filter.
Signals
All three OpenTelemetry signals are supported, configured entirely from configuration files -- no code required:
- Traces -- spans with parent-child relationships across the stream's processing phases, span kinds, attributes, timestamped events, links, baggage, statuses and exception recording, all evaluated at runtime from HAProxy sample fetches and log-format expressions.
- Metrics -- counter, histogram, up-down counter and gauge instruments with configurable aggregation and histogram bucket boundaries.
- Logs -- log records with severity levels, optional span correlation and runtime-evaluated attributes.
Exporters
Selected in the YAML configuration of the SDK pipeline:
| Type | Description |
|---|---|
otlp_grpc |
OTLP over gRPC |
otlp_http |
OTLP over HTTP (JSON or Protobuf) |
otlp_file |
Local files in OTLP format |
zipkin |
Zipkin-compatible backends |
elasticsearch |
Elasticsearch |
ostream |
Text output to a file (for debugging) |
memory |
In-memory buffer (for testing) |
Highlights
- Declarative model:
otel-scopesections bind telemetry actions to stream events,otel-groupsections are invoked from HAProxy TCP/HTTP rules, and anotel-instrumentationsection sets the global behavior. - Context propagation between cascaded HAProxy instances or external services: inject/extract via HTTP headers or HAProxy variables, with the
otel.context()sample fetch to test in ACLs whether a valid context was propagated. - Runs on HTTP-mode and TCP-mode proxies; on TCP the connection lifecycle is traced and the forwarded payload is counted through the
otel.bytes_in/otel.bytes_outsample fetches. - ACL-driven conditions at instrumentation, scope and event level.
- Percentage-based rate limiting (0.0--100.0) to control overhead.
- Periodic
idle-timeoutevents for long-lived streams. - Hard/soft error modes with runtime error logging and flood control.
- CLI management over the HAProxy socket (
flt-otelprefix): status inspection, instrument and scope listing, enable/disable, error-mode switching, logging control and debug level. - Bridging into HAProxy variables:
set-var,set-var-ctx(trace-id, span-id, traceparent, ...) andunset-varscope directives.
Dependencies
- HAProxy 3.4 or later -- the filter is built together with HAProxy as an external addon via the
EXTRA_MAKEmechanism. - OpenTelemetry C Wrapper version 2.2.1 exactly; at startup the filter verifies that the linked library and the headers it was compiled against carry the same version string.
Building
PKG_CONFIG_PATH=/opt/lib/pkgconfig make -j8 TARGET=linux-glibc EXTRA_MAKE="../haproxy-opentelemetry"
Optional build variables (OTEL_DEBUG, OTEL_USE_VARS, OTEL_INC, OTEL_LIB, OTEL_RUNPATH, OTEL_STATIC) are described in the README.
Documentation
README/README.md-- overview, build and quick startREADME-configuration-- complete configuration referenceREADME-implementation-- internals and design notestest/-- ready-to-run example configurations, test guides and a speed-test harness
Known limitations
- Delivery is best-effort by OpenTelemetry design: telemetry may be dropped through sampling, queue limits, network failures or backend unavailability, so the data should not be relied on where completeness is critical.
- One filter instance is operational per HAProxy process: the parser accepts several
filter opentelemetrydeclarations with unique ids, but the OTel C Wrapper currently supports a single active configuration.
License
GPL 2.0 or later for the sources, LGPL 2.1 or later for the headers -- the same licensing scheme as HAProxy itself.