Graham Dumpleton: Zero-code tr... Note

Graham Dumpleton: Zero-code tracing with wrapture

This text describes how to use the "wrapture" tool to observe and trace Python programs without modifying their source code. Initially, tracing involved editing the program's entry point, which is undesirable for inherited or shared code. A more flexible approach uses a separate configuration file, wrapture.toml, to specify what to observe and where to send the trace data. This configuration file defines observation targets and their associated methods, along with data redaction rules.The wrapture.toml file allows specific method names or glob patterns to be targeted within modules. The tool is run using python -m wrapture followed by the program script, which applies the configuration before executing the program. This method generates the same trace output as the source-modified approach but keeps observation logic external. For longer-running applications, the trace output can be directed to a file, such as trace.jsonl, in JSON Lines format.This file format captures detailed event information, including arguments, results, exceptions, and timing, making it easily processable by common tools like jq. Safety considerations for leaving tracing active include a bounded queue to prevent blocking and summarization of arguments to avoid retaining live objects. When direct command-line execution is not possible, autowrapt can be used to inject wrapture at interpreter startup via an environment variable.This bootstrapping mechanism is generally intended for development or debugging, not production environments. Once tracing is injected, it can be dynamically controlled – suspended and resumed or completely reverted – without restarting the application, using features accessible through wrapture.bootstrap. The next step for wrapture involves applying this tracing capability to more complex application units, such as those found in web applications.