Distinguish liveness, readiness and metrics

In this lesson you will distinguish liveness, readiness and metrics. Work with the Equipment Rental API in the downloadable lab. The reference is a complete solution with separate lesson checks, so you can inspect the answer, make a deliberate local change and verify its behavior.

Liveness asks whether the process can respond. Readiness asks whether it can serve work that depends on its current dependencies. /health/live returns without a database query; /health/ready performs SELECT 1 and reports 503 if the database cannot be reached. Restarting a healthy process repeatedly because a database is unavailable can make recovery harder.

Readiness does not prove every business function works or that migrations are compatible. The delivery rehearsal separately checks schema revision, contract requests and rollback planning. Metrics count request method, route pattern and status group. They omit user ids, rental ids and query parameters, because those values create unbounded series and may expose private information. The local /metrics route is a teaching JSON view, not a production monitoring service; a deployment should choose its exporter and access boundary explicitly. Read a symptom in context: readiness failure with passing liveness points to a dependency path, while rising 409 capacity conflicts may be expected business behavior rather than server outages.

Worked source: equipment/api.py, create_app.

Run lesson23. Both health routes pass with fresh PostgreSQL. A separate app points to an unused local port: liveness still passes while readiness returns 503. Ten different missing URLs contribute to one unmatched metrics row, demonstrating bounded labeling.

def test_lesson23(db):
    app = create_app(
        Settings(database_url=os.environ["LAB_DATABASE_URL"], jwt_secret=KEY)
    )
    with TestClient(app) as client:
        assert client.get("/health/live").status_code == 200
        assert client.get("/health/ready").status_code == 200
        for identifier in range(10):
            client.get(f"/missing-{identifier}")
        rows = client.get("/metrics").json()
        unmatched = [row for row in rows if row["route"] == "unmatched"]
        assert len(unmatched) == 1 and unmatched[0]["count"] == 10
    failed = create_app(
        Settings(
            database_url="postgresql+psycopg://unused:unused@127.0.0.1:1/aabha_lab_missing?connect_timeout=1",
            jwt_secret=KEY,
        )
    )
    with TestClient(failed) as client:
        assert client.get("/health/live").status_code == 200
        assert client.get("/health/ready").status_code == 503

python run_checks.py -k lesson23