All jobs

Add Structured Logging to a Flask App

Yes. An agent adds a JSON formatter with a per-request id to the app's existing handlers, carries the id through gunicorn's access log, tests it and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the logging the app already has. In an app shaped like miguelgrinberg/microblog, app/__init__.py builds the app in create_app() and, when not in debug or testing, attaches an SMTPHandler at ERROR when MAIL_SERVER is set, a StreamHandler at INFO when LOG_TO_STDOUT is set, and otherwise a RotatingFileHandler on logs/microblog.log with maxBytes=10240, backupCount=10 and the format %(asctime)s %(levelname)s: %(message)s [in %(pathname)s:%(lineno)d], then logs Microblog startup. config.py reads LOG_TO_STDOUT from the environment, boot.sh runs gunicorn -b :5000 --access-logfile - --error-logfile - microblog:app in the Docker image, and Procfile runs gunicorn too. requirements.txt pins Flask==3.0.0 and gunicorn==21.2.0. Error pages in app/errors/handlers.py roll back the session on 500, and app/api/errors.py builds JSON errors for the API blueprint. tests.py holds unittest cases on a TestConfig with an in-memory SQLite database. The lines are readable, but nothing joins the lines of one request, and a log aggregator has to parse the bracketed format with a regex.

It adds python-json-logger to requirements.txt with a pinned version and a new app/logging.py with two pieces: a JsonFormatter that emits asctime, levelname, name, message, pathname and lineno, and a logging.Filter that, when has_request_context() is true, adds request_id, method, path and remote_addr from flask.g and request, and leaves them out for the rq worker in app/tasks.py and for CLI commands. A LOG_FORMAT setting in config.py, json or text with text as default, decides which formatter the stream and file handlers get, so a developer tailing logs/microblog.log sees the old lines until they opt in. create_app() gains a before_request that sets g.request_id from an incoming X-Request-ID header or uuid4().hex, and an after_request that echoes it, applied to every blueprint including the API.

The handler setup moves out of create_app() into a configure_logging(app) function so it can be exercised under test; its behaviour is unchanged. In tests.py a new LoggingCase creates the app with LOG_FORMAT='json', attaches a handler over a StringIO, requests /auth/login with an X-Request-ID header through the test client, parses the captured line with json.loads and asserts request_id matches the header and path is /auth/login; a second case asserts a generated id is echoed in the response header. boot.sh adds %({x-request-id}o)s to gunicorn's --access-logformat, so the access line for a request carries the same id the application lines do.

The agent runs python -m unittest tests, then starts the app with LOG_TO_STDOUT=1 LOG_FORMAT=json flask run, requests the index and a 404 with curl, and pastes the JSON lines in the pull request, including the Microblog startup line that now has no request fields. flask translate compile and the migrations are untouched.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "codex",
  "input": "Add structured JSON logging with a request id to this Flask app and open a pull request. Read requirements.txt, config.py, microblog.py, app/__init__.py, app/errors/handlers.py, app/api/errors.py, app/tasks.py, boot.sh, Procfile, Dockerfile and tests.py first. Add python-json-logger pinned in requirements.txt. Add app/logging.py with a JSON formatter emitting asctime, levelname, name, message, pathname and lineno, and a logging filter that adds request_id, method, path and remote_addr only when a request context exists. Add a LOG_FORMAT setting to config.py, json or text, default text, and apply it to the stream and file handlers; move the handler setup into a configure_logging(app) function with unchanged behaviour. In create_app add a before_request that sets g.request_id from X-Request-ID or uuid4().hex and an after_request that echoes it. Add %({x-request-id}o)s to the gunicorn access log format in boot.sh. Add a LoggingCase to tests.py that captures a JSON line for a request to /auth/login with a supplied id and asserts request_id and path, and that a generated id is echoed. Run python -m unittest tests, then run the app with LOG_TO_STDOUT=1 and LOG_FORMAT=json, request the index and a missing page, and paste the JSON lines and the test output in the pull request. Do not change the SMTP handler or any route.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. 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.
  2. 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.
  3. 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

What comes back is a pull request with one pinned line in requirements.txt, a new app/logging.py, a LOG_FORMAT entry in config.py, the refactored handler setup and the two hooks in app/__init__.py, one flag in boot.sh and a new test case class. The description shows JSON lines from a real flask run: the startup line without request fields, the index request with its request_id, and the 404 with path set to the missing page, plus the unittest summary.

The repository has no GitHub Actions workflow, so the test output and the pasted lines are the proof, with every command in the run's transcript. A reviewer who runs python -m unittest tests locally sees the same cases.

A reviewer checks that text remains the default so logs/microblog.log reads as before, that the filter does not raise outside a request such as in the rq worker, that a caller-supplied id is kept, and that the gunicorn access line shows the id. Then they set LOG_FORMAT=json in the deployment and map request_id in their log search.

Run it on every service onboarded to the log pipeline

A team moving its Flask services to one log search starts a POST /o/{org}/sessions per repository with this prompt and that repository in resources. Each run reads its own create_app(), so a service that already logs JSON gets only the request id and the gunicorn flag, and one with a plain app.logger gets the formatter too; each opens its own pull request.

Set a webhook_url on the key and run.completed arrives per run with data.session_url, from which the pull request link is read.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

Logging changes are judged by the lines they produce, and the two mistakes that matter, a filter that raises when there is no request context and a formatter that drops the traceback, only appear when the app really runs and really errors. In a Rush sandbox the agent runs the test suite, starts the app, sends real requests including a 404 and reads the lines back, and keeps that output in the run with the pull request.

The same request applies to every Flask service a team has, and the laptop stays untouched: no virtualenv, no logs/ directory, no half-finished branch. The turn parks when it ends, so a follow-up to add the current user's id to the fields wakes it where it stopped.

Frequently asked questions

Will my log file change format?

Not until you set LOG_FORMAT=json. The default is text, which keeps the exact %(asctime)s %(levelname)s: %(message)s line the RotatingFileHandler writes today.

Does the rq worker get request fields?

No. The filter checks has_request_context() and adds request_id and the other fields only inside a request, so lines from app/tasks.py carry the base fields alone. Passing the id into a task is a follow-up the pull request notes.

Why change boot.sh?

Gunicorn writes its own access line per request. Adding %({x-request-id}o)s to the access log format prints the response header the app sets, so the access line and the application lines of one request share an id.

Is the SMTP error mail affected?

No. The SMTPHandler keeps its own formatting and ERROR level, and the pull request does not touch it. Only the stream and file handlers take the new formatter.

More Flask jobs

The same job on other stacks

Keep reading