What the agent does
The agent reads how the app is assembled and how its checks run, because in a Litestar project the lint hooks are stricter than the code. In a project like litestar-org/litestar-hello-world, app.py defines two handlers, /async which awaits a short sleep and /sync with sync_to_thread=False, lists both in __all__, and builds app = Litestar(route_handlers=[...]). pyproject.toml is a PDM project with litestar[standard]>=2.4.1, a lint group with ruff, mypy in strict mode, pyright, codespell and pre-commit, and a test group with pytest, pytest-asyncio and pytest-cov. .pre-commit-config.yaml runs ruff with select = ["ALL"], mypy with litestar[standard] as an additional dependency, slotscheck, ensure-dunder-all and pdm-lock-check, so a dependency added without refreshing pdm.lock fails the validate job in .github/workflows/ci.yaml. tests/test_app.py has two TestClient tests, and test.yaml runs pdm install then pdm run pytest on Python 3.8 through 3.11.
The dependency goes in through PDM so the lock stays consistent: pdm add "litestar[standard,prometheus]", which adds the prometheus-client extra and rewrites pdm.lock. The constraint >=2.4.1 lets PDM resolve a current 2.x release, where the plugin is importable as litestar.plugins.prometheus; if a project pins an older 2.x, the same classes live under litestar.contrib.prometheus and the agent uses that path instead and says so.
In app.py the agent creates PrometheusConfig(app_name="litestar-hello-world", prefix="litestar"), adds PrometheusController to route_handlers so /metrics is served in Prometheus text format, and adds prometheus_config.middleware to the app's middleware list so every request is counted and timed under the configured prefix with the method, path and status as labels. __all__ gains the new names so the ensure-dunder-all hook stays green, and the type annotations satisfy mypy strict without a cast. excluded_http_methods and group_path are left at their defaults and named in the pull request as the two knobs to reach for first; the /metrics scrape itself appears in the counters, which is normal and noted.
A third test in tests/test_app.py requests /sync once and then /metrics, asserts a 200 with a text content type, and asserts the body contains a sample whose name starts with the litestar_ prefix and whose labels name /sync. The agent runs pdm install, pdm run pytest, and pre-commit run --all-files so ruff, mypy, slotscheck, the dunder-all check and the lock check all pass before the pull request opens, then starts the app with litestar run once and pastes a few lines of the real scrape output into the description.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add Prometheus metrics to this Litestar application. Read app.py, pyproject.toml, pdm.lock, tests/test_app.py, .pre-commit-config.yaml and .github/workflows/ci.yaml and test.yaml first. Add the prometheus extra with pdm add so pyproject.toml and pdm.lock change together. In app.py create a PrometheusConfig with an app_name and a prefix, add PrometheusController to route_handlers and the config's middleware to the app's middleware, using litestar.plugins.prometheus or litestar.contrib.prometheus depending on the resolved Litestar version, and keep __all__ complete for the ensure-dunder-all hook. Add a test that requests /sync and then /metrics and asserts the status, the text content type and a sample under the prefix labelled with /sync. Run pdm install, pdm run pytest and pre-commit run --all-files and fix anything ruff, mypy, slotscheck or the lock check reports. Start the app once with litestar run and capture a few lines of /metrics. Open a pull request that lists the dependency change, the two app.py additions, the test and the captured scrape lines.",
"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
What comes back is a pull request that changes pyproject.toml and pdm.lock for the extra, app.py for the config, controller and middleware, and tests/test_app.py for the new test. The description shows a few lines of the /metrics output as the running app produced them, names the prefix and the labels, and lists excluded_http_methods and group_path as the settings to adjust once real paths with ids appear.
The run's record keeps pdm add, the full pre-commit run --all-files output with every hook's result, the pytest run with the three tests, and the litestar run session with the scrape, so a reviewer sees the lint and type checks pass under the project's strict settings.
Before merging, a reviewer decides on the app_name label their Prometheus uses, whether /metrics should be excluded from its own counters, and whether a scrape job should be added to their Prometheus config, which the pull request leaves to the deployment repository.
Run it on every new service from the template
A team that starts each Litestar service from the hello-world template can run this once per repository from its own server: one POST /o/{org}/sessions per repository, each with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started rather than a second pull request.
After that, a Grafana alert on a service whose scrape target is down can start a run through an automation's webhook trigger, since a Grafana contact point can send the Authorization: Bearer header the trigger needs, with the prompt "check that /metrics still answers on this service's main branch and report what changed". Duplicate deliveries are dropped with an Idempotency-Key header on the trigger's URL, a UUID v5 of the alert's fingerprint.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A Litestar template enforces more than most projects: ruff with every rule on, strict mypy, slotscheck, a dunder-all check and a lock check, all in pre-commit and all in CI. A metrics change that is right in the browser still fails on a missing __all__ entry or an unrefreshed pdm.lock. The agent runs the same hooks in its sandbox and fixes those before the pull request exists.
The sandbox keeps the hook output, the tests and the live scrape, so the pull request can show real metric lines and a green pre-commit run rather than asking a reviewer to install PDM and find out.
Frequently asked questions
Why pdm add instead of editing pyproject.toml?
Because .pre-commit-config.yaml runs pdm-lock-check, which fails when pyproject.toml and pdm.lock disagree, and CI runs that hook. pdm add updates both in one step; a hand edit would pass locally and fail the validate job.
Which import path does the plugin use?
On a current Litestar 2.x it is litestar.plugins.prometheus; older 2.x releases expose the same PrometheusConfig and PrometheusController under litestar.contrib.prometheus. The agent checks the version PDM resolved and uses the path that exists, and the pull request names it.
Will /metrics count its own scrapes?
Yes, by default the middleware sees every request, including the scrape. The pull request names excluded_http_methods and the config's path exclusion as the way to change that, and leaves the default so the first dashboard shows the endpoint is alive.
Does it change the Python versions CI tests?
No. The matrix in ci.yaml stays at 3.8 through 3.11, and the agent confirms the extra installs on the version it runs. If prometheus-client drops a version the matrix still lists, the pull request says so rather than editing the matrix.
More Litestar jobs
The same job on other stacks
- Add Prometheus Metrics to a Phoenix LiveView App (Phoenix LiveView)
- Add Prometheus Metrics to a Quarkus App (Quarkus)
- Add Prometheus Metrics to a Rocket App (Rocket)