telemetry: public /api/stats endpoint (Tier B showcase) - #1
Conversation
Adds a stdlib-only Vercel Python serverless function at api/stats.py that exposes honest, GitHub-derived metrics about the codebase. The endpoint is consumed by the Production Telemetry panel on https://eleventh.dev. Per the schema at https://github.com/IgnazioDS/IgnazioDS/blob/main/TELEMETRY_SCHEMA.md this system runs in showcase mode (Tier B): the Vercel deploy is a public landing page, not a system serving production workload. Rather than fabricate `runbooks_active_now` / `approvals_pending` counters that would have nothing to count, the endpoint reports real signals: - commits_30d, commits_total via GitHub Link header pagination - primary_language, repo_stars via GET /repos/:owner/:repo - last_commit_at via GET /repos/.../commits?per_page=1 - lines_of_code via committed api/_telemetry_static.json (regenerated by scripts/compute_telemetry_static.py) - mode = "showcase" explicit Tier-B signal for the widget Implementation: - BaseHTTPRequestHandler entrypoint, no third-party deps; sub-200ms cold start on Vercel. - Module-scope 5-min cache keeps us well under GitHub's 60-req/hr unauth rate limit even across many warm invocations. - All counters clamped by SAFETY_CAPS to prevent runaway exposure. - Never returns HTTP 5xx: GitHub failures degrade to status="degraded" with last-good-cache or zeroed metrics, contract stays valid. - CORS headers (* origin) set both at vercel.json edge and inside the Python handler — belt-and-suspenders so the homepage widget can poll the endpoint cross-origin. Tests (tests/test_stats.py, stdlib unittest): - happy path: response shape matches Tier B contract - degraded path: GitHub unreachable -> 200 with status="degraded" - stale-cache fallback: last good response served on subsequent failure - safety caps: oversize values clamped - handler always returns 200, never 5xx - OPTIONS returns 204 with CORS headers To refresh lines_of_code before deploying: python3 scripts/compute_telemetry_static.py git add api/_telemetry_static.json
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 993d5543a6
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| def do_GET(self) -> None: # noqa: N802 (interface contract) | ||
| try: | ||
| payload = _build_response() | ||
| except Exception: # noqa: BLE001 (last-resort: contract forbids 5xx) |
There was a problem hiding this comment.
This handler defines do_GET and do_OPTIONS only, so HEAD /api/stats falls through to BaseHTTPRequestHandler's default unsupported-method path and returns 501, which is a 5xx. That violates the endpoint’s documented “never returns HTTP 5xx” behavior and can surface in environments where proxies, uptime checks, or bots probe with HEAD; add do_HEAD (or equivalent method handling) so HEAD returns a non-5xx response with the same headers as GET.
Useful? React with 👍 / 👎.
1 participant
Summary
api/stats.pyexposing the public Tier-B telemetry contractcommits_30d,commits_total,last_commit_at,primary_language,repo_stars,lines_of_code) withmode: "showcase"flagged so the homepage widget renders this tile as a deployed scaffold rather than a live workload systemWhy showcase mode (
mode: "showcase")Per the schema at https://github.com/IgnazioDS/IgnazioDS/blob/main/TELEMETRY_SCHEMA.md, this repo is currently a static landing page with a CLI scaffold (no DB, no queues, no runbook executions). Reporting fabricated
runbooks_active_now/approvals_pendingcounters would violate the credibility constraint of the homepage telemetry panel. The endpoint instead reports real signals about the codebase. When the system is promoted to production workload, the implementation upgrades to Tier A andmodeflips tolive.Implementation
api/stats.py—BaseHTTPRequestHandlerVercel function, sub-200ms cold start, no third-party depsSAFETY_CAPSclamps every counter to prevent runaway exposurestatus: "degraded"with last-good-cache or zeroed metrics, contract stays valid*origin) set both atvercel.jsonedge and inside the Python handlerscripts/compute_telemetry_static.pyregeneratesapi/_telemetry_static.json(the LOC artifact) before each deployVerification (preview deploy)
Headers:
Content-Type: application/json,Access-Control-Allow-Origin: *,Access-Control-Allow-Methods: GET, OPTIONS,Cache-Control: public, max-age=30.Test plan
python3 -m unittest tests.test_stats— 6/6 pass (happy path, degraded path, stale-cache fallback, safety caps, handler 200, OPTIONS 204)curl /api/statsreturns HTTP 200 with the documented shapehttps://eleventh.devconsole (verify before merge)curl https://agent-runbook-orchestrator.vercel.app/api/stats