Hi all,
I’ve been building an open-source Python project called Flatline and wanted to share a practical tutorial-style introduction for anyone dealing with apps that freeze, hang, or die before normal debugging gives you anything useful.
Repository:
https://github.com/tibberous/Flatline
Flatline is a Python process debugger/supervisor designed for situations like:
GUI freezes
hung child processes
silent crashes
startup failures
shutdown races
apps that stop responding before they emit a useful traceback
According to the current project README, Flatline supervises a Python subprocess, monitors heartbeats, detects freezes, opens an interactive crash console, captures stack/variable snapshots, and writes stack_trace.log, variables.log, and error.log.
What Flatline does
Flatline runs your app under supervision instead of relying on the app to diagnose itself cleanly.
The current README describes these core behaviors:
launches a Python subprocess
monitors heartbeats via TCP relay
detects freezes when heartbeats go stale
opens an interactive crash console on crash/freeze
captures stack trace and variable dump
writes log files automatically.
It supports two main heartbeat modes:
DB mode: beat events are stored in MariaDB and freeze detection uses DB timestamps
Poll mode: a non-blocking proc.poll() thread tracks child liveness without requiring a database.
Quick start
The README’s simplest entry point is:
python flatline.py app.py
Flatline “always runs in supervisor mode,” so there is no separate debug mode to enable.
Example command-line usage
From the current README:
python flatline.py
python flatline.py script.py X Y
python flatline.py --app script.py
python flatline.py --config myapp.ini
python flatline.py --version
python flatline.py --help
The bundled example.py also demonstrates launching a target script with Flatline and passing through extra arguments to the supervised app.
Example configuration
The bundled config.ini format in the README looks like this:
[flatline]
app = example.py
freeze_threshold = 2.5
poll_interval = 1.0
poll_fail_limit = 3
[database]
enabled = false
host = 127.0.0.1
port = 3306
user = root
password =
database = flatline
That means you can start in simple poll mode, then move to database-backed heartbeat tracking later if you want more persistent beat logging.
Adding heartbeats to your app
The current README shows the intended pattern:
from source.remote_client import RemoteClient
flatline = RemoteClient()
class MyWindow:
def __init__(self):
flatline.beat('INIT', 'MyWindow')
def resizeEvent(self, event):
flatline.beat('RESIZE', 'MyWindow')
It also notes that beat() is rate-limited so identical reason/caller pairs inside 50ms are dropped.
What happens when something goes wrong
Flatline’s README describes the crash console keys as:
1 stack trace
2 variable dump
3 graceful close
4 SIGTERM
5 force kill
6 refresh
7 shell command
8 network connections
9 network monitor
R restart
S status
Q quit.
The logs bundled with the project also show the parent-side watchdog/debugger behavior in practice: relay server startup, process watchdog startup, socket REPL on localhost:5050, child launch, and crash console opening when the child exits non-zero or becomes unhealthy.
Demo app
The current README says the bundled app.py demo includes:
a left-panel code editor
a right-panel black/green output console
editable demo code
redirected print() output
an About dialog.
That makes it easy to test:
normal execution
deliberate exceptions
freeze handling
child supervision behavior
Why I built it
I originally built Flatline while debugging a much larger Python desktop application that had freezes, startup failures, shutdown hangs, and hard-to-catch runtime faults. The goal was to keep the debugger useful even when the child process was not cooperating.
Feedback I’d love
I’d especially appreciate feedback on:
whether the current CLI/config flow feels Pythonic
whether the heartbeat model should stay this simple or grow more structured
whether the crash-console workflow is useful outside desktop apps
what kinds of failures you most want a tool like this to help with
Repository again:
https://github.com/tibberous/Flatline
I’ve been building an open-source Python project called Flatline and wanted to share a practical tutorial-style introduction for anyone dealing with apps that freeze, hang, or die before normal debugging gives you anything useful.
Repository:
https://github.com/tibberous/Flatline
Flatline is a Python process debugger/supervisor designed for situations like:
GUI freezes
hung child processes
silent crashes
startup failures
shutdown races
apps that stop responding before they emit a useful traceback
According to the current project README, Flatline supervises a Python subprocess, monitors heartbeats, detects freezes, opens an interactive crash console, captures stack/variable snapshots, and writes stack_trace.log, variables.log, and error.log.
What Flatline does
Flatline runs your app under supervision instead of relying on the app to diagnose itself cleanly.
The current README describes these core behaviors:
launches a Python subprocess
monitors heartbeats via TCP relay
detects freezes when heartbeats go stale
opens an interactive crash console on crash/freeze
captures stack trace and variable dump
writes log files automatically.
It supports two main heartbeat modes:
DB mode: beat events are stored in MariaDB and freeze detection uses DB timestamps
Poll mode: a non-blocking proc.poll() thread tracks child liveness without requiring a database.
Quick start
The README’s simplest entry point is:
python flatline.py app.py
Flatline “always runs in supervisor mode,” so there is no separate debug mode to enable.
Example command-line usage
From the current README:
python flatline.py
python flatline.py script.py X Y
python flatline.py --app script.py
python flatline.py --config myapp.ini
python flatline.py --version
python flatline.py --help
The bundled example.py also demonstrates launching a target script with Flatline and passing through extra arguments to the supervised app.
Example configuration
The bundled config.ini format in the README looks like this:
[flatline]
app = example.py
freeze_threshold = 2.5
poll_interval = 1.0
poll_fail_limit = 3
[database]
enabled = false
host = 127.0.0.1
port = 3306
user = root
password =
database = flatline
That means you can start in simple poll mode, then move to database-backed heartbeat tracking later if you want more persistent beat logging.
Adding heartbeats to your app
The current README shows the intended pattern:
from source.remote_client import RemoteClient
flatline = RemoteClient()
class MyWindow:
def __init__(self):
flatline.beat('INIT', 'MyWindow')
def resizeEvent(self, event):
flatline.beat('RESIZE', 'MyWindow')
It also notes that beat() is rate-limited so identical reason/caller pairs inside 50ms are dropped.
What happens when something goes wrong
Flatline’s README describes the crash console keys as:
1 stack trace
2 variable dump
3 graceful close
4 SIGTERM
5 force kill
6 refresh
7 shell command
8 network connections
9 network monitor
R restart
S status
Q quit.
The logs bundled with the project also show the parent-side watchdog/debugger behavior in practice: relay server startup, process watchdog startup, socket REPL on localhost:5050, child launch, and crash console opening when the child exits non-zero or becomes unhealthy.
Demo app
The current README says the bundled app.py demo includes:
a left-panel code editor
a right-panel black/green output console
editable demo code
redirected print() output
an About dialog.
That makes it easy to test:
normal execution
deliberate exceptions
freeze handling
child supervision behavior
Why I built it
I originally built Flatline while debugging a much larger Python desktop application that had freezes, startup failures, shutdown hangs, and hard-to-catch runtime faults. The goal was to keep the debugger useful even when the child process was not cooperating.
Feedback I’d love
I’d especially appreciate feedback on:
whether the current CLI/config flow feels Pythonic
whether the heartbeat model should stay this simple or grow more structured
whether the crash-console workflow is useful outside desktop apps
what kinds of failures you most want a tool like this to help with
Repository again:
https://github.com/tibberous/Flatline
Attached Files
