/metrics never reports how close a client is to being throttled

Nobody has started this yet — be first.

Business impact

Right now the only rate-limit signal exposed via /metrics is a counter of rejections that already happened. There is no way for an on-call dashboard or alert to see a client approaching its limit before it actually gets throttled -- graphing "client X is down to 2 tokens, about to get cut off" is impossible today; the only visibility is after the 429s start, which is too late to react proactively.

Problem

RateLimiter.check() already computes tokens_remaining on every call -- it is right there in the the proxy handler gets back -- but that number is thrown away the moment the handler finishes reading . There is a Gauge already defined in , labeled by and , so it shows up in ' exposition format -- nothing anywhere calls on it.

Current behavior

The rate_limit_tokens_remaining Gauge always reads 0 for every route/client combination, regardless of how many tokens are actually left, because no call site anywhere invokes .labels(...).set(...) on it.

Expected behavior

Every time a rate-limited route's request goes through the rate-limit check in app/routers/proxy.py, rate_limit_tokens_remaining for that (route_id, client_key) pair is updated to whatever RateLimitResult.tokens_remaining reports -- whether the request was allowed or rejected.

Steps to reproduce

pytest practice_tickets/tests/test_ticket_03_rate_limit_tokens_remaining_metric.py -v.
Or manually: send requests against a rate-limited route, then check GET /metrics for gateway_rate_limit_tokens_remaining{route_id=...,client_key=...}.
Observe: the gauge reads 0 no matter how many tokens have actually been consumed.

Why this matters

The metric and its .labels(...).set(...) call signature both already exist in app/metrics.py -- what is missing is wiring it up at the one call site in app/routers/proxy.py that already has result (the RateLimitResult) in scope after calling rate_limiter.check(...). Nothing about the rate limiter itself needs to change.

Suggested approach

Look at where app/routers/proxy.py calls rate_limiter.check(...) and already has result in scope. This is a one-line wiring job at the call site, not new plumbing -- both the metric and its update signature already exist.

Acceptance criteria

After a rate-limited route handles a request, the gateway_rate_limit_tokens_remaining{route_id=...,client_key=...} gauge reflects RateLimitResult.tokens_remaining from that request's check, for both allowed and rejected requests
Routes with no rate_limit configured never touch this metric

Verification

pytest practice_tickets/tests/test_ticket_03_rate_limit_tokens_remaining_metric.py -v

Hints (0/2)

Try it without hints first — the reading is the exercise.

Working on this ticket

Work on a branch named for the ticket — that's what you'll submit.

Branch off your fork

$git checkout -b feat/rate-limit-tokens-remaining-metric

Fix it and commit

Meet every acceptance criterion, and add a test that would have caught this.

Push the branch

$git push -u origin feat/rate-limit-tokens-remaining-metric

Submit it below

Paste your fork URL and the branch name, with a short write-up of the root cause.

Submit your fix

Questions

Stuck on something?

Ask about anything unclear in the ticket — the maintainer and anyone who has solved it can answer. Please don't post full solutions.

No questions yet. If something in this ticket reads ambiguously, you are probably not the only one — ask.

The project

Dynamic API Gateway & Reverse Proxy

A FastAPI reverse proxy that streams every request and response without ever buffering a body in full, with hot-reloadable routing, per-route auth, Redis token-bucket rate limiting, and a per-upstream circuit breaker.

Fork on GitHub

Download

Setup

Dynamic API Gateway & Reverse Proxy

git clone <your-fork>
cd FastAPIDevTraining/gateway_proxy
cp .env.example .env   # adjust GATEWAY_ADMIN_TOKEN etc. if you like
docker compose up --build   # Redis + the gateway (uvicorn --reload) + 2 demo upstreams

The gateway is reachable at . Two demo upstreams come up alongside it — (low-latency JSON echo at , plus for the streaming-passthrough demo) and (, , for timeout and circuit-breaker demos) — and wires five example routes against them, one per feature. Verify the stack with (liveness only) and (pings Redis, which every rate-limited route depends on). Every endpoint (route CRUD, reload, persist, breaker snapshot) requires .