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

New issue

Open

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

pyr0ball commented

2026-04-16 13:06:39 -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 (previously suppressed by missing root handler).

Endpoints to instrument

Session bootstrap (/api/session or equivalent): log auth= + tier= on every call; log UUID on new guest creation.
Primary action endpoint (search/scan/label/etc.): expand existing log line 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: search auth=guest tier=free adapter=api pages=1 listings=48 q='rtx 4090'

Why

Structured key=value log lines are grep/awk-friendly and can be shipped to Loki + Grafana later without changing the format. Enables understanding of anon vs guest 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 (previously suppressed by missing root handler). ## Endpoints to instrument - **Session bootstrap** (`/api/session` or equivalent): log `auth=` + `tier=` on every call; log UUID on new guest creation. - **Primary action endpoint** (search/scan/label/etc.): expand existing log line 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: search auth=guest tier=free adapter=api pages=1 listings=48 q='rtx 4090' ``` ## Why Structured key=value log lines are grep/awk-friendly and can be shipped to Loki + Grafana later without changing the format. Enables understanding of anon vs guest vs authenticated usage split without client-side tracking. ## Reference Circuit-Forge/snipe@873b9a1 — working implementation.