feat: structured auth logging for log-based analytics #86

New issue

Closed

opened 2026-04-16 13:06:43 -07:00 by pyr0ball · 0 comments

pyr0ball commented

2026-04-16 13:06:43 -07:00

Owner

Summary

Add structured auth-type logging to API endpoints so traffic can be analysed by log parsing rather than relying entirely on web analytics.

What Snipe did (reference implementation)

def _auth_label(user_id: str) -> str:
    """Classify user_id → local/anon/guest/authed — no PII."""
    if user_id == "local": return "local"
    if user_id == "anonymous": return "anon"
    if user_id.startswith("guest:"): return "guest"
    return "authed"

Add logging.basicConfig(level=logging.INFO, format="%(levelname)s:%(name)s: %(message)s") so app-level logs appear in docker logs alongside the Uvicorn access log.

Endpoints to instrument

Session bootstrap: log auth= + tier= on every call; log UUID on new guest creation.
Primary action endpoints (scan/add item/recipe search/etc.): expand existing log lines with auth=, tier=, and key request params.

Expected log output

INFO:api.main: session new_guest user_id=<uuid>
INFO:api.main: session auth=authed tier=paid
INFO:api.main: scan auth=guest tier=free barcode='012345678901'

Why

Structured key=value log lines are grep/awk-friendly. Enables understanding of anon vs authenticated usage split without client-side tracking.

Reference

Circuit-Forge/snipe@873b9a1 — working implementation.

## Summary Add structured auth-type logging to API endpoints so traffic can be analysed by log parsing rather than relying entirely on web analytics. ## What Snipe did (reference implementation) ```python def _auth_label(user_id: str) -> str: """Classify user_id → local/anon/guest/authed — no PII.""" if user_id == "local": return "local" if user_id == "anonymous": return "anon" if user_id.startswith("guest:"): return "guest" return "authed" ``` Add `logging.basicConfig(level=logging.INFO, format="%(levelname)s:%(name)s: %(message)s")` so app-level logs appear in `docker logs` alongside the Uvicorn access log. ## Endpoints to instrument - **Session bootstrap**: log `auth=` + `tier=` on every call; log UUID on new guest creation. - **Primary action endpoints** (scan/add item/recipe search/etc.): expand existing log lines with `auth=`, `tier=`, and key request params. ## Expected log output ``` INFO:api.main: session new_guest user_id=<uuid> INFO:api.main: session auth=authed tier=paid INFO:api.main: scan auth=guest tier=free barcode='012345678901' ``` ## Why Structured key=value log lines are grep/awk-friendly. Enables understanding of anon vs authenticated usage split without client-side tracking. ## Reference Circuit-Forge/snipe@873b9a1 — working implementation.