7.9 KiB
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.
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.