# Add Prometheus Metrics to a Litestar App

Yes. An agent adds Litestar's Prometheus plugin to your app with its middleware and /metrics controller, updates pdm.lock, writes a scrape test and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-prometheus-metrics/litestar/). Opens the console with this prompt ready to send, in a Project that has your repository.

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

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

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

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

- [Add Rate Limiting to a Litestar API](https://getrush.ai/run/add-rate-limiting/litestar/)
- [Add Request ID Logging to a Litestar App](https://getrush.ai/run/add-request-id-logging/litestar/)
- [Add Response Caching to a Litestar App](https://getrush.ai/run/add-response-caching/litestar/)

## The same job on other stacks

- [Add Prometheus Metrics to a Phoenix LiveView App](https://getrush.ai/run/add-prometheus-metrics/phoenix-liveview/)
- [Add Prometheus Metrics to a Quarkus App](https://getrush.ai/run/add-prometheus-metrics/quarkus/)
- [Add Prometheus Metrics to a Rocket App](https://getrush.ai/run/add-prometheus-metrics/rocket/)

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