From 414bbcf208c7057f0b0002b3a7a9122284533568 Mon Sep 17 00:00:00 2001 From: Build System Date: Mon, 18 May 2026 02:48:59 +0200 Subject: [PATCH] obs: permanent structured emit-decision debug logging MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add gated ngx_log_debug at the output emit-decision point in ngx_http_zstd_filter_compress: zstd emit?: outsz:N rc0:N last:N ctx_last:N ctx_flush:N action:N zstd emit: suppressed empty non-terminal buffer NGX_DEBUG-gated (the ngx_log_debug* macros compile to nothing in release builds), so zero runtime cost when off; visible with `error_log ... debug`. Behaviour is unchanged — this only observes the existing guard, it does not alter it. Rationale: this module has a recurring truncation / zero-size-buffer / terminal-frame bug class (a209f96, 2af5889, PR#23/#49, the 2026-05 bug B). Every prior diagnosis required temporarily patching in debug lines and rebuilding, repeatedly. This makes the single most diagnostic probe permanent: the exact state the emit guard saw. Verified during bug-B work — it immediately exposed the forced-flush mechanism without a patch/rebuild loop. Builds clean under the project -Werror flags (nginx 1.31.0). --- filter/ngx_http_zstd_filter_module.c | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/filter/ngx_http_zstd_filter_module.c b/filter/ngx_http_zstd_filter_module.c index 60071dd..9174107 100644 --- a/filter/ngx_http_zstd_filter_module.c +++ b/filter/ngx_http_zstd_filter_module.c @@ -670,7 +670,26 @@ ngx_http_zstd_filter_compress(ngx_http_request_t *r, ngx_http_zstd_ctx_t *ctx) */ last = rc == 0 && ctx->last && directive == ZSTD_e_end; + /* + * Structured emit-decision trace. Permanent: compiled out of + * release builds via NGX_DEBUG (zero runtime cost when off), + * visible with `error_log ... debug`. This is the single most + * useful probe for the module's recurring truncation / + * zero-size-buffer / terminal-frame bug class — it records exactly + * what the emit guard saw (output size, libzstd return, terminal + * and flush state, action) so future diagnosis is one + * `error_log debug` away instead of a patch/rebuild cycle. Behaviour + * is unchanged; this only observes. + */ + ngx_log_debug6(NGX_LOG_DEBUG_HTTP, r->connection->log, 0, + "zstd emit?: outsz:%uz rc0:%d last:%d ctx_last:%d " + "ctx_flush:%d action:%d", + (size_t) ngx_buf_size(ctx->out_buf), rc == 0, last, + ctx->last, ctx->flush, (ngx_uint_t) ctx->action); + if (ngx_buf_size(ctx->out_buf) == 0 && !last && !(rc == 0 && ctx->flush)) { + ngx_log_debug0(NGX_LOG_DEBUG_HTTP, r->connection->log, 0, + "zstd emit: suppressed empty non-terminal buffer"); return NGX_AGAIN; }