What the agent does
The agent reads how the app logs and where queries run before choosing a mechanism. In an app laid out like miguelgrinberg/microblog, create_app in app/__init__.py configures app.logger only when not in debug or testing: a RotatingFileHandler on logs/microblog.log with a format of time, level, message and pathname:lineno, or a StreamHandler when LOG_TO_STDOUT is set, and an SMTPHandler for errors when MAIL_SERVER is set. requirements.txt pins SQLAlchemy 2.0.23 and Flask-SQLAlchemy 3.1.1, config.py reads settings from the environment with python-dotenv, and boot.sh runs the app under gunicorn with access and error logs to stdout. Queries run in two places: request handlers under app/main, app/auth and app/api, and app/tasks.py, where export_posts runs inside an rq worker with an app context but no request.
Flask-SQLAlchemy has a recorder for this, SQLALCHEMY_RECORD_QUERIES with get_recorded_queries() giving each query's statement, parameters, start_time, end_time, duration and location, but it is documented as a debugging aid and it only sees queries made during a request, so the worker's queries would never be timed. The agent chooses SQLAlchemy's engine events instead: a before_cursor_execute listener stores a start time in conn.info, and an after_cursor_execute listener computes the elapsed time and, when it crosses the threshold, writes one warning through current_app.logger with the duration in milliseconds, the statement, and the number of parameters. It writes nothing when the threshold is unset, so a deployment that does not opt in pays only the two function calls per statement.
The listeners live in a new app/slow_queries.py with an init_app(app) that registers them on db.engine inside an app context, called from create_app after db.init_app(app), so they cover the worker as well as the web process because both call create_app. The threshold is SLOW_DB_QUERY_SECONDS in config.py, read from the environment with a default of 0.5, and tests.py's TestConfig sets it to 0 so every statement qualifies in tests. Because the app's log format already ends with [in pathname:lineno], the agent passes stacklevel so that location points at the handler that issued the query rather than at the listener, and it adds the SQLAlchemy Connection's info guard so a statement issued through db.session.execute on a connection reused across requests is timed per statement, not per connection. Parameter values are never logged; a search term or an email bound to a slow statement stays out of logs/microblog.log.
tests.py gains a SlowQueryCase that runs a query under self.assertLogs(self.app.logger, level='WARNING') with the threshold at zero and checks the record names the statement and a duration, then raises the threshold and asserts no record. The agent runs python -m unittest tests.py -v, starts the app with flask run and LOG_TO_STDOUT=1 plus SLOW_DB_QUERY_SECONDS=0, loads /explore, and reads the warnings on stdout with the app/main/routes.py line each one came from. It also runs rq worker microblog-tasks against a local Redis it installs with apt-get, triggers /export_posts, and shows that the worker's statements are timed too.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add slow query logging to this Flask + SQLAlchemy app. Read requirements.txt, config.py, app/__init__.py, app/models.py, app/main/routes.py, app/tasks.py, boot.sh and tests.py first. Do not use Flask-SQLAlchemy's SQLALCHEMY_RECORD_QUERIES, because app/tasks.py runs queries in an rq worker outside any request; use SQLAlchemy's before_cursor_execute and after_cursor_execute engine events instead. Write app/slow_queries.py with an init_app that registers both listeners on db.engine, storing the start time in conn.info and logging one warning through the app logger when the elapsed time crosses SLOW_DB_QUERY_SECONDS, with the duration in milliseconds, the statement and the number of parameters, never their values; pass stacklevel so the log's pathname and lineno point at the caller. Add SLOW_DB_QUERY_SECONDS to config.py from the environment with a default of 0.5 and set it to 0 in TestConfig. Call init_app from create_app after db.init_app so the worker is covered too. Add a SlowQueryCase to tests.py using assertLogs for a record at threshold 0 and no record above it. Run python -m unittest tests.py -v, start the app with LOG_TO_STDOUT=1 and the threshold at 0, load /explore, install Redis, run an rq worker, trigger /export_posts, and paste the warnings from both processes and the test output into the pull request. Change no query or template.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request adds app/slow_queries.py, and changes app/__init__.py, config.py, tests.py and the README's configuration list. Its description pastes the python -m unittest tests.py -v output, a few warnings from the web process for /explore with the duration, statement and [in app/main/routes.py:59] style location, and two from the rq worker during an export, so the reviewer sees that the worker path is covered and what a line looks like before one appears in production.
With the default threshold of half a second, a deployment logs nothing until a statement is slow, and SLOW_DB_QUERY_SECONDS moves that line through the environment like every other setting in config.py. In tests the threshold is zero, so a future test that accidentally runs hundreds of statements becomes visible in the test log.
Before merging, a reviewer picks a threshold for their database, decides whether the warnings should also go to the SMTPHandler that emails errors, which they do not by default because they are warnings, and confirms that statement text without parameter values is the privacy line they want in logs/microblog.log.
Run it on every service with no query timings
An engineer who suspects a slow page but has no timings starts this from the terminal with this body and comes back to a pull request. One POST /o/{org}/sessions per Flask app, each with its own resources URL; the run reads where each app runs queries, so an app with a worker gets engine events and an app with only request handlers may get the simpler recorder, with the reason in the pull request.
Send a request_id, a UUID, with each body so a retried call returns the run it already started. A key runs at most max_concurrent sessions at once, 4 by default, and a request past that answers 202 with status: "queued" and starts when a slot frees. A webhook_url on the key brings run.completed for each run the key started, with data.session_url to read for the pull request link.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A logging change is judged by what it prints and where, and the only way to see that is to run the app and the worker and make a statement cross the line. The agent does that in its own sandbox, with Redis installed and the threshold at zero, and pastes the lines from both processes, so the reviewer judges real output rather than a description.
The transcript keeps every command and its output, so the reviewer reads the test run, the web warnings and the worker warnings without reproducing the setup. Several Flask services can be instrumented at once, each in its own sandbox, and nothing merges until a person reads the diff.
Frequently asked questions
Why not use SQLALCHEMY_RECORD_QUERIES?
It records queries made during a request and hands them back with get_recorded_queries(), which is convenient for a request hook but blind to the rq worker in app/tasks.py, and Flask-SQLAlchemy documents it as a debugging aid. Engine events see every statement on the engine, in the web process and the worker, with the same two listeners.
Will the log show parameter values?
No. The listener logs the statement with its placeholders and the number of parameters. A search term, an email or a password hash bound to a slow statement never reaches logs/microblog.log or stdout. If you want values in a development environment, the pull request names the one line to change.
What does it cost when nothing is slow?
Two Python function calls per statement, one storing a timestamp in conn.info and one subtracting it. No record is built and nothing is formatted unless the threshold is crossed. With SLOW_DB_QUERY_SECONDS unset the default of half a second applies; set it to a large value to log nothing.
Does it work under gunicorn?
Yes. boot.sh runs gunicorn microblog:app, which calls create_app once per worker process, and init_app registers the listeners on that process's engine. Each gunicorn worker times its own statements and writes through the same app.logger handlers, to stdout when LOG_TO_STDOUT is set as it is in the Docker image.