Concepts

Owlmetry's data model is built around a small set of composable primitives. Events capture what happened, metrics measure how long things take, funnels track multi-step conversions, and experiments let you compare variants. Error events cluster into trackable issues, optional file attachments let you ship bytes alongside errors, and integrations sync external signals into per-user properties. Everything is scoped to projects and apps, secured by API keys, and filterable by data mode.

Understanding these concepts will help you instrument your app effectively and get the most out of the dashboard and CLI.

• Events — The core data unit. Every interaction, error, and state change becomes a structured event with log levels, session tracking, timestamps, deduplication, and custom attributes. Events are the foundation that metrics and funnels build on.
• Structured Metrics — Lifecycle operations (start/complete/fail/cancel), single-shot measurements, duration tracking, and aggregation queries. Use metrics to track performance-critical operations like API calls, image uploads, or checkout flows.
• Funnels — Multi-step conversion tracking with open and closed analysis modes, drop-off rates, and experiment segmentation. Funnels answer "where are users dropping off?" and "which variant converts better?"
• A/B Experiments — Client-side variant assignment with persistent storage and automatic event tagging. Assign variants, measure impact through funnel segmentation, and ship the winner.
• Issues — Error events automatically fingerprinted and clustered into trackable issues with status lifecycle, occurrence tracking, regression detection, comments, merging, and per-project email alerts.
• Event Attachments — Upload input files alongside error events to reproduce bugs locally. Per-user and per-project quotas keep storage bounded.
• User Properties — Custom key-value metadata on each project-level user (plan tier, subscription status, revenue). Merged on each call with a 50-key limit.
• Integrations — Per-project connections to external services like RevenueCat that sync subscriber data into user properties via webhooks plus on-demand backfill.
• Background Jobs — Async work powered by pg-boss: retention cleanup, partition creation, soft-delete cleanup, issue scanning and notification, attachment cleanup, app version sync, and on-demand RevenueCat sync.
• Latest Version Detection — Per-app latest_app_version resolved hourly from the App Store (Apple) or computed from production events. Powers the green/amber version badges shown across events, users, and issues.
• Projects & Apps — How projects group apps across platforms, bundle ID validation, project color, retention policies, and auto-created client keys. A single project can have iOS, Android, web, and backend apps — all sharing the same dashboard.
• Authentication & API Keys — Passwordless email auth, client vs agent vs import keys, permissions, team roles (owner > admin > member), and invitations.
• Data Mode — Filtering between production and development data across the dashboard, CLI, and API. Keep debug noise out of production views without losing visibility into dev builds.