ferronweb/ferron 3.0.0-rc.10

on GitHub

Breaking changes

Observability

• EventTraceContext API change: the EventTraceContext struct for ferron_observability has been updated to include tracestate. If your custom Ferron modules rely on the EventTraceContext struct, you may need to update it to include tracestate (you can use tracestate: None).

Added

Runtime

• Support for pinning into specific CPU cores: Ferron now supports pinning worker threads to specific CPU cores (for asymmetric CPU cores and NUMA). This can be configured via the cpu_affinity directive in the global configuration block.

Changed

HTTP server core

• HTTP body buffering: added support for disabling request and response body buffering using Incremental: ?1 or X-Accel-Buffering: no headers.

Observability

• http.route is now a route template: previously, the ferron.request span reported http.route as the requested hostname (or "*"). It now reports the matched route template built from the configured location block names, for example /api/users/:id, and is omitted when no location block matched.
• ferron.host added to request spans: the requested virtual host is now reported as ferron.host on the ferron.request span. It uses the same attribute name as the TLS metrics, so traces and metrics join on the same key. server.address is unchanged and still reports the bound socket address.
• Sampling probability reported in tracestate: when Ferron starts a trace itself and trace_sampling uses a ratio, the request's trace context now carries the OpenTelemetry ot tracestate entry (for example ot=0.1), on the propagated headers and on the exported span. Backends that extrapolate sampled traces can scale counts back up; previously a ratio sampler silently reported only the sampled fraction of traffic. No ot entry is written for always_on, always_off, parentbased_always_on, a ratio of 1.0 or 0.0, or attribute_based sampling. An incoming tracestate is passed through unchanged.
• Active health checking metric attributes: the metrics related to active health checking now have resolved IP address attributes when metrics_resolved_ip is enabled (similarly to circuit breaker metrics).
• Aggregate active health checking partial success metrics: added a ferron.proxy.health.partial_success metric that reports health check probe results that succeeded only for some backend servers (percentage of successes in 0.0-1.0 scale).
• Circuit breaker and active health check status metrics for multi-address upstreams: improved overall metric clarity and reduced ambiguity when metrics_resolved_ip is disabled.
• TLS and HTTP protocol error log improvement: when server is logging to text-format application logs (not JSON structured ones), it now logs client IP address and port for TLS and HTTP protocol error logs.

HTTP server core

• request.uri.path improvement: the request.uri.path variable is now resolving to URL-decoded value for more consistent matching. request.uri and request.uri.query are documented as not necessarily URL-decoded.

Fixed

HTTP server core

• trace.id and span.id resolution fix: previously, trace.id and span.id variable interpolations resolve to a doubly hex-encoded IDs, not proper single hex-encoded values.
• HEAD request response body discard: When sending a response for an HTTP HEAD request, the response body is now discarded instead of being sent to the client, improving HTTP spec compliance (see zincio-http changelog).
• Conditional configuration validation: the server is now reporting (via ferron validate) invalid forms of if, if_not, location and handle_error directives.
• HTTP/3 protocol hardening: hardened the HTTP/3 implementation against potential QPACK decoding vulnerabilities (see zincio-http changelog).

Observability

• tracestate is now exported on spans: the OTLP exporter wrote an empty trace_state on every span, discarding the W3C tracestate that Ferron parses and propagates to upstreams. The span now reports it.
• Span trace flags follow the sampling decision: the OTLP exporter hardcoded the "sampled" flag on every span. The flag sent to the OTLP backend or collector now reflects the recorded decision.
• Prometheus scrape error metric: previously, ferron_prometheus_scrape_errors_total metric didn't increase at all. This has been fix to increase when an internal error with Prometheus endpoint occured.
• Connection pool metric fix: previously, outstanding connection count measured from exported metrics (like Prometheus or OTLP) was bogus, it didn't decrease properly due to a logic bug.

Reverse proxying

• Strict-DNS URL resolution fix: previously, strict-DNS URL resolution dropped the upstream path prefix (like /api in http://backend.example/api). This has been fixed to preserve the upstream path prefix.