haproxy-opentelemetry 1.0.0

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-scope sections bind telemetry actions to stream events, otel-group sections are invoked from HAProxy TCP/HTTP rules, and an otel-instrumentation section 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_out sample fetches.
• ACL-driven conditions at instrumentation, scope and event level.
• Percentage-based rate limiting (0.0--100.0) to control overhead.
• Periodic idle-timeout events for long-lived streams.
• Hard/soft error modes with runtime error logging and flood control.
• CLI management over the HAProxy socket (flt-otel prefix): 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, ...) and unset-var scope directives.

Dependencies

• HAProxy 3.4 or later -- the filter is built together with HAProxy as an external addon via the EXTRA_MAKE mechanism.
• 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 start
• README-configuration -- complete configuration reference
• README-implementation -- internals and design notes
• test/ -- 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 opentelemetry declarations 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.