Product observability — activation funnel, client errors, and backend telemetry boundaries

[Flow-Fly]

Parent initiative: #72
Related backend capability: #132
Related mobile capability: #382

Outcome

Understand whether visitors reach meaningful creative milestones, where they stop, and whether production services are healthy—without collecting artwork, project names, filenames, palettes, or other private creative data.

This is a capability-level roadmap issue, not one delivery slice. It must be split into reviewable slices after the product metrics, privacy boundary, and hosting choice are approved.

Why now

Cloudflare's visitor count does not answer the product questions that matter:

• Did the editor load successfully?
• Did someone create or open a project?
• Did they make a drawing action?
• Did they create a second animation frame?
• Did they play, save, or export their work?
• Did onboarding help them reach those milestones?
• Once accounts exist, did sign-in and synchronization succeed?

A small baseline should exist before the welcome/tutorial experience ships so its effect can be measured.

Observability layers

These tools solve different problems and should not be treated as mutually exclusive.

1. Website traffic and browser performance

Keep Cloudflare Web Analytics for aggregate visits, page views, loading performance, and Core Web Vitals.

2. Product activation events

Record a deliberately small milestone funnel through a provider-neutral client API. Candidate milestones:

• editor_loaded
• project_created
• project_opened
• first_drawing_action
• second_frame_created
• playback_started
• project_saved
• export_completed
• tutorial_started
• tutorial_completed
• tutorial_skipped
• later: sign_in_completed, first_sync_completed, and sync failures

A small Cloudflare Worker endpoint writing to Workers Analytics Engine is the leading low-cost candidate at the current traffic level. Confirm limits, privacy, abuse controls, querying, retention, and future pricing before choosing it.

3. Client failure visibility

Capture application startup failures and unhandled errors with release/build metadata. Error reporting must not include project payloads or other creative content. Decide whether the activation endpoint is sufficient or a dedicated error service is justified.

4. Backend operational telemetry

When #132 becomes a deployed service, add structured logs, request IDs, health signals, latency/error metrics, and sync outcome metrics.

Scaleway Cockpit/Grafana integration belongs primarily to this layer: infrastructure logs, metrics, dashboards, and alerts for the API, database, and object storage. It does not replace product activation analytics.

Privacy boundary

Do not collect:

• artwork or project bytes;
• project names or filenames;
• palette values;
• imported image metadata;
• free-form user text;
• authentication provider tokens;
• exact interaction streams or pointer movements.

Define the minimum dimensions needed for each event. Any persistent anonymous identifier, account-level retention measurement, geographic enrichment, or third-party service requires an explicit privacy decision and documentation.

Delivery outline

1. Write the event taxonomy, allowed dimensions, retention expectations, and privacy rules.
2. Add a provider-neutral event port with a no-op/default implementation and development inspection.
3. Prove one production sink for the approved milestone events.
4. Instrument the smallest representative funnel.
5. Add a basic query/dashboard for activation.
6. Add client error visibility.
7. Extend operational telemetry only as backend/auth/sync slices are deployed.

Capability acceptance

• The owner can see the count or rate for each approved activation milestone.
• Tutorial start, skip, and completion can be compared with normal editor activation.
• Events contain no project content or unnecessary personal data.
• Telemetry failure never blocks drawing, saving, exporting, or offline use.
• Development and automated tests do not send production events.
• Costs and limits are documented and remain appropriate for current traffic.
• Backend logs and metrics have a clear later integration path with Scaleway/Grafana.
• The implementation is split into bounded delivery slices before coding begins.

Decisions required before slicing

• Exact event taxonomy and allowed dimensions.
• Whether return usage is measured, and under which privacy/consent model.
• Cloudflare Worker + Analytics Engine versus another product analytics sink.
• Whether client error reporting shares that sink or uses a dedicated service.
• Retention period and access controls.
• Which Scaleway/Grafana signals are required for the first deployed backend.

Non-goals

• No surveillance-style session replay.
• No tracking every click or drawing gesture.
• No full Grafana/Prometheus platform before a deployed backend exists.
• No billing metering or entitlement implementation.
• No requirement to sign in for local observability or local editor use.

References

• Cloudflare Web Analytics: https://developers.cloudflare.com/web-analytics/about/
• Workers Analytics Engine: https://developers.cloudflare.com/analytics/analytics-engine/
• Workers Analytics Engine pricing: https://developers.cloudflare.com/analytics/analytics-engine/pricing/

[Flow-Fly]

Approved delivery slice: privacy-first telemetry foundation

The owner approved a banner-free first slice with no production collection.

Linked task issues:

• Telemetry contract: define privacy-safe product events #406 — closed product-event contract and runtime privacy validation
• Telemetry client: add no-op default and development inspection #407 — production-safe no-op client port and development inspection sink
• Observability workflow: document the recurring privacy decision #408 — recurring observability decision and privacy/consent documentation

All three tasks ship together in one draft pull request from 8767582e849391bd97052d580a090e895ebb3986.

The capability remains open and risk:medium: production sinks, provider choice, real feature instrumentation, client failure reporting, and backend operational telemetry still require later slicing and explicit privacy/product decisions.

This slice does not edit any AGENTS.md file while #405 owns those files.