birdseye

birdseye provides a non-linear debugging experience focused on data flow rather than line-by-line stepping:

• Loop Iteration Navigation: Move back and forth through loop iterations to observe how expression values change over time.
• Exception Highlighting: Identify which specific expressions raise exceptions, including those that are suppressed by try/except blocks.
• Data Structure Exploration: Expand concrete data structures and objects to inspect their contents (depth and length are automatically limited to prevent data overload).
• Chronological Call Organization: Function calls are organized by file and function, then ordered by time, providing a clear timeline of execution.

To manage memory and performance, Birdseye uses sampling and truncation strategies for data collection:

• Loop Sampling: Only the first and last 3 iterations of loops are stored. (Note: If an expression is evaluated in the middle of a loop, up to two additional iterations where it was evaluated may be included).
• Value Representation: A limited version of repr() is used via the cheap_repr package to reduce data size.
• Nesting Depth: Nested data structures and objects are expanded by a maximum of 3 levels. This depth is further decreased inside loops, unless all current loops are in their first iteration.
• Object Recording: Only specific pieces of objects are recorded rather than the entire object state.

Birdseye works by parsing a decorated function's source code into a standard Python Abstract Syntax Tree (AST). It then modifies the AST by wrapping every statement in a with statement and every expression in a function call. This modified tree is compiled into a new code object used to construct a brand new function.

Because Birdseye reconstructs the function rather than wrapping it, the @eye decorator must be applied first. If other decorators are applied before @eye, they may be bypassed by the AST reconstruction or have no effect on the tracing.

By default, birdseye saves data from the first and last three iterations of a loop. If you need to inspect a specific iteration in the middle of a long loop, you can use these strategies:

1. Conditional Logic: Use an if or try/except statement to isolate the specific iteration. birdseye ensures that for every statement/expression node in a loop, at least two iterations where that node was evaluated are saved. If a statement is only evaluated during your specific target iteration, those iterations will be captured.
2. Function Wrapping: Wrap the loop's contents in a function and decorate that function with @eye. This allows you to find the specific call you need by inspecting the arguments and return values in the calls table, though this incurs a performance cost.

Birdseye traces every function call and nontrivial expression, which introduces significant overhead. When using Birdseye, be aware of the following:

• Execution Speed: Programs will run significantly slower. Avoid tracing functions that are called frequently or contain many loop iterations.
• Memory Usage: Large amounts of data are collected for every call. Functions with many loop iterations or large nested objects can consume significant memory during execution and when viewing results in a browser.
• Visibility: Function calls are only visible in the Birdseye interface once they have completed execution.

The birdseye VS Code extension allows you to view the birdseye UI directly inside your editor.

1. Install the extension from the Visual Studio Marketplace.
2. Open the Command Palette (F1 or Cmd+Shift+P).
3. Select Show birdseye to start the server and open the browser pane within VS Code.

The Birdseye server provides the web interface for viewing traces. You can run it via the birdseye CLI command.

To run a remote server accessible from any network interface, use the --host 0.0.0.0 flag.

For production environments, it is recommended to use a WSGI server like gunicorn instead of the default Flask development server. The WSGI application is located at birdseye.server:app.

Instead of decorating individual functions with @eye, you can trace an entire module or its top-level execution by adding a specific import statement at the top of the file.

• To trace every function in the file and the module execution itself, use import birdseye.trace_module_deep.
• To trace only the module execution (and reduce performance impact), use import birdseye.trace_module.

Important Caveats:

• These import statements must be unindented (at the top level), not inside if or try blocks.
• If the module is being imported by another module (rather than run directly):
  • In Python 2, the module will not be traced.
  • birdseye must be imported somewhere before the traced module is imported.
  • The execution of the entire module will be traced, not just the code following the import statement.

Install the birdseye package using pip. It is recommended to use the --user flag to install it for the current user.

pip install --user birdseye

To access the birdseye UI on PythonAnywhere, the birdseye server must run within a web app. You can use a dedicated web app or integrate it into an existing one using WSGI middleware.

Option 1: Dedicated Web App In your WSGI configuration file (/var/www/your_domain_com_wsgi.py), use:

from birdseye.server import app as application

Option 2: Combine with an existing Web App Append the following to your existing WSGI file to mount birdseye at a specific prefix (e.g., /birdseye):

import birdseye.server
from werkzeug.wsgi import DispatcherMiddleware

application = DispatcherMiddleware(application, {
    '/birdseye': birdseye.server.app
})

Security Note: Because birdseye exposes your code and data, ensure your PythonAnywhere web app has Force HTTPS and Password protection enabled under the Security settings.