httpdbg Documentation

The httpdbg library uses several internal utilities to provide high-fidelity debugging information:

1. get_current_instruction: Analyzes the traceback.StackSummary to find the specific line of code that initiated a request. It filters out internal httpdbg hooks and asyncio frames to focus on the user's code.
2. extract_short_stack_from_file: Reads the source file of a stack frame to reconstruct the actual code instruction. It attempts to handle multi-line statements by looking ahead for balanced parentheses.
3. construct_call_str: Generates a string representation of a function call, including the module, function name, and the values of all passed *args and **kwargs. This allows you to see exactly what parameters were passed to the HTTP client.

You can configure httpdbg behavior using the following environment variables:

• HTTPDBG_MULTIPROCESS_DIR: Specifies the directory used for multiprocess communication/storage.
• HTTPDBG_LOG_LEVEL: Sets the logging verbosity level.
• HTTPDBG_LOG_PATH: Specifies the file path where logs should be written.

export HTTPDBG_LOG_LEVEL=DEBUG
export HTTPDBG_LOG_PATH=/var/log/httpdbg.log
export HTTPDBG_MULTIPROCESS_DIR=/tmp/httpdbg_mp

The HTTPRecords constructor accepts the following arguments:

• client (bool): If True, captures client-side HTTP requests. Defaults to True.
• server (bool): If True, captures server-side HTTP responses. Defaults to False.
• ignore (tuple[tuple[str, int], ...]): A collection of pairs used to filter out specific traffic. Each pair consists of a string pattern and an integer (typically a status code or port identifier).

# Example: Capture both client and server traffic, ignoring localhost on port 80
records = HTTPRecords(
    client=True, 
    server=True, 
    ignore=(("localhost", 80),)
)

The httprecord symbol provides access to individual HTTP records captured by the library. It is available at the top-level httpdbg package.

from httpdbg import httprecord

# Use httprecord to interact with captured HTTP data

Use get_new_uuid() to generate a 10-character string consisting of random ASCII letters. This is specifically designed to be compatible with method naming rules.

from httpdbg.utils import get_new_uuid

uuid = get_new_uuid()
print(uuid)  # Example output: 'aBcDeFgHiJ'

To properly associate captured requests with their origins or logical groupings, use the add_initiator and add_group methods. This sets the current_initiator and current_group context for subsequent record creation.

• add_initiator(initiator: Initiator): Registers an Initiator object and sets it as the current active initiator.
• add_group(group: Group): Registers a Group object and sets it as the current active group.

from httpdbg.records import HTTPRecords
# Assuming initiator and group objects are already instantiated

records = HTTPRecords()
records.add_initiator(my_initiator)
records.add_group(my_group)

The httpdbg_srv context manager starts a background server that intercepts HTTP requests and records them into an HTTPRecords object. It is designed to be used within a with statement.

When the context block exits, the server is automatically shut down. If an error occurs during server startup, it raises a HttpdbgException.

from httpdbg.server import httpdbg_srv

# Start the interceptor on localhost at port 8080
with httpdbg_srv('127.0.0.1', 8080) as records:
    # Perform your HTTP operations here
    # The 'records' object will contain the intercepted data
    print(f"Intercepted {len(records)} requests")

# Server is automatically shut down here

If an HTTP request fails with an exception, use add_new_record_exception to log the failure as an HTTPRecord.

Arguments:

• initiator (Initiator): The initiator responsible for the request.
• group (Group): The group the request belongs to.
• url (str): The URL of the attempted request.
• exception (Exception): The exception that occurred.

try:
    # ... perform request ...
    pass
except Exception as e:
    records.add_new_record_exception(current_initiator, current_group, target_url, e)

Use export_html to generate an HTML representation of captured HTTP traffic. This function is available at the top-level httpdbg package via lazy loading.

from httpdbg import export_html

# Example usage (actual arguments depend on the export implementation)
export_html(records, filename='output.html')

Use export_html() to write an HTML report directly to a file on disk.

Arguments:

• records (HTTPRecords): The collection of HTTP records to include.
• filename (Path): The destination file path where the HTML will be written.

from pathlib import Path
from httpdbg import HTTPRecords
from httpdbg.export import export_html

# records: your HTTPRecords instance
# output_file: the path where you want to save the report
output_file = Path("report.html")
export_html(records, output_file)