Echoz Debug Output

Use this module when you need nginx itself to emit a response for debugging, diagnostics, or small utility endpoints.

When to use this module

  • You want a quick debug endpoint without involving an application upstream.
  • You need to inspect request variables or request bodies during integration work.
  • You want to wrap another upstream response with simple prefix or suffix content.
  • You need lightweight internal redirects or fire-and-forget subrequests.

nginx.conf synthesis

Use echoz and echozn for direct response output, or the body-filter directives to wrap another response.

location /debug/info {
    echoz "Method: $request_method";
    echoz "URI: $uri";
    echoz "Host: $host";
}

location /echo-body {
    echoz_read_request_body;
    echoz_request_body;
}

location /wrapped {
    echoz_before_body "<html><body>";
    echoz_after_body "</body></html>";
    proxy_pass http://backend;
}

# Internal redirect to a named location
location /old {
    echoz_exec @new;
}

location @new {
    echoz "Redirected!";
}

This is most useful for controlled internal endpoints, diagnostics, and simple response shaping. The module provides two nginx modules in one: a content handler for generating response bodies and a body filter for wrapping other handlers’ output.

Directive reference

echoz

  • Contexts: location
  • Default: disabled

Outputs text with a trailing newline. Use it when readability matters more than strict byte-for-byte output.

echozn

  • Contexts: location
  • Default: disabled

Outputs text without adding a newline. Use it for JSON fragments or exact response bodies. Safe as a subrequest target for auth_request, SSI, and mirror — echozn does not emit a response body for header_only subrequests, so it works correctly when used in subrequest-only contexts.

echoz_duplicate

  • Contexts: location
  • Default: disabled

Repeats a string a fixed number of times. It is mostly useful for tests, response shaping experiments, and synthetic payloads.

echoz_flush

  • Contexts: location
  • Default: disabled

Flushes the current output buffer. Use it when you want nginx to send buffered echo output earlier in the response flow.

echoz_sleep

  • Contexts: location
  • Default: disabled

Pauses execution for a configured interval. This is mainly a test and diagnostics tool, not a normal production behavior.

echoz_request_body

  • Contexts: location
  • Default: disabled

Outputs the request body. Use it to inspect incoming payloads on test endpoints.

echoz_read_request_body

  • Contexts: location
  • Default: disabled

Reads the request body into memory so later echo directives can use it. Pair it with echoz_request_body when you want body inspection.

echoz_exec

  • Contexts: location
  • Default: disabled

Performs an internal redirect to another location — either a regular location path or a named location (@name). Use it when you want a simple internal handoff instead of returning content directly.

echoz_location_async

  • Contexts: location
  • Default: disabled

Fires a true background subrequest — the child response is discarded and not merged back into the parent response. Use it for fire-and-forget internal signaling where you don’t need the subrequest result. If you want the child body in the parent response, use a foreground mechanism such as SSI instead.

echoz_before_body

  • Contexts: location
  • Default: disabled

Prepends text to the response body from another handler. Runs in the output filter chain, not the content phase, so it wraps responses generated by other directives or upstream handlers. Use it with echoz_after_body for simple response wrapping.

echoz_after_body

  • Contexts: location
  • Default: disabled

Appends text after the response body from another handler. Like echoz_before_body, runs in the output filter chain. Use it with echoz_before_body for simple response wrapping.

echoz_status

  • Contexts: location
  • Default: response default

Sets the response status code. Use it when the endpoint should return a controlled non-200 response.

echoz_header

  • Contexts: location
  • Default: none

Adds a response header. This is useful for debug metadata, test contracts, and simple integration signaling.

Works well with

  • Stock nginx return and rewrite — use these for simple redirects and static responses; echoz adds variable interpolation, request body inspection, and response wrapping.
  • Request ID when you want debug endpoints to expose tracing values.
  • JSON Schema Validation for quick validation-and-echo test flows.
  • njs Runtime when you need more logic than static echo directives provide.