# 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 Rush](https://cloud.getrush.ai/run/add-structured-logging/flask/). Opens 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`

```json
{
  "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.

## 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

- [Add Type Hints to a Flask Codebase](https://getrush.ai/run/add-type-hints/flask/)
- [Find Dead Code in a Flask App](https://getrush.ai/run/find-dead-code/flask/)
- [Fix Failing GitHub Actions Checks in a Flask App](https://getrush.ai/run/fix-failing-ci/flask/)

## The same job on other stacks

- [Add Structured Logging to a Gin API from a Linear Issue](https://getrush.ai/run/add-structured-logging/gin/)
- [Add Structured Logging to a Hono Worker](https://getrush.ai/run/add-structured-logging/hono/)
- [Add Structured Logging to a Koa API](https://getrush.ai/run/add-structured-logging/koa/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
