Debugging

HTTPX tries to hide the gory details of protocol handling. However, it can expose them with its “debug” mode (with verbosity levels), which outputs connection state, HTTP headers/payload, HTTP/2 frames, all that might be considered relevant for internal debugging purposes, or even just for bug reporting.

You can enable it either by using session or request options (for single-request debugging), or using environment variables (for whole process debugging).

Options

Debugging logs can be configured by using any of the following options:

  • :debug: debugging stream where logs are written to (can be anything that responds to #<<(String), like STDERR).
  • :debug_level: sets the verbosity level (1 or 2, the latter being more verbose).
  • :debug_redact: replaces any string which may contain sensitive information (request header and body payloads, for example) with the "[REDACTED]" placeholder.

Here’s how you can use them in your code:

HTTPX.with(debug: STDERR, debug_level: 2).get("https://google.com")
# LOTS OF DEBUGGING OUTPUT
HTTPX.with(debug: STDERR, debug_level: 2, debug_redact: true).get("https://google.com")
# LOTS OF REDACTED DEBUGGING OUTPUT

Environment variables

httpx supports HTTPX_DEBUG environment variable to enable debugging logs without changing your code. This is very useful for script-based debugging, and collecting data for issue reporting.

You can also set HTTPX_DEBUG_REDACT to 1 to produced redacted logs, in case you cannot afford to expose sensitive information when reporting issues.

# sets verbosity/debug level to 1, write to standard error:
> HTTPX_DEBUG=1 bundle exec ruby my_debugging_script_with_httpx.rb
# redact them like this:
> HTTPX_DEBUG=1 HTTPX_DEBUG_REDACT=1 bundle exec ruby my_debugging_script_with_httpx.rb

Next: JRuby/Truffleruby/Other Rubies