52 lines
3.3 KiB
Markdown
52 lines
3.3 KiB
Markdown
|
# Sprint: website observability wire-up
|
||
|
|
|
||
|
|
## Vision issues
|
||
|
|
- #426 — Website observability — make disinto.ai an observable addressable
|
||
|
|
|
||
|
|
## What this enables
|
||
|
|
After this sprint, the factory can read engagement data from disinto.ai. The planner
|
||
|
|
will have daily evidence files in `evidence/engagement/` to answer: how many people
|
||
|
|
visited, where they came from, which pages they viewed. Observables will exist.
|
||
|
|
The prerequisites for two milestones unlock:
|
||
|
|
- Adoption: "Landing page communicating value proposition" (evidence confirms it works)
|
||
|
|
- Ship (Fold 2): "Engagement measurement baked into deploy pipelines" (verify-observable step becomes non-advisory)
|
||
|
|
|
||
|
|
## What exists today
|
||
|
|
|
||
|
|
The design and most of the code are already done:
|
||
|
|
|
||
|
|
- `site/collect-engagement.sh` — Complete. Parses Caddy's JSON access log, computes unique visitors / page views / top referrers, writes dated JSON evidence to `$OPS_REPO_ROOT/evidence/engagement/YYYY-MM-DD.json`.
|
||
|
|
- `formulas/run-publish-site.toml` verify-observable step — Complete. Checks Caddy log activity, script presence, and evidence recency on every deploy.
|
||
|
|
- `docs/EVIDENCE-ARCHITECTURE.md` — Documents the full pipeline: Caddy logs → collect-engagement → evidence/engagement/
|
||
|
|
- `docs/OBSERVABLE-DEPLOY.md` — Documents the observable deploy pattern.
|
||
|
|
- `docker/edge/Dockerfile` — Caddy edge container exists for the factory.
|
||
|
|
|
||
|
|
What's missing is the wiring: three pieces that connect the parts together.
|
||
|
|
|
||
|
|
## Complexity
|
||
|
|
|
||
|
|
Files touched: 3-4 (lib/generators.sh, lib/ops-setup.sh, disinto-factory/SKILL.md, possibly site/collect-engagement.sh)
|
||
|
|
Subsystems: Caddy config generation, ops repo initialization, cron registration
|
||
|
|
Sub-issues: 3
|
||
|
|
Gluecode ratio: ~85% gluecode, ~15% greenfield
|
||
|
|
|
||
|
|
This is almost entirely wiring existing infrastructure — not new capability.
|
||
|
|
|
||
|
|
## Risks
|
||
|
|
|
||
|
|
- Production vs. factory Caddy: The factory's generated Caddyfile is for the local dev proxy (Forgejo + Woodpecker + staging). The production disinto.ai runs on a separate host Caddy. Sub-issue 1 must address both: update the template (for new deployments) and document the manual step for the existing production host.
|
||
|
|
- Ops repo path on production host: collect-engagement.sh writes to $OPS_REPO_ROOT/evidence/engagement/. The script must commit via Forgejo API (no SSH required) so it can run on any host with a token.
|
||
|
|
- Log format mismatch: collect-engagement.sh assumes Caddy's structured JSON format. If the production Caddy uses default Combined Log Format, the script will produce empty reports silently. Fix: add a format-detection guard.
|
||
|
|
|
||
|
|
## Cost — new infra to maintain
|
||
|
|
|
||
|
|
- One cron entry on the production host (55 23 * * *)
|
||
|
|
- Daily evidence files in ops repo (evidence/engagement/*.json) — ~1KB/file, negligible storage
|
||
|
|
- No new services, containers, or agents
|
||
|
|
|
||
|
|
## Recommendation
|
||
|
|
|
||
|
|
Worth it. Three small implementation issues close a design that is already fully specified and mostly implemented. The return: a live observable, daily engagement data in the ops repo, and the planner can begin evidence-driven gap analysis on the landing page. This is the cheapest path from Fold 2 to Fold 3.
|
||
|
|
|
||
|
|
Do NOT add Plausible/Umami at this stage. The Caddy-log approach is cookie-free, zero-dependency, and already coded. Richer analytics can layer on top once basic observability is confirmed working.
|