askrobots / dbbasic-object-server
Public
Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
danq9
signup: the person chooses the password and name on the confirm page
83c7aa6
2 weeks, 5 days ago
History
dbbasic-package.json · 5.2 KB · 73 lines
| 1 | { |
| 2 | "id": "app-analytics", |
| 3 | "name": "Analytics", |
| 4 | "version": "0.3.0", |
| 5 | "description": "First-party traffic analytics (port of q9's analytics app): an append-mode page_views collection fed by a server-side capture hook (object_analytics), one row per non-asset request -- path/method/status/ip/user_agent/referrer/session/is_owner. Live traffic + bot-attack visibility (4xx and /api hits ARE captured on purpose), and a rollup source for dashboards. Capture is off unless DBBASIC_ANALYTICS is set (per-request write is an operator choice); admin-read only, closed to the generic write surface. Bounded by the daemon's time-windowed retention pass (DBBASIC_ANALYTICS_RETENTION_DAYS, default 30) -- the platform's heaviest write path and the stress test for massive-file rotation. No pages: the shell/dashboard + rollups are the surface. 0.2.0 adds /visitors, which answers a different question from /analytics: not what was requested, but how many PEOPLE came. It counts visitors, bots and the operator's own traffic APART rather than as one number, because undifferentiated unique-IP counts are dominated by scanners -- on this very server 45% of distinct paths were hit exactly once by things probing for /wp-login.php -- and a metric that turns a quiet day into a busy one is worse than no metric. A bot is decided behaviourally (an address that never successfully loaded a real page) rather than by a user-agent blocklist, because the blocklist is always out of date and the behaviour is not. Our own hits are labelled, never hidden: seeing your own visit is how you know the page is recording anything at all. 0.3.0 wires up GOALS, CONVERSIONS and FUNNELS -- the `conversions` collection had existed for a while and NOTHING wrote to it, which is worse than an absent feature because an empty table reads as 'nobody converted' when the truth is 'nothing was ever recorded'. system_record_conversion HANDLES the transitions that already happen (orders.record.created/updated, payments.record.created, scans.record.updated) and records four goals -- order_confirmed, order_collected, payment_received, scan_confirmed -- one row each, idempotent by provenance: the source (`orders/ord-1`) lives in the metadata blob and a replayed event records nothing twice, because the dispatcher is at-least-once and `confirmed` is a state an order SITS in rather than an edge it crosses. It is a reaction, post-commit, best-effort, never a gate, and it degrades out loud when app-analytics is absent rather than silently (silence reads as 'already counted'). The thread those funnels need is the new first-party `dbbasic_visitor` cookie in object_server: opaque secrets.token_urlsafe, Path=/, HttpOnly, SameSite=Lax, DBBASIC_ANALYTICS_VISITOR_DAYS (180), never set when DNT:1 or Sec-GPC:1 is present, never on an asset/API path, withheld from page objects, and NEVER written into the same page_views or conversions row as a user_id -- docs/analytics.md's cookie rule 4, enforced in build_page_view/build_conversion and pinned by tests rather than left to judgement. object_conversions.py is the pure fold half: funnel() (ordered path-prefix or event_type steps, distinct visitors and drop-off per step, threaded by session token and falling back to IP for rows with none -- and REPORTING the IP-stitched fraction, because a funnel that hides its own uncertainty is the analytics this package exists in opposition to), returning_visitors() (explicitly a floor and not a census, with the caveat returned as data so a surface cannot render the number without it) and time_to_conversion() (median/spread, counting aged-out first visits apart rather than dropping them, which would bias the median toward fast conversions). /visitors renders all of it, including one worked funnel configured from the analytics.funnel_steps setting so a shop describes its own without code; with nothing configured it shows what to configure, built from the paths and event types this server actually recorded.", |
| 6 | "compatibility": { |
| 7 | "dbbasic_object_server": ">=0.1.0" |
| 8 | }, |
| 9 | "dependencies": [ |
| 10 | "app-rollup", |
| 11 | "app-views" |
| 12 | ], |
| 13 | "objects": [ |
| 14 | { |
| 15 | "id": "site_visitors", |
| 16 | "path": "objects/site/visitors.py" |
| 17 | }, |
| 18 | { |
| 19 | "id": "system_record_conversion", |
| 20 | "path": "objects/system/record_conversion.py" |
| 21 | } |
| 22 | ], |
| 23 | "schemas": [ |
| 24 | { |
| 25 | "collection": "page_views", |
| 26 | "path": "schemas/page_views.json" |
| 27 | }, |
| 28 | { |
| 29 | "collection": "conversions", |
| 30 | "path": "schemas/conversions.json" |
| 31 | } |
| 32 | ], |
| 33 | "permissions": [ |
| 34 | { |
| 35 | "path": "permissions/rules.json" |
| 36 | } |
| 37 | ], |
| 38 | "seed": [ |
| 39 | { |
| 40 | "collection": "rollup_definitions", |
| 41 | "path": "seed/rollup_definitions.tsv" |
| 42 | }, |
| 43 | { |
| 44 | "collection": "views", |
| 45 | "path": "seed/views.tsv" |
| 46 | }, |
| 47 | { |
| 48 | "collection": "site_routes", |
| 49 | "path": "seed/site_routes.tsv" |
| 50 | } |
| 51 | ], |
| 52 | "migrations": [], |
| 53 | "nav": [ |
| 54 | { |
| 55 | "id": "analytics", |
| 56 | "label": "Analytics", |
| 57 | "path": "/analytics", |
| 58 | "blurb": "First-party traffic: page views by path, status and referrer", |
| 59 | "surface": "operator", |
| 60 | "group": "System", |
| 61 | "order": 650 |
| 62 | }, |
| 63 | { |
| 64 | "id": "visitors", |
| 65 | "label": "Visitors", |
| 66 | "path": "/visitors", |
| 67 | "blurb": "Unique visitors by hour and day, with bots counted apart", |
| 68 | "surface": "operator", |
| 69 | "group": "System", |
| 70 | "order": 655 |
| 71 | } |
| 72 | ] |
| 73 | } |