89 lines
7.9 KiB
Markdown
89 lines
7.9 KiB
Markdown
# Eddy product usage monitor
|
||
|
||
Client default-on **产品使用数据** switch is independent of conversation sync and compatibility telemetry.
|
||
Off stops collection/uploads and clears pending events; it does not retroactively collect the disabled interval.
|
||
Only fixed enums and small numeric fields are accepted: random installation/session/operation/event ids,
|
||
time, event/action/source/outcome, duration/queue time, Eddy release and macOS major.
|
||
No message, user input, task title/id, filesystem path, screenshot, URL, raw exception, script or App content.
|
||
|
||
`POST /api/eddy/usage`: schema 1 needs browser/Eddy SSO; schema 2 (Eddy runtime level 6 / Mac app 0.9.13) may also come
|
||
without any credential. batchId (64 hex), events (1–100).
|
||
Body max 128 KiB. Events older than 8 days or more than 5 minutes in the future are rejected.
|
||
Each event: id/installation (32 hex), at (ms), name/action/source (closed enums), release, macosMajor;
|
||
optional session/operation (32 hex), outcome, durationMs/queueMs (0–7 days).
|
||
Portal views/sessions/engagement require a portal source and session; engagement max 60 seconds.
|
||
Runtime events require runtime source; jobs require job source. Unknown event fields are rejected.
|
||
PK = SHA256(installation + ':' + id). Atomic insert ignores duplicates and returns `{batchId, accepted}`.
|
||
Each new event records the uploading account (`owner`, lower-case SSO email) for the administrator per-user view.
|
||
|
||
Schema 2 (`drizzle/0073_eddy_usage_devices.sql`) adds per event: `device` (16 hex: sha256(IOPlatformUUID)[:16], the value
|
||
every Eddy request already sends as `X-Eddy-Machine`; the same Mac keeps it across reinstalls and folders), `deviceSource`
|
||
(hardware | hostname), `env` (clients upload only `production`; anything else is rejected as a client bug), optional
|
||
`appVersion` (`0.9.13+15`) and `props` — a closed set per name/action of enums, flags, bounded integers and version strings
|
||
(`eddy_usage_rules.ts` PROPS, mirrored by `eddyctl/usage.py`). The Mac app's own events use source `shell`: sessions,
|
||
engagement (≤5 min per event), `view.opened` of its screens, `runtime.prepare`, `home.shown`, `permission.flow`,
|
||
`update.flow`, `device.profile`. A schema 2 batch without a credential must come from one device; it is stored with
|
||
`owner` NULL and `anonymous` true and charged to one shared `anonymous` ingestion budget (its own limits, at most half the global ones — see ingestion-limits.md;
|
||
the device id is reporting data, never the quota key, so changing it buys nothing). A credential that does not verify
|
||
is still 401, so a lapsed sign-in is noticed.
|
||
The client deletes only acknowledged files, caps the queue at 1,000/7 days, uploads every 30 seconds,
|
||
and binds a queue entry to its original API endpoint. Collection does not wait on upload requests.
|
||
|
||
Names: session.started, view.opened, engagement, operation.started, operation.completed,
|
||
app.launch, app.session, agent_job.completed; schema 2 adds runtime.prepare, home.shown, permission.flow, update.flow,
|
||
device.profile, and (P1) desk.action, preview.change, dock.attach, agent.entry, notice.shown, notice.action, app.crash
|
||
(runtime) and the operations storage.clean (props what / freedMB) and storage.tidy. Actions, views (Portal and Mac app)
|
||
and props are in `eddy_usage_rules.ts`. The metrics add `details` — those P1 events by action and their one closed
|
||
detail (kind / what / class / agent / value) with counts, devices, success rate, median duration and MB freed — crashes
|
||
per App hour (summary.appCrashes over appRuntimeMs) and more adoption (desk captures, previews, docking, Agent entry).
|
||
Portal workers emit operation starts/ends; their nested CLI skips counting. Manual/Agent CLI uses
|
||
exit status plus top-level ok:false/isError. Actual launches measure spawn→ready including failed spawn;
|
||
jobs use their actual exit and artifact validation. App runtime is ready→supervisor-exit duration,
|
||
not user-interaction time. Session ids restart per Portal document load.
|
||
|
||
`GET /api/eddy/admin/usage?days=28&release=...&user=<email>`: browser SSO administrator only, no Eddy-session admin bypass.
|
||
Returns summary (installations, devices, accounts, devices with anonymous uploads, Portal and Mac app sessions and
|
||
time), daily UTC buckets, per-name/action/source counts and percentiles, release breakdown,
|
||
`users` (per account, `anonymous` for uploads without a sign-in: devices, installations, sessions, actions, launch/operation
|
||
outcomes, Portal/Mac app/App time, last event), `devices` (per Mac: first 8 hex digits only, installations, number of
|
||
accounts but never which, sessions, time, launches, App time, Mac app builds, latest hardware profile; up to 500),
|
||
`funnel` (devices whose first launch is in the range — a Mac app start on a fresh eddy folder or its first runtime
|
||
preparation — and how many then had the runtime ready, reached home, installed an App, opened a task, had an Agent edit,
|
||
shared; median time to each), `retention` (those devices by UTC week of first launch: any event on day 1, days 7–13,
|
||
days 28–34; a window counts only once it has fully passed), `adoption` (of the active devices, how many opened a task,
|
||
used the design desk, cold-restarted an App, had an Agent edit, shared, imported, relayed), `appVersions`, and `flows`
|
||
(update and permission steps);
|
||
`user` filters every section to one account. No raw rows or installation ids. Activity counts use distinct random
|
||
installations, **not deduplicated people**; the per-user rows group by uploading account. Events from before
|
||
`owner` was recorded are matched by `budget_owner` (sha256 of the email) against known Eddy accounts
|
||
(sign-ins, synced-history owners); unmatched ones appear as `sha256:<prefix>`, events older than that as null.
|
||
Success denominator includes success/failure/timeout/interrupted, excludes cancellation and missing outcomes.
|
||
Latency P50/P95 uses successful completed events; queue P95 includes all completions.
|
||
Portal active time requires visible/focused/recent-input, excludes long sleep gaps. Ongoing App sessions
|
||
are absent from completed runtime sums. Days are rolling 24-hour periods; edge daily bins can be partial.
|
||
Abandoned pre-SSO sign-in, offline/opted-out clients, dropped queue entries and missing completions
|
||
are not a complete product funnel. No native FPS/CPU claim or automatic alerting.
|
||
|
||
Management → Eddy → **使用与表现** exposes 7/28/90-day, release and user filters, device/account/install and Mac app
|
||
KPIs, the activation funnel, weekly retention, feature use, per-user and per-device tables, per-action reliability/latency
|
||
tables, update and permission steps, Mac app builds, daily trends and page counts. Auto refresh every visible minute.
|
||
`eddy_usage_events` retains received events for 90 days, pruned at boot, hourly and during ingestion.
|
||
Data collection is additional to legacy compatibility observations, not an extension of their raw payloads.
|
||
|
||
Rollout: apply additive `drizzle/0066_eddy_usage.sql` through deployment, then server, then client. Schema 2 the same
|
||
way: `drizzle/0073_eddy_usage_devices.sql`, then this server (it keeps accepting schema 1), then the Eddy runtime, then
|
||
the Mac app.
|
||
This follows the separate conversation migration 0065 when both features ship together.
|
||
Client rollback stops new collection; server rollback can leave the additive table in place.
|
||
Development tests use only explicitly isolated `TEST_DATABASE_URL`, never the production database.
|
||
|
||
```sh
|
||
bun test control-server/test/eddy_usage.test.ts
|
||
TEST_DATABASE_URL=postgres://user@127.0.0.1:55483/test bun test control-server/test/eddy_usage.integration.test.ts
|
||
EDDY_TEST_SOURCE=/path/to/eddy-source TEST_DATABASE_URL=postgres://user@127.0.0.1:55483/test bun test control-server/test/eddy_usage.integration.test.ts
|
||
```
|
||
|
||
Integration database needs migrations 0032 (SSO) and 0066. Synthetic cross-repository probe verifies
|
||
actual Python→HTTP→Hono→Postgres, authentication, no admin bypass, fixed-field rejection, idempotency,
|
||
exact success/percentile denominators, range/version filters, retention and opt-out.
|